Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
docs(mcp): record run_prompt's Claude Code path and the push removal
Jack Rudenko3fe49800059a
diff --git a/CLAUDE.md b/CLAUDE.mdindex 63560378..7249abc4 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -20,7 +20,7 @@ lives in `ROADMAP.md`.- `providers/devin.md`, `providers/grok-subscription.md`, `providers/antigravity.md`, `providers/qwen-alibaba.md` — one per reverse-engineered provider- `headless-vs-interactive.md` — `-p` is not interactive-minus-a-TTY; an UNKNOWN `--agent` name issilently unvalidated under `--input-format stream-json` (a VALID one is applied correctly); why magmux,- and why the MCP server starts no child with `-p`+ and the one `-p` the MCP server does start (`run_prompt` on a Claude model)- `pane-session.md` — MCP and CLI `team` slots and `create_session` as interactive Claude Code inheadless magmux panes: transcript turn oracle, settle on `turn_duration` (32 s quiet path gatedon Stop hooks), prompt delivery by file with read coverage, boot dialogs never accepted, the pane@@ -30,9 +30,9 @@ lives in `ROADMAP.md`.- `custom-endpoints.md`, `predefined-endpoints.md` — user config; the 25-vendor bundled catalog- `onepassword.md` — secret resolution, the four denial causes, the handshake lock, route pinning- `keychain.md` — the macOS Keychain backend: enumerate-for-presence vs read-for-value, the `security` traps, the Providers-tab write/delete-- `mcp-channel.md` — the 14-tool MCP surface, channel sessions on panes (`send_input` queueing,- `capture_session`, the session records the magus monitor reads), channel wire format- (`awaiting_permission`, no `finishing`), progress keepalive+- `mcp-channel.md` — the 14-tool MCP surface and its four groups, sessions on panes (`send_input`+ queueing, `capture_session`, the session records the magus monitor reads), `run_prompt`'s Claude+ Code print path, progress keepalive- `team-capture.md` — why `team`'s exit 0 proves nothing, and why a slot's answer is everyassistant message of its turn, from the transcript, starting after the task file was read- `team-lifecycle.md` — why no slot is ever killed on a timer, why `run` returns once everydiff --git a/ai-docs/architecture/README.md b/ai-docs/architecture/README.mdindex 0da7a4d2..f9f34b48 100644--- a/ai-docs/architecture/README.md+++ b/ai-docs/architecture/README.md@@ -31,12 +31,12 @@ three earlier write-ups this material cites were lost.| [`network-recovery.md`](network-recovery.md) | The two-tier connection hold: why the deadline is DERIVED from `API_TIMEOUT_MS` (measured 359.607 s, a default and not a watchdog), why the tier-2 status is 503 and never 429, why the banner is magmux's `overlay` and never a pane of ours (closing a pane wedged Claude Code), why its lease is renewed on its own tick and not by ladder events, the five sites where a network failure wore an auth status code, and why a pane child gets no watchdog | touch the retry ladder, `recovery/`, the tier-2 status, the recovery banner, or any `x-claudish-recovery` reader || [`behavior-layer.md`](behavior-layer.md) | Layer 4, the harness-convention SUPERVISOR: the rule engine, the four hooks, the 115-call plan-mode measurement it was built on, and opt-in telemetry | write a `behavior/` rule, or change harness-conformance handling || [`advisor.md`](advisor.md) | `--advisor` for any main model: why it is independent of `--monitor` yet keeps four of its launch bits, the decorator around the ROUTED handler, id capture by tool name (the `toolu_` prefix that made it a no-op on every foreign provider), the tee and retained session-keyed state, the ten stub paths and advice origin, Claude Code's advisor gates, metered panel billing, and the inherited-placeholder 401 | touch `--advisor`, `advisor-decorator.ts`, `native-handler-advisor.ts`, `advisor-startup.ts`, monitor-gated launch code, or native auth in `claude-runner.ts` |-| [`headless-vs-interactive.md`](headless-vs-interactive.md) | Why `-p` is NOT interactive-without-a-TTY: an UNKNOWN `--agent` is SILENTLY unvalidated under `--input-format stream-json` (measured, exit 0, no stream frame, `result: success`), upstream closed it as not planned, why magmux is in the dependency tree, why the MCP server no longer starts any child with `-p`, and why a driver cannot rely on magmux's pane states | drive Claude Code headlessly, add a child-spawn flag, or assume a headless run behaves like an interactive one |+| [`headless-vs-interactive.md`](headless-vs-interactive.md) | Why `-p` is NOT interactive-without-a-TTY: an UNKNOWN `--agent` is SILENTLY unvalidated under `--input-format stream-json` (measured, exit 0, no stream frame, `result: success`), upstream closed it as not planned, why magmux is in the dependency tree, the one `-p` the MCP server starts (`run_prompt` on a Claude model) and why it is safe, and why a driver cannot rely on magmux's pane states | drive Claude Code headlessly, add a child-spawn flag, or assume a headless run behaves like an interactive one || [`pane-session.md`](pane-session.md) | MCP `team` slots, CLI `team` and `create_session` as interactive Claude Code in headless magmux panes: the transcript as turn oracle, boot from screen content and closed dialog lists ("never accept"), the four settle paths with the measured `secondaryQuietMs` (32 s), prompt delivery by file with read coverage and exact `require_pattern` semantics, the environment snapshot and shell shim, the pane watcher and the identity-checked reap, the socket traps, `seq` ownership, the D9/D10 bounds, the phase table, and the frozen mod contract v1 | edit `pane/`, team or channel spawn, the settle rule, prompt delivery, the reap or sweep, or any field the mod contract carries || [`picker.md`](picker.md) | The OpenTUI model picker: why it is an inline dialog and not a dashboard (the density gate that manufactured the rejected build), the provider list as the default screen with nothing prefetched (3915 → 1436 ms), the discovery outcome that stopped `[]` meaning five things, the local served-by index (22 network queries measured at 10 018 ms), the no-terminal gate's complement law, and the capture and compile traps | change `picker/`, `selectModel`, discovery outcomes or fetchers, `should-open-picker.ts`, or a TUI test that asserts on a frame || [`context-window.md`](context-window.md) | Why setting one env lever accomplishes nothing, why the status line reports the ENFORCED window, and local-model token accounting | change context-window resolution, the status line, or token accounting || [`theming.md`](theming.md) | One detected theme for every surface, and the module-load palette-snapshot bug class it keeps producing (found six times) | add a colored CLI line or TUI surface |-| [`mcp-channel.md`](mcp-channel.md) | The 14-tool MCP surface (7 channel tools, `capture_session` among them), channel sessions on panes: the flag check, the owner's verdict, `send_input` queueing, the session records (`spawn.json`, `waits.jsonl`, `meta.json`, `events.jsonl`, `screen.txt`) and what the monitor reads, `get_diagnostics`; the channel wire format (`awaiting_permission` in, `finishing` out), the client-side conditions gating channel rendering, and the `notifications/progress` keepalive | add or rename an MCP tool, or change channel sessions, their records or their notifications |+| [`mcp-channel.md`](mcp-channel.md) | The 14-tool MCP surface (groups low-level / agentic / session / debug, `CLAUDISH_MCP_TOOLS`), sessions on panes: the flag check, the owner's verdict, `send_input` queueing, the session records (`spawn.json`, `waits.jsonl`, `meta.json`, `events.jsonl`, `screen.txt`) and what the monitor reads, `get_diagnostics`; `run_prompt`'s two paths (the Claude Code print call on the user's login, the proxy with no `max_tokens`); why the channel push was removed; and the `notifications/progress` keepalive | add or rename an MCP tool or group, change `run_prompt`, or change sessions or their records || [`team-capture.md`](team-capture.md) | Why exit 0 proves nothing under `claude -p` (the measurement behind `require_pattern`), and why a slot's answer is every assistant message of its turn, read from the transcript, starting after the task file was read | change how `team` classifies output or builds `response-<slot>.md` || [`team-lifecycle.md`](team-lifecycle.md) | Why nothing kills a slot on a timer, the measurement that removed the deadline, why `run` returns once every prompt is accepted (≤ 120 s), the run registry by `run_id`, the `blocked` rule, the team record ended exactly once, and one driver with two owners | add a deadline, change when `team` returns, or touch per-slot liveness, cancel or the run record || [`debugging.md`](debugging.md) | Debug logging, `CLAUDISH_UPSTREAM_ERROR_LOG`, raw SSE capture, and the failed-translation workflow | diagnose a model producing wrong, empty, or garbled output |diff --git a/ai-docs/architecture/headless-vs-interactive.md b/ai-docs/architecture/headless-vs-interactive.mdindex 930bcf44..fe4e2725 100644--- a/ai-docs/architecture/headless-vs-interactive.md+++ b/ai-docs/architecture/headless-vs-interactive.md@@ -123,12 +123,13 @@ an agent driving another agent is exactly the case where a human needs to be abl`packages/magmux-{darwin,linux}-*` ship with the CLI. Since 10.4 its main consumer is`packages/cli/src/pane/`: every MCP `team` slot, every CLI `team`/`--team --mode json` slot and every-`create_session` is an interactive Claude Code in its own headless magmux pane, and the MCP server-no longer starts any child with `-p` ([`pane-session.md`](pane-session.md)). `team-grid.ts` and+`create_session` is an interactive Claude Code in its own headless magmux pane+([`pane-session.md`](pane-session.md)). The one `-p` child the MCP server starts is `run_prompt` on+a Claude model, below. `team-grid.ts` and`--grid` remain the side-by-side viewer for a human, not the rationale.The MCP-server constraint quoted above is about `magmux mcp`, magmux's OWN MCP server. claudish's-MCP server spawns its panes itself, headless, because a team slot or a channel session has no human+MCP server spawns its panes itself, headless, because a team slot or a session has no humanin front of it; the pane's screen is still readable through `team(mode:"capture")` and`capture_session`, which is what the peer's Claude Code mod draws.@@ -238,4 +239,43 @@ named dialog headers on the screen plus the pending tool in the transcript; teamnever exercised. A refused agent is FAILED `agent_rejected` with the child's own line.- **Prefer magmux over `-p`** for anything where a silent behavioural difference would corruptthe result rather than merely degrade it. claudish's own `-p` single-shot mode still exists for- users who pipe a prompt in; nothing in the MCP server uses it.+ users who pipe a prompt in; the MCP server uses it in exactly one place, below.++## The one `-p` the MCP server starts: `run_prompt` on a Claude model++`run_prompt` (and each Claude entry of `compare_models`) on a bare Claude name runs+`claudish -p --model <model> --output-format json --tools "" --strict-mcp-config+--setting-sources "" --disable-slash-commands --no-session-persistence` with the prompt on stdin+(`mcp/run-prompt-claude-code.ts`; the full rationale is in [`mcp-channel.md`](mcp-channel.md)+"`run_prompt`: two paths"). It has to be a Claude Code call because claudish may not read the+Claude Code login itself, and it can be `-p` because none of what makes `-p` untrustworthy applies:++- **The measured divergence needs `--input-format stream-json` and `--agent`.** This call uses+ neither: its input is plain text on stdin, and it passes no agent, so there is no validation for+ Claude Code to skip silently.+- **There is nothing to validate.** `--tools ""` and `--strict-mcp-config` leave the child no tools+ and no MCP servers (`system/init`: `tools: []`, `mcp_servers: []`); a flag Claude Code ignored+ could only widen that, and the init frame would show it.+- **It is one turn with nothing to drive.** A session needs the REPL because it waits, queues+ `send_input` and answers dialogs; this call sends one prompt and reads one answer, which is what+ print mode is.+- **Exit 0 is never the verdict.** The answer is the `type: "result"` frame: `is_error` and+ `api_error_status` decide failure (a bad model exits 1 with `is_error: true` and+ `api_error_status: 404`), and output with no result frame is an error, never a success.++Measured for this call on Claude Code 2.1.301 (session+`dev-feature-mcp-run-prompt-claude-20261016-a7c3`):++- `--output-format json` prints a JSON ARRAY of frames (`system/init`, `assistant`,+ `rate_limit_event`, `result`), not the single object older releases printed. The parser takes+ both.+- `--setting-sources ""` keeps the subscription login: `apiKeySource: "none"`, answer `OK`. The+ login lives in the Keychain, not in a settings source. `--bare` does not: it reads only+ `ANTHROPIC_API_KEY`/`apiKeyHelper`.+- The working directory decides the context size, even with every settings source off: CLAUDE.md+ and memory still load, 8 718 input tokens in this repo against 580–597 in an empty directory.+ The call runs in a new empty one.+- claudish passes every one of these flags to `claude` unchanged, empty values included, and adds+ `--settings <file>` and `--dangerously-skip-permissions`. Its passthrough parser takes a value+ only when it does not start with `-`, so the prompt goes on stdin and the system prompt in a file+ (`--system-prompt-file`); `- Say OK` on stdin was answered correctly.diff --git a/ai-docs/architecture/mcp-channel.md b/ai-docs/architecture/mcp-channel.mdindex 3013aca0..753018ab 100644--- a/ai-docs/architecture/mcp-channel.md+++ b/ai-docs/architecture/mcp-channel.md@@ -1,18 +1,24 @@-> The 14-tool MCP surface, the channel sessions behind it, the channel wire format, client-side gating conditions, and the progress keepalive.+> The 14-tool MCP surface and its four groups, the sessions behind it (panes, records, polling), `run_prompt`'s two paths, the removed channel push, and the progress keepalive.>> Extracted from `CLAUDE.md` (v7.64.0). Indexed in [`README.md`](./README.md).-# Channel Mode (v6.4.0+)+# MCP sessions and tool surface-The MCP server supports a channel mode that enables async model sessions with push notifications.+The MCP server runs async model sessions (`create_session` and the other session tools) that the+host polls, plus `run_prompt` and `team`. The file keeps its old name, `mcp-channel.md`, because+`CLAUDE.md` and the index link to it; the channel push it was named for is gone (see "Push+notifications were removed").## Architecture-Uses the low-level `Server` class (not `McpServer`) from `@modelcontextprotocol/sdk/server/index.js` to declare `experimental: { 'claude/channel': {} }` capability. The SDK's `assertNotificationCapability()` has no default case — custom notification methods like `notifications/claude/channel` pass through.+Uses the low-level `Server` class (not `McpServer`) from `@modelcontextprotocol/sdk/server/index.js`.+`capabilities` is `{ tools: {} }` for every `CLAUDISH_MCP_TOOLS` value, with no `experimental` key,+and `serverInfo.version` is `VERSION` from `version.ts` (generated from `packages/cli/package.json`;+it said `9.0.0` until 10.7.0).## Components (`packages/cli/src/channel/`)-- **SessionManager** — the channel's policy and records: creates sessions, owns the queue of+- **SessionManager** — the sessions' policy and records: creates sessions, owns the queue of`send_input`, decides a turn's verdict, writes the session records, enforces `timeout_seconds`- **PaneSession** (`packages/cli/src/pane/`) — the mechanism: one interactive Claude Code in itsown headless magmux pane, with the transcript as its turn oracle. Team uses the same driver@@ -31,7 +37,7 @@ interactive Claude Code is what users actually run.Everything about the pane — boot, the transcript turn oracle and its settle paths, prompt deliveryby file with read coverage, the child's environment, the watcher and the identity-checked reap,the socket traps, the frozen mod contract — is in [`pane-session.md`](pane-session.md). This file-covers what the channel adds on top.+covers what the session tools add on top.**`claude_flags` are checked before anything starts** (`checkChildFlags`, shared with `team`):claudish's own pane argv, transport breakers (`-p`, `--output-format`, `--input-format`, `--stdin`,@@ -56,8 +62,7 @@ fails.`classifyRunOutput` with no byte floor and no pattern (`api_error`, `prompt_not_read`, `refused`,`empty_output`), and the session is terminal at that verdict, before its pane is reaped. Aninteractive session continues after each turn and fails only on an API-error turn (D20); a turn-whose task file was not fully read records the anomaly and `meta.prompt_not_read` on the next-frame. A question or a permission dialog waits for `send_input` (team fails it instead).+whose task file was not fully read records a `prompt_not_read` anomaly in `events.jsonl`. A question or a permission dialog waits for `send_input` (team fails it instead).Terminal states are absorbing: a late pane exit can never upgrade or overturn a CANCELLED orTIMEOUT already recorded.@@ -104,17 +109,11 @@ per-pane watchers still remove every process and file.`{session_id, state:"CANCELLED", changed}` at once; the pane close and the process-group reap finishin the background (worst case ≈ 12 s). A second call returns the same state with `changed:false`.-**`"timeout"` is a first-class wire event — the record and the channel agree.**-They diverged until Phase 3: `EVENT_TO_TASK_STATUS` had no `"timeout"` key and fell-through to `?? "working"`, so emitting the real event reported a *dead* session as still-working. The timeout path therefore recorded `"timeout"` and emitted `"failed"`, and a-consumer watching only the channel could not tell "ran out of time" from "errored".-`["timeout", "failed"]` now exists in that map (SEP-1686 has no `timeout` member; `failed`-is its only honest projection). The map is now built from a `Record<ChannelEventType, TaskStatus>`-over the runtime list `CHANNEL_EVENT_TYPES`, so an event type without a projection is a compile-error, and `awaiting_permission` (a dialog only `send_input` can move on) projects to-`input_required` instead of falling through to `working`. **Mutation-proven**: remove the timeout-key and a timed-out session goes back to `status: "working"` on the wire.+**`timeout` is its own state, never `failed`.** A session killed by its own `timeout_seconds` is+TIMEOUT in memory, `meta.json` `status: "timeout"`, and `to: "timeout"` in `waits.jsonl`. Until+Phase 3 of the channel work the channel wire said `failed` for it, because the SEP-1686 projection+had no `timeout` key and fell through to `working`; that projection (`mapEventToTaskStatus`) was+deleted with the push in 10.7.0, and the records never had the split.**Session shape follows the prompt.** `create_session` WITH a prompt is one-shot: it is terminalat the verdict of the turn that prompt started. WITHOUT a prompt it is interactive: it waits in@@ -126,7 +125,7 @@ at the verdict of the turn that prompt started. WITHOUT a prompt it is interactian empty input box between turns, or a turn is blocked on a question; `awaiting_permission` iff apermission or plan-approval dialog is open. A one-shot session is terminal at its verdict, so thereis no "answered but still exiting" state for a wait to be confused with — 10.4.0's `finishing`-channel event is gone with the transport (RB1). The wait for Claude Code's end-of-turn record after+event is gone with the transport (RB1). The wait for Claude Code's end-of-turn record afterthe model's message ends survives only as `activity:"finishing"` on a RUNNING session. Apromptless session's first wait opens at boot-ready, not at creation: before boot a send is queued,not answered (RB2).@@ -142,14 +141,15 @@ not answered (RB2).````since` keys the wait (the `closed` line repeats it); `turns` is `turnsCompleted` at the-open; `to` is the channel event of the new state, never another wait (the phase table has no-wait-to-wait edge). It is append-only because an observer polling the directory (the magus+open; `to` is the channel event of the new state (`channelEventFor`: `running`, `tool_executing`,+`completed`, `failed`, `cancelled`, `timeout`, …), never another wait (the phase table has no+wait-to-wait edge). The vocabulary outlived the push it was named for: the field is a record+contract the monitor reads, so it keeps those words. It is append-only because an observer polling the directory (the magus`claudish` plugin monitor) must see a wait that opened and closed between two of its reads — amarker file that exists only during the wait cannot give it that.The writer is the pane's `onTransition` hook: synchronous, every wire-state change, never-coalesced, and called BEFORE the channel frame, so the line is on disk by the time anyone hears of-the wait. It reports the net change of one event-processing step, so a turn that settles with a+coalesced. It reports the net change of one event-processing step, so a turn that settles with asend already queued (RUNNING → IDLE → ADMITTING in one step) opens no wait. The terminal transitioncloses any open wait before `meta.json` is written, so a live writer never leaves an open waitbeside a `meta.json`. One `appendFileSync` of < 200 bytes per line; a write failure goes to stderr@@ -295,7 +295,7 @@ a missing diagnostic: it is a session that never sees its own witness.### `CLAUDISH_UPSTREAM_ERROR_LOG` is set per session`captureUpstreamError` (`handlers/composed-handler.ts`) is a no-op when that env var is-unset, and it was unset for every channel child. Its own comment states the cost: `log()`+unset, and it was unset for every session child. Its own comment states the cost: `log()`only persists under `--debug`, so the body distinguishing a retryable rate limit from a hardquota wall is gone the moment it is classified. Each session now points its child at`<sessionDir>/upstream-errors.jsonl` — set unconditionally, overriding any inherited value,@@ -306,10 +306,11 @@ and `get_diagnostics` hands these records to an agent.## MCP Tools (14 total)-- **Low-level** (4): `run_prompt`, `list_models`, `search_models`, `compare_models`+- **Low-level** (3): `run_prompt`, `list_models`, `search_models`- **Agentic** (3): `preflight`, `team`, `report_error`-- **Channel** (7): `create_session`, `send_input`, `get_output`, `cancel_session`,+- **Session** (7): `create_session`, `send_input`, `get_output`, `cancel_session`,`list_sessions`, `get_diagnostics`, `capture_session`+- **Debug** (1): `compare_models``preflight` exists because `--probe` is CLI-ONLY. An MCP consumer had no way tocheck its models before committing to them, so it either shelled out to the CLI or@@ -335,109 +336,144 @@ The tool list is pinned by an EXACT frozen array in `channel/e2e-channel.test.tsadding or removing a tool without updating that test fails CI. That is deliberate:it is a wire contract, and an accidental change to the tool surface should be loud.-Tool gating via `CLAUDISH_MCP_TOOLS` env var: `all` (default), `low-level`, `agentic`, `channel`.+Tool gating via the `CLAUDISH_MCP_TOOLS` env var (lower-cased, `resolveToolGroups` in+`mcp-server.ts`):-## Tool Registration Pattern--Uses a `ToolDefinition[]` registry with raw JSON Schema (not Zod). Two `setRequestHandler` calls replace McpServer's ergonomic API:-- `ListToolsRequestSchema` → returns filtered tool list-- `CallToolRequestSchema` → dispatches to handler by name--## Channel Notifications--`server.notification({ method: "notifications/claude/channel", params: { content, meta } })` — pushed by SessionManager's `onStateChange` callback when a session's channel event changes, plus a coalesced `tool_executing` repeat (at most one per second) when the tool or the tool count changes. The method, capability, and params shape match Anthropic's [Channels reference](https://code.claude.com/docs/en/channels-reference) byte-for-byte.--The wire format is contractually pinned by `channel-wire-format.test.ts`:--```json-{- "method": "notifications/claude/channel",- "params": {- "content": "<string>",- "meta": {- "session_id": "<8-char hex>",- "event": "starting|running|tool_executing|waiting_for_input|awaiting_permission|completed|failed|cancelled|timeout",- "model": "<model-id>",- "elapsed_seconds": "<numeric string>",- "task_id": "<same as session_id>",- "status": "working|input_required|completed|failed|cancelled",- "created_at": "<ISO 8601 from session start>",- "last_updated_at": "<ISO 8601 at notification time>"- }- },- "jsonrpc": "2.0"-}-```+| Value | Tools |+|---|---|+| unset, `all` | all 14 |+| `low-level` | `run_prompt`, `list_models`, `search_models` |+| `agentic` | `preflight`, `team`, `report_error` |+| `session` | the 7 session tools |+| `debug` | `compare_models` |+| `channel`, or any other value | all 14 |++`session` was `channel` until 10.7.0. The rename removed the old name with no alias, per the+thesaurus rule, so `channel` now falls into the unknown-value rule and selects everything. The+stderr startup line shows `tools: channel, 14 tools`, but an MCP host does not show stderr.+`compare_models` moved to `debug` at the same time: it sends one prompt to several models in+sequence and shows raw answers, which is a route check, not work. Real multi-model work is `team`.++## `run_prompt`: two paths++`run_prompt` (and each entry of `compare_models`) is one quick prompt to one model: one request,+one answer, no tools, no session. `runPrompt` in `mcp-server.ts` picks the path with+`nativeRouteFor()` (`providers/native-route.ts`) FIRST — the proxy's own gate, so the tool cannot+disagree with the proxy (the CLAUDE.md invariant about bare Claude names):++| Model | Path |+|---|---|+| a bare Claude name: `claude-*`, `opus`, `sonnet`, `haiku`, `opusplan`, `internal`, `default` | `runPromptViaClaudeCode` (`mcp/run-prompt-claude-code.ts`): one Claude Code print-mode call through claudish |+| everything else, including `anthropic@claude-*` (metered), `dv@claude-*` and `anthropic/claude-*` | `runPromptViaProxy`: one Anthropic Messages request to the in-process proxy, which routes it like any request |-The event is derived from the session's state by `channelEventFor` (`session-manager.ts`):-STARTING → `starting`; RUNNING → `tool_executing` when its activity is a tool name, else `running`;-AWAITING_INPUT → `waiting_for_input`; AWAITING_PERMISSION → `awaiting_permission`; COMPLETED,-CANCELLED, TIMEOUT → their own event; FAILED and EMPTY → `failed`. Frames may add `tool` and-`tool_count`, `activity` (whenever it is non-null), `prompt_not_read` and `send_rejected`. The-content is claudish's own short text per event: the question or dialog text when the session is-blocked, the reason and detail on `failed`.+**Why a Claude name cannot use the proxy.** Until 10.7.0 every model took the proxy path, and+`run_prompt {model: "claude-opus-5-5"}` answered `Proxy error: 401 … x-api-key header is+required`: the proxy's native route forwards the CALLER's credential, and an MCP tool call has+none. claudish must never read the Claude Code OAuth token or its Keychain item, so the only way+onto the user's subscription is the unmodified `claude` binary signing in on its own login.-When rendered by Claude Code, each notification arrives in the agent's context as:+**The Claude Code print call.** `resolveClaudishLaunch` (`CLAUDISH_BIN`, else `claudish` on PATH —+the same claudish the panes start) runs:```-<channel source="claudish" session_id="…" event="…" model="…" elapsed_seconds="…">-<content here>-</channel>+<claudish> -p --model <model> --output-format json --tools "" --strict-mcp-config+ --setting-sources "" --disable-slash-commands --no-session-persistence+ (--system-prompt-file <file> | --system-prompt "")```-`meta` keys must match `[a-zA-Z0-9_]+` — Claude Code silently drops keys with hyphens or other characters. Our schema uses underscore-only keys (`session_id`, `elapsed_seconds`, etc.); when adding new `extraMeta` keys in `SessionManager.emitFrame`, keep this constraint.--The `task_id` / `status` / `created_at` / `last_updated_at` fields are SEP-1686 (MCP Tasks) forward-compatibility — additive only, no current consumer behavior change. The 9-value `event` collapses to the 5-value `status` per `EVENT_TO_TASK_STATUS` in `mcp-server.ts`; **every member of `ChannelEventType` must have a key there** — enforced at compile time now, because `mapEventToTaskStatus` falls through to `?? "working"` and a missing key silently reports a finished session as running. When Claude Code ships `notifications/tasks/status` receiver support, the migration is a method-name swap + payload restructure; see `ROADMAP.md` (Channel notifications → Phase 2) and `ai-docs/sessions/dev-research-mcp-tool-progress-20260508-235612-8d9da3e8/sep-1686-migration-schema.md` (write-up lost — predates the ai-docs tracking fix) for the full plan.+The original model string is passed; claudish's CLI owns alias normalisation. Measured on Claude+Code 2.1.301 (session `dev-feature-mcp-run-prompt-claude-20261016-a7c3`):-## Enabling channel rendering in Claude Code--The Claudish MCP server emits the documented wire format, but Claude Code gates channel **registration** behind several conditions that have nothing to do with the wire contract. All of these must be satisfied for `<channel>` blocks to surface in the agent's context:--| Requirement | Why |+| Choice | Why ||---|---|-| Claude Code v2.1.80 or later | Channels feature minimum version |-| Anthropic auth via claude.ai OR Console API key | Channels are NOT supported on Bedrock, Vertex, or Foundry |-| Interactive session (no `-p` / `--print`) | Channel registration is bound to the interactive event loop. Empirically verified: in `-p` mode the registration codepath never runs and frames are silently dropped |-| Server defined in project `.mcp.json` or `~/.claude.json` | `--mcp-config` is NOT consulted by the channel resolver. Tools loaded via `--mcp-config` work; channels declared by the same server do not register |-| Server explicitly named in `--channels` OR `--dangerously-load-development-channels` | Being in MCP config alone is not enough. Per Anthropic docs: *"a server also has to be named in `--channels`"* |-| Org policy `channelsEnabled: true` (Team/Enterprise only) | Pro/Max users without an org skip this check |--**Launch command — bare server**:--```bash-# in a directory with .mcp.json containing a "claudish" entry-claude --dangerously-load-development-channels server:claudish-```--**Launch command — via the Magus `code-analysis` plugin** (Claudish is bundled there as an MCP server):--```bash-claude --dangerously-load-development-channels plugin:code-analysis@magus-```+| prompt on stdin, system prompt in a file | claudish's passthrough parser takes a flag value only when it does not start with `-` (`cli.ts` `passthroughFlagTakesValue`), so a prompt or value starting with `-` would be misparsed. stdin reaches `claude -p` unchanged (`- Say OK` answered correctly), and keeps the prompt out of `ps` |+| `--system-prompt ""` when none is given | omitting it loads Claude Code's default system prompt (3 232 input tokens against 586); the proxy path sends no system prompt either |+| a new empty working directory | `--setting-sources ""` does NOT stop CLAUDE.md and memory loading: 8 718 input tokens in this repo, 580–597 in an empty directory. The cwd is `<tmp>/claudish-run-prompt-*/cwd`; the system prompt file sits beside it, so the cwd is empty even then. Both are removed after the call |+| `--setting-sources ""` | still authenticates: `apiKeySource: "none"`, the Keychain login. The login is not a settings source |+| `--strict-mcp-config`, `--tools ""` | without them the child loads the user's plugins and starts another `claudish --mcp`; with them the init frame shows `mcp_servers: []`, `tools: []` |+| no `--bare` | `--bare` reads only `ANTHROPIC_API_KEY`/`apiKeyHelper`, never the login, and 401s again |++**The environment.** `claudeCodePrintEnv` is the server's environment minus+`isStrippedFromChildEnv` (`pane/pane-launch.ts`, the list the pane spawner uses: `CLAUDECODE`,+`CLAUDE_CODE_CHILD_SESSION`, `MAGMUX_*`, terminal identity, `CLAUDE_CODE_SESSION_ID` and the launcher+pids), minus `PANE_MARKER_VARS` (a marker would make the child a pane child, which refuses `-p`+and exits 64), minus `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` and `ANTHROPIC_BASE_URL`.+`ANTHROPIC_API_KEY` goes unconditionally, not only claudish's placeholder: a bare Claude name in+`run_prompt` runs on the Claude Code login, and a user who wants the metered Anthropic API names+it as `anthropic@claude-*`.++**Process handling.** All three stdio streams are pipes: this process's stdin and stdout are the+JSON-RPC transport, and an inherited one would eat the host's requests or corrupt the stream. The+child is `detached` and stopped by its process group (SIGTERM, SIGKILL 5 s later), because+`claudish` on PATH may be the `bin/claudish.cjs` launcher, which orphans the real process on a+plain SIGTERM. There is no wall-clock deadline, as on the proxy path: the child stops on the call's+`AbortSignal` (`ToolCallContext.signal`, from the SDK's `extra.signal`: `notifications/cancelled`+or the host's own timeout) or at server shutdown (`stopAllClaudeCodePrintChildren` in+`installMcpShutdown`). Measured end to end: 1.3 s for a 404, 2.4 s for a Haiku answer.++**The answer.** Claude Code 2.1.301 `--output-format json` prints a JSON ARRAY of frames+(`system/init`, `assistant`, `rate_limit_event`, `result`); older releases printed one result+object. `parseClaudeCodePrintOutput` accepts both and reads the last `type: "result"` frame and the+`system/init` frame. `result` is the answer; `usage.input_tokens + cache_creation_input_tokens ++cache_read_input_tokens` is the input (a cached prefix is context the model saw); the init frame's+`apiKeySource` becomes the `Auth:` line (`"none"` → `Auth: Claude Code login (subscription)`).+`total_cost_usd` is not shown: on a subscription it is a list-price equivalent+(`costBasis: "list"`), not money spent. Exit 0 proves nothing; the verdict is the result frame:++| Condition | Error text |+|---|---|+| `is_error: true` (API error, "Not logged in") | `Claude Code: <result>` plus ` (HTTP <api_error_status>)` when it is a number |+| the executable cannot start | `cannot start claudish (<command>): <code>` |+| no result frame | `claudish -p exited <code>: <stderr tail, sanitized>` (the missing-`claude` case lands here) |+| empty `result` | `Model returned empty response` |+| the call's signal fired | `cancelled` |++**No `max_tokens` on either path.** `run_prompt` and `compare_models` have no output-limit+parameter, and `runPromptViaProxy`'s body has no `max_tokens`. Step 5w strips every limit field the+adapters write and adds the wire's `tokenParam` only when the request carries a limit, so the+upstream applies its own default and no number is pinned ([`wire.md`](wire.md)). Measured 200 with+no limit on chat-completions (`mm@MiniMax-M3`, `kimi-k3`), responses (`gpt-6.1-sol`) and+anthropic-messages (`mmc@MiniMax-M3`). The one known host that REQUIRES `max_tokens` is+`api.anthropic.com`, reached now only by the explicit metered `anthropic@claude-*`; if it 400s,+the fix belongs in step 5w (write the connection's catalog `maxOutputTokens` for+`anthropic-messages`), never in the MCP server.++Why `-p` is acceptable for this one call, when the session tools refuse it:+[`headless-vs-interactive.md`](headless-vs-interactive.md) "The one `-p` the MCP server starts".-The `--dangerously-load-development-channels` flag triggers a one-time confirmation prompt per session. To remove that prompt, the plugin would need to be added to Anthropic's curated channel allowlist (security review required) or to your org's `allowedChannelPlugins` managed setting.+## Tool Registration Pattern-## Diagnostic tracing — `CLAUDISH_CHANNEL_TRACE=1`+Uses a `ToolDefinition[]` registry with raw JSON Schema (not Zod). Two `setRequestHandler` calls replace McpServer's ergonomic API:+- `ListToolsRequestSchema` → returns filtered tool list+- `CallToolRequestSchema` → dispatches to handler by name-When the channel pipeline appears broken (e.g., client never renders `<channel>` blocks), set `CLAUDISH_CHANNEL_TRACE=1` before starting the MCP server. The diagnostics module (`packages/cli/src/channel/diagnostics.ts`) then emits `[channel-trace] …` lines to stderr at three checkpoints:+## Push notifications were removed (10.7.0)-1. `fired sid=… type=… model=… elapsed=…s` — onStateChange callback entered (producer side fires)-2. `callback returned sid=… type=…` — bridge invoked `server.notification()` without throwing-3. `WIRE-OUT {…json…}` — the JSON-RPC frame literally hit stdout+Until 10.7.0 the server declared `experimental: {"claude/channel": {}}` and pushed a+`notifications/claude/channel` frame on every session state change (plus a coalesced+`tool_executing` repeat at most once a second) and on every `team` progress tick, with SEP-1686+forward-compatibility fields (`task_id`, `status`, `created_at`, `last_updated_at`). Removed with+it: the capability, the `onStateChange` bridge and `SessionManager.emitFrame`, `notifyChannel`,+the SEP-1686 projection (`mapEventToTaskStatus`), the `ChannelEvent` type, and the+`CLAUDISH_CHANNEL_TRACE` diagnostics (`channel/diagnostics.ts`).-If you see (1) but not (2): the bridge is throwing or rejecting silently.-If you see (1)+(2) but not (3): the SDK's transport is dropping the frame.-If you see all three but the client doesn't render the notification: the issue is client-side — most often one of the gating conditions in "Enabling channel rendering in Claude Code" above is unmet.+Why: Claude Code rendered those frames only for an interactive host started with `--channels` (or+`--dangerously-load-development-channels`) and the server in project `.mcp.json` or+`~/.claude.json` — `--mcp-config` is not consulted by the channel resolver, and `-p` never+registers channels. Every other host dropped every frame, and a host polling `list_sessions` gets+the same facts from the records. The frames were never a keepalive either (next section).-Off by default. Zero overhead in production.+Where the facts are now: `list_sessions` rows (`state`, `activity`, `idle_seconds`, accounting),+`get_output`, `get_diagnostics`, `capture_session`, and the session records (`spawn.json`,+`waits.jsonl`, `meta.json`, `events.jsonl`, `screen.txt`), which the magus monitor reads and which+are byte-identical to before. `waits.jsonl` keeps the channel-event vocabulary in its `to` field.+`team` progress is `team(mode:"status")`. The `notifications/progress` keepalive stays.-When the MCP server is spawned by a host that captures stderr (e.g. Claude Code), set `CLAUDISH_CHANNEL_TRACE_FILE=/path/to/log` alongside `CLAUDISH_CHANNEL_TRACE=1` to mirror trace lines to a file you can `tail` from outside the host process. The file is opened with `appendFileSync` so multiple sessions append safely.+The trigger to reconsider is in `ROADMAP.md`: Claude Code delivering `notifications/tasks/status`+(SEP-1686) into the agent's context without `--channels`.-Diagnostic scripts:-- `packages/cli/src/channel/test-helpers/channel-diagnostic.ts` — drives the MCP server with raw JSON-RPC against the OpenRouter free model. Confirms the producer→bridge→wire pipeline.-- `packages/cli/src/channel/test-helpers/client-diagnostic.ts` — spawns `claude -p` against the instrumented MCP server and compares what the server sent vs. what the client surfaced. Useful for diagnosing client-side gating.-- `packages/cli/src/channel/test-helpers/claudish-mock.ts` — a standalone mock MCP server that exposes a single `start_mock_session` tool, then emits a scripted sequence of 6 channel notifications over ~9 seconds. Decouples channel-rendering tests from real-model behavior.-- `scripts/pane-drive.ts` — drives one pane session from the command line (`--fake <scenario>` for the hermetic fake child).+Diagnostic script: `scripts/pane-drive.ts` drives one pane session from the command line+(`--fake <scenario>` for the hermetic fake child).## Testing@@ -445,7 +481,7 @@ Diagnostic scripts:bun test ./packages/cli/src/channel/```-Channel sessions are panes, so the suites that start one run a REAL headless magmux with the pane+Sessions are panes, so the suites that start one run a REAL headless magmux with the panefake child (`pane/test-helpers/fake-interactive-child.ts`) as `CLAUDISH_BIN`, under a per-test`CLAUDISH_PANE_ROOT` and an allowlisted environment, and assert after each test that no process,socket, record or launcher directory is left. Without magmux they skip with "magmux not installed —@@ -453,22 +489,21 @@ not checked". `testing.md` has the rules.- `session-manager.test.ts` — the pure seams (`channelEventFor` over every `SlotState`,`toMetaRecord`, `sessionRowOf`, `normaliseTimeoutSeconds`), the two-generation disk reader, the- hostile-id and bounded-read guards, live pane sessions (one-shot and promptless frames, a send- queued while STARTING (G7) or RUNNING, the timeout staying TIMEOUT in memory, `meta.json` and on- the wire (G1/G2), cancel, recovery from disk), and the module-load signal exit codes (G3). G4 is- the flag check.+ hostile-id and bounded-read guards, live pane sessions (one-shot and promptless `waits.jsonl`+ transitions, a send queued while STARTING (G7) or RUNNING, the timeout staying TIMEOUT in memory,+ `meta.json` and `waits.jsonl` (G1/G2), cancel, recovery from disk), and the module-load signal+ exit codes (G3). G4 is the flag check.- `session-records.contract.test.ts`, `session-state-records.contract.test.ts`,`spawn-record.contract.test.ts`, `host-pid.contract.test.ts`, `session-timeout.test.ts` — theon-disk records the monitor reads. These were written blind from the 10.4.0 specification; thepane port changed only the adapters and the fake, and every replaced assertion cites its RB/Dnumber.-- `channel-wire-format.test.ts`, `event-task-status.test.ts` — the wire format and the SEP-1686- projection, including `awaiting_permission` and the absence of `finishing`.+- `channel-wire-format.test.ts` — the capability declaration: no `experimental` for any tool mode.- `../mcp-contract.e2e.test.ts` — the mod contract v1 through a real MCP server over JSON-RPC;`../mcp-shutdown.e2e.test.ts` — stdin EOF, SIGTERM and SIGKILL of a server holding a live sessionand a live team run.-**The tool list is pinned twice, and adding a tool must break both.** `e2e-channel.test.ts` freezes the full 14-name list and the channel-only 7, deliberately: that list is a wire contract and an accidental change to it should be loud. `get_diagnostics` and `capture_session` each broke both pins on the way in, which is the guard working.+**The tool list is pinned per group, and adding a tool must break a pin.** `e2e-channel.test.ts` freezes the full 14-name list, the session-only 7 and the low-level 3, deliberately: that list is a wire contract and an accidental change to it should be loud. `get_diagnostics` and `capture_session` each broke both pins on the way in, which is the guard working.E2E tests use `--strict-mcp-config --bare --dangerously-skip-permissions` for isolation. SessionManager tests point child spawns at the tree under test via `CLAUDISH_BIN` (`spawn-claudish.ts`), never at the installed binary.@@ -493,11 +528,13 @@ Claude Code aborts a tool call that puts nothing on the transport for its idle w| `notifications/progress` | survived 90s || `notifications/claude/channel` | aborted at 30s |-Channel and progress are **complementary, not alternatives**: channel is the visible surface with no keepalive, progress is the invisible keepalive — it still renders nowhere. A tool that blocks for minutes needs both.+**Progress is the keepalive**, and the only one: a channel frame never reset the idle timer (the+row above is kept as the measurement that showed it; the channel push itself was removed in+10.7.0). Progress still renders nowhere.-**`heartbeat: true` is set on exactly four tools**: `team`, `run_prompt`, `compare_models`, `preflight`. `team(mode:"run")` itself returns once every slot's prompt is accepted (at most 90 s + 30 s), but `run-and-judge` holds the call for the whole run. `create_session` deliberately does NOT carry it — it returns `{session_id, state}` as soon as the pane exists, without waiting for boot, and cannot reach the idle timer; the session's own long life is reported over channel frames, which is a different question.+**`heartbeat: true` is set on exactly four tools**: `team`, `run_prompt`, `compare_models`, `preflight`. `team(mode:"run")` itself returns once every slot's prompt is accepted (at most 90 s + 30 s), but `run-and-judge` holds the call for the whole run. `create_session` deliberately does NOT carry it — it returns `{session_id, state}` as soon as the pane exists, without waiting for boot, and cannot reach the idle timer; the session's own long life is read by polling `list_sessions`, which is a different question.-**The emitter is TIME-driven, not event-driven**, and that is the load-bearing choice. `team` already emitted a channel frame on every state change and still died at exactly 1800s, because a model that thinks for 30 minutes produces no state changes — an event-driven emitter goes silent precisely while the idle timer is counting.+**The emitter is TIME-driven, not event-driven**, and that is the load-bearing choice. `team` once emitted a channel frame on every state change and still died at exactly 1800s, because a model that thinks for 30 minutes produces no state changes — an event-driven emitter goes silent precisely while the idle timer is counting.Interval defaults to 10s (the measured-working value), overridable with `CLAUDISH_MCP_PROGRESS_INTERVAL_MS`, clamped to `[1000, 60000]`, garbage → default. Resolved once per server, not per call, so a long session cannot change cadence mid-flight. The first frame lands at t+interval, so a 200ms call stays completely silent.diff --git a/ai-docs/architecture/team-lifecycle.md b/ai-docs/architecture/team-lifecycle.mdindex e86e8dcb..4df7d689 100644--- a/ai-docs/architecture/team-lifecycle.md+++ b/ai-docs/architecture/team-lifecycle.md@@ -192,10 +192,9 @@ eviction, or after a server restart, `status` still answers from `status.json`### The run's record in the sessions directory, ended exactly once-Returning early has a cost: the run's completion reaches the caller only through-a channel frame, and Claude Code drops channel frames unless the session named-claudish in `--channels`. The run's own `status.json` sits wherever the caller-pointed `path`, which no outside observer knows. Review panels finished unseen+Returning early has a cost: the run's completion is not pushed to the caller at+all. The run's own `status.json` sits wherever the caller pointed `path`, which+no outside observer knows. Review panels finished unseenfor days this way. So `team(mode:"run")` also writes a record into the sessionsdirectory the magus `claudish` plugin monitor already watches: