feat(v0.10.2): watchPaths + FileChanged auto-evidence (X4)

Adopt the undocumented Claude Code 2.1.x watchPaths + FileChanged hook
contract. SessionStart envelope now emits watchPaths for the project's
marker files (CLAUDE.md, README.md, .docs/plans). When any of them
changes, Claude Code fires FileChanged → ingest-hook appends an
evidence event to the active task.

FileChanged payload schema verified in 2.1.160:
  literal("FileChanged"), file_path: y.string(),
  event: y.enum(["change","add","unlink"])

- SessionStart envelope: watchPaths array of existing absolute paths.
  Missing files skipped (Claude Code logs watcher error and gives up
  on non-existent paths).
- FileChanged branch in ingest-hook: appends evidence event with
  cwd-trimmed display path. No open task → silent no-op.
- TJ_WATCH_PATHS=0 opts out of watchPaths emission.

4 tests:
- session_start_emits_watch_paths_for_existing_marker_files
- session_start_omits_watch_paths_when_disabled_via_env
- file_changed_hook_appends_evidence_to_active_task
- file_changed_hook_with_no_open_task_is_no_op

Closes tj-aym (X4) — completes v0.10.x epic (tj-h7d).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: Shahinyanm

CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.2] - 2026-06-02
+
+**`watchPaths` + FileChanged → auto-evidence on marker file edits.** X4
+of the v0.10.x undocumented-hooks adoption. SessionStart envelope now
+emits `watchPaths` — Claude Code starts monitoring the project's
+marker files (CLAUDE.md, README.md, .docs/plans/), and whenever one
+of them changes (write, create, delete), Claude Code fires the
+`FileChanged` hook event. Our `ingest-hook` handler translates that
+into an `evidence` event on the active task. Captures
+"instructions / plans were edited mid-session" without anyone manually
+typing it. Schema verified in Claude Code 2.1.160:
+`literal("FileChanged"), file_path: y.string(), event:
+y.enum(["change","add","unlink"])`.
+
+### Added
+- SessionStart envelope emits `watchPaths` containing the absolute
+  paths of `CLAUDE.md`, `README.md`, and `.docs/plans` when they
+  exist under the current cwd. Missing files are skipped — Claude
+  Code's watcher logs an error on non-existent paths, so we don't
+  ask it to watch them.
+- `FileChanged` branch in the `ingest-hook` handler: appends an
+  `evidence` event (`FileChanged (change|add|unlink): <relative path>`)
+  to the most-recent open task. No active task → silently no-op.
+- 4 new integration tests:
+  - `session_start_emits_watch_paths_for_existing_marker_files`
+  - `session_start_omits_watch_paths_when_disabled_via_env`
+  - `file_changed_hook_appends_evidence_to_active_task`
+  - `file_changed_hook_with_no_open_task_is_no_op`
+
+### Changed
+- Path display in FileChanged evidence trims the project cwd prefix
+  so the journal stays project-relative and doesn't waste tokens on
+  the absolute home path.
+
+### Configuration
+- `TJ_WATCH_PATHS=0` suppresses watchPaths emission for users who
+  don't want their marker-file edits auto-logged.
+
+### Migration
+- None — additive on SessionStart envelope + new hook branch.
+  Claude Code 2.1.x+ required for FileChanged event firing; older
+  versions ignore unknown envelope keys and never emit FileChanged,
+  so the handler simply never fires for them.
+
 ## [0.10.1] - 2026-06-02
 
 **SessionStart envelope: `sessionTitle` + `initialUserMessage`.**

Cargo.lock

@@ -7,7 +7,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.10.1"
+version = "0.10.2"
 edition = "2021"
 rust-version = "1.88"
 license = "MIT"

Cargo.toml

@@ -16,7 +16,7 @@ name = "task-journal"
 path = "src/main.rs"
 
 [dependencies]
-tj-core = { package = "task-journal-core", version = "0.10.1", path = "../tj-core" }
+tj-core = { package = "task-journal-core", version = "0.10.2", path = "../tj-core" }
 anyhow = { workspace = true }
 clap = { workspace = true }
 tracing = { workspace = true }

crates/tj-cli/Cargo.toml

@@ -1540,6 +1540,33 @@ fn main() -> Result<()> {
                     bundle.push_str("\n\n");
                 }
 
+                // v0.10.2 X4: emit `watchPaths` so Claude Code starts
+                // monitoring our marker files (CLAUDE.md, README.md,
+                // .docs/plans). When any of them changes, Claude Code
+                // fires a FileChanged hook event — our ingest-hook
+                // handler below treats those as `evidence` entries on
+                // the active task so the journal captures
+                // "instructions were updated mid-session" without the
+                // user manually logging it. Only paths that exist at
+                // SessionStart time are emitted (no point watching a
+                // non-existent file — Claude Code logs `watcher error`
+                // and gives up on it). Gated by TJ_WATCH_PATHS=0.
+                let allow_watch_paths = std::env::var("TJ_WATCH_PATHS").as_deref() != Ok("0");
+                let watch_candidates = [
+                    cwd.join("CLAUDE.md"),
+                    cwd.join("README.md"),
+                    cwd.join(".docs").join("plans"),
+                ];
+                let watch_paths: Vec<String> = if allow_watch_paths {
+                    watch_candidates
+                        .iter()
+                        .filter(|p| p.exists())
+                        .map(|p| p.to_string_lossy().to_string())
+                        .collect()
+                } else {
+                    Vec::new()
+                };
+
                 // v0.10.1 X2: extend SessionStart envelope with the
                 // undocumented `sessionTitle` + `initialUserMessage`
                 // fields verified in Claude Code 2.1.160's K45 Zod
@@ -1569,6 +1596,14 @@ fn main() -> Result<()> {
                         recent.len(),
                     ),
                 });
+                if !watch_paths.is_empty() {
+                    hook_specific["watchPaths"] = serde_json::Value::Array(
+                        watch_paths
+                            .into_iter()
+                            .map(serde_json::Value::String)
+                            .collect(),
+                    );
+                }
                 let allow_initial_user_msg =
                     std::env::var("TJ_INITIAL_USER_MESSAGE").as_deref() != Ok("0");
                 // `task-journal create` writes an [open] event, so
@@ -1590,6 +1625,64 @@ fn main() -> Result<()> {
                 return Ok(());
             }
 
+            // v0.10.2 X4: FileChanged. Claude Code 2.1.x fires this
+            // event whenever a path in `watchPaths` (emitted on
+            // SessionStart) changes. Payload: { file_path, event:
+            // "change"|"add"|"unlink" }. We translate it into an
+            // `evidence` event on the active task — captures
+            // "the user/agent edited CLAUDE.md mid-session" without
+            // anyone typing anything. Schema verified in 2.1.160:
+            // `literal("FileChanged"), file_path: y.string(), event:
+            // y.enum(["change","add","unlink"])`.
+            //
+            // No active task → drop silently (we're not opening a
+            // task just because a watched file moved). No events_path
+            // → ditto, fresh project.
+            if kind == "FileChanged" {
+                if !events_path.exists() {
+                    return Ok(());
+                }
+                let state_path =
+                    tj_core::paths::state_dir()?.join(format!("{project_hash}.sqlite"));
+                let conn = tj_core::db::open(&state_path)?;
+                tj_core::db::ingest_new_events(&conn, &events_path, &project_hash)?;
+                let recent = recent_task_contexts(&conn, 1)?;
+                let Some(tc) = recent.into_iter().next() else {
+                    return Ok(());
+                };
+                let file_path = payload
+                    .get("file_path")
+                    .and_then(|v| v.as_str())
+                    .unwrap_or("(unknown)");
+                let change = payload
+                    .get("event")
+                    .and_then(|v| v.as_str())
+                    .unwrap_or("change");
+                // Trim noisy absolute paths to project-relative when
+                // possible — the journal is per-project so the prefix
+                // is redundant and just steals tokens from the pack.
+                let display_path = cwd
+                    .to_str()
+                    .and_then(|c| file_path.strip_prefix(c))
+                    .map(|s| s.trim_start_matches('/').to_string())
+                    .unwrap_or_else(|| file_path.to_string());
+                let evidence_text = format!("FileChanged ({change}): {display_path}");
+                let mut event = tj_core::event::Event::new(
+                    &tc.task_id,
+                    tj_core::event::EventType::Evidence,
+                    tj_core::event::Author::Classifier,
+                    tj_core::event::Source::Hook,
+                    evidence_text,
+                );
+                event.confidence = Some(0.9);
+                event.status = tj_core::event::EventStatus::Confirmed;
+                let mut writer = tj_core::storage::JsonlWriter::open(&events_path)?;
+                writer.append(&event)?;
+                writer.flush_durable()?;
+                println!("{}", event.event_id);
+                return Ok(());
+            }
+
             // PreCompact: Claude Code is about to compact the conversation.
             // Two responsibilities:
             //   1. Catch-up ingest — read the transcript JSONL tail (entries