agent-postmortem 0.3.5__tar.gz → 0.4.0__tar.gz

{agent_postmortem-0.3.5 → agent_postmortem-0.4.0}/CHANGELOG.md

@@ -5,6 +5,142 @@ 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.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
+
+- The default (share) output could print an agent's own label. A story sentence starts with
+  a capital, and when an agent's whole story was its interrupt finding, whose title starts
+  with the label, the label was capitalized before the name substitution ran. That
+  substitution matched names case-sensitively, so a workflow label such as `impl:t2` or a
+  subagent description starting with a lowercase letter printed as `Impl:t2` in the
+  STORIES section of `run` and in `stories[].text` of `run --json`. A story clause is now
+  capitalized after its names are replaced, so it reads `Agent-1 interrupted after ...`.
+  `scan`, `run --bug-report`, `rescue` and the hook messages never carried it, and none of
+  the 382 runs on the maintainer's machine hit it. `--local` and `--raw` are unchanged.
+
 ## [0.3.5]
 
 ### Changed

{agent_postmortem-0.3.5 → agent_postmortem-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-postmortem
-Version: 0.3.5
+Version: 0.4.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
@@ -35,7 +35,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 +88,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 | each job's session is read like any session; `watch --session` and `status` pass the job's own state (working, blocked, done, stopped) through as Claude Code records it, and a resumed session hears which of its subagents never returned. Work still in flight inside the job is not modeled |
 | 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 +139,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. 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 +190,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 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 +228,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 +262,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 +272,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
 

{agent_postmortem-0.3.5 → agent_postmortem-0.4.0}/README.md

@@ -12,7 +12,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 +65,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 | each job's session is read like any session; `watch --session` and `status` pass the job's own state (working, blocked, done, stopped) through as Claude Code records it, and a resumed session hears which of its subagents never returned. Work still in flight inside the job is not modeled |
 | 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 +116,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. 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 +167,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 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 +205,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 +239,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 +249,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