[Siddhant-K-code]

Problem

Hooks and auto-instrumentation write sessions to $AGENT_TRACE_DIR, but the global --trace-dir flag defaulted to the literal .agent-traces. With AGENT_TRACE_DIR set, list, replay, health, stats and the other read commands looked in ./.agent-traces and missed every session the hooks had recorded.

Change

store.default_trace_dir() is a single resolver, read on each call rather than at import time. It is now used by:

• the global --trace-dir default in cli.py (computed in build_parser(), so each invocation and each test that patches os.environ sees the current value)
• hooks._get_store_dir()
• integrations/_base._get_store()

Precedence:

1. An explicit --trace-dir DIR.
2. $AGENT_TRACE_DIR, when set and non-empty.
3. .agent-traces. Hooks keep their existing fallback to <payload cwd>/.agent-traces before this.

Relative values are passed through unchanged, so writers and readers resolve them against the working directory.

Every command that builds TraceStore(args.trace_dir) picks up the new default, including list, replay, inspect, export, stats, health, mcp, dashboard, watch, retention, import and config-watch.

Behavior change: empty AGENT_TRACE_DIR

Hooks checked "AGENT_TRACE_DIR" in os.environ and integrations used os.environ.get(..., default). Both passed an empty string through as the store path, which resolves to the working directory. Hook files then landed in the project root, and .gitignore protection did not apply because the store refuses to ignore the cwd. An empty value is now treated as unset everywhere, so the CLI, hooks and integrations agree.

Left alone on purpose

• _command_index argv pre-scan: it only skips --trace-dir tokens and resolves no directory.
• server --storage: a separate collector with its own AGENT_STRACE_STORAGE variable.
• rbac, apply and config-diff --dir: admin config stores that hooks never write, and they never read the global --trace-dir.
• Library defaults:
  • decorator.start_session(trace_dir=...), a possible follow-up
  • jsonl_import.import_jsonl
  • workspace.py helpers
  • the TraceStore constructor
• Cwd-relative artifacts: baseline.json, datasets/default.jsonl, eval-summary.md, the watch alerts.log and the config-watch snapshot.
• config-watch workspace root: it is derived from the trace dir's parent. That is existing behavior and a possible follow-up.
• VS Code extension: it has its own agentTrace.traceDir setting.
• action.yml: it passes --trace-dir explicitly.

Docs

• docs/commands.md: new "Global options" section with the precedence rules.
• docs/setup.md: short note on AGENT_TRACE_DIR.
• The --trace-dir help text now describes the env fallback.

Tests

tests/test_trace_dir_env.py clears AGENT_TRACE_DIR and related env in setUp and runs inside a temp cwd. It covers:

• resolver cases: unset, set, empty and relative
• a parser default that is read at call time
• list, replay, inspect, health, stats, mcp, dashboard and watch defaulting to the env dir
• real hook handlers writing to the env dir, then list, health and replay reading it through main()
• explicit --trace-dir overriding the env
• an empty env falling back to .agent-traces
• a relative env path for both writer and reader
• writer parity for hooks and integrations, including that empty-env hook writes stay out of the cwd root

Full suite: 2404 tests pass (2 skipped) both with AGENT_TRACE_DIR unset and with it set to a temp directory.

No version bump.