claude-code

# claude-code The claude-code worker exposes the Claude Code API as iii functions. One `claude::run` call executes one headless Claude Code turn — the same agent the user runs in their terminal, with the same login, filesystem, and permission model — in a chosen working directory, and returns the final result, token usage, and cost. The worker is a pure pass-through: named payload fields cover the common path, the `options` field forwards any Agent SDK option verbatim, and every message Claude Code emits is published untouched on the `claude::raw-event` trigger type. A translated AgentEvent view is published on `claude::agent-event`, which is what the iii console and the acp worker render. Bind either with `{ session_id }`; frames are live only (not stored or replayed), ordered by `(epoch, seq)`. Requires the `claude` CLI on the host with an existing login or `ANTHROPIC_API_KEY` in the worker environment. When a turn needs a capability beyond Claude Code itself, add another iii worker to the bus instead of bolting anything onto this one. ## When to Use - Delegate a whole coding task ("add an endpoint and run the tests") in one call, instead of orchestrating individual `coder::*` / `shell::*` calls yourself: `claude::run` with `prompt` and `cwd`. - Continue a conversation across calls: pass the same `session_id` again and the worker resumes the underlying Claude Code session with full context. - Run long jobs without holding the call open: `claude::start` returns `{session_id, started}` immediately; bind `claude::raw-event` with `{ session_id }` for raw progress or `claude::agent-event` for the rendered view; interrupt with `claude::stop`. - Act on the whole backend: turns carry the iii runtime context by default, so the agent discovers and calls any registered function through the iii CLI (engine::functions::list, `iii trigger <fn> --help`) with the matching Bash allow rule pre-set; disable per turn with `iii_context: false`. - Plan before touching anything: `permission_mode: "plan"` runs Claude Code's native plan mode (read-only, returns the plan as the result); then send "implement the plan" on the same `session_id` with `permission_mode: "acceptEdits"`. - Reach past the named payload fields: anything the Agent SDK accepts goes through `options` unchanged — `{"options": {"forkSession": true, "includePartialMessages": true}}` — and `includePartialMessages` puts token-level `stream_event` frames on `claude::raw-event`. ## Boundaries - Spawns the host `claude` CLI per turn — needs Claude Code installed and authenticated; not available inside a bare container without it. - Function execution happens inside Claude Code's own permission model (`permission_mode`, `allowed_tools`, `disallowed_tools`), not the engine's; set `approval_gate: true` to route every call through `policy::check_permissions` (fail-closed, needs the harness worker). - One turn per session at a time: check `claude::status` (`live: true`) before sending another `claude::run` for the same `session_id`; parallel runs against one session race on the underlying Claude Code resume. - `claude::agent-event` carries whole-message frames (`message_complete`, `function_execution_start/end`, `turn_end`, `agent_end`); token deltas exist only on `claude::raw-event` and only when `includePartialMessages` is set. ## Functions - `claude::run` — run one Claude Code turn and wait; accepts `prompt` (or a `messages` array whose last user entry becomes the prompt), plus `model`, `cwd`, `permission_mode`, `allowed_tools`, `disallowed_tools`, `max_turns`, `system_prompt`, `append_system_prompt`, and raw `options`; returns `{session_id, claude_session_id, result, stop_reason, usage, total_cost_usd}`. - `claude::start` — same payload, returns `{session_id, started}` immediately; progress arrives on the event feeds. - `claude::stop` — interrupt the live run for a session. - `claude::status` — point-in-time session view: live flag, status, turns, usage, cost. - `claude::sessions::list` — every session this worker has run. - `run::start_and_wait` — alias for `claude::run` under the entrypoint the console and acp worker drive, so both run Claude Code with no changes. ## The terminal half The same worker also runs Claude Code as a terminal page on the console: it installs the CLI on the terminal host (the `shell` worker's), equips a workspace with the iii skills and engine notes, and opens Claude in a `shell::pty` session. A person opens it; the session's turns are published on `claude::agent-event` with the same frames a `claude::run` turn produces, so both halves render alike. Use it when an operator wants to talk to Claude Code interactively — with login handled in the terminal — or wants an agent that can scaffold and register new iii workers from inside the engine. `pi` is the same terminal shape with the pi agent. Boundaries: - `claude::terminal::describe`, `claude::terminal::activity`, and `claude::ui-content` are console plumbing, flagged internal. Do not call them; a terminal is opened by a person, from the page. - The command is fixed to Claude Code. Use the `shell` worker for anything else — including `shell::pty::sessions` to see what a terminal is doing. - The workspace must be reachable by the `shell` worker: it owns the session. - `claude::auth::status` reports which plan a terminal session spends (subscription vs API key, and an API key silently outranks a subscription login). The page shows it in the status bar; agents are denied it.