Claude Code¶

type: claude drives Claude Code through the Claude Agent SDK as a local subprocess, and records the Claude Code sessions you run yourself.

Enable¶

Run Claude Code once as the server account and complete its login. Add the block below to tentacles.yaml, bind claude in a channel's agents list, and check and restart Octomate. For your own native sessions, follow Claude Code client setup.

tentacles:
  claude:
    type: claude
    permission_mode: default      # the SDK's own scale, handed over verbatim
    max_turns: ~
    approval_timeout: 3600        # seconds before an unanswered card expires
    instrument: false
    claims: {}

The harness supplies the model catalog: at startup Octomate asks the CLI for its models and the account's provider, and keys each as <provider>:<model> by the model it runs, such as anthropic:claude-opus-5-5. Descriptions and supported efforts come from the same call where the CLI reports them. The CLI is the one the Claude Agent SDK bundles, so the models on offer follow the SDK's version.

Driven runs¶

A driven turn launches claude with the SDK in the thread's workspace, passing the project's extra_roots as additional directories. Local customisation is off: the CLI runs in safe mode, so user settings, hooks, plugins and skills do not load, and only the MCP servers Octomate passes are mounted. That is one server, Octomate's own, built in process for this turn, whose tools Claude lists as mcp__octomate__<tool>. Octomate's routing and history instructions are appended to the system prompt.

Driven commands use Claude's native sandbox and fail to start when it is unavailable. Requests for an unsandboxed retry do not bypass it. The normal approval flow still applies, including the selected permission mode.

Claude's native read restriction limits file tools and sandboxed commands from reading user data outside the workspace and project extra roots. System paths and native temporary storage remain available; this is not a workspace-only filesystem. Octomate does not maintain a separate runtime path allowlist. See the native sandbox matrix for measured boundaries and remaining limits.

The session id is settled before the CLI starts, and the same session is resumed on every later turn of the conversation. Claude files a session under the directory it ran in and resumes it only from there, so when a thread binds to a project Octomate moves the transcript to the workspace's slot before resuming. One live client per conversation, and one turn at a time: a message sent while a turn is running does not interrupt it.

Choose from the model's native effort levels, including max where offered. The selected name is passed to Claude unchanged. Driven turns request summarized thinking for channels that display it.

Runtime commands¶

The command catalog reads Claude's SDK initialization metadata without sending a prompt. It preserves command names, descriptions and argument hints; aliases are retained as Claude-specific metadata. Native discovery requires an existing workspace and uses its model, permission mode, project directories and saved session ID. It does not create the workspace or persist an inspection session.

Discovery uses the same safe mode and strict MCP configuration as driven turns. Only Octomate's tool-only MCP server can be mounted during a turn, so there are no MCP prompts to add to the command catalog. Local commands, skills and plugins stay disabled. With SDK 0.2.152 and bundled CLI 2.1.259, a test workspace command remained absent even with setting_sources=["project"]; it appeared when safe mode was removed. Omitting setting_sources uses the SDK's normal filesystem defaults; safe mode is the restriction here. Loading local commands would require a separate configuration opt-in for both discovery and execution, which Octomate does not yet expose. See the SDK command guide.

The SDK caches initialization metadata per client. The host caches the catalog until refresh, context changes, eviction or invalidation when a driven turn starts or the tentacle starts or stops. Refresh opens a new inspection client to obtain a new runtime snapshot. Missing command metadata is reported as a discovery limitation; missing or empty native command lists still leave Octomate's /plan and /fork controls available.

Native execution sends the selected command through SDK query() with the raw argument text and the conversation's saved session. The execution client checks its own initialization metadata before submitting the command; a removed or changed entry requires a refresh and is never sent as an ordinary prompt. Commands absent from the catalog are rejected. An advertised command that needs a terminal returns the runtime's refusal text.

Direct output is saved on the command receipt without creating a model run. Commands that start model activity use the normal streaming, approval and run history path. SDK error results fail the receipt; successful direct text appears once. Attachments are not supported.

/clear updates the conversation's resumable session ID from the SDK's final result. /compact leaves summarization to Claude. Neither command deletes or rewrites Octomate's recorded history.

/plan and /fork are Octomate controls, available even when the SDK does not advertise them. /plan or /plan on saves plan mode; /plan off saves Claude's default permission mode for subsequent runs. During a run, use the conversation's permission control to change the active client. /fork copies a driven conversation, its settings and workspace into a new thread. Select that thread to continue; the source stays unchanged. Forking requires a saved Claude session and starts no agent turn.

Other commands appear when the connected SDK advertises them:

Command	Handling
`/context`, `/compact`, `/clear`	Native execution; direct feedback is recorded without inventing a model run. `/clear` keeps Octomate's history and adopts Claude's new session ID.
`/model`	Disabled; use the agent/model picker when starting a conversation.
`/effort`	Native entry disabled; use the gateway `/effort` to save the selection.
`/plan [on\\|off]`	Octomate saves the permission mode without submitting a prompt.
`/fork`	Octomate creates an independent thread and Claude session with the copied history.
`/permissions`	Disabled; use the conversation's permission control.
`/resume`	Disabled; select an existing conversation in Octomate.
`/goal`	Omitted; automatic continuation is not integrated.
Other advertised commands and skills	Native execution with their raw arguments; real agent activity uses the normal recorded stream. Safe mode still limits which skills appear.

Approvals and questions¶

You can change a driven conversation's permission mode while it is running. The choice also applies to subsequent runs.

Two bridges, both landing on the same cards:

Tool permission. The SDK asks Octomate before each tool the posture does not already allow. Octomate raises an approval, waits up to approval_timeout, and answers allow or deny. "Allow for session" is remembered on the conversation. A commissioned run with no user to ask is denied at once, with a message telling the agent to proceed another way.
Questions. Claude's AskUserQuestion tool is intercepted by a hook. Since a hook can only allow or deny, the user's answer travels back as the reason for a deny, which Claude reads as the answer. Choices are capped at five, and a multi-select question takes several picks.

The bridge parks the live SDK client while it waits, so an answer is not durable across an Octomate restart: restart mid-question and the run is gone, though the conversation resumes on the next message.

The gateway's teleport tool follows Claude's normal MCP permissions, including bypass mode and existing grants. Octomate relays approval requests through the same bridge without adding another confirmation.

Native sessions¶

A thread becomes available as its opening prompt arrives from the transcript. A console with the thread open shows the turn a whole message at a time. When the turn finishes, it settles into the ledger. Saved history preserves the transcript's message order even when timestamps disagree.

octomate claude hooks install starts transcript streaming on each prompt. Messages appear only as their transcript reaches Octomate; a disconnected tail leaves them waiting to sync. Each subagent keeps its own ordered conversation under the parent. A session's own title becomes the thread's name. Permission mode changes are observed and recorded, never set.

The hook and tailer reference describes session lifecycle, run reservations and transcript processing.

The tail's bytes of the session transcript are also kept, for their owner, so the session can teleport: its history up to the last whole turn is forked into the landed thread's workspace and resumed there by this tentacle. A session that began streaming before this was kept has nothing to fork. The installer also registers a PreToolUse hook for the gateway's teleport alone, which stamps the session's id into the call so the session can teleport itself; re-run the installer to add it.

Resuming a driven session natively skips already recorded driven turns when their runtime identity is available. See switching sessions for where new turns land and the limits for older history.

What the tail skips: transcript line types it does not model, and inline subagent relics from transcripts older than the per-file subagent layout.

Not yet¶

Remote hosts. An ssh block is parsed and warned about, not honoured. Runs stay local until workspaces can be forked on another machine.
Structured output returns whatever the CLI produced, validated once, with no retry loop.
Images in a prompt are dropped; the driven prompt is text.