fix(framework): a file written through the shell belongs to no task

[blafourcade]

Context

Task attribution derives a task from the file_written lines the run journal records. The journal reads a written path out of the host's own hook payload, and WRITTEN_PATH_EXTRACTOR_BY_HOST knows Claude Code's Write, Edit and NotebookEdit.

Found by

A live headless Claude Code session, run against the plugin loaded with --plugin-dir. Asked to create a file inside a task folder, the model did not use Write:

TOOL_USE: Bash {"command": "mkdir -p …/2026_08_21_live && printf 'probe' > …/notes.md"}

The journal recorded session_start and turn_end and no file_written. The session's tokens were measured in full — 77,412, verified by hand against the transcript — and it belongs to no task.

No fixture could have surfaced this: every captured payload in scripts/__tests__/fixtures uses the file tools, so every test asserted the path that does work.

Expected

A file written into a task folder is attributed to that task, however the tool chose to write it.

Actual

Bash carries a command string, not a path, so the write is invisible. The same is true of Codex, which writes through apply_patch — this is the same gap reaching a second tool.

Scope

• Whether a written path can be recovered from a shell command at all, and at what cost in false positives. A command mentioning a path is not a command that wrote it, and attributing on a mention would invent a task.
• Whether PostToolUse offers anything better than the command string — a changed-files list, an exit status with paths.
• If neither: state it as a limit rather than closing it. It is already written down in docs/telemetry-limits.md.

Not in scope: guessing. A task attributed from a path that merely appeared in a command is worse than no task.

Relations

Field	Value
parent	#631
related	#691, #690

[blafourcade]

Closed by observation rather than by parsing.

What changed

The hook now records a written path two ways, and says which:

source	How	Cost
tool-stated	the host handed a path in the payload	free, and exact
observed	the task tree changed during the turn	one walk per turn, not per tool call

The command string is never read. A command mentioning a path is not a command that wrote it, and attributing on a mention would invent a task — which is what this ticket asked to avoid.

Why at turn end

A turn ends once per prompt while tools fire dozens of times. Observing there costs one walk per turn instead of one per call, and it preserves the guarantee a test already pinned: a tool call that wrote nothing still shells out to git zero times. That test caught a first attempt that ran the pass on every PostToolUse.

The recorded moment is the end of the turn rather than the write itself. Nothing here observed when a file changed, only that it had — and a task is derived from the path, never from the moment.

Proven live

The same headless session that opened this ticket, re-run against the fix:

{"type":"file_written","at":"2026-08-21T12:31:42Z",
 "path":"aidd_docs/tasks/2026_08/2026_08_21_shell/notes.md","source":"observed"}

task 2026_08/2026_08_21_shell    2026-08-21 to 2026-08-21
  sessions                  1
  tokens                    77,431    71% cache

The model wrote through the shell, and the task reports.

What it also fixes

Task attribution stops being Claude Code's alone. The observed pass reads the repository rather than a payload, so it runs identically on every host the journal already covers — Codex included, whose apply_patch writes were the other half of this gap.

The limit that remains

An observation can, in principle, attribute a file something else on the machine wrote into a task folder during the same turn. Recorded in docs/telemetry-limits.md, and filterable: a consumer that must not risk it reads only source: "tool-stated".