pan-wizard 3.36.0 → 3.37.0

package/docs/HOOKS.md

@@ -0,0 +1,638 @@
+# PAN Hook System
+
+PAN ships a small set of built-in hooks that enhance the development experience — the ones in the table below, which is the whole set (`ls hooks/*.js`). Hooks are JavaScript files that execute in response to host lifecycle events; they were written for Claude Code and are also registered on Codex, Gemini CLI and Copilot CLI under each host's own event names (see [Hook Runtime Support](#hook-runtime-support)).
+
+## Built-in Hooks
+
+| Hook | Event Type | Purpose |
+|------|-----------|---------|
+| `pan-statusline.js` | `statusLine` | Displays context window usage in the status bar and writes metrics to a bridge file |
+| `pan-context-monitor.js` | `PostToolUse` | Reads the bridge file, or the session transcript when there is none, and injects a note into the agent's context when the host will compact it soon |
+| `pan-check-update.js` | `SessionStart` | Checks for PAN updates in the background, caches result |
+| `pan-guard.js` | `PreToolUse` (Gemini CLI: `BeforeTool`; Copilot CLI: `preToolUse`) | Checks each file a tool call is about to write: a credential in the written text, a direct write to PAN's own state (`state.md`, `findings.jsonl`, the token ledger), a judge agent writing outside the planning tree, a test file the phase in flight does not declare. `hooks.guard: report` (the default) logs each match to `.planning/guard.jsonl`; `enforce` also denies a credential write, a state write and a judge write. |
+| `pan-cost-logger.js` | `SubagentStop` | Appends per-spawn cost records to `.planning/metrics/tokens.jsonl` — consumed by `/pan:cost` |
+| `pan-trace-logger.js` | `SubagentStop` | Appends decision/error/redundancy events to `.planning/optimization/traces/<session>/trace.jsonl` — consumed by `/pan:learn` and `/pan:learn --optimize`. Auto-creates a day-scoped session if no explicit `optimize trace init` is active. |
+| `pan-stop-guard.js` | `Stop` (Gemini CLI: `AfterAgent`; Copilot CLI: `agentStop`) | Blocks a session stop **once** when the auto-advance chain dropped at a phase boundary — autonomy armed on disk (`workflow.auto_advance` or `mode: yolo`), no failure/gaps/blocker recorded in `state.md`, roadmap phases unbuilt — and tells the agent to continue the chain (P-1809/P-1810/P-1812). |
+| `pan-state-reinject.js` | `SessionStart`, matcher `compact` (Claude Code, Codex); `PreCompress` + `AfterTool` (Gemini CLI); `preCompact` + `postToolUse` (Copilot CLI) | After a context compaction, hands the model the phase, plan, status and stop point from `.planning/state.md` as `additionalContext`, so a summarised session resumes the work in flight instead of re-planning it. Silent without a current phase and an unbuilt roadmap phase; never writes into the project. |
+
+### pan-statusline.js
+
+**Event:** `statusLine` (runs continuously to update the Claude Code status bar; Copilot CLI's experimental statusline too. Gemini CLI has no statusline command, so PAN writes none there.)
+
+**What it does:**
+1. Reads the session's context window metrics from the JSON payload Claude Code pipes to stdin
+2. Formats a status line showing usage percentage
+3. Writes metrics to a bridge file at `<os-tmpdir>/pan-hooks-<uid>/claude-ctx-{session_id}.json` — a per-user `0700` subdirectory of the OS temp dir (`os.tmpdir()`), not literally `/tmp` on non-POSIX hosts such as Windows
+
+The bridge file enables the context monitor to read metrics without coupling to the statusline's execution cycle.
+
+When Claude Code's payload carries `rate_limits` (a subscription's 5-hour and 7-day usage windows), the status line also shows them (`5h 42% · 7d 81%`, red from 90%) and writes them, account-wide, to `<os-tmpdir>/pan-hooks-<uid>/claude-limits.json` (`{five_hour, seven_day, timestamp}`, each window `{used_percentage, resets_at}`). `pan-tools cost limits` reads that file, and `/pan:focus-auto` and `/pan:army` stop at `cost.weekly_limit_stop_pct`.
+
+**Bridge file format:**
+```json
+{
+  "session_id": "abc123",
+  "remaining_percentage": 28.5,
+  "used_pct": 89,
+  "total_input_tokens": 143000,
+  "context_window_size": 200000,
+  "model_id": "<model id>",
+  "timestamp": 1708200000
+}
+```
+
+> Note: `used_pct` is rescaled so 80% real usage displays as 100% — it will not equal `100 − remaining_percentage`.
+
+### pan-context-monitor.js
+
+**Event:** `PostToolUse` (runs after every tool call)
+
+**What it does:**
+1. Reads the bridge file written by the statusline hook, or, when there is no fresh bridge, the session transcript (below)
+2. Works out how much room is left before the host compacts the session
+3. If little is left, injects a note as `additionalContext` that the agent sees
+
+**What it measures against.** Claude Code's percentages are against the full model window, but the host compacts earlier. With token counts, from the bridge or the transcript, the room left is measured against the point the host compacts at:
+- **The window:** `CLAUDE_CODE_AUTO_COMPACT_WINDOW`, then `autoCompactWindow` in settings — each settings file in turn, local, then project, then user, gives its per-model value under `modelSettings`, else its value for every model, and the first file that sets one wins — then the model window.
+- **The trigger:** the host compacts about 33K tokens short of that window, whatever its size. That gives the documented ~967K on a native 1M window. On `2026-10-04` a 100K window compacted after a call that measured 67,032 tokens, and not after one that measured 54,371 (harness `context-note-headless`). `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` lowers the trigger to its percentage of the window when that is lower.
+- **No compaction:** with `DISABLE_AUTO_COMPACT=1` or `autoCompactEnabled: false` the host never compacts, so the model window applies.
+
+**What it says — no countdown.** The note carries no figure. Vendor guidance is that a visible remaining-context number makes a model wrap up early and cut corners, and a STOP order after a tool result reads like an injection. So the note:
+- says it comes from the hook, not the user;
+- asks for a checkpoint in `.planning/state.md` (`/pan:pause` writes it), or, in a project with no `.planning/state.md`, "wherever this project records its progress", with no `/pan:pause` hint;
+- says compaction is safe, because PAN restores the planning state afterwards;
+- asks for no shortcuts.
+
+**Thresholds** (of the room before compaction):
+
+| Level | Room left | The note asks for |
+|-------|-----------|---------------|
+| Normal | > 35% | No note |
+| WARNING | <= 35% | A checkpoint at the next natural stopping point, then carry on at full quality |
+| CRITICAL | <= 25% | A checkpoint before the next step, then finish the current task properly |
+
+**Without the status line.** `claude -p` renders no status line (checked `2026-10-04`), and a user may run a status line of their own, so often there is no bridge. Then the monitor reads the transcript the payload names:
+- **The tokens in context:** the newest assistant record's `input_tokens + cache_read_input_tokens + cache_creation_input_tokens`. That record issued the tool call the hook runs after, and the sum is what the status line reports as `context_window.total_input_tokens`. Only the tail of the file is read, and further back only while a large tool result hides the record (at most 4 MB).
+- **After a compaction:** a `compact_boundary` record after the newest call means the context was just rebuilt, so there is no note until the next call measures it.
+- **The window:** from the model id on that record, by the rules of Claude Code's model-config page. On the Anthropic API, the models it lists with a native 1M window get 1M; the hook keeps that list in `modelWindowFor()`. Opus and Sonnet models without a native 1M window have 200K unless their `[1m]` variant is configured (`model` in settings, or `ANTHROPIC_MODEL`), and Haiku has 200K. A context past 200K can only be a 1M window, and that rule comes first. Otherwise `CLAUDE_CODE_DISABLE_1M_CONTEXT=1` means 200K everywhere. On Bedrock, Google Cloud or Foundry a native-1M model's window is unknown, and an unknown window gives no note rather than a guess.
+- **Subagents:** a tool call inside a subagent carries `agent_id`, and its payload still names the main transcript. The monitor measures the subagent's own file and never the main session's bridge: `agent_transcript_path` when the payload carries one, else `<session>/subagents/agent-<id>.jsonl`, or for a subagent the Workflow tool spawned, `<session>/subagents/workflows/<run>/agent-<id>.jsonl`. It debounces each subagent apart.
+- **Codex and Copilot:** PAN does not register the monitor there. Codex has no status-line bridge and its transcript has another shape, and Copilot's documented payload is camelCase (`sessionId`, `transcriptPath`) while the monitor reads only `session_id`, so it could never measure on either; an upgrade removes an older install's entry. In a project that also has the Claude Code install, Copilot runs the `.claude/settings.json` registration, and what Copilot passes that one has not been observed.
+
+A fresh bridge still wins for a main-thread call: it is the status line's own reading. The harness scenario `context-note-headless` checks the fallback in a real `claude -p` session.
+
+**Debounce logic:**
+- First warning fires immediately
+- After a note, the next one comes no sooner than the fifth tool call after it (the four calls in between are silent)
+- Severity escalation (WARNING → CRITICAL) bypasses debounce
+
+**Safety:**
+- Wrapped in try/catch — exits silently on error
+- Never blocks tool execution
+- Stale bridge metrics (>60s old) fall through to the transcript
+- A missing bridge, transcript or model window means no note, never an error
+
+### pan-check-update.js
+
+**Event:** `SessionStart` (registered without a matcher, so it runs at every session start the host reports — including the restart after a compaction — not only at startup)
+
+**What it does:**
+1. Reads the installed PAN version from a `VERSION` file: the project's install first, then the `pan-wizard-core/VERSION` beside the hook's own copy (how a plugin install finds its version), then the global install
+2. Spawns a background process to query npm for the latest version
+3. Caches the result to `~/.claude/cache/pan-update-check.json` (on other runtimes the installer swaps in that runtime's config directory: `~/.gemini`, `~/.codex`, `~/.copilot`)
+4. The statusline reads the cached result for its update badge (on Gemini CLI and Codex, which run no PAN statusline, only `pan-tools version --check` reads it); the hook itself re-queries npm on every SessionStart, in a detached child, so the session is never blocked
+
+The update check runs at each session start and doesn't block tool execution.
+
+### pan-cost-logger.js
+
+**Event:** `SubagentStop` (runs when a Task-spawned sub-agent finishes)
+
+**What it does:**
+1. No-ops unless the project already has a planning tree (`.planning/`, or the tree `PAN_PLANNING_DIR` / `PAN_TRACK` selects). A local install marker alone does not count: a globally-installed hook fires in every repo the user opens, and telemetry fills a planning tree but never creates one
+2. Parses the SubagentStop event payload on stdin and reads whichever of these the host supplies: `agent_type` / `subagent_type`, `agent_id`, `session_id`, `transcript_path`, `agent_transcript_path`, `cwd`, `usage.*`, `model`, `phase`, `command` (the trace logger also reads `exit_code`). Only the first few are reliably present — real payloads observed by PAN carried no `model` or `phase`, and `usage` is absent entirely in headless mode (see the transcript fallback below); the hook backfills `command`/`phase` from the active trace session (and, when the trace session names none — the day-scoped auto-session never does — `phase` from state.md's current phase and `command` from the latest `/pan:*` or `/pan-*` command turn in the parent transcript — or `exec-lean` when that turn is autodev's lean execute unit, whose prompt names the `exec-lean` workflow and no slash command, `LEAN_UNIT_RE`) and derives `model`/`tier` from the transcript
+3. Attributes tokens from the **subagent's own transcript** when the host names one — Claude Code's `transcript_path` is the *parent* session's file, and the subagent's conversation sits beside it as `<parent dir>/<session_id>/subagents/agent-<agent_id>.jsonl` — or, for a subagent the Workflow tool spawned (the native `/pan-*` scripts), one level down under its run: `subagents/workflows/<wf_id>/agent-<agent_id>.jsonl` — so `agent_id` (a documented common input field, present when the hook fires inside a subagent) resolves it; an explicit `agent_transcript_path` wins. Without an id it falls back to **this event's slice** of the parent transcript (the records past a per-transcript cursor) — see the per-agent transcripts note below; an id whose file is absent consumes nothing and records an unmeasured spawn (`token_source: "agent-transcript-missing"`, zeros). Within a slice, one API turn counts once: Claude Code writes a turn as one record per content block, each repeating the turn's `message.id` with a usage snapshot, and the last snapshot wins. Either slice's token axes are plausibility-clamped — above 500M cache-read or 10M output (the ceilings `aggregate()` quarantines on) or 20M input / 100M cache-write (hook-only sanity limits) a value is a session's cumulative usage, dropped to `0` with `clamped: true`. The span is written as measured; the reader quarantines a parent-transcript slice that ran longer than six hours (a row from the agent's own transcript is exempt)
+4. Appends a structured record to `.planning/metrics/tokens.jsonl` with `source: "hook"` to distinguish hook-sourced records from caller-appended ones, unless a [duplicate guard](#duplicate-and-re-fire-guards) drops it. It records nothing for the host's own helper agents (see [Host-internal helper agents](#host-internal-helper-agents))
+5. Silent on any error — never blocks the agent loop
+
+**Record shape** — the row as the hook writes it (values illustrative; the `v: 3` predecessor was a dump against a two-record transcript fixture):
+```json
+{
+  "v": 4,
+  "ts": "2026-08-06T10:21:22.465Z",
+  "agent": "pan-executor",
+  "agent_id": "a15f28b4fab5c68d1",
+  "command": null,
+  "model": "claude-opus-<version>",
+  "tier": "reasoning",
+  "input_tokens": 5120,
+  "output_tokens": 240,
+  "cache_read_tokens": 8000,
+  "cache_write_tokens": 500,
+  "cache_write_1h_tokens": 0,
+  "cache_write_5m_tokens": 500,
+  "cost_usd": null,
+  "duration_ms": 6789,
+  "phase": "07",
+  "session": "abc-123",
+  "source": "hook",
+  "token_source": "agent-transcript",
+  "clamped": false,
+  "event_sig": "15235bf7d229360296873bf0fadeb5f3f79703d4"
+}
+```
+
+Notes on the fields that are not self-evident:
+
+- **`v`** — ledger row schema version, a literal in each hook (`SCHEMA_V`). Rows written before it existed carry no `v`; `cost rebuild` only checks that it is present, as one sign of a hook-written row it may replace. Readers in `pan-wizard-core` take a row field by field rather than switching on the version, so added fields are additive: a mixed-shape ledger aggregates as one. `v: 4` added `agent_id` and the `agent-transcript` token source.
+- **`agent_id`** — the host's per-spawn id, `null` where the host supplies none. It is what makes the agent's own transcript addressable, and it tells two same-type siblings apart without hashing the payload.
+- **`tier`** — derived from `model` (reasoning / mid / fast), `null` for a model the hook can't classify, so `/pan:cost`'s by-tier view is not blind on the hook path.
+- **`cache_write_1h_tokens`** / **`cache_write_5m_tokens`** — the split of `cache_write_tokens` by cache lifetime (one-hour writes bill at a higher rate than five-minute ones), read from the `usage.cache_creation` block of the transcript (or of the payload's `usage` on the fallback path). Present only when the source carried that block; dropped when the write total was clamped.
+- **`long_prompt`** — the tokens (`input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`, `cache_write_1h_tokens`) of the requests in this slice whose prompt, cache reads and writes included, was over `above` (100,000) tokens. A model priced by prompt length bills those requests at its higher rates request by request, and a row sums many requests, so the read side prices this part at the model's long rate and the rest at its base rate. Present only when some request was over the threshold; dropped when any total was clamped. Transcript paths only; `cost rebuild` writes it too.
+- **`duration_ms`** — the span of this event's transcript slice, first record timestamp to last. `null` when either bound is missing, never a fabricated `0`.
+- **`token_source`** — `"agent-transcript"` when the counts came from the subagent's own transcript, `"agent-transcript-missing"` when the host named an agent whose file was not there (an unmeasured spawn: zeros, excluded from `calls` by the reader), `"transcript"` when they came from a slice of the parent session transcript (the fallback when the host names no agent), `"usage-fallback"` when there was no transcript at all and the payload's own `usage` was used instead.
+- **`clamped`** — `true` when a plausibility guard dropped a token value to `0`, on any transcript or fallback path, so a guarded zero is distinguishable from a genuine zero-token run. Until v3.29 only the `usage-fallback` path had a guard, which is why every oversum row in the field carried `clamped: false`. The span is never clamped: `duration_ms` is the measured first-to-last record span, and `cost.cjs` quarantines a parent-slice row whose span exceeds six hours (a row sliced from the agent's own transcript is exempt — it cannot carry anyone else's usage).
+- **`event_sig`** — a SHA-256 of the SubagentStop payload as delivered on stdin, cut to 40 hex characters (the length of the SHA-1 it replaced): this spawn's identity. A dual-registration re-fire is the same bytes and so carries the same signature; a sibling whose payload differs in any field carries a different one. It is what lets the hook count two parallel siblings as two spawns while still suppressing a re-fire of one of them. `null` if the payload could not be serialized. [Duplicate and re-fire guards](#duplicate-and-re-fire-guards) below describes how it is used.
+
+**Integration:** records flow into the existing `cost.cjs` aggregator; they appear in `/pan:cost report` without additional configuration. The `source: "hook"` field marks automatic captures apart from `pan-tools cost append` caller-driven records, which carry no `source`: the aggregator counts both alike, and `cost rebuild` uses the field to find the rows it may replace. During a `/pan:army` campaign every squad agent fires `SubagentStop`, so this same per-spawn stream is what the `/pan:hud` dashboard aggregates into its per-squad telemetry — no army-specific instrumentation exists; the dashboard just reads `tokens.jsonl`.
+
+**P-1805 transcript fallback:** Claude Code in **headless `claude -p` mode** does NOT include `data.usage` in the SubagentStop payload — it only ships `transcript_path`. When `data.usage` is missing/empty, the hook calls `readUsageFromTranscript(transcriptPath, sessionId)` which parses the JSONL transcript line-by-line, filters entries to the payload's `session_id` (the parent session's, so it does not isolate the subagent), and sums `usage` fields across all assistant messages. Falls back to zeros silently if the transcript is unreadable. Since then the order has reversed: `data.usage` proved to be a cumulative session counter, so the transcript is read whenever the payload names one, and `usage` is only the fallback when it names none (`token_source` `usage-fallback`). Since 2026-06 the same transcript pass also captures the assistant **model id** (`message.model`, last-seen wins) whenever the payload lacks one — `resolveRate()` prefix-matches versioned ids onto rate-table families so `/pan:cost` can price hook records. This was surfaced by the wookie autonomous build where every `tokens.jsonl` record showed zero tokens — per-agent cost attribution is now restored.
+
+**Per-agent transcripts:** the transcript fallback above slices the file `transcript_path` names — and on `SubagentStop` that file is the **parent session's** transcript, shared by the main thread and every subagent. Slicing it per event attributed whatever the session had done since the previous stop to whichever subagent happened to stop next; the first stop on a long-lived session (cursor `0`, or a cursor a ledger quarantine had deleted) booked the session's entire history to one row — 7.5 billion cache-read tokens over a ten-day "duration" was observed in a field ledger — and siblings that stopped before the parent grew produced the complementary all-zero rows (63% of that ledger). Claude Code writes each subagent's own conversation beside the parent transcript as `<parent dir>/<session_id>/subagents/agent-<agent_id>.jsonl` (Workflow-tool subagents one level down, under `subagents/workflows/<wf_id>/`), whose first record carries the same `agentId` and `sessionId`; both hooks now derive that path from the payload's `agent_id` (or take an explicit `agent_transcript_path`) and slice *it*, keyed by its own cursor so a resumed agent is charged only its new lines. The parent-slice path remains for hosts that supply no id, now clamped like the fallback. One consequence stated plainly: the parent slice had also been the only place the **main thread's** usage entered the ledger; with per-agent attribution the hooks record subagent spawns and nothing else, which is what `/pan:cost` always claimed to count; `pan-tools cost rebuild` adds one `(main thread)` row per session from its transcript unless run with `--no-main-thread`.
+
+**Runtime support:** Claude Code registers it via settings.json `SubagentStop`. Gemini CLI does not: it has no subagent-completion event, and it hands every hook the main session's transcript rather than the subagent's, so there is nothing to measure. (From v3.4 until `2026-09-23` PAN registered it there under `SubagentStop`, a key Gemini skips with an "Invalid hook event name" warning — it never ran.) Since 2026-06: Codex registers it in `.codex/hooks.json` (Claude-compatible `SubagentStop`) and Copilot CLI in `.github/hooks/pan.json` (`subagentStop`). PAN registers no hooks on OpenCode.
+
+### pan-trace-logger.js
+
+**Event:** `SubagentStop` (runs alongside pan-cost-logger when a Task-spawned sub-agent finishes)
+
+**What it does:**
+1. No-ops unless the project already has a planning tree — same gate as the cost logger, for the same reason
+2. Parses the SubagentStop event payload on stdin, reading the same fields with the same caveats (the `exec-lean` attribution of autodev's lean sessions included) — except that it takes `phase` only from the payload or the trace session, never from state.md (so in the day-scoped auto-session it is `null` unless the payload names one), and names an untyped agent from the host's `agent-<id>.meta.json` — and attributes tokens from this event's transcript slice (it keeps its **own** cursor — the cost logger fires on the same event and the two must not consume each other's slice)
+3. Calls `ensureSessionId()` — creates a day-scoped `sess_auto_YYYYMMDD` trace session if none active, so tracing is always-on with zero setup. A day-scoped auto-session from an earlier day is finalized and rolled over; an explicit session stays sticky while in use but is rolled over the same way once it has ended or gone quiet for a day
+4. Builds these event types:
+   - `decision:agent_completion` — per-agent record with input/output/cache tokens, agent name, phase, and the spawn's tool calls and failed tool results
+   - `redundancy:uncached_heavy_run` — fired when output > 3000 tokens with zero cache hits (signals repeated research the optimizer should flag)
+   - `error:tool_error` — one per distinct failed tool call in the subagent's own transcript (see [Tool-failure capture](#tool-failure-capture))
+5. Appends events to `.planning/optimization/traces/<session>/trace.jsonl`, unless a [duplicate guard](#duplicate-and-re-fire-guards) drops the batch
+6. Silent on error — never blocks the agent loop
+
+**Record shape** — the completion event as the hook writes it, for the same spawn as the cost row above (the two hooks fire on one event, so the `event_sig` matches; values illustrative — in this auto-session the trace logger would write `phase: null` unless the payload named one, since it reads no state.md):
+```json
+{
+  "v": 5,
+  "ts": "2026-08-06T10:21:22.554Z",
+  "session": "sess_auto_20260806",
+  "agent": "pan-executor",
+  "phase": "07",
+  "type": "decision",
+  "category": "agent_completion",
+  "description": "pan-executor completed",
+  "context": {
+    "model": "claude-opus-<version>",
+    "command": null,
+    "agent_id": "a15f28b4fab5c68d1",
+    "input_tokens": 5120,
+    "output_tokens": 240,
+    "cache_read_tokens": 8000,
+    "total_tokens": 5360,
+    "duration_ms": 6789,
+    "exit_code": 0,
+    "token_source": "agent-transcript",
+    "clamped": false,
+    "tool_calls": 14,
+    "tool_errors": 2,
+    "event_sig": "15235bf7d229360296873bf0fadeb5f3f79703d4"
+  },
+  "impact": "trivial",
+  "correction": null,
+  "tokens_wasted": null
+}
+```
+
+`v`, `agent_id`, `duration_ms`, `token_source`, `clamped`, and `event_sig` mean the same as on the cost row (see the field notes there); the trace event nests all of them but `v` under `context` and adds `total_tokens` (input + output). The trace logger resolves the agent transcript, dedupes block records by `message.id` and clamps the token axes exactly as the cost logger does, with its own cursor; a `clamped` completion never fires the `uncached_heavy_run` heuristic, since a guard-produced zero is not a cache miss. The `redundancy:uncached_heavy_run` event in the same batch carries the same `v`/`ts`/`session`/`agent`/`phase` envelope with a smaller `context` (`output_tokens`, `cache_read_tokens`) and `tokens_wasted` set.
+
+`tool_calls` and `tool_errors` count the tool calls and the failed tool results in this spawn's own transcript slice. Both are `null` whenever the slice is not the agent's own, holds no new records, or capture is switched off (see the off switch below). The trace schema `v` is 5 since the evidence loop added them. The cost ledger's rows did not change and stay at 4.
+
+#### Tool-failure capture
+
+The optimiser learns from failures. Until the evidence loop, the only failures it saw were the ones an agent chose to report with `pan-tools optimize trace log`, and across the field projects that was none. Meanwhile about one subagent spawn in four had a failed tool call in its own transcript (measured 2026-09-28). The hook already reads that transcript for tokens, so it records the failed tool results from the same slice:
+
+- **One event per distinct failure.** A failure is identified by its tool, its class and its message with the digits normalised. Each event carries a `count`, so a retry loop repeating one failure produces one event, not a flood. At most 10 events are written per spawn; the completion's `tool_errors` keeps the total. An event's `context` holds `tool`, `error_class`, `exit_code`, `message`, `message_sig` (a short hash of the redacted message with digits normalised), `count`, `command` and `agent_id`.
+- **Classes.** `exit_code` (a Bash or PowerShell command exited non-zero, with `exit_code` set), `not_found`, `permission_denied`, `edit_precondition`, `network_or_timeout`, `user_rejected`, `tool_input`, `other`. For a shell failure the message is the first line after `Exit code <n>` that is not npm/yarn/pnpm's `> script` echo.
+- **Redacted before it is written.** Some projects commit their traces, so the message loses bearer tokens, key/value secrets (`token=`, `password:`, `Authorization:`), known token prefixes (`sk-`, `ghp_`, `xox*-`, `AKIA…`, JWTs), long mixed letter-and-digit runs and URL query strings. The project directory becomes `.` and the home directory `~`. The message is capped at 160 characters.
+- **Only where it is attributable.** Capture runs only on the agent-transcript path. A slice of the shared parent transcript would book the session's failures to whichever spawn stopped, so that path records none. A resumed agent is sliced from its cursor, so earlier failures are not counted twice.
+- **Off switch.** `"execution": { "error_pattern_learning": false }` in `.planning/config.json` turns capture off. The key was shipped as "reserved"; this is its meaning.
+- **Not an agent verdict.** A failed call is often a normal step, such as a TDD red run or a grep with no match. `optimize learn` groups failures per agent into `tool_error_patterns`, ranked by how many spawns they recur in (then by occurrences), with the session count alongside, and the optimiser draws a suggestion only from recurring ones (never a memory entry).
+
+Judge verdicts (verifier, plan checker, reviewer, design checker) reach the trace another way. `pan-tools findings record`, which the workflows run to read the verdict they branch on, logs `verdict_passed`, `verdict_failed` or `verdict_needs_human`, plus `verdict_retry` when the same judge's previous verdict on that phase was a failure. That path works on every runtime, because it is a verb rather than a hook.
+
+**Integration:** events flow into the existing `optimize.cjs` analyzer; they're picked up by `/pan:learn` (one session, or the last n pooled with `--sessions <n>`) and `/pan:learn --optimize` (cumulative stats; `apply` records a report's suggestions for a person to act on). The loop is trace → learn → optimize apply → a person writes the lesson where the agents read it → repeat; nothing in a report reaches an agent on its own.
+
+**P-1805 transcript fallback:** Same fix as `pan-cost-logger.js`, with the same later reversal: the transcript is read whenever the payload names one and `data.usage` is only the fallback when it names none. `readUsageFromTranscript()` now reads the slice described above (the subagent's own transcript when one resolves, else the parent transcript at `data.transcript_path`) and sums `usage` once per API turn, the last snapshot per `message.id`, over the records whose `sessionId` (or `session_id`), where present, matches the payload's. Trace events now carry real token counts during autonomous runs instead of zeros. There is no timing fallback: `data.usage` carries no timing, so whenever no transcript slice is read, `duration_ms` stays `null` rather than a measured or fabricated span.
+
+**Runtime support:** same surface as the cost logger — Claude via settings.json, Codex via `.codex/hooks.json`, Copilot via `.github/hooks/pan.json` (all on their SubagentStop-equivalent events; no-op on hosts that don't fire it). Not registered on Gemini CLI, for the cost logger's reason, or on OpenCode.
+
+Tool-failure capture needs a per-agent transcript, so today it works on Claude Code only. On Copilot CLI both loggers read the camelCase payload the Copilot hooks reference documents: `sessionId`, `transcriptPath`, `agentId`, and `agentName`, which is the agent's configured name and wins over `agentType`, the kind of agent. Before that, every Copilot spawn was booked as `unknown`. Copilot has one session transcript and no per-subagent file, so its rows carry the agent's name, `token_source: agent-transcript-missing`, and no captured failures. This payload shape is documented, not yet observed live; the fixture says so. Codex fires `SubagentStop`, but its per-agent transcript layout is unverified, so no capture is claimed there.
+
+**Why the loggers stay synchronous.** Claude Code's `async: true` would run a hook without blocking the session. The cost and trace loggers keep a read-modify-write cursor file shared by every stop, so overlapping asynchronous runs could lose each other's updates. A lost cursor entry makes the next stop re-read that transcript from the start and count its tokens twice. That is the defect class the per-agent attribution work fixed, so do not add `async` to these two (market item M16, declined 2026-09-28). The Codex registration does not follow this: there the installer gives both loggers `async: true` (`mergeCodexHooksConfig` in `bin/install-lib.cjs`).
+
+### Host-internal helper agents
+
+Claude Code also fires `SubagentStop` for helper agents of its own. One is the compaction summariser; another runs at almost every turn end of an interactive session. Their payload carries an `agent_id`, an **empty** `agent_type`, and an `agent_transcript_path` that the host never writes. A real `/compact` payload captured on Claude Code 2.1.280 is the fixture `tests/fixtures/hooks/subagent-stop-internal-claude.json`.
+
+The host documents `agent_type` as present whenever a hook fires inside a subagent. So a payload that names an agent instance with no type, and whose transcript does not exist, is not a spawn anyone asked for. Both loggers record nothing for it: no cost row, no trace event, and no trace session minted just for it.
+
+Before this rule, each such payload was booked as an `unknown` zero-token spawn: 181 rows in three field projects between 2026-09-17 and 2026-09-28, which skewed the ledger's spawn counts and `optimize learn`'s agent stats. Rows written before the rule stay in the ledgers.
+
+Two cases are deliberately still recorded. A **named** spawn whose file is late or missing keeps its zero-token `agent-transcript-missing` row (the sibling logic below depends on it). A payload that names no agent instance at all keeps the parent-slice path that other hosts use. The rule is `isHostInternalAgent()`, identical in both hooks.
+
+### Duplicate and re-fire guards
+
+One `SubagentStop` can reach the hooks more than once. A project with **both** a global and a local PAN install registers two commands for the event (different paths, so the host runs both) and the two processes share one cursor file — the field's source of ~57% duplicate rows in 2026-07. At the same time PAN's own wave topology spawns **parallel siblings** that share the session transcript, so a legitimate second spawn can look a lot like a re-fire. Both hooks resolve this the same way, with two layers:
+
+1. **The per-transcript seen-event marker** (in the cursor file, bounded by `MAX_SEEN_SIGS` per transcript and `MAX_SEEN_TRANSCRIPTS` overall, FIFO on both axes). An event that consumed no new transcript records is treated as a re-fire only when its `event_sig` was already seen for that transcript; otherwise it is a sibling or a first fire and gets recorded with zero tokens.
+2. **The adjacent-row duplicate guard.** The new row / completion is compared against the **immediately preceding** ledger row (for the trace logger, the file's last `agent_completion`) across every field but `ts` — `event_sig` included. A true re-fire is the same bytes on stdin, so it produces the same row and matches; two siblings the payload can tell apart differ in their signature and both survive.
+
+**What this guarantees, and what it does not.** A re-fire is suppressed while it is still *recognizable*: its signature sits in the marker window, or the row it duplicates sits immediately before it. Nothing further. A re-fire that arrives after its signature has been evicted from the marker window, and that is no longer adjacent to the row it duplicates, **is recorded** — a phantom row. The no-`transcript_path` path is a wider residual still: it has no transcript to key the marker layer by, so an interleaved dual registration there (A, B, A′, B′) leaves both re-fires out of adjacency reach and admits both. Each hook's suite pins the residual rather than asserting it away.
+
+**Why the guard is not wider than that.** It was, briefly: the second layer scanned a tail of recent rows for an identical one and additionally treated a repeated `event_sig` as a re-fire whenever the candidate carried no tokens and no measured duration. Both halves delete real spawns. On the shared session transcript that PAN's own wave topology produces, sequential subagents of one type deliver byte-identical payloads — hence one signature — and identical rows whenever their slices happen to match; a run of five genuine spawns collapsed to two, and when those slices carried real usage the tokens went with them. The invariant the second condition rested on ("an event that consumed a real slice never looks contentless") is false as well: a slice of records carrying neither `usage` nor `timestamp` yields zeros and a `null` duration. Deleting real cost data is strictly worse than a phantom row, so the guard stays adjacent-only and the residual above is documented instead of engineered away. Each hook's suite carries the reproduction as a floor (`grep -n 'no genuine spawn' tests/cost-logger-hook.test.cjs tests/trace-logger.test.cjs`).
+
+**One conditional worth knowing.** Two *concurrent same-type* siblings are admitted as two spawns only if the host puts some per-invocation field on the payload. PAN has confirmed that `agent_type`/`subagent_type` varies between siblings of different type, and that `session_id` and the transcript path are shared with the parent. Claude Code also sends `agent_id`, its documented per-spawn id (present in the captured `tests/fixtures/hooks/subagent-stop-claude.json`), which tells same-type siblings apart. On a host that sends no such id, no field is confirmed to vary between two same-type siblings: their payloads are the same bytes, a new spawn and a re-fire are indistinguishable, and the second is suppressed. See the `eventSignature` comment in either hook for the full evidence trail.
+
+### pan-state-reinject.js (market-ideas M10)
+
+**Runtime support:** Claude Code (`SessionStart` with the `compact` matcher, in `settings.json` and the Claude plugin's `hooks/hooks.json`) and Codex (the same, in `.codex/hooks.json`, synchronous); Gemini CLI (`PreCompress` and `AfterTool` in `settings.json`) and Copilot CLI (`preCompact` and `postToolUse` in `.github/hooks/pan.json`) in two steps, below. Not in the Agent Plugins bundle's Copilot `hooks/hooks.json`. OpenCode runs no hooks; PAN's OpenCode plugin carries the same position into its compaction instead (next section).
+
+**Why `SessionStart` and not `PostCompact`:** both hosts document `PostCompact`, and both discard its output — Claude Code lists it under "no decision control", and Codex's `PostCompact` output schema has no `additionalContext`. What each host does after a compaction is start the session again with `source: "compact"` and honour `hookSpecificOutput.additionalContext` from `SessionStart` hooks that match it. The hook also checks `source` itself, so a registration without the matcher stays silent on every other start.
+
+**Gemini CLI and Copilot CLI (market-ideas M33):** neither starts the session again after a compaction — Gemini's `SessionStart` sources are `startup`, `resume` and `clear`, Copilot's `startup`, `resume` and `new` — and the event each fires before one cannot add context (Gemini's `PreCompress` is advisory, Copilot's `preCompact` notification-only). So the hook runs in two steps:
+
+1. `--mark` on `PreCompress` / `preCompact`: when a phase is in flight, it leaves a marker for this session and project, `state-reinject-<hash>.json`, named by a hash of the two so neither leaks into a file name. It goes in the per-user `0700` directory the stop guard and the context monitor use, `<os-tmpdir>/pan-hooks-<uid>/`, and is written `0600`. When that directory is not provably the user's (a link; on POSIX, another owner or group or other access) the hook writes nothing.
+2. `--inject gemini` on `AfterTool` (every tool, no matcher) / `--inject copilot` on `postToolUse`: if the session has a fresh marker, it consumes it, reads the planning tree again (the position after the compaction, not before it) and returns the block once — `hookSpecificOutput.additionalContext` on Gemini, a top-level `additionalContext` on Copilot. Both hosts append it to that tool's result. With no marker it prints nothing; what every other tool call pays is one Node start and a rename that fails.
+
+A tool result is the first point after a compaction where both hosts take added context, and it also reaches an autonomous `-p` run that never sees another prompt. The marker is renamed before it is read, so two hook runs racing on one tool result cannot both inject; one no session came back for expires after six hours and is swept by the next `--mark`, which removes only this hook's files from the shared directory. In a project with both a Claude and a Copilot install, Copilot also runs Claude's registration of this script, but that one is the `SessionStart` mode, which a Copilot start never matches, so the hook needs none of the other Copilot hooks' deferral to the Claude copy.
+
+Checked live on Copilot CLI 1.0.88 (`2026-10-03`): a manual `/compact` fired `preCompact` and left the marker, and the first tool call after it returned the block, which Copilot appended to the tool result as "Additional guidance from postToolUse hooks" and the model quoted back. Not yet checked live on Gemini CLI, whose test session could not sign in; the Gemini half rests on the v0.61.0 hooks reference and the unit tests.
+
+**What it injects:** a short block — current phase and name, plan `N of M`, status, the `Stopped At` line (or the last activity when there is none), the resume file, and the first unticked roadmap phase — followed by an instruction to re-read `state.md` and the current plan before the next step. Each field is truncated on its own and the block stays under 2,000 characters, well inside the host's 10,000-character limit. Template placeholders (`[X]`) and `None` are not treated as values.
+
+**When it is silent:** no `state.md`, no `Current Phase`, no `roadmap.md`, or every roadmap phase already ticked. It reads the planning tree the payload's `cwd` names (honouring `PAN_PLANNING_DIR`/`PAN_TRACK` like every PAN hook that reads the planning tree) and writes nothing into the project — the field sweep found hooks that scaffolded `.planning/` in projects that never ran PAN, and this one cannot. The Gemini and Copilot marker is the only file it writes, and it lives in the OS temp directory.
+
+**Failure posture:** fail-open — malformed stdin, a payload without a session id (the marker modes), or an unreadable file exits 0 with no output.
+
+
+### The OpenCode plugin: pan-wizard.js (memory optimisation O12)
+
+**Where:** `<opencode config dir>/plugins/pan-wizard.js`, written by a local or global OpenCode install from `pan-wizard-core/opencode/pan-wizard.js`. It is tracked in the manifest and removed on uninstall, which keeps any plugins of your own. It is CommonJS: the `{"type":"commonjs"}` `package.json` PAN writes in the config directory, one level above `plugins/`, marks it as such for a loader that honours the `type` field. It exports one object both OpenCode loaders accept, `{ id: "pan-wizard", server, setup }`: OpenCode 1 calls `server()`, and OpenCode 2, whose loader refuses a plugin without `setup` or `effect`, calls `setup()`, which registers the same hand-off through `ctx.session.hook("compaction", …)` and pushes the block onto the event's `system` parts (or `context`).
+
+**What it does:** OpenCode runs no command hooks, so `pan-state-reinject.js` cannot run there. A plugin's `experimental.session.compacting` hook fires before OpenCode writes a session's continuation summary, and strings pushed onto `output.context` go into that prompt. The plugin pushes the same position the hook gives the other hosts: phase, plan, status, stopping point, and first unbuilt phase. It reads them from the planning tree on disk, honours `PAN_PLANNING_DIR` / `PAN_TRACK`, and asks for `state.md` to be re-read after the compaction.
+
+**Safety:** it is inert without a current phase and an unbuilt roadmap phase. It never writes, and fails open: an error adds nothing and never breaks a compaction.
+
+**Checked on OpenCode `1.18.32` (`2026-10-04`, no model call):**
+- `opencode debug config` lists the plugin, and `live-gate-opencode` repeats that check.
+- An instrumented copy showed OpenCode importing the module, calling `server()` with the project directory, and receiving the compaction hook.
+
+`tests/opencode-plugin.test.cjs` pins what the hook pushes onto `output.context`, calling it directly with a stand-in `output`; no real compaction runs in that test.
+
+### pan-stop-guard.js (P-1809)
+
+**Runtime support:** Claude Code (`Stop` in `settings.json`, and in the Claude plugin's `hooks/hooks.json`), Codex (`Stop` in `.codex/hooks.json`, synchronous — an `async` handler cannot block), Copilot CLI (`agentStop` in `.github/hooks/pan.json`) and Gemini CLI (`AfterAgent` in `settings.json` — Gemini's end-of-turn event, which re-prompts the agent with the reason on a block exactly as Claude's `Stop` does). Codex and Copilot hand the hook `stop_hook_active` like Claude Code (Copilot keeps that one field snake_case inside its camelCase payload), accept the same `{"decision":"block","reason":…}` output, and turn a block into a continuation prompt; Copilot blocks only on that JSON form, not on exit code 2, and ends the turn itself after eight consecutive blocks. Gemini sets `stop_hook_active` only for a continuation the block started directly, not after one that used tools, so there the guard keeps its one-shot promise with a marker per session, project and target phase in the per-user `0700` hook directory; a second stop aimed at the same phase is allowed. Until `2026-09-23` PAN registered it on Gemini under `Stop`, which Gemini skips. Codex and Copilot gained it on `2026-09-26`; the Claude plugin build carried every hook but this one until the same date. Not registered for OpenCode.
+
+**Event:** `Stop` on Claude Code and Codex, `agentStop` on Copilot CLI, `AfterAgent` on Gemini CLI (runs when the main session tries to end its turn)
+
+**What it does:** catches the auto-advance boundary drop mechanically. Field runs showed autonomous chains ending between transition.md's state update and the next-phase Task spawn at a low, nondeterministic rate — a failure prose instructions can reduce but not eliminate. When the session stops, this hook blocks **once**, with a reason instructing the agent to spawn the next phase, if and only if the disk shows the exact drop fingerprint:
+
+1. `.planning/config.json` shows an autonomy signal: `workflow.auto_advance: true` **or** `mode: "yolo"` (P-1810). The guard is **inert** in every other project. The chain's trigger is flag OR config OR yolo; a Stop hook cannot see the `--auto` flag, so every entry hop (discuss/plan/exec-phase) persists the flag into config — arming on config alone left the guard dark on a real flag-driven drop (PanLoop finding 7). transition.md's Route B clears `auto_advance` at the milestone boundary, which disarms that half at the true end of a chain.
+2. `.planning/state.md` shows **no legitimate-stop marker** (gaps found, failed verification, a recorded blocker). This condition is deliberately inverted (P-1812): the guard originally required the status to read "Ready to plan", and one field batch produced four different phrasings for the same boundary — the only run with unbuilt phases was disarmed by wording alone. An unrecognised phrasing now **arms** the guard (fail-safe: at worst one extra continuation, bounded by the one-shot design) instead of disarming it (fail-open: silent truncation). Genuine gaps/verification/blocker stops still pass through.
+3. `.planning/roadmap.md` still has unticked `- [ ] **Phase N:` checklist lines.
+
+**Loop safety:** the host sets `stop_hook_active` on stop attempts that follow a stop-hook block, and the guard always allows those. It fires at most once per stop chain — a user who genuinely wants to stop is delayed by exactly one continuation, never trapped. The block reason tells an agent that was asked to stop to end its turn again, and never to change `workflow.auto_advance`, `workflow.stop_guard` or `mode` to get past the guard: those are the user's settings and every later session reads them. To stop at each phase as a standing choice, change them yourself: Auto-advance in `/pan:settings`, or the escape hatch below, which also disarms a `mode: "yolo"` project.
+
+**Escape hatch:** `workflow.stop_guard: false` in `.planning/config.json` disables the guard without disarming auto-advance.
+
+**Failure posture:** fail-open everywhere — missing `.planning/`, unparseable config/state/roadmap, or malformed stdin all allow the stop silently. A missed catch costs a re-run; a wrong block traps a session, so the guard never blocks on uncertainty.
+
+### pan-guard.js (program A7)
+
+**Runtime support:** Claude Code and Codex (`PreToolUse`, synchronous on Codex: an `async` handler cannot deny), Gemini CLI (`BeforeTool`) and Copilot CLI (`preToolUse`), plus the Claude plugin's `hooks/hooks.json`. Not OpenCode. The command carries `--host <runtime>`, because each host's payload and its way of denying a call differ; a camelCase Copilot payload (`toolName`, `toolArgs`) gets Copilot's deny whatever the flag says, because Copilot also runs the hooks in `.claude/settings.json`. In a project with both installs the `.github` copy steps aside for the Claude registration, as the other hooks do. Live behaviour on Gemini is unproven without a key.
+
+**What it does:** reads the tool call (`tool_name` and `tool_input` on Claude, Codex and Gemini; `toolName` and the JSON string `toolArgs` on Copilot; Codex's `apply_patch` text for the files a patch adds or updates) and checks each file about to be written:
+
+- **secret_write**: the written text holds a credential, a known token shape (`ghp_`, `sk-ant-`, `AKIA`, a private key block …) or a quoted key=value secret (`api_key`, `password`, `client_secret` …) of twelve or more characters, mixing letters and digits, that is not a placeholder (`process.env`, `${VAR}`, `your-…`); unquoted `.env`-style values are not matched;
+- **state_write**: a direct write to `state.md`, `findings.jsonl` or `metrics/tokens.jsonl`, which pan-tools owns (state.md through `pan-tools state init|section|quick-task|apply|patch|update`);
+- **judge_write**: a judge (`pan-verifier`, `pan-reviewer`, `pan-plan-checker`, `pan-design-checker`) writing outside the planning tree. It needs the agent's name in the payload (`agent_type`, which Claude Code sends inside a subagent); where the host sends none, the rule never matches;
+- **undeclared_test_edit**: a test file that no unfinished plan of the phase in flight (`**Current Phase:**` in state.md) lists in `files_modified`.
+
+**Modes** (`hooks.guard` in `.planning/config.json`): `report` (the default) appends each match to `.planning/guard.jsonl` and lets the call run; `enforce` also denies a secret write, a state write and a judge write, with exit 2 and the reason on stderr on Claude Code, Codex and Gemini, or Copilot's `{"permissionDecision": "deny", "permissionDecisionReason": …}` output; `off` disables it. Under `enforce` the test rule still only reports. The state rule denies since program A7b moved every shipped writer of state.md onto pan-tools verbs; a denied agent is told which verb to use.
+
+**Failure posture:** inert outside a PAN project; fail-open on a payload it cannot parse; never fail-open on a matched deny. It writes nothing but its log line.
+
+## Architecture
+
+```text
+Statusline Hook (pan-statusline.js)
+    | writes
+    v
+<os-tmpdir>/pan-hooks-<uid>/claude-ctx-{session_id}.json  (bridge file — not literally /tmp)
+    ^ reads (main thread, while fresh)
+    |
+Context Monitor (pan-context-monitor.js, PostToolUse)  --- reads, without a fresh bridge --->  the session transcript
+    |                                                                                      (a subagent's own file for its calls)
+    | injects
+    v
+additionalContext → Agent sees warning → /pan:pause
+
+SessionStart
+    |
+    v
+Check Update (pan-check-update.js)
+    | writes cache
+    v
+~/.claude/cache/pan-update-check.json
+
+Tool call about to write a file (PreToolUse; Gemini BeforeTool, Copilot preToolUse)
+    |
+    v
+Guard (pan-guard.js)
+    | appends each match → .planning/guard.jsonl; under hooks.guard: enforce, denies a credential, state or judge write
+
+Sub-agent finishes
+    |
+    +--> Cost Logger (pan-cost-logger.js, SubagentStop)
+    |        | appends record
+    |        v
+    |    .planning/metrics/tokens.jsonl ← consumed by /pan:cost
+    |
+    +--> Trace Logger (pan-trace-logger.js, SubagentStop)
+             | appends decision/redundancy/error events
+             v
+         .planning/optimization/traces/<session>/trace.jsonl ← consumed by /pan:learn, /pan:learn --optimize
+
+Session restarts after a compaction (Claude Code / Codex SessionStart, matcher compact)
+    |
+    v
+State Re-inject (pan-state-reinject.js, SessionStart)
+    | reads .planning/state.md + roadmap.md → additionalContext
+
+Before a compaction (Gemini PreCompress, Copilot preCompact)
+    |
+    v
+State Re-inject --mark  → <os-tmpdir>/pan-hooks-<uid>/state-reinject-<session+project hash>.json
+    ^ consumes (once)
+    |
+State Re-inject --inject (Gemini AfterTool, Copilot postToolUse)
+    | reads .planning/state.md + roadmap.md → additionalContext on that tool result
+
+Session stop (Claude Code / Codex Stop, Copilot agentStop, Gemini AfterAgent)
+    |
+    v
+Stop Guard (pan-stop-guard.js, Stop / agentStop / AfterAgent)
+    | at an auto-advance boundary: block once with a continue reason; otherwise allow
+```
+
+The hooks communicate through files rather than being directly coupled:
+- Any hook can fail independently without breaking the others
+- Bridge and log files are inspectable for debugging
+- No shared memory or IPC needed
+
+## Installation
+
+Hooks are automatically installed and registered during `npx pan-wizard`. The block below is Claude Code's `settings.json` with the command paths shortened: a local install (the default) writes project-relative commands such as `node .claude/hooks/pan-check-update.js`, and a `--global` install writes the config directory's absolute path, quoted:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "node ~/.claude/hooks/pan-statusline.js"
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claude/hooks/pan-check-update.js"
+          }
+        ]
+      },
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claude/hooks/pan-state-reinject.js"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claude/hooks/pan-guard.js --host claude"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claude/hooks/pan-context-monitor.js"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claude/hooks/pan-cost-logger.js"
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claude/hooks/pan-trace-logger.js"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claude/hooks/pan-stop-guard.js"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Build Pipeline
+
+Hook sources live alongside the dist directory:
+
+```text
+hooks/
+  pan-statusline.js         # Source
+  pan-context-monitor.js    # Source
+  pan-check-update.js       # Source
+  pan-guard.js              # Source
+  pan-cost-logger.js        # Source
+  pan-trace-logger.js       # Source
+  pan-stop-guard.js         # Source
+  pan-state-reinject.js     # Source
+  dist/                     # Copied output (installed to user's machine)
+    pan-statusline.js
+    pan-context-monitor.js
+    pan-check-update.js
+    pan-guard.js
+    pan-cost-logger.js
+    pan-trace-logger.js
+    pan-stop-guard.js
+    pan-state-reinject.js
+```
+
+Build command:
+```bash
+npm run build:hooks    # Copies hooks from hooks/ to hooks/dist/
+```
+
+The build script (`scripts/build-hooks.js`) simply copies the files named in its `HOOKS_TO_COPY` list (a new hook must be added there) — no bundling or transpilation needed since hooks are pure Node.js with zero dependencies.
+
+## Hook Runtime Support
+
+| Runtime | Hooks supported | Notes |
+|---------|----------------|-------|
+| Claude Code | Yes | Full support via settings.json hook registration, including the state re-injection on `SessionStart` with the `compact` matcher |
+| Copilot CLI | Yes | `.github/hooks/pan.json` (version 1 schema: sessionStart, preToolUse, postToolUse, preCompact, subagentStop, agentStop — the state re-injection's two steps on `preCompact` and `postToolUse`). No context monitor: Copilot's payload names the session `sessionId`, which the monitor never read, so it measured nothing and is no longer registered. Copilot also runs the hooks in the project's `.claude/settings.json`, so in a project with both installs the Copilot copy of each hook steps aside for the Claude registration and each runs once. The pre-tool guard steps aside the same way, and the copy that runs reads Copilot's camelCase payload and denies with Copilot's JSON decision even though its registration says `--host claude`. The state re-injection is the exception: its Claude registration is the `SessionStart` mode a Copilot start never matches, so its Copilot copy runs. Headless (`copilot -p`) Copilot loads repository hooks only in a trusted folder, or with `COPILOT_ALLOW_ALL=true` or `GITHUB_COPILOT_PROMPT_MODE_REPO_HOOKS=true` — see TROUBLESHOOTING |
+| OpenCode | No (one plugin) | PAN registers no hooks there. Its plugin, `.opencode/plugins/pan-wizard.js`, adds PAN's position to the compaction prompt |
+| Gemini CLI | Partly | settings.json, in Gemini's own event names: `SessionStart` runs the update check, `BeforeTool` the guard, `AfterAgent` the stop guard, and `PreCompress` and `AfterTool` the state re-injection's two steps. No context monitor (no Gemini hook payload or setting carries context-window usage, and Gemini has no statusline command) and no cost or trace logger (no subagent-completion event). Until `2026-09-23` PAN wrote Claude's names here — `PostToolUse`, `SubagentStop`, `Stop` — which Gemini skips, with an "Invalid hook event name" warning, whenever it loads the settings |
+| Codex | Yes | `.codex/hooks.json` since 2026-06 (Claude-compatible PascalCase events; loads once the project is trusted). PAN registers these hooks there — update check, the guard on `PreToolUse` (synchronous), cost and trace loggers, the stop guard on `Stop`, and the state re-injection on `SessionStart` with the `compact` matcher; the observers (update check, cost and trace loggers) carry `async: true` (Codex CLI 0.148+) while the stop guard and the re-injection stay synchronous, because an async handler's output is deferred to a later turn and it cannot block. Codex runs a non-managed hook only after you trust it, and records that trust against a hash of the hook, so a new or changed PAN hook is skipped until you review it in `/hooks` — see TROUBLESHOOTING. No context monitor: Codex has no statusline, and its transcript has another shape than the Claude Code records the monitor reads, so it could never warn there; PAN stopped registering it, and an upgrade removes an older install's entry |
+
+PAN registers hooks on Claude Code, Gemini CLI, Codex, and Copilot CLI. It registers none on OpenCode, where one PAN plugin keeps the phase in flight through a compaction.
+
+## Developing Custom Hooks
+
+### Hook Input
+
+Hooks receive JSON on stdin with context about the event:
+
+**PostToolUse:**
+```json
+{
+  "session_id": "abc123",
+  "tool_name": "Bash",
+  "tool_input": { "command": "npm test" }
+}
+```
+
+### Hook Output
+
+Hooks can return JSON on stdout. For `PostToolUse`, the payload is a nested envelope:
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "PAN context note (from the context-monitor hook, not the user): this session's context is filling up."
+  }
+}
+```
+
+The `additionalContext` field (nested under `hookSpecificOutput`) injects text into the agent's conversation — this is the exact shape the context monitor emits to communicate warnings.
+
+### Worked Example: Phase Completion Logger
+
+A simple PostToolUse hook that detects phase completions and logs them.
+
+**1. Create the hook** (`hooks/my-phase-logger.js`):
+
+```javascript
+#!/usr/bin/env node
+'use strict';
+
+try {
+  let input = '';
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', () => {
+    let data; try { data = JSON.parse(input); } catch { process.exit(0); }
+
+    // Only care about Bash tool calls that look like phase-complete
+    if (data.tool_name !== 'Bash') return;
+    const cmd = (data.tool_input && data.tool_input.command) || '';
+    if (!cmd.includes('phase complete')) return;
+
+    // Log to a file (hooks can't write to the agent's output directly)
+    const fs = require('fs');
+    const os = require('os');
+    const path = require('path');
+    const timestamp = new Date().toISOString();
+    fs.appendFileSync(path.join(os.tmpdir(), 'pan-phase-log.txt'),
+      `${timestamp} | Phase completed | ${cmd}\n`
+    );
+
+    // Optionally inject context back to the agent
+    const result = { hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: 'Phase completion logged.' } };
+    process.stdout.write(JSON.stringify(result));
+  });
+} catch (e) {
+  // Silent exit — never break the agent
+  process.exit(0);
+}
+```
+
+**2. Test locally:**
+
+```bash
+echo '{"tool_name":"Bash","tool_input":{"command":"phase complete 3"}}' | node hooks/my-phase-logger.js
+# Should output: {"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"Phase completion logged."}}
+```
+
+**3. Register in settings.json:**
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claude/hooks/my-phase-logger.js"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**4. Copy to install location:**
+
+```bash
+cp hooks/my-phase-logger.js ~/.claude/hooks/
+```
+
+**Debugging tips:**
+- Use `process.stderr.write()` for debug logging (stderr doesn't affect hook output)
+- Check `<os-tmpdir>/pan-hooks-<uid>/` for bridge files if your hook writes there
+- Test with `echo '{}' | node your-hook.js` to verify it handles empty input gracefully
+
+### Best Practices
+
+1. **Always wrap in try/catch** — A broken hook should never break the agent's workflow
+2. **Exit quickly** — Hooks run synchronously before/after tool calls. Keep execution fast.
+3. **No side effects on failure** — If your hook can't read its data, exit silently
+4. **Use the bridge file pattern** — For hooks that need to share data, write to a per-user directory under `os.tmpdir()` (PAN uses `pan-hooks-<uid>`, mode 0700) and read from there
+5. **Test independently** — Hooks are standalone Node.js scripts. Test with `echo '{}' | node your-hook.js`