Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
docs(mcp): describe hook records and stop naming the magus monitor
Jack Rudenko3d32b9d20a32
diff --git a/README.md b/README.mdindex 56c93f2c..28f762ee 100644--- a/README.md+++ b/README.md@@ -343,7 +343,7 @@ claudish [OPTIONS] <claude-args...>### Environment Variables-Claudish automatically loads `.env` from the current directory at startup. For the full list, see [Settings Reference](docs/settings-reference.md).+Claudish loads provider API keys and model settings (`CLAUDISH_MODEL`, `CLAUDISH_MODEL_*`) from `.env` in the current directory at startup; any other variable there is ignored, so set the rest in your shell. For the full list, see [Settings Reference](docs/settings-reference.md).#### API Keys (at least one required for cloud models)@@ -482,7 +482,7 @@ Claudish uses a two-scope configuration system:|------|-------|---------|| `~/.claudish/config.json` | Global | Profiles, telemetry, routing rules (shared across projects) || `.claudish.json` | Local | Project-specific profiles and routing rules (overrides global) |-| `.env` | Local | Environment variables (auto-loaded at startup) |+| `.env` | Local | Provider API keys and model settings (auto-loaded at startup) |**Profile configuration** (`~/.claudish/config.json`):diff --git a/ai-docs/architecture/mcp-sessions.md b/ai-docs/architecture/mcp-sessions.mdindex b517cd5b..5261cf74 100644--- a/ai-docs/architecture/mcp-sessions.md+++ b/ai-docs/architecture/mcp-sessions.md@@ -242,9 +242,11 @@ server's own `hostPid`.### `meta.json` — the final record, and `events.jsonl`'s assistant lines`meta.json` is written once, at the terminal transition and before the pane is reaped, through-`toMetaRecord`. It keeps every 10.4.0 key under its 10.4.0 name, because the monitor reads-`status` (an unknown value reads as `failed`), `terminalReason`, `elapsedSeconds`,-`turnsCompleted`, `toolCallCount`, `costUsd` and `exitCode`:+`toMetaRecord`. Its existence is the run's end record: the magus `claudish-usage` skill and the+multimodel `team` and `delegate` commands wait, bounded, for this file to appear. It keeps every+10.4.0 key under its 10.4.0 name, because the monitor reads `status` (an unknown value reads as+`failed`), `terminalReason`, `elapsedSeconds`, `turnsCompleted`, `toolCallCount`, `costUsd` and+`exitCode`:- `status`: COMPLETED → `completed`; FAILED and EMPTY → `failed`; CANCELLED → `cancelled`;TIMEOUT → `timeout`;@@ -261,6 +263,22 @@ server's own `hostPid`.`events.jsonl` carries one `assistant` line per main-chain message id, first-seen order, each once,which is exactly what the monitor counts as replies (RB5).+### Hook records in an MCP session++When hooks are loaded ([`hooks.md`](hooks.md)), an MCP session's records gain these, all+additive:++- `<sessionDir>/hook-inbox.jsonl`, created (0600) for **every** child before it spawns and named in+ the child's `CLAUDISH_HOOK_INBOX`. The child's proxy appends `stop`, `inject`, `annotate`, `end` and+ `capped` lines; the server reads it at each settle and deletes it at reap.+- `events.jsonl` anomaly keys: `hook_injection_delivered`, `hook_injection_dropped:<reason>`,+ `hook_injection_not_read`, `hook_hold_error`, `hook_hold_watchdog`.+- `get_diagnostics` adds `pendingHookInputs`, and its `phase` can read `SETTLING` while+ `sessionIdle` hooks run. The row `state` stays `RUNNING`, with activity `hook`, which `sessionEventFor`+ reports as `running`, never `tool_executing`. `pendingInputs` still counts caller input only.+- A one-shot session that a hook extends stays `RUNNING` across its turn chain, and its output grows+ turn by turn: each chain turn's answer is appended when the turn is recorded, before any hook runs.+### Diagnostics are captured unconditionally, and reachable from the APITwo sessions once ran 900 s of genuine billed work — 241 assistant messages, ~94 k outputdiff --git a/ai-docs/architecture/pane-session.md b/ai-docs/architecture/pane-session.mdindex bba9018d..e64f2eff 100644--- a/ai-docs/architecture/pane-session.md+++ b/ai-docs/architecture/pane-session.md@@ -613,8 +613,10 @@ run the user's profile.- **The snapshot.** The owner passes its environment as JSON in `CLAUDISH_PANE_ENV` — inherited,never written to disk, the same exposure class as the variables themselves. The child claudish- (`pane/child-env.ts`, imported first by `index.ts`) sets every snapshot key, removes every key the- snapshot lacks except the shell-managed ones, then deletes `CLAUDISH_PANE_ENV`. A profile that+ (`pane/child-env.ts`, imported by `index.ts` right after `launch-guard.ts`) sets every snapshot+ key, removes every key the snapshot lacks except the shell-managed ones, then deletes+ `CLAUDISH_PANE_ENV`. The markers and the snapshot are control variables: no env file in the+ child's cwd can set them (`launch-env.ts`, `ai-docs/architecture/hooks.md`). A profile thatre-exports `OPENAI_API_KEY` or `CLAUDE_CONFIG_DIR` is undone. On Linux a snapshot over 131,000bytes fails the start (`MAX_ARG_STRLEN` is 131,072 per string).- **The shim.** `SHELL=<ctl>/sh-shim`, set after the snapshot is taken: `[ "$1" = -l ] && shift;@@ -631,7 +633,9 @@ run the user's profile.`CLAUDISH_UPSTREAM_ERROR_LOG`, and `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1` when the owner leftit unset (it suppresses side calls billed on the routed model), with `CLAUDE_CODE_NATIVE_CURSOR=1`under the same rule (traffic off makes Claude self-draw a reverse-video cursor on the faint- placeholder, which the input gate reads as `box_not_empty`).+ placeholder, which the input gate reads as `box_not_empty`). For every child, also+ `CLAUDISH_HOOK_INBOX` (the owner-created hook inbox) and `CLAUDISH_HOOK_SESSION`+ (`{"kind","id","role"}`); see [`hooks.md`](hooks.md).- **`MAGMUX_*` survives in the child.** magmux injects `MAGMUX_SOCK` into the pane; it is excludedfrom the snapshot and kept when the snapshot is applied, so the child knows it is already inside amultiplexer and never wraps itself in a second magmux.@@ -642,8 +646,10 @@ run the user's profile.argv, and any positional token or `--`, by claudish's own value-consumption rule). After`parseArgs` the child asserts it is interactive, not a team run, with no positional prompt;otherwise it prints `claudish: pane child refused: <reason>` and exits 64 (FAILED `child_exited`).-- `CLAUDISH_PANE_ENV` and `CLAUDISH_PANE_CWD` (`PANE_LAUNCH_VARS`) are deleted from Claude Code's- own environment. `CLAUDISH_PANE_CHILD` is KEPT there; the next section says why.+- `CLAUDISH_PANE_CHILD`, `CLAUDISH_PANE_CWD`, `CLAUDISH_HOOK_INBOX` and `CLAUDISH_HOOK_SESSION`+ survive the snapshot. `CLAUDISH_PANE_ENV`, `CLAUDISH_PANE_CWD` and the two hook markers+ (`PANE_LAUNCH_VARS`) are deleted from Claude Code's own environment, so the model never sees the+ inbox path. `CLAUDISH_PANE_CHILD` is KEPT there; the next section says why.**One level of nesting.** A `create_session` child (gpt-6.1-sol) once called the claudish MCP`create_session` itself; that session (#969aa2) failed `prompt_not_accepted`. It was a claudish MCP@@ -923,8 +929,9 @@ terminals absorb, so a late pane `exit` cannot overturn a CANCELLED or TIMEOUT.| phase | wire state | leaves by ||---|---|---|| BOOTING | STARTING | gate `ready` (IDLE, or ADMITTING with a queued prompt); boot dialog, blocked screen, 90 s → FAILED; binding check failed → FAILED `pane_lost` |-| ADMITTING | STARTING for the prompt the session was created with, else RUNNING | gate `ok` with history evidence, or the witness → RUNNING; a stop row (vim mode, boot dialog, `bad_request`, an unexpected code), a panel command, or 30 s → FAILED `prompt_not_accepted` / `first_run_dialog` (created prompt) or back to IDLE with `send_not_accepted` (a later send) |-| RUNNING | RUNNING | question → QUESTION; permission → PERMISSION; `decide` → IDLE (`continue`) or COMPLETED / EMPTY / FAILED |+| ADMITTING | STARTING for the prompt the session was created with, else RUNNING | gate `ok` with history evidence, or the witness → RUNNING; a stop row (vim mode, boot dialog, `bad_request`, an unexpected code), a panel command, or 30 s → FAILED `prompt_not_accepted` / `first_run_dialog` (created prompt) or back to IDLE with `send_not_accepted` (a later send); an unaccepted hook injection in a one-shot session → SETTLING (`hook_admit_abandoned`), which concludes on the chain so far |+| RUNNING | RUNNING | question → QUESTION; permission → PERMISSION; `decide` → IDLE (`continue`) or COMPLETED / EMPTY / FAILED; with a hook binding and idle work, `settle_hold` → SETTLING |+| SETTLING | RUNNING (activity `hook`) | only with a hook binding: the settled turn is recorded and `sessionIdle` runs. `hold_inject` → IDLE (an injection is admitted next); `hold_rewake` → RUNNING (same turn); `turn_continue` → IDLE; the verdict → COMPLETED / EMPTY / FAILED. See [`hooks.md`](hooks.md) || IDLE | AWAITING_INPUT | queued send → ADMITTING; background re-wake → RUNNING (same turn); clean exit after `/exit` or ≥ 1 settled turn → COMPLETED || QUESTION | AWAITING_INPUT | the tool resolves → RUNNING; `onBlocked` verdict → FAILED || PERMISSION | AWAITING_PERMISSION | same as QUESTION |@@ -949,7 +956,8 @@ type and new fields may only be added.and out, `cost_usd` (always null for native Claude routes — Claude Code's own cost is API-ratepricing, fictional spend for a subscription user; D12), tool calls, turns completed,`last_activity_at`, `idle_seconds`, `activity` (`thinking`, `background`, `finishing`, a tool name,- `AskUserQuestion`; unknown values mean busy) and `pane`.+ `AskUserQuestion`, `hook` while a settled turn's hooks run; unknown values mean busy) and `pane`.+ `hook` needed no version change, because an unknown value already meant busy.- `reason_detail` (added within v1, 2026-10-16) is one line, at most 160 characters, saying why`reason`: for `api_error` the provider's `error.message` from the LAST record of the upstream-errorcapture (`errors/<slot>-upstream.jsonl` for team, `upstream-errors.jsonl` for a session), else the