Skip to content
Registry

claude-code

v0.2.8

Claude Code as an iii worker — claude::* runs headless turns and claude::terminal::* runs the same CLI in a shell::pty session on its own console page. Both publish raw messages on the claude::raw-event trigger type and AgentEvent frames on claude::agent-event.

license: Apache-2.0anthropicclaudeclicoding-agentconsole-uiheadlessterminal

Install

bash
iii trigger compose::add worker=claude-code@0.2.8

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Functions12

claude::auth::status

Function

Check who pays for a Claude terminal session on this host. Reports a Claude subscription, an API key (which overrides the login), or nothing yet; read from `claude auth status` on the host.

Request
Empty object
Response
  • api_key_sourcestring
  • billingstringrequiredenum subscription, api-key, none, unknown
  • detailstringrequired
  • emailstring
  • labelstringrequired
  • logged_inboolean
  • methodstring
  • organizationstring
  • subscription_typestring

claude::on-config-change

Function

Internal: reload claude-code configuration when it changes.

Request
Empty object
Response
valuenull

claude::run

Function

Run one Claude Code turn and wait for the result. Accepts `prompt` or a `messages` array plus a raw SDK `options` pass-through; streams raw Claude Code messages onto claude::events, AgentEvent frames onto agent::events, and returns {session_id, result, usage, total_cost_usd}.

Request
  • allowed_toolsstring[]

    Allow rules, e.g. "Bash(git *)"

  • append_system_promptstring

    Append to the default system prompt

  • cwdstring

    Working directory the turn runs in

  • disallowed_toolsstring[]

    Deny rules

  • iii_contextboolean

    Append the iii runtime discovery prompt (engine catalog via the iii CLI)

  • max_turnsintegermax 9007199254740991

    Cap on agentic turns

  • messagesobject[]

    Alternative to prompt: role/content messages; the last user entry becomes the prompt

    • contentany ofrequired
      any of (2)
      Variant 1
      valuestring
      Variant 2
      itemsobject[]
      • typestringrequired
    • rolestringrequired
  • modelstring

    Model id or alias; empty = Claude Code default

  • optionsobject

    Raw Agent SDK options forwarded verbatim (camelCase), e.g. forkSession, includePartialMessages

  • parent_session_idstring

    The session delegating this run. Written to the child session metadata, which is what nests it under its parent in the console — the same link a harness sub-agent carries.

  • permission_modestringenum default, acceptEdits, plan, bypassPermissions

    Claude Code permission mode for this turn

  • promptstring

    The user prompt for this turn

  • session_idstring

    iii session id; reuse to resume the same Claude Code conversation

  • system_promptstring

    Replace the Claude Code system prompt

  • timeout_msintegermax 9007199254740991

    Reserved for callers; not forwarded

Response
  • busyboolean
  • claude_session_idany of
    any of (2)
    Variant 1
    valuestring
    Variant 2
    valuenull
  • is_errorboolean
  • num_turnsnumber
  • reasonstring
  • resultstring
  • session_idstringrequired
  • stop_reasonstring
  • total_cost_usdnumber
  • usageany of
    any of (2)
    Variant 1
    • cache_read_tokensnumber
    • cache_write_tokensnumber
    • input_tokensnumberrequired
    • output_tokensnumberrequired
    Variant 2
    valuenull

claude::sessions::list

Function

List every Claude Code session this worker has run.

Request
Empty object
Response
  • sessionsobject[]required
    • claude_session_idany ofrequired
      any of (2)
      Variant 1
      valuestring
      Variant 2
      valuenull
    • cwdstringrequired
    • modelstringrequired
    • session_idstringrequired
    • statusstringrequiredenum working, done, error
    • total_cost_usdnumberrequired
    • turnsnumberrequired
    • updated_at_msnumberrequired
    • usageany ofrequired
      any of (2)
      Variant 1
      • cache_read_tokensnumber
      • cache_write_tokensnumber
      • input_tokensnumberrequired
      • output_tokensnumberrequired
      Variant 2
      valuenull

claude::start

Function

Start a Claude Code turn and return immediately; watch agent::events (group_id = session_id) for progress and turn_end.

Request
  • allowed_toolsstring[]

    Allow rules, e.g. "Bash(git *)"

  • append_system_promptstring

    Append to the default system prompt

  • cwdstring

    Working directory the turn runs in

  • disallowed_toolsstring[]

    Deny rules

  • iii_contextboolean

    Append the iii runtime discovery prompt (engine catalog via the iii CLI)

  • max_turnsintegermax 9007199254740991

    Cap on agentic turns

  • messagesobject[]

    Alternative to prompt: role/content messages; the last user entry becomes the prompt

    • contentany ofrequired
      any of (2)
      Variant 1
      valuestring
      Variant 2
      itemsobject[]
      • typestringrequired
    • rolestringrequired
  • modelstring

    Model id or alias; empty = Claude Code default

  • optionsobject

    Raw Agent SDK options forwarded verbatim (camelCase), e.g. forkSession, includePartialMessages

  • parent_session_idstring

    The session delegating this run. Written to the child session metadata, which is what nests it under its parent in the console — the same link a harness sub-agent carries.

  • permission_modestringenum default, acceptEdits, plan, bypassPermissions

    Claude Code permission mode for this turn

  • promptstring

    The user prompt for this turn

  • session_idstring

    iii session id; reuse to resume the same Claude Code conversation

  • system_promptstring

    Replace the Claude Code system prompt

  • timeout_msintegermax 9007199254740991

    Reserved for callers; not forwarded

Response
  • session_idstringrequired
  • startedbooleanrequired

claude::status

Function

Check the status of a Claude Code session.

Request
  • session_idstringrequired

    iii session id returned by claude::run / claude::start

Response
  • livebooleanrequired
  • recordany ofrequired
    any of (2)
    Variant 1
    • claude_session_idany ofrequired
      Show 2 nested
      any of (2)
      Variant 1
      valuestring
      Variant 2
      valuenull
    • cwdstringrequired
    • modelstringrequired
    • session_idstringrequired
    • statusstringrequiredenum working, done, error
    • total_cost_usdnumberrequired
    • turnsnumberrequired
    • updated_at_msnumberrequired
    • usageany ofrequired
      Show 2 nested
      any of (2)
      Variant 1
      • cache_read_tokensnumber
      • cache_write_tokensnumber
      • input_tokensnumberrequired
      • output_tokensnumberrequired
      Variant 2
      valuenull
    Variant 2
    valuenull
  • session_idstringrequired

claude::stop

Function

Stop a live Claude Code run for a session.

Request
  • session_idstringrequired

    iii session id returned by claude::run / claude::start

Response
  • reasonstring
  • session_idstringrequired
  • stoppedbooleanrequired

claude::task

Function

Delegate one task to Claude Code and return its session id immediately — the sub-agent shape: it never parks the caller. The outcome is written to state under scope `agent_tasks`, key the child session id, so bind a `state` trigger on that BEFORE calling and be woken by it; progress streams onto agent::events (group_id = session_id). Pass `parent_session_id` to nest the child under the session that delegated it.

Request
  • allowed_toolsstring[]

    Allow rules, e.g. "Bash(git *)"

  • append_system_promptstring

    Append to the default system prompt

  • cwdstring

    Working directory the turn runs in

  • disallowed_toolsstring[]

    Deny rules

  • iii_contextboolean

    Append the iii runtime discovery prompt (engine catalog via the iii CLI)

  • max_turnsintegermax 9007199254740991

    Cap on agentic turns

  • modelstring

    Model id or alias; empty = Claude Code default

  • optionsobject

    Raw Agent SDK options forwarded verbatim (camelCase), e.g. forkSession, includePartialMessages

  • parent_session_idstring

    The session delegating this run. Written to the child session metadata, which is what nests it under its parent in the console — the same link a harness sub-agent carries.

  • permission_modestringenum default, acceptEdits, plan, bypassPermissions

    Claude Code permission mode for this turn

  • session_idstring

    iii session id; reuse to resume the same Claude Code conversation

  • system_promptstring

    Replace the Claude Code system prompt

  • taskstringrequiredmin 1 chars

    The child's self-contained goal. It cannot see the caller's context, so name every resource it needs.

  • timeout_msintegermax 9007199254740991

    Reserved for callers; not forwarded

Response
  • session_idstringrequired
  • startedbooleanrequired

claude::terminal::activity

Function

A Claude Code lifecycle event from a terminal session (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd), posted by the workspace hooks. Translated into AgentEvent frames on the events stream.

Request
  • cwdstring
  • hook_event_namestring
  • promptstring
  • session_idstring
  • tool_inputobject
  • tool_namestring
  • tool_responseunknown
  • tool_use_idstring
Response
  • eventstringrequired
  • okbooleanrequired

claude::terminal::describe

Function

What a Claude terminal session runs: the claude binary, its argv, the workspace directory, and the session environment. The console page passes this straight to shell::pty::open.

Request
Empty object
Response
  • activity_bridgestring

    The `iii` CLI on the terminal host that carries this session's activity to the bus. Empty means nothing will reach the events stream.

  • argsstring[]required
  • cwdstringrequired
  • detailstring

    Anything wrong that does not stop a session from opening.

  • envobjectrequired
  • programstringrequired

claude::ui-content

Function

Console UI asset content (console plumbing).

Request
  • pathstringrequired
Response
  • contentstringrequired
  • content_typestring

run::start_and_wait

Function

Alias for claude::run under the shared agent entrypoint: run a turn for {session_id, messages} and return when it ends.

Request
  • allowed_toolsstring[]

    Allow rules, e.g. "Bash(git *)"

  • append_system_promptstring

    Append to the default system prompt

  • cwdstring

    Working directory the turn runs in

  • disallowed_toolsstring[]

    Deny rules

  • iii_contextboolean

    Append the iii runtime discovery prompt (engine catalog via the iii CLI)

  • max_turnsintegermax 9007199254740991

    Cap on agentic turns

  • messagesobject[]

    Alternative to prompt: role/content messages; the last user entry becomes the prompt

    • contentany ofrequired
      any of (2)
      Variant 1
      valuestring
      Variant 2
      itemsobject[]
      • typestringrequired
    • rolestringrequired
  • modelstring

    Model id or alias; empty = Claude Code default

  • optionsobject

    Raw Agent SDK options forwarded verbatim (camelCase), e.g. forkSession, includePartialMessages

  • parent_session_idstring

    The session delegating this run. Written to the child session metadata, which is what nests it under its parent in the console — the same link a harness sub-agent carries.

  • permission_modestringenum default, acceptEdits, plan, bypassPermissions

    Claude Code permission mode for this turn

  • promptstring

    The user prompt for this turn

  • session_idstring

    iii session id; reuse to resume the same Claude Code conversation

  • system_promptstring

    Replace the Claude Code system prompt

  • timeout_msintegermax 9007199254740991

    Reserved for callers; not forwarded

Response
  • busyboolean
  • claude_session_idany of
    any of (2)
    Variant 1
    valuestring
    Variant 2
    valuenull
  • is_errorboolean
  • num_turnsnumber
  • reasonstring
  • resultstring
  • session_idstringrequired
  • stop_reasonstring
  • total_cost_usdnumber
  • usageany of
    any of (2)
    Variant 1
    • cache_read_tokensnumber
    • cache_write_tokensnumber
    • input_tokensnumberrequired
    • output_tokensnumberrequired
    Variant 2
    valuenull

Triggers0

No triggers registered

Search the registry

Find workers, kits and executables, or jump to a page.