feat(config-watch): AGENTS.md change detector (#86)

* fix: use extra_paths instead of undefined extra in config_watch check

Co-authored-by: Ona <no-reply@ona.com>

* feat(config-watch): AGENTS.md change detector (#86)

- config_watch.py: take_snapshot, diff_snapshots, find_affected_sessions, cmd_config_watch
- Subcommands: snapshot, check, history, affected
- SHA-256 hashing of watched config files; snapshots stored in .agent-traces/config-snapshots.json
- Default watch list: AGENTS.md, CLAUDE.md, system_prompt.md/txt, .cursorrules, .github/copilot-instructions.md
- check exits 1 when config has changed (CI gate)
- 42 tests in tests/test_config_watch.py
- README: new config-watch section and command reference entries
- Version bump 0.49.0 → 0.50.0

Closes #86

Co-authored-by: Ona <no-reply@ona.com>

---------

Co-authored-by: Ona <no-reply@ona.com>

Author: Siddhant-K-code

README.md

@@ -186,6 +186,7 @@ print(f"Replay with: agent-strace replay {meta.session_id}")
 | `curve` | Personal cost-efficiency curve |
 | `a2a-tree` | Cross-agent trace correlation (A2A protocol) |
 | `mcp` | MCP server: expose traces as queryable tools for a debugging agent |
+| `config-watch` | Snapshot and diff AGENTS.md and other config files; find affected sessions |
 
 ```
 agent-strace setup [--redact] [--global]        Generate Claude Code hooks config
@@ -237,6 +238,14 @@ agent-strace oncall --rotation-start DATE       On-call readiness for agent-modi
 agent-strace curve [--export csv]               Personal agent cost-efficiency curve
 agent-strace inflation [--compare m1,m2]        Token inflation calculator across model versions
 agent-strace a2a-tree [session-id]              Visualise A2A agent call graph
+agent-strace config-watch snapshot [--label TEXT] [--watch PATH]
+                                                Snapshot current config file state
+agent-strace config-watch check [--format text|json] [--watch PATH]
+                                                Diff current state vs last snapshot (exit 1 if changed)
+agent-strace config-watch history [--format text|json]
+                                                List all snapshots
+agent-strace config-watch affected [--since DURATION] [--format text|json]
+                                                Sessions that ran after a config change
 ```
 
 ### Import existing Claude Code sessions
@@ -437,6 +446,58 @@ Rules are configurable via `.agent-strace-lint.json`:
 | `error-retry-loop` | WARN | Same tool errored and was retried 3+ times |
 | `no-output` | WARN | Session completed with no write or file-modifying tool calls |
 
+### Config change detector
+
+Track changes to AGENTS.md and other agent configuration files. Snapshot the current state before a change, then check what drifted and which sessions ran after it.
+
+```bash
+# Record a snapshot of all watched config files
+agent-strace config-watch snapshot
+
+# Add a label to identify the snapshot
+agent-strace config-watch snapshot --label "before-prompt-refactor"
+
+# Check whether anything changed since the last snapshot (exit 1 if yes)
+agent-strace config-watch check
+
+# Machine-readable diff
+agent-strace config-watch check --format json
+
+# List all snapshots
+agent-strace config-watch history
+
+# Find sessions that ran after a config change
+agent-strace config-watch affected
+
+# Limit to sessions from the last 7 days
+agent-strace config-watch affected --since 7d
+```
+
+Example output:
+
+```
+$ agent-strace config-watch check
+CHANGED  AGENTS.md          (sha256: a1b2c3d4 → e5f6a7b8)
+ADDED    .claude/settings.json
+No changes to: CLAUDE.md, system_prompt.md
+
+$ agent-strace config-watch affected
+2 session(s) ran after a config change:
+
+  abc123def456  2026-05-20T14:32:01  (after change to: AGENTS.md)
+  789xyz012abc  2026-05-20T15:10:44  (after change to: AGENTS.md)
+
+Run `agent-strace drift` to compare behaviour before and after the change.
+```
+
+Watched files by default: `AGENTS.md`, `CLAUDE.md`, `system_prompt.md`, `system_prompt.txt`, `.cursorrules`, `.github/copilot-instructions.md`. Add extra paths with `--watch`:
+
+```bash
+agent-strace config-watch snapshot --watch .claude/settings.json --watch custom_prompt.txt
+```
+
+Snapshots are stored in `.agent-traces/config-snapshots.json`. Use `check` as a CI gate — it exits 1 when config has changed since the last snapshot.
+
 ### Data retention
 
 Enforce configurable retention policies to automatically delete old session data — required for GDPR, SOC 2, and internal data policies.

src/agent_trace/__init__.py

@@ -1,3 +1,3 @@
 """agent-trace: strace for AI agents."""
 
-__version__ = "0.49.0"
+__version__ = "0.50.0"

src/agent_trace/cli.py

@@ -49,6 +49,7 @@
 from .integrations import detect_and_instrument, _INTEGRATIONS
 from .budget_report import cmd_budget_report
 from .compare import cmd_compare
+from .config_watch import cmd_config_watch
 from .lint import cmd_lint
 from .retention import cmd_retention
 from .sample import cmd_sample
@@ -883,6 +884,32 @@ def build_parser() -> argparse.ArgumentParser:
     p_sample.add_argument("--seed", type=int, default=None,
                           help="random seed for reproducible random sampling")
 
+    # config-watch
+    p_cw = sub.add_parser("config-watch",
+                          help="detect AGENTS.md and config file changes between sessions")
+    cw_sub = p_cw.add_subparsers(dest="config_watch_command")
+
+    cw_snap = cw_sub.add_parser("snapshot", help="record a snapshot of current config files")
+    cw_snap.add_argument("--label", metavar="TEXT",
+                         help="human-readable label for this snapshot")
+    cw_snap.add_argument("--watch", metavar="PATH", action="append",
+                         help="additional file to watch (repeatable)")
+
+    cw_check = cw_sub.add_parser("check",
+                                  help="check whether config has changed since last snapshot")
+    cw_check.add_argument("--watch", metavar="PATH", action="append",
+                          help="additional file to watch (repeatable)")
+    cw_check.add_argument("--format", choices=["text", "json"], default="text")
+
+    cw_hist = cw_sub.add_parser("history", help="show full snapshot history")
+    cw_hist.add_argument("--format", choices=["text", "json"], default="text")
+
+    cw_aff = cw_sub.add_parser("affected",
+                                help="list sessions that ran after a config change")
+    cw_aff.add_argument("--since", metavar="DURATION",
+                        help="only sessions newer than this (e.g. 7d, 24h)")
+    cw_aff.add_argument("--format", choices=["text", "json"], default="text")
+
     # compare
     p_compare = sub.add_parser("compare", help="session-to-session regression report")
     p_compare.add_argument("session_id_a", nargs="?",
@@ -1053,6 +1080,7 @@ def main() -> None:
         "auto": cmd_auto,
         "budget-report": cmd_budget_report,
         "compare": cmd_compare,
+        "config-watch": cmd_config_watch,
         "lint": cmd_lint,
         "retention": cmd_retention,
         "sample": cmd_sample,