Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/coding-agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -558,7 +558,9 @@ Without anything else installed, the signer turns what it saw and then never hea
with `parent` from a bound harness process is a `run.child` record in its parent;
- in system mode, a transcript tailer that stops calling the signer while the run is open, killed, crashed or never
started, from the moment the hook took its token (`tailer_lost`), and a second tailer token for the same run
(`tailer_redelegated`);
(`tailer_redelegated`); in dev mode, a tailer the run's next hook event finds stopped without a word (`tailer_lost`):
the hook then starts a new one where the stopped one got, so the lines written meanwhile are recorded late, not lost
(at most 10 times a run, [limits](limits.md));
- writes after the run ended (`late_activity`, in a run-set), apart from each client's first one, from which it learns
that the run ended (an idle close) and moves to a new run. A hook moves to a new run too when the signer was reset
(its data dir or run token key made anew) and refuses the session's run token: the earlier run, if the store still
Expand Down
2 changes: 1 addition & 1 deletion docs/limits.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ What Tracekit guarantees and doesn't, per deployment, on one page: [guarantees](
| **(1.2)** A coding-agent hook completes each call that got no post-tool event (declined in the harness's own permission prompt, interrupted, or a post-tool payload it couldn't read) as an error when the session ends. That result is the hook's word, not the harness's; a session killed before its end event leaves such calls as `decided_not_completed` gaps instead. | No hook event says that a call was declined or interrupted, and a background sub-agent's call can still run when a turn ends; the session's end is the first point where none can. | Read a `tool.result` error "no PostToolUse came" as "not seen to run". | [coding agents](coding-agents.md#what-the-signer-records-as-a-gap) |
| **(1.3)** A coding-agent hook blocks only tool calls. A prompt, Stop, tool result or session event whose hook fails (the signer unreachable, `tracekit` missing or broken) runs unrecorded, with a hook error in the transcript. Hook commands `tracekit init` wrote before 1.3, and Cursor hooks it wrote up to 1.4.2 (`failClosed` on every event), still turn such a failure into a block. | On a prompt, a block erases it; on Stop, it sends the agent back to work in a loop. Every tool call is still decided before it runs. | Read hook errors in the transcript; run `tracekit init` again after upgrading to get the current commands (`tracekit doctor` flags old ones in dev and system mode as `D-HOOKS-EVENT`, and old system-mode ones also as `D-HOOKS-VENV`). | [plugin](../plugin/README.md#when-a-hook-cant-run) |
| **(1.2)** `concurrent_run` covers only runs bound to a harness process (harness binding, Linux system mode): a second run started from inside the same harness process while another session's run is open there, once both have recorded an event since it registered. SDK and server runs, which run several at once by design, and harnesses without binding get no such check. A run started with `parent` (a sub-agent's) gets none either: the agent can read its session's run token, so a second session can pose as a child, and shows only as a `run.child` record in the parent. Which runs overlap is kept in memory and snapshots: a signer restart with no snapshot since forgets a pending one. | One harness process drives one session at a time; without a binding the signer can't tell a forged second run from a legitimate parallel one, and an older session's run left open and idle is no overlap. | Turn on harness binding for coding agents; pass `parent` for a sub-agent's run; read each `run.child` against the harness's transcripts. | [format v2](format-v2.md#3-events) |
| **(1.2)** A killed transcript tailer is a `tailer_lost` gap only in system mode, once it has made no call (heartbeat or record) for 90 s while the run is open, counted from when the hook took its token, and only while the signer runs: the watch is kept in memory. In dev mode the tailer runs as the agent's user, which may not send heartbeats, so a killed tailer leaves no gap. Heartbeats show that a process holding the run's tailer token is alive, not that it reads the session's real transcript: the agent's user starts the tailer (through sudo) and names its transcript, so it can stop the real one and start one of its own on a file it writes. A second tailer token for the run is a `tailer_redelegated` gap, but a decoy handed the first token (the agent's user can read the hook's memory) isn't. A tailer that keeps its heartbeats but stops reading is caught only by its idle limit. | The signer can't watch the tailer's process or see the transcript; the heartbeat is its only signal, and only an identity the agent doesn't control may send it. | Use [system mode](deploy.md#laptop-system-mode) (init as root with `--v2`) where a killed tailer must show; compare the run's transcript records with the transcript itself where it matters; re-check runs that span a signer restart. | [coding agents](coding-agents.md#what-the-signer-records-as-a-gap) |
| **(1.2)** A killed transcript tailer is a `tailer_lost` gap only in system mode, once it has made no call (heartbeat or record) for 90 s while the run is open, counted from when the hook took its token, and only while the signer runs: the watch is kept in memory. In dev mode the tailer runs as the agent's user, which may not send heartbeats: it holds a lock file for its life instead, and the run's next hook event that finds the lock free records a `tailer_lost` gap and starts a new tailer where the stopped one got, by the run's progress log (at most 10 times a run). One quiet for two hours stops with no gap ("parked" in that log), and the run's next event starts it again. Both files are the agent's user's: it can take the lock itself, so a tailer it stops and replaces that way leaves no gap, and it can write the log (an offset past lines not yet read, then "parked") before it kills the tailer, so the new one skips those lines with no gap, as it could stop a dev-mode tailer unrecorded before. A tailer that stops after the run's last hook event leaves no gap either, and with its log removed a new one reads on from where the hook last saw the transcripts, skipping what the stopped one hadn't read by then. Heartbeats show that a process holding the run's tailer token is alive, not that it reads the session's real transcript: the agent's user starts the tailer (through sudo) and names its transcript, so it can stop the real one and start one of its own on a file it writes. A second tailer token for the run is a `tailer_redelegated` gap, but a decoy handed the first token (the agent's user can read the hook's memory) isn't. A tailer that keeps its heartbeats but stops reading is caught only by its idle limit. | The signer can't watch the tailer's process or see the transcript; the heartbeat is its only signal, and only an identity the agent doesn't control may send it. | Use [system mode](deploy.md#laptop-system-mode) (init as root with `--v2`) where a killed tailer must show; compare the run's transcript records with the transcript itself where it matters; re-check runs that span a signer restart. | [coding agents](coding-agents.md#what-the-signer-records-as-a-gap) |
| **(1.5.3)** The transcript tailer checks the transcript lines it already read on every wake while that check is quick (under 10 ms, a transcript of about 25 MB); a larger one only once a hundred checks' time has passed, at most every 30 s, while the transcript keeps changing (a 400 MB one: about every 16 s; one of 800 MB or more: every 30 s). An edit to an already read line in that window is a `tailer_lost` gap only once the check runs, after the lines written meanwhile; one undone before then, or made just before the run ends while the transcript keeps changing, is none. | Finding an edit anywhere in what was read means reading all of it again: 0.3 s for 816 MB, which on every wake kept the tailer busy for much of a CPU core. | Keep coding-agent sessions short where in-place edits must be caught at once (`/clear` or a new session starts a new transcript); compare the run's transcript records with the transcript itself where it matters. | [coding agents](coding-agents.md#what-the-signer-records-as-a-gap) |
| A session's later run (the signer closed the earlier one after an hour idle, or the session was resumed) records its transcript from where the hook last saw it while the earlier run was open: the lines Claude Code wrote after that run's last hook call (most often the closing text of a turn) can be in both runs. A resumed session is read from where its transcript (Codex's rollout, Gemini CLI's chat recording) ended at SessionStart, so a harness that writes the earlier history only after that hook repeats it in the new run. **(1.5.1)** A Claude Code session that goes on after a SessionEnd with no SessionStart (a message to the session, a usage limit's reset) is read from where its transcripts ended at the new run's first hook: what Claude Code wrote between the SessionEnd and that hook (the new prompt; a first tool call's tool use, then a `reconcile.fabricated` gap) is read by no run, since the earlier run's tailer stopped at the SessionEnd. A call in that window whose hook didn't record it (a killed or timed-out hook) leaves no `reconcile.hook_missing` gap. | The hook can't see how far the earlier run's tailer got; it measures the transcript at its own calls, and a SessionEnd removes the session's state. | Read a session's runs in order (`tracekit view --dev`): each holds what was written while it was open. | [coding agents](coding-agents.md#what-was-asked-and-said) |
| **(1.5.1)** A Claude Code run's decides are compared with the transcript's tool uses without what Claude Code drops or fills in before its hooks: a key the tool doesn't take that the model sent (`run_in_background` on Agent, `persistent` and `timeout` on Monitor, `description` on Write; the first two are the tool's own in other Claude Code builds), Monitor's default `timeout_ms` (300000), a SendMessage `summary` that is its message's first line cut to 200 characters, and a Bash call's free-text `description` (the hook decides a retry that only rewords it with the approved call's, [approve, then retry](approvals.md#approve-then-retry)). A decide that differs from the model's tool use only there is no `reconcile.args_mismatch`, even when the hook, not Claude Code, made the difference; any other key or value is one, including a key a model makes up that isn't listed yet. Which runs are Claude Code's is the agent name the run registered, which the client gives: a run that says it is Claude Code gets the same leeway, for those keys only (no shipped rule reads them). An LLM gateway's record of a Claude Code call holds the arguments as the model sent them, before any of Claude Code's changes, so those changes (a Bash command's leading `cd`, Edit's `replace_all`, a key the tool doesn't take) read as `args_mismatch` there. | Claude Code hands its PreToolUse hook the tool use after its own checks and defaults, and its transcript keeps the model's keys; the list is the changes seen in Claude Code 2.1 transcripts against its hooks' input. | Read an `args_mismatch` on a Claude Code call against the call in its transcript: a key the model added that the tool doesn't take is Claude Code's own change. | [coding agents](coding-agents.md#what-was-asked-and-said) |
Expand Down
Loading
Loading