agent-postmortem 0.3.6__tar.gz → 0.5.0__tar.gz

{agent_postmortem-0.3.6 → agent_postmortem-0.5.0}/CHANGELOG.md

@@ -5,6 +5,226 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0]
+
+0.5 tells a session about the workers it launched, with nothing to arm. Claude Code records a
+background session's state in its job file and tells nobody: a worker sat 8.5 hours on a
+permission prompt while the session that launched it heard nothing. Now that session reads one
+line at its next tool call or prompt, and an idle session is woken for it. This needs the plugin;
+without it, `status` and `scan` print the same reasons when someone runs them.
+
+### Added
+
+- Worker notice. The plugin reads the `claude --bg` in the session's own Bash call and follows
+  that worker from then on: `WORKER night-run (a1b2c3d4) blocked 15m: waiting for a permission
+  approval (approve Entering worktree). A person must approve it: claude attach a1b2c3d4`. A
+  permission prompt, a question, a first prompt never sent, an API error, a failure and a worker
+  idle on a stuck command each have their own line, told once per change at the next tool call
+  or prompt, ahead of anything else the hook has to say. A worker that delivered gets a one-line
+  note with no problem word. The worker's own words are never printed: only the name its launch
+  printed, the short id and a permission's tool. A worker that finishes on its own schedule is
+  told finishing twice, then not until trouble. A first look after an upgrade tells trouble from
+  the last 24 hours and deliveries from the last 10 minutes, and records the rest silently. A
+  launch by a subagent, by another session or by a Bash call that ran in the background is not
+  linked; `status` and `scan` still list those workers.
+- Idle wake. Every Stop starts a watcher (`hook stop-watch`, an `asyncRewake` hook) when the
+  session has a worker or a running command to follow, and it wakes an idle session with the
+  same line. It checks every 20 s, wakes at most once per 5 minutes, leaves as soon as the session
+  acts again, and gives a worker's own report 2 minutes to arrive before it wakes for a delivery.
+  A session is never woken for a line it could not record as told, and any error exits without
+  waking it. It needs Claude Code 2.1.314 or later, a reboot loses it until the next Stop, and
+  `AGENT_POSTMORTEM_WAKE=0` turns it off. A running session starts it after `/reload-plugins` or
+  a restart; the per-call line does not need either.
+- Reason classes in `status` and `scan`. A BLOCKED row says what the session waits for
+  (`waiting for a permission approval`, `waiting for an answer`, `stopped on an API error`, `the
+  reason is not recorded`) and `dispatched by this session` when it did, those rows first. A
+  worker that delivered and waits on a decision has its own DELIVERED row. `--local` adds the
+  tool and the command that helps (`-> claude attach <id>`, `-> claude logs <id>`), `status
+  --json` adds `class` and `mine`, and `--local` adds `label` and `short`. Another session's row
+  older than 3 days folds into one count line.
+- `scan` lists under NEEDS ATTENTION every background session waiting on a person or failed in
+  the last day, read at scan time and whatever `--since` says, the caller's own workers first. One
+  that delivered is not listed. `scan --json` gains `blocked` only when one is listed.
+- Stall checks. A background command whose output has not changed for 30 minutes, or whose output
+  ends in codex's "Reading additional input from stdin..." for 2 minutes, is told once through a
+  COMMAND line at the next tool call or prompt. `status` prints a STALLED row and `scan` lists the
+  session first under NEEDS ATTENTION when its process is alive, its turn ended 30 minutes ago and
+  nothing is set to wake it. The BACKGROUND line counts such a session as stalled, not working. A
+  command under a real `timeout`, a timer by any path to `sleep`, or one carrying the marker
+  `# postmortem: silent-wait` is quiet by design, and only the stdin rule still speaks for it. So
+  is `perl -e 'alarm N; exec @ARGV' ...` or `'alarm shift; exec @ARGV' N ...`, in that exact shape
+  with only exact, literal steps around it. Any other wrapper is told once, in words that say it
+  may be fine: a loose rule would silence the only alarm for a real hang.
+- Codex stdin warning. `hook pre-bash` warns before a background `codex exec` with no stdin
+  redirect runs: codex reads stdin to its end when it is not a terminal, and one review hung
+  26 hours that way.
+- A Stop with a background command still running asks the session to arm a deadline, once per
+  command, wherever the idle watcher would not catch a hang: an interactive session, an older
+  Claude Code or plugin, or a command whose output the watcher cannot read (`> "$LOG"`).
+  A Monitor or a wake that can still fire counts as that deadline.
+- A background session whose subagents and workflows have all ended, with no `status`, `scan`,
+  `run` or `watch` of this tool since, is reminded once at a Stop with nothing else to say to run
+  `status` before reporting done. An interactive session gets none, and
+  `AGENT_POSTMORTEM_WATCH_HINT=0` turns it off.
+- At a session start with nothing else to say, at most once a day, the plugin says so when the
+  `agent-postmortem` on PATH is older than the plugin and its newer hooks stay silent. `hook
+  capabilities` lists `hooks`, and an older CLI is never started for `stop-watch`.
+
+### Changed
+
+- A tool call with nothing new starts about a third faster: 26 ms down to 15 ms for the CLI on Linux,
+  measured in a container. It no longer loads `dataclasses`, `tempfile`, `secrets` or `datetime`,
+  nor OpenSSL where Python has its builtin sha256, and that call uses none of them. Every tool call
+  of every session pays this.
+- `watch` flushes every line. A Monitor reads it through a pipe, where block buffering delivered
+  nothing until the run ended. It also stops quietly when its reader closes the pipe.
+- `watch --session`, `status` and `scan` read a worker's `tempo` before its `state`, which is
+  written only when a turn ends: a worker on a permission prompt reads `state: working, tempo:
+  blocked`, and one given a new prompt reads `state: blocked, tempo: active`.
+- The top-level help names `watch --session` and a background worker's blocked or needs-input
+  state.
+- In a session that is itself a background worker, `status` lists only the rows it launched and
+  ends the count line with `; this session launched <n>, scan lists the rest`. `--json` keeps every
+  row with its owner, and if it launched a worker whose id it never saw, all rows stay.
+
+### Fixed
+
+- `status` no longer keeps a finished subagent as RUNNING. A subagent resumed by a message ends
+  with a notice naming only its task, no tool-use id, and the live read dropped it, so the first
+  notice stood while the transcript grew past it. It now counts when the task is a subagent this
+  session launched.
+- A commit's id is read per segment of the shell command. When an assignment or expansion
+  elsewhere in the command made the whole command unplaced, an agent's printed summary line was
+  dropped and its COMMITS read `?`. Substitutions that spell a commit still read `?`.
+- A Monitor no longer gets the deadline request (Claude Code lists it as a plain shell task, so a
+  Monitor is now known from the session's own Monitor calls), and a deliberately silent wait no
+  longer reads as hung and suggests stopping it.
+- On CI the hook-speed test compares a nothing-new call with a bare start of the same interpreter
+  in interleaved rounds. A shared runner read 152 ms against the 150 ms budget on a correct
+  build; the 150 ms test still runs where CI is unset.
+
+## [0.4.0]
+
+0.4 adds live mode: the tool checks a subagent's "done" the moment it returns, and tells the
+main agent at its next tool call, with nothing to arm. It speaks only for what Claude Code does
+not already say: an interrupt nothing in the session explains, a failure that left files
+changed, and a return its own transcript contradicts. A second `scan` is fast.
+
+### Added
+
+- Per-call live checks. The plugin runs `hook post-tool` after every tool call and
+  `hook prompt-submit` on every prompt. When one of the session's own subagents was interrupted
+  with nothing in the session to explain it, failed after changing files (with the count), or
+  returned while its own last entry is an error or the file its prompt asked for is missing,
+  the agent hears it at its next tool call, or at its next prompt if it sat idle. A call with
+  nothing new prints nothing: 58 ms median through the plugin with its bundled CLI, about
+  130 ms with a CLI on PATH, which the plugin checks at every call.
+  Each ending is told once across every channel: these hooks, `watch --session`, Stop and the
+  resume sentence.
+- `agent-postmortem watch --session [SESSION_ID|PATH]` follows one session, for a Claude Code
+  Monitor on a long background run. It prints a line only for the endings above, passes
+  background-session state changes through, says ENDED when the session exits, and a re-armed
+  watch never repeats a line.
+- `agent-postmortem status [SESSION]` prints one snapshot of a session: its subagents running,
+  returned, interrupted or failed, what an interrupted one changed, returns their own
+  transcripts contradict, how each of its workflows ended, and the background sessions' states
+  as Claude Code records them. With no argument it reads the calling session. A second call
+  reads only what was appended (0.13 to 0.37 s warm on the maintainer's machine). A session
+  that ran shell commands in the background (for example a `codex exec` worker) gets one
+  COMMANDS line counting them by how Claude Code says they ended, with the oldest running
+  one's age, and saying that status does not check their output.
+- `agent-postmortem statusline subagents` is a `subagentStatusLine` command for Claude Code's
+  subagent panel. It rewrites a row only when it has something to add: an interrupt nothing in
+  the session explains, how many paths an interrupted or failed subagent changed, a return its
+  own last entry contradicts, or quiet time over two minutes. `AGENT_POSTMORTEM_STATUSLINE=0`
+  turns it off.
+- `hook agent-launched` runs on every Agent and Task launch. A foreground subagent that returns
+  on an error or without its prompted output file is reported in the same hook. The first
+  background launch of a session says that its subagents are checked when they return and
+  that a Monitor running `watch --session` is an option for a long run; a foreground launch
+  gets no hint, and `AGENT_POSTMORTEM_WATCH_HINT=0` turns it off.
+- `hook session-start` on a resumed session says how many of its own subagents never returned
+  or were interrupted before it stopped, and how many paths they changed, unless a live
+  channel already told it.
+- `watch <RUN_ID>` checks each result the moment it lands. A workflow agent that returns
+  `ok: false`, failed tests, failure counts or a report path that does not exist gets a CLAIM
+  line in place of its OK line, so the main agent hears about it before using the result.
+- `agent-postmortem --version` names the build when it was installed from a git checkout, as
+  `agent-postmortem <version> (<branch> <commit>, <date>)`, with `+dirty` when tracked files
+  were modified. A release prints the plain version, and `hook capabilities` always does.
+- The plugin keeps its bundled CLI at the plugin's version. Before, it installed one only when
+  none was found, so a plugin upgrade left the old CLI in place. Now SessionStart compares the
+  bundled CLI's version with the plugin's and, when they differ, reinstalls the plugin's
+  version in the background, at most once a day per version. A CLI you installed yourself on
+  PATH is never touched, and neither is a bundled CLI that is a link to a CLI outside the
+  plugin's data directory.
+
+### Changed
+
+- A second `scan` is fast. Each run's analysis is cached by the exact size, time and inode of
+  every file it reads, and is read again the moment any of them changes, a path it checked
+  appears or disappears, the config or version changes, or its 72-hour report window closes.
+  A transcript that grew is parsed again on its own, so a live session with hundreds of
+  subagents no longer makes every scan slow: on the maintainer's machine a warm scan takes
+  2.7 s after the largest session grew, where it took 17 to 23 s. A warm scan prints exactly
+  what a cold one prints. `--no-cache` reads everything.
+- `scan --since D` no longer reads runs it is about to drop: a run whose files were all last
+  written more than a day before D is skipped before it is parsed. The result set is the same,
+  except for a run with no readable event at all, which has no start date and can be left out.
+  The totals line says `SINCE D` instead of `ALL TIME`.
+- `scan` says it is working. On a terminal one stderr line counts the runs read and is erased
+  at the end; elsewhere, a scan of more than 50 runs prints one line when it starts.
+- The `missing_artifact` path rule, shared with the live check: a path must start a token,
+  templates (`<case>`, `{id}`, `*`, `$VAR`) are skipped, and a period that ends the sentence
+  right after a path no longer hides it. On the maintainer's 355 runs this removes 12 info
+  findings (placeholders and slashes inside relative paths) and adds 16, all in sessions
+  built to leave that file missing.
+- README: a table maps the live words KILL, FAILED and CLAIM to what `scan` and `run` print.
+
+### Fixed
+
+- A subagent that another subagent launched in the foreground no longer stays RUNNING
+  ("quiet 7d") in `status`, the resume sentence and the per-call check after it returned. Its
+  result lands in its launcher's transcript as a "[Subagent hand-back]" with no notice in the
+  main one; live mode now reads it there, as `run` already did.
+- The share-label fix of 0.3.6 also covers an attempt whose journal entry has no key and an
+  agent id that carries two labels. Such an attempt's interrupt finding is told as the run's
+  story, and its label is now replaced there too.
+- A forked session no longer owns its parent's history when the copied entries carry the fork's
+  own `sessionId` (Claude Code 2.1.305 and later). The hook attachments in the copied block still
+  name the session that wrote them, and that now marks where the fork's own entries begin. On a
+  background session forked from its dispatcher, `status` had counted the dispatcher's subagent
+  as running and `run` had said WORK AT RISK unknown; both now read 0 subagents.
+- `rescue plan` on a session names, under BRIEF FOR A RELAUNCH, only what the rescued subagents
+  wrote. It listed every subagent's files, so a relaunched agent was told to build on other
+  agents' work. A workflow's brief still covers the whole run.
+- A commit run behind `NAME=VALUE`, `env NAME=VALUE` or `mise exec ... --` counts as a commit
+  command, so an agent that committed that way and printed no summary line reads `COMMITS ?`
+  instead of `0`.
+- `scan --since <today>` could print more runs under SINCE than under LAST 7 DAYS. A run whose
+  files carry no timestamp is kept by `--since`; the 7-day line now places it by its newest
+  file write too.
+- `status --local` and `--raw` print real agent ids (the `agent-<id>.jsonl` names), and a blocked
+  or failed background session's own name and working directory. Before, `--no-redact` printed
+  the same aliases as the default, which ends with one line saying what `--local` adds.
+- `scan` marks the caller's own runs: a triage row ends in `(this session)` or
+  `(started by this session)` when `CLAUDE_CODE_SESSION_ID` names that session.
+- A story's count agrees with its noun: `1 Bash command backgrounded`, not `1 Bash commands`.
+- An unattributed interrupt's title says what the transcript logged: `..., cause unattributed,
+  logged as a user interrupt, consistent with a runtime kill`.
+- `status` says how each of the session's workflows ended. Open ones keep their `watch` command,
+  a failed, killed or stopped one points at `run`, and completed ones are one count line, where
+  a long session printed one watch line per workflow.
+- A worktree removed after its run (a merged branch, cleaned up) no longer reads as false
+  alarms: its report files are named as in a directory that no longer exists, WHAT TO DO stops
+  asking to check them, WORK AT RISK names the removed directory instead of a `git status`
+  command for it, and `status` makes no CLAIM of an output there.
+- `rules propose` reads through scan's cache: 101 s on 382 runs before, 1.2 s warm.
+- A no-match error repeats a typed `wf_` or `s_` id and says `agent-postmortem scan --all` lists
+  every run id.
+- A FAILED workflow whose agents all completed says that Claude Code reported the failure and to
+  check what the workflow itself returned.
+
 ## [0.3.6]
 
 ### Fixed

{agent_postmortem-0.3.6 → agent_postmortem-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-postmortem
-Version: 0.3.6
+Version: 0.5.0
 Summary: Reads the Claude Code logs already on your machine and tells you which agent's 'done' you can't trust, and what to run next.
 Project-URL: Homepage, https://github.com/zeyusuntt/agent-postmortem
 Project-URL: Issues, https://github.com/zeyusuntt/agent-postmortem/issues
@@ -23,9 +23,13 @@ Description-Content-Type: text/markdown
 
 # agent-postmortem
 
-Which "done" in your last Claude Code run can't you trust?
+Claude Code records the state. The plugin tells you.
 
-agent-postmortem reads the transcripts Claude Code already wrote under `~/.claude/projects` and, for every Workflow run and every session with subagents, says which agents were killed (in a Workflow, often quietly started over), which never returned, which said "done" while their own result said otherwise, and which files and commits that left at risk. Then it lists at most 3 next steps. No setup, no proxy, no LLM, no network access, and it never changes your files.
+One night a background worker sat 8.5 hours on a permission prompt. Its job file said `blocked` and `approve Entering worktree`, the session that launched it heard nothing, and its agent list showed the worker as idle. With the plugin, that session reads this at its next tool call, and an idle session is woken for it: `WORKER night-run (a1b2c3d4) blocked 15m: waiting for a permission approval (approve Entering worktree). A person must approve it: claude attach a1b2c3d4`.
+
+Nothing has to be armed. The plugin reads the `claude --bg` in the session's own Bash call and follows that worker from then on. A permission prompt, a question, an API error, a failure, or a worker idle on a command that never ends is told once per change, and a worker that delivered gets a one-line note. `AGENT_POSTMORTEM_WAKE=0` keeps a session from being woken.
+
+Which "done" in your last Claude Code run can't you trust? agent-postmortem reads the transcripts Claude Code already wrote under `~/.claude/projects` and, for every Workflow run and every session with subagents, says which agents were killed (in a Workflow, often quietly started over), which never returned, which said "done" while their own result said otherwise, and which files and commits that left at risk. Then it lists at most 3 next steps. No setup, no proxy, no LLM, no network access, and it never changes your files.
 
 On the maintainer's machine (scan 2026-10-27, 0.3.2), 13 of 166 workflow runs launched at least one agent's task a second time, and 10.2 hours went to retries and to attempts that ended without a result.
 
@@ -35,7 +39,7 @@ uvx agent-postmortem scan
 
 That runs the latest release from PyPI with [uv](https://docs.astral.sh/uv/), which fetches Python 3.11 or later if you don't have it; nothing else to install. On a machine with no runs yet it says where it looked and suggests `agent-postmortem demo`.
 
-The command-line tool is local and read-only: Python standard library only, no LLM, no network access, and it never changes your files, transcripts, commits, or branches. (The Claude Code plugin's one network action, installing that tool, is described under Privacy; Limits notes two rare git index modes in which git's own `status` still updates its bookkeeping.) What it covers, below, lists the run shapes it handles and the ones it does not yet. Status: alpha, used so far on the maintainer's own machines. Claude Code only.
+The command-line tool is local and read-only: Python standard library only, no LLM, no network access, and it never changes your files, transcripts, commits, or branches. (The Claude Code plugin's one network action, installing that tool into its own data directory or replacing that copy with the plugin's version, is described under Privacy; Limits notes two rare git index modes in which git's own `status` still updates its bookkeeping.) What it covers, below, lists the run shapes it handles and the ones it does not yet. Status: alpha, used so far on the maintainer's own machines. Claude Code only.
 
 [![CI](https://github.com/zeyusuntt/agent-postmortem/actions/workflows/ci.yml/badge.svg)](https://github.com/zeyusuntt/agent-postmortem/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/agent-postmortem.svg)](https://pypi.org/project/agent-postmortem/)
@@ -88,9 +92,9 @@ Coverage today, checked against the failure reports in Claude Code's issue track
 | Workflow runs: runtime kills and retries | covered | kills logged as `[Request interrupted by user]` with no one at the keyboard, cold same-key retries and the time they cost, failed attempts with their cause (usage limit and reset time, machine sleep, server error), and a workflow the harness reported failed |
 | A "done" you can't trust | covered | an agent that completed while its own result reports failed tests, `ok: false` or blockers (`claim_contradiction`), or while its Codex companion call never started (`codex_unavailable`) |
 | Subagents that never returned | covered | WORK AT RISK says `unknown` instead of `none`, and names them |
-| `claude -p` (headless) | partial | killed and unreturned subagents show; the process's own exit status (for example exit 0 with `result: success` after a kill) is not in the transcript, so the tool cannot see it |
+| `claude -p` (headless) | partial | killed and unreturned subagents show; with the plugin, a foreground subagent that returns on an error or without its prompted output file is reported at once. The process's own exit status (for example exit 0 with `result: success` after a kill) is not in the transcript, so the tool cannot see it |
 | Background subagents (`run_in_background`) | partial | killed and unreturned ones show; a "completed" that arrived while the agent's own background work was still running, or with a tool call that never got a result, is not flagged yet |
-| `claude --bg` sessions | not yet | each job's session is read like any session, but the job's own state (its "done" line, work still in flight) is not |
+| `claude --bg` sessions | partial | with the plugin, the session that launched a worker is told each change at its next tool call or prompt and woken when idle (permission prompt, question, API error, failure, a stuck command, delivered). `status` and `scan` give the same reason when someone runs them, and `watch --session` prints each state change. Not linked: a launch by a subagent, by another session, or by a Bash call that itself ran in the background; `status` and `scan` still list those. "No report past its expected time" is not covered, since nothing records an expected time |
 | Agent teams | not yet | teammates and their idle or blocked states are not modeled |
 | Cross-session messages (`SendMessage`) | not yet | whether a message was delivered is not checked |
 
@@ -139,9 +143,12 @@ Verdict: 0.3 stops guessing. Severity, the WORK AT RISK block, and the run's end
 | `agent-postmortem rescue plan <run-id>` | Print a read-only decision packet: what a killed or failed attempt wrote, its repo state, declared checks, and the steps to take next. Never edits anything or runs a check itself. |
 | `agent-postmortem rescue status <run-id>` | Print what the main session's own transcript shows was run and observed after the run ended. Reports only what it saw, never a confirmation that a check passed. |
 | `agent-postmortem watch <run-id>` | Follow one running workflow: print START, then KILL, FAILED, OK (a result came back), and QUIET as they happen, then DONE or LIMIT. DONE comes the moment the session's own record says the run ended, or after a grace period once every journal key is resolved. Read-only, designed to be a Claude Code Monitor command. |
+| `agent-postmortem watch --session [<session-id>]` | Follow one session while it runs, for a Claude Code Monitor: a line only when a subagent is interrupted with nothing in the session to explain it, fails after changing files, or returns while its own last entry says otherwise, plus background-session state changes. With no id it follows the session you are in. |
+| `agent-postmortem status [<session-id>]` | One snapshot of a session: its subagents running, returned, interrupted or failed, what an interrupted one changed, returns its own transcript contradicts, and the background sessions' states with what each waits for and whether this session dispatched it (a session that is itself a background worker lists only the rows it launched). Reads only what was appended since the last call. |
+| `agent-postmortem statusline subagents` | A `subagentStatusLine` command: adds a fact to a row of Claude Code's subagent panel and leaves every other row as Claude Code draws it. |
 | `agent-postmortem hook <event>` | Claude Code plugin hook entry point; reads hook JSON from stdin. |
 
-`scan`, `run`, `rules`, `trend`, and `rescue` take `--json` and the level flags; `apply` takes the level flags only; `demo` and `watch` take `--json` only; `hook` takes neither. The level flags are `--local` and `--raw` (`--no-redact` is the same as `--raw`); see Privacy.
+`scan`, `run`, `rules`, `trend`, `rescue`, and `status` take `--json` and the level flags; `apply` takes the level flags only; `demo` and `watch` take `--json` only; `statusline` and `hook` take neither. The level flags are `--local` and `--raw` (`--no-redact` is the same as `--raw`); see Privacy.
 
 ## Why
 
@@ -187,7 +194,18 @@ Install the command-line tool first (Quick start above), so the plugin finds it
 /plugin install agent-postmortem@agent-postmortem
 ```
 
-Its hooks shell out to the same CLI, never touch a run directory, and never fail a turn. On `SessionStart` they summarize any run that finished since you last looked. On `Stop` and `StopFailure` they check every subagent and workflow unit spawned so far and print a finding the moment it is detected, not only at session end. On `SessionEnd` they run the read-only tooling checks over the main thread itself. On a `Workflow` launch they register the run immediately, so it is tracked even before its own directory exists, and hand the session the `watch` command to arm as a Monitor. Two skills come with it: `/postmortem` for the verdict and `/rescue` for the bounded rescue protocol.
+Its hooks shell out to the same CLI, never touch a run directory, and never fail a turn. After every tool call and on every prompt they read the job files of the workers this session launched with `claude --bg` and tell each change once, in a `WORKER` line that says the state, the reason and what helps; at each Stop a watcher starts if there is something to follow, and it wakes the session when it has gone idle. It checks every 20 s, wakes at most once per 5 minutes, and leaves when the session acts again. It needs Claude Code 2.1.314 or later, a session already running starts it after `/reload-plugins` or a restart, and `AGENT_POSTMORTEM_WAKE=0` turns it off. After every tool call and on every prompt the hooks also check the session's own subagents: one that was interrupted with nothing in the session to explain it, failed after changing files, or returned while its own transcript contradicts the return is reported to the agent at its next tool call, once. A call with nothing new prints nothing. On `SessionStart` they summarize any run that finished since you last looked, and a resumed session hears which of its own subagents never returned. On `Stop` and `StopFailure` they check every subagent and workflow unit spawned so far and print a finding the moment it is detected, not only at session end. On `SessionEnd` they run the read-only tooling checks over the main thread itself. On a `Workflow` launch they register the run immediately, so it is tracked even before its own directory exists, and hand the session the `watch` command to arm as a Monitor. Two skills come with it: `/postmortem` for the verdict and `/rescue` for the bounded rescue protocol.
+
+For your own view, add the subagent panel command to `~/.claude/settings.json`, at the top level:
+
+```json
+"subagentStatusLine": {
+  "type": "command",
+  "command": "agent-postmortem statusline subagents"
+}
+```
+
+It rewrites a row of the subagent panel only when it has a fact to add (an interrupt nothing explains, how many paths an interrupted or failed subagent changed, a return its own last entry contradicts, quiet over two minutes) and leaves every other row as Claude Code draws it. `agent-postmortem status` prints the same facts for the session you are in.
 
 ## What it detects
 
@@ -214,6 +232,17 @@ The honesty rule: `mislabeled_kill` blames the runtime only when the same key wa
 
 The verdict follows from those severities: `FAILED` when the harness itself reported the workflow failed (or a finding is critical, which no detector produces today), `DEGRADED` when any finding is major, `CLEAN` otherwise, with `(INCOMPLETE)` added when the tool could not read everything. `run`, `demo`, and `scan` exit 3 for `FAILED` and 4 for `INCOMPLETE` without `FAILED`; 3 wins when both apply. They exit 2 when there is nothing to judge: no run matches, or no runs at all under the root, in which case the message says where it looked (`~/.claude/projects` by default), what it reads, and to try `agent-postmortem demo`.
 
+### Live words and report words
+
+`watch`, `status`, the statusline and the hooks speak in three words; `scan` and `run` speak in
+verdicts and detector names. A line to settle in one is the same thing in the other:
+
+| Live line | What it means | In `scan` and `run` |
+|---|---|---|
+| `KILL` | a subagent was interrupted and nothing in the session explains it | `mislabeled_kill`, and `silent_retry` when a workflow restarted it |
+| `FAILED` | an agent failed (usage limit, API error, stall) or the harness failed the workflow | `attempt_failed`; the verdict `FAILED` and `workflow_failed` |
+| `CLAIM` | an agent said it was done, but its own result or its last entry says otherwise | `claim_contradiction`, `missing_artifact`, and `codex_unavailable` when a Codex review never ran |
+
 ### Quieting a detector
 
 A detector you have already acted on, or one that does not apply to how you work, can be quieted without losing its data. List its id in `~/.config/agent-postmortem/config.toml` (or `$XDG_CONFIG_HOME/agent-postmortem/config.toml`):
@@ -237,7 +266,7 @@ The default output is meant for sharing: names become aliases, every path the to
 | local | `--local` | real labels, phase titles, agent ids, and project names | a recognized path is relative to the repository, `~/.../<name>` inside your home directory, otherwise `path-N`; never a recognized absolute path | only with `--evidence` |
 | raw | `--raw` | real | absolute | only with `--evidence` |
 
-At `local` and `raw` the first line of a command's output says so and says not to paste it (an error printed alone on stderr carries no such line; at the default and `local` levels an error never echoes a path or id, and at `raw` it prints as 0.2 did). Hooks and `watch` always print at the default level. An error message never echoes a path or id you typed back at the default level: it says `path-1` or `value-1` and names what it expected.
+At `local` and `raw` the first line of a command's output says so and says not to paste it (an error printed alone on stderr carries no such line; at the default and `local` levels an error never echoes a path or a private id, and at `raw` it prints as 0.2 did). Hooks and `watch` always print at the default level. An error message never echoes a path or id you typed back at the default level: it says `path-1` or `value-1` and names what it expected. The one exception is a public run id (`wf_...`, `s_...`), which is what `scan` prints and is repeated as typed.
 
 An alias is a prefix, 12 or more hex characters, of an HMAC of the real id under a secret created once on your machine. Once assigned, an alias never changes: the same agent has the same alias in `run`, `rescue`, `watch`, and hook messages, the same project in `scan --all` and `run`, and nobody without the secret can turn an alias back into the id or match it to a transcript file. On top of that, the default and `local` levels replace your home directory with `~`, a bare account name with `user`, an email with `email:` plus a 6-character hash, a session id inside text with `uuid:` plus its last 4 hex digits, and any other project slug with `project:` plus a 6-character hash.
 
@@ -247,7 +276,7 @@ Paths inside free text (finding titles, diagnostics, error messages, and at `--l
 
 State lives in `$XDG_STATE_HOME/agent-postmortem/`, or `~/.local/state/agent-postmortem/` if that variable is unset: `state.json` (which findings a session already reported, and the rules the 0.1 `apply` command wrote, now read-only history), plus `secret` and `aliases.json` for the aliases. All three are mode 0600. The secret and the registry are never printed; `trend` shows the applied-rule history from `state.json` at the active level. If a command prints `stable aliases unavailable` on stderr, that output named everything `agent-1`, `agent-2`, and so on instead of by alias; nothing is repaired automatically, because a new secret would change every alias. Remove both `secret` and `aliases.json` to start over with new aliases.
 
-The plugin's one network action happens on `SessionStart` only: when it has not installed a CLI into its own data directory and no `agent-postmortem` on `PATH` passes its protocol check, it installs the CLI from PyPI at the plugin's own version, or from the matching GitHub tag if that install fails, into that data directory, retrying at most once every 24 hours on failure; opt out by setting `AGENT_POSTMORTEM_NO_AUTO_INSTALL=1`, or by installing the CLI yourself first.
+The plugin's one network action happens on `SessionStart` only: it installs the CLI into its own data directory (uv keeps its download cache, and Python if it has to fetch one, in its usual places) from PyPI at the plugin's own version, or from the matching GitHub tag if that install fails. It does so when it has not installed a CLI there and no `agent-postmortem` on `PATH` passes its protocol check, retrying at most once every 24 hours on failure, and when the CLI it installed there reports another version than the plugin's (after a plugin upgrade), in the background and at most once a day per version. A CLI on `PATH`, or a bundled CLI that is a link to one outside that directory, is never replaced. Opt out of both by setting `AGENT_POSTMORTEM_NO_AUTO_INSTALL=1`, or by installing the CLI yourself first.
 
 ## How it was built
 
@@ -255,7 +284,7 @@ It was built across two Claude Code Workflow runs, and those same runs are among
 
 ## Limits
 
-The formats this tool parses are internal to Claude Code, not a published API, and were observed on versions 2.1.251 to 2.1.312; a future version can change them without notice. A few transcript entry types first seen in 2.1.285 to 2.1.310 (`tools-used`, `relocated`, `agent-setting`, `history-suppression`, `continued-in`) are not interpreted yet, so an attempt whose transcript holds one reads as "the tool cannot see all of what was written". Claude Code deletes transcripts older than 30 days by default (the `cleanupPeriodDays` setting), and with them the history `scan`, `trend` and `rules propose` read; raise that setting to keep more. A session's retries are not observable the way a workflow's are: a session has no cache key to compare attempts against, so `silent_retry` never fires on one. Whether a main-session interrupt was a human pressing Escape is not knowable from the transcript, so it is never attributed, only recorded as a limit. Tested on macOS and Linux only. The repository check (`run --observe`, `rescue status`) uses `git status` to inspect paths, with every filter driver switched off and no network transport allowed; in a repository with a sparse index or a split index, git's own `status` can still store a cached tree object or refresh the shared index file's timestamps, without changing tracked content, commits, or branches.
+The formats this tool parses are internal to Claude Code, not a published API, and were observed on versions 2.1.251 to 2.1.318; a future version can change them without notice. A few transcript entry types first seen in 2.1.285 to 2.1.310 (`tools-used`, `relocated`, `agent-setting`, `history-suppression`, `continued-in`) are not interpreted yet, so an attempt whose transcript holds one reads as "the tool cannot see all of what was written". Claude Code deletes transcripts older than 30 days by default (the `cleanupPeriodDays` setting), and with them the history `scan`, `trend` and `rules propose` read; raise that setting to keep more. A session's retries are not observable the way a workflow's are: a session has no cache key to compare attempts against, so `silent_retry` never fires on one. Whether a main-session interrupt was a human pressing Escape is not knowable from the transcript, so it is never attributed, only recorded as a limit. Tested on macOS and Linux only. The repository check (`run --observe`, `rescue status`) uses `git status` to inspect paths, with every filter driver switched off and no network transport allowed; in a repository with a sparse index or a split index, git's own `status` can still store a cached tree object or refresh the shared index file's timestamps, without changing tracked content, commits, or branches.
 
 ## Contributing
 

{agent_postmortem-0.3.6 → agent_postmortem-0.5.0}/README.md

@@ -1,8 +1,12 @@
 # agent-postmortem
 
-Which "done" in your last Claude Code run can't you trust?
+Claude Code records the state. The plugin tells you.
 
-agent-postmortem reads the transcripts Claude Code already wrote under `~/.claude/projects` and, for every Workflow run and every session with subagents, says which agents were killed (in a Workflow, often quietly started over), which never returned, which said "done" while their own result said otherwise, and which files and commits that left at risk. Then it lists at most 3 next steps. No setup, no proxy, no LLM, no network access, and it never changes your files.
+One night a background worker sat 8.5 hours on a permission prompt. Its job file said `blocked` and `approve Entering worktree`, the session that launched it heard nothing, and its agent list showed the worker as idle. With the plugin, that session reads this at its next tool call, and an idle session is woken for it: `WORKER night-run (a1b2c3d4) blocked 15m: waiting for a permission approval (approve Entering worktree). A person must approve it: claude attach a1b2c3d4`.
+
+Nothing has to be armed. The plugin reads the `claude --bg` in the session's own Bash call and follows that worker from then on. A permission prompt, a question, an API error, a failure, or a worker idle on a command that never ends is told once per change, and a worker that delivered gets a one-line note. `AGENT_POSTMORTEM_WAKE=0` keeps a session from being woken.
+
+Which "done" in your last Claude Code run can't you trust? agent-postmortem reads the transcripts Claude Code already wrote under `~/.claude/projects` and, for every Workflow run and every session with subagents, says which agents were killed (in a Workflow, often quietly started over), which never returned, which said "done" while their own result said otherwise, and which files and commits that left at risk. Then it lists at most 3 next steps. No setup, no proxy, no LLM, no network access, and it never changes your files.
 
 On the maintainer's machine (scan 2026-10-27, 0.3.2), 13 of 166 workflow runs launched at least one agent's task a second time, and 10.2 hours went to retries and to attempts that ended without a result.
 
@@ -12,7 +16,7 @@ uvx agent-postmortem scan
 
 That runs the latest release from PyPI with [uv](https://docs.astral.sh/uv/), which fetches Python 3.11 or later if you don't have it; nothing else to install. On a machine with no runs yet it says where it looked and suggests `agent-postmortem demo`.
 
-The command-line tool is local and read-only: Python standard library only, no LLM, no network access, and it never changes your files, transcripts, commits, or branches. (The Claude Code plugin's one network action, installing that tool, is described under Privacy; Limits notes two rare git index modes in which git's own `status` still updates its bookkeeping.) What it covers, below, lists the run shapes it handles and the ones it does not yet. Status: alpha, used so far on the maintainer's own machines. Claude Code only.
+The command-line tool is local and read-only: Python standard library only, no LLM, no network access, and it never changes your files, transcripts, commits, or branches. (The Claude Code plugin's one network action, installing that tool into its own data directory or replacing that copy with the plugin's version, is described under Privacy; Limits notes two rare git index modes in which git's own `status` still updates its bookkeeping.) What it covers, below, lists the run shapes it handles and the ones it does not yet. Status: alpha, used so far on the maintainer's own machines. Claude Code only.
 
 [![CI](https://github.com/zeyusuntt/agent-postmortem/actions/workflows/ci.yml/badge.svg)](https://github.com/zeyusuntt/agent-postmortem/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/agent-postmortem.svg)](https://pypi.org/project/agent-postmortem/)
@@ -65,9 +69,9 @@ Coverage today, checked against the failure reports in Claude Code's issue track
 | Workflow runs: runtime kills and retries | covered | kills logged as `[Request interrupted by user]` with no one at the keyboard, cold same-key retries and the time they cost, failed attempts with their cause (usage limit and reset time, machine sleep, server error), and a workflow the harness reported failed |
 | A "done" you can't trust | covered | an agent that completed while its own result reports failed tests, `ok: false` or blockers (`claim_contradiction`), or while its Codex companion call never started (`codex_unavailable`) |
 | Subagents that never returned | covered | WORK AT RISK says `unknown` instead of `none`, and names them |
-| `claude -p` (headless) | partial | killed and unreturned subagents show; the process's own exit status (for example exit 0 with `result: success` after a kill) is not in the transcript, so the tool cannot see it |
+| `claude -p` (headless) | partial | killed and unreturned subagents show; with the plugin, a foreground subagent that returns on an error or without its prompted output file is reported at once. The process's own exit status (for example exit 0 with `result: success` after a kill) is not in the transcript, so the tool cannot see it |
 | Background subagents (`run_in_background`) | partial | killed and unreturned ones show; a "completed" that arrived while the agent's own background work was still running, or with a tool call that never got a result, is not flagged yet |
-| `claude --bg` sessions | not yet | each job's session is read like any session, but the job's own state (its "done" line, work still in flight) is not |
+| `claude --bg` sessions | partial | with the plugin, the session that launched a worker is told each change at its next tool call or prompt and woken when idle (permission prompt, question, API error, failure, a stuck command, delivered). `status` and `scan` give the same reason when someone runs them, and `watch --session` prints each state change. Not linked: a launch by a subagent, by another session, or by a Bash call that itself ran in the background; `status` and `scan` still list those. "No report past its expected time" is not covered, since nothing records an expected time |
 | Agent teams | not yet | teammates and their idle or blocked states are not modeled |
 | Cross-session messages (`SendMessage`) | not yet | whether a message was delivered is not checked |
 
@@ -116,9 +120,12 @@ Verdict: 0.3 stops guessing. Severity, the WORK AT RISK block, and the run's end
 | `agent-postmortem rescue plan <run-id>` | Print a read-only decision packet: what a killed or failed attempt wrote, its repo state, declared checks, and the steps to take next. Never edits anything or runs a check itself. |
 | `agent-postmortem rescue status <run-id>` | Print what the main session's own transcript shows was run and observed after the run ended. Reports only what it saw, never a confirmation that a check passed. |
 | `agent-postmortem watch <run-id>` | Follow one running workflow: print START, then KILL, FAILED, OK (a result came back), and QUIET as they happen, then DONE or LIMIT. DONE comes the moment the session's own record says the run ended, or after a grace period once every journal key is resolved. Read-only, designed to be a Claude Code Monitor command. |
+| `agent-postmortem watch --session [<session-id>]` | Follow one session while it runs, for a Claude Code Monitor: a line only when a subagent is interrupted with nothing in the session to explain it, fails after changing files, or returns while its own last entry says otherwise, plus background-session state changes. With no id it follows the session you are in. |
+| `agent-postmortem status [<session-id>]` | One snapshot of a session: its subagents running, returned, interrupted or failed, what an interrupted one changed, returns its own transcript contradicts, and the background sessions' states with what each waits for and whether this session dispatched it (a session that is itself a background worker lists only the rows it launched). Reads only what was appended since the last call. |
+| `agent-postmortem statusline subagents` | A `subagentStatusLine` command: adds a fact to a row of Claude Code's subagent panel and leaves every other row as Claude Code draws it. |
 | `agent-postmortem hook <event>` | Claude Code plugin hook entry point; reads hook JSON from stdin. |
 
-`scan`, `run`, `rules`, `trend`, and `rescue` take `--json` and the level flags; `apply` takes the level flags only; `demo` and `watch` take `--json` only; `hook` takes neither. The level flags are `--local` and `--raw` (`--no-redact` is the same as `--raw`); see Privacy.
+`scan`, `run`, `rules`, `trend`, `rescue`, and `status` take `--json` and the level flags; `apply` takes the level flags only; `demo` and `watch` take `--json` only; `statusline` and `hook` take neither. The level flags are `--local` and `--raw` (`--no-redact` is the same as `--raw`); see Privacy.
 
 ## Why
 
@@ -164,7 +171,18 @@ Install the command-line tool first (Quick start above), so the plugin finds it
 /plugin install agent-postmortem@agent-postmortem
 ```
 
-Its hooks shell out to the same CLI, never touch a run directory, and never fail a turn. On `SessionStart` they summarize any run that finished since you last looked. On `Stop` and `StopFailure` they check every subagent and workflow unit spawned so far and print a finding the moment it is detected, not only at session end. On `SessionEnd` they run the read-only tooling checks over the main thread itself. On a `Workflow` launch they register the run immediately, so it is tracked even before its own directory exists, and hand the session the `watch` command to arm as a Monitor. Two skills come with it: `/postmortem` for the verdict and `/rescue` for the bounded rescue protocol.
+Its hooks shell out to the same CLI, never touch a run directory, and never fail a turn. After every tool call and on every prompt they read the job files of the workers this session launched with `claude --bg` and tell each change once, in a `WORKER` line that says the state, the reason and what helps; at each Stop a watcher starts if there is something to follow, and it wakes the session when it has gone idle. It checks every 20 s, wakes at most once per 5 minutes, and leaves when the session acts again. It needs Claude Code 2.1.314 or later, a session already running starts it after `/reload-plugins` or a restart, and `AGENT_POSTMORTEM_WAKE=0` turns it off. After every tool call and on every prompt the hooks also check the session's own subagents: one that was interrupted with nothing in the session to explain it, failed after changing files, or returned while its own transcript contradicts the return is reported to the agent at its next tool call, once. A call with nothing new prints nothing. On `SessionStart` they summarize any run that finished since you last looked, and a resumed session hears which of its own subagents never returned. On `Stop` and `StopFailure` they check every subagent and workflow unit spawned so far and print a finding the moment it is detected, not only at session end. On `SessionEnd` they run the read-only tooling checks over the main thread itself. On a `Workflow` launch they register the run immediately, so it is tracked even before its own directory exists, and hand the session the `watch` command to arm as a Monitor. Two skills come with it: `/postmortem` for the verdict and `/rescue` for the bounded rescue protocol.
+
+For your own view, add the subagent panel command to `~/.claude/settings.json`, at the top level:
+
+```json
+"subagentStatusLine": {
+  "type": "command",
+  "command": "agent-postmortem statusline subagents"
+}
+```
+
+It rewrites a row of the subagent panel only when it has a fact to add (an interrupt nothing explains, how many paths an interrupted or failed subagent changed, a return its own last entry contradicts, quiet over two minutes) and leaves every other row as Claude Code draws it. `agent-postmortem status` prints the same facts for the session you are in.
 
 ## What it detects
 
@@ -191,6 +209,17 @@ The honesty rule: `mislabeled_kill` blames the runtime only when the same key wa
 
 The verdict follows from those severities: `FAILED` when the harness itself reported the workflow failed (or a finding is critical, which no detector produces today), `DEGRADED` when any finding is major, `CLEAN` otherwise, with `(INCOMPLETE)` added when the tool could not read everything. `run`, `demo`, and `scan` exit 3 for `FAILED` and 4 for `INCOMPLETE` without `FAILED`; 3 wins when both apply. They exit 2 when there is nothing to judge: no run matches, or no runs at all under the root, in which case the message says where it looked (`~/.claude/projects` by default), what it reads, and to try `agent-postmortem demo`.
 
+### Live words and report words
+
+`watch`, `status`, the statusline and the hooks speak in three words; `scan` and `run` speak in
+verdicts and detector names. A line to settle in one is the same thing in the other:
+
+| Live line | What it means | In `scan` and `run` |
+|---|---|---|
+| `KILL` | a subagent was interrupted and nothing in the session explains it | `mislabeled_kill`, and `silent_retry` when a workflow restarted it |
+| `FAILED` | an agent failed (usage limit, API error, stall) or the harness failed the workflow | `attempt_failed`; the verdict `FAILED` and `workflow_failed` |
+| `CLAIM` | an agent said it was done, but its own result or its last entry says otherwise | `claim_contradiction`, `missing_artifact`, and `codex_unavailable` when a Codex review never ran |
+
 ### Quieting a detector
 
 A detector you have already acted on, or one that does not apply to how you work, can be quieted without losing its data. List its id in `~/.config/agent-postmortem/config.toml` (or `$XDG_CONFIG_HOME/agent-postmortem/config.toml`):
@@ -214,7 +243,7 @@ The default output is meant for sharing: names become aliases, every path the to
 | local | `--local` | real labels, phase titles, agent ids, and project names | a recognized path is relative to the repository, `~/.../<name>` inside your home directory, otherwise `path-N`; never a recognized absolute path | only with `--evidence` |
 | raw | `--raw` | real | absolute | only with `--evidence` |
 
-At `local` and `raw` the first line of a command's output says so and says not to paste it (an error printed alone on stderr carries no such line; at the default and `local` levels an error never echoes a path or id, and at `raw` it prints as 0.2 did). Hooks and `watch` always print at the default level. An error message never echoes a path or id you typed back at the default level: it says `path-1` or `value-1` and names what it expected.
+At `local` and `raw` the first line of a command's output says so and says not to paste it (an error printed alone on stderr carries no such line; at the default and `local` levels an error never echoes a path or a private id, and at `raw` it prints as 0.2 did). Hooks and `watch` always print at the default level. An error message never echoes a path or id you typed back at the default level: it says `path-1` or `value-1` and names what it expected. The one exception is a public run id (`wf_...`, `s_...`), which is what `scan` prints and is repeated as typed.
 
 An alias is a prefix, 12 or more hex characters, of an HMAC of the real id under a secret created once on your machine. Once assigned, an alias never changes: the same agent has the same alias in `run`, `rescue`, `watch`, and hook messages, the same project in `scan --all` and `run`, and nobody without the secret can turn an alias back into the id or match it to a transcript file. On top of that, the default and `local` levels replace your home directory with `~`, a bare account name with `user`, an email with `email:` plus a 6-character hash, a session id inside text with `uuid:` plus its last 4 hex digits, and any other project slug with `project:` plus a 6-character hash.
 
@@ -224,7 +253,7 @@ Paths inside free text (finding titles, diagnostics, error messages, and at `--l
 
 State lives in `$XDG_STATE_HOME/agent-postmortem/`, or `~/.local/state/agent-postmortem/` if that variable is unset: `state.json` (which findings a session already reported, and the rules the 0.1 `apply` command wrote, now read-only history), plus `secret` and `aliases.json` for the aliases. All three are mode 0600. The secret and the registry are never printed; `trend` shows the applied-rule history from `state.json` at the active level. If a command prints `stable aliases unavailable` on stderr, that output named everything `agent-1`, `agent-2`, and so on instead of by alias; nothing is repaired automatically, because a new secret would change every alias. Remove both `secret` and `aliases.json` to start over with new aliases.
 
-The plugin's one network action happens on `SessionStart` only: when it has not installed a CLI into its own data directory and no `agent-postmortem` on `PATH` passes its protocol check, it installs the CLI from PyPI at the plugin's own version, or from the matching GitHub tag if that install fails, into that data directory, retrying at most once every 24 hours on failure; opt out by setting `AGENT_POSTMORTEM_NO_AUTO_INSTALL=1`, or by installing the CLI yourself first.
+The plugin's one network action happens on `SessionStart` only: it installs the CLI into its own data directory (uv keeps its download cache, and Python if it has to fetch one, in its usual places) from PyPI at the plugin's own version, or from the matching GitHub tag if that install fails. It does so when it has not installed a CLI there and no `agent-postmortem` on `PATH` passes its protocol check, retrying at most once every 24 hours on failure, and when the CLI it installed there reports another version than the plugin's (after a plugin upgrade), in the background and at most once a day per version. A CLI on `PATH`, or a bundled CLI that is a link to one outside that directory, is never replaced. Opt out of both by setting `AGENT_POSTMORTEM_NO_AUTO_INSTALL=1`, or by installing the CLI yourself first.
 
 ## How it was built
 
@@ -232,7 +261,7 @@ It was built across two Claude Code Workflow runs, and those same runs are among
 
 ## Limits
 
-The formats this tool parses are internal to Claude Code, not a published API, and were observed on versions 2.1.251 to 2.1.312; a future version can change them without notice. A few transcript entry types first seen in 2.1.285 to 2.1.310 (`tools-used`, `relocated`, `agent-setting`, `history-suppression`, `continued-in`) are not interpreted yet, so an attempt whose transcript holds one reads as "the tool cannot see all of what was written". Claude Code deletes transcripts older than 30 days by default (the `cleanupPeriodDays` setting), and with them the history `scan`, `trend` and `rules propose` read; raise that setting to keep more. A session's retries are not observable the way a workflow's are: a session has no cache key to compare attempts against, so `silent_retry` never fires on one. Whether a main-session interrupt was a human pressing Escape is not knowable from the transcript, so it is never attributed, only recorded as a limit. Tested on macOS and Linux only. The repository check (`run --observe`, `rescue status`) uses `git status` to inspect paths, with every filter driver switched off and no network transport allowed; in a repository with a sparse index or a split index, git's own `status` can still store a cached tree object or refresh the shared index file's timestamps, without changing tracked content, commits, or branches.
+The formats this tool parses are internal to Claude Code, not a published API, and were observed on versions 2.1.251 to 2.1.318; a future version can change them without notice. A few transcript entry types first seen in 2.1.285 to 2.1.310 (`tools-used`, `relocated`, `agent-setting`, `history-suppression`, `continued-in`) are not interpreted yet, so an attempt whose transcript holds one reads as "the tool cannot see all of what was written". Claude Code deletes transcripts older than 30 days by default (the `cleanupPeriodDays` setting), and with them the history `scan`, `trend` and `rules propose` read; raise that setting to keep more. A session's retries are not observable the way a workflow's are: a session has no cache key to compare attempts against, so `silent_retry` never fires on one. Whether a main-session interrupt was a human pressing Escape is not knowable from the transcript, so it is never attributed, only recorded as a limit. Tested on macOS and Linux only. The repository check (`run --observe`, `rescue status`) uses `git status` to inspect paths, with every filter driver switched off and no network transport allowed; in a repository with a sparse index or a split index, git's own `status` can still store a cached tree object or refresh the shared index file's timestamps, without changing tracked content, commits, or branches.
 
 ## Contributing