Skip to content

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.md
index 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.md
index 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 API
Two sessions once ran 900 s of genuine billed work — 241 assistant messages, ~94 k output
diff --git a/ai-docs/architecture/pane-session.md b/ai-docs/architecture/pane-session.md
index 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 that
re-exports `OPENAI_API_KEY` or `CLAUDE_CONFIG_DIR` is undone. On Linux a snapshot over 131,000
bytes 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 left
it 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 excluded
from the snapshot and kept when the snapshot is applied, so the child knows it is already inside a
multiplexer 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-rate
pricing, 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-error
capture (`errors/<slot>-upstream.jsonl` for team, `upstream-errors.jsonl` for a session), else the