Claude Code Adapter

The Claude Code adapter connects Sortie to the Claude Code CLI via subprocess management. It launches Claude Code in headless mode with --output-format stream-json, reads newline-delimited JSON (JSONL) from stdout, and normalizes events into Sortie’s own event vocabulary. Registered under kind "claude-code".

Each turn spawns an independent subprocess.

See also: WORKFLOW.md configuration for the full agent schema, environment variables for ANTHROPIC_API_KEY and provider routing, error reference for all agent error kinds, how to write a prompt template for template authoring.

Configuration

The adapter reads from two configuration sections in WORKFLOW.md front matter: the generic agent block (shared by all adapters) and the claude-code extension block (pass-through to the Claude Code CLI).

agent section

These fields control the orchestrator’s scheduling behavior. They are not passed to the Claude Code CLI.

agent:
  kind: claude-code
  command: claude
  max_turns: 5
  max_sessions: 3
  max_concurrent_agents: 4
  stall_timeout_ms: 300000

claude-code extension section

These fields are adapter-specific, and each maps to a Claude Code CLI flag. permission_mode and session_persistence are checked before any run starts; see validate-time checks. Every other value reaches the CLI as written and unvalidated by Sortie, except mcp_config, which the generated configuration supersedes; see Sortie’s own tools and the mcp_config field. Consult claude --help on your installed version for what each flag accepts and how the CLI reacts to an invalid value.

claude-code:
  permission_mode: bypassPermissions
  model: <model-id>
  fallback_model: <fallback-model-id>
  max_turns: 50
  max_budget_usd: 5
  effort: high
  allowed_tools: "Edit,Write,Bash"
  mcp_config: ./mcp-servers.json

agent.max_turns vs. claude-code.max_turns

These two fields have the same name but control different systems.

With agent.max_turns: 5 and claude-code.max_turns: 50, the orchestrator runs up to 5 turns. Within each turn, Claude Code takes up to 50 agentic steps. The total agentic step budget per session is at most 250.

Setting claude-code.max_turns too low causes Claude Code to exit mid-task. Setting agent.max_turns too low causes the orchestrator to stop re-invoking the agent before the issue is resolved.

Fallback model scope

The adapter forwards fallback_model to --fallback-model unchanged and does not validate or interpret it. The value may name a single model or a comma-separated list. Which failure classes Claude Code treats as fallback-eligible, and any limit on how many models a chain may name, are the CLI’s own behavior; see the external references for where to look it up.

Whatever the CLI decides applies only within the current invocation. The adapter spawns one CLI invocation per turn, and each turn starts that invocation with the configured primary model.

Sortie’s own tools and the mcp_config field

Sortie generates one MCP server configuration per session, declaring a sortie-tools stdio server that exposes Sortie’s own tools to the agent. That generated file, not the raw claude-code.mcp_config value, is what the adapter passes to --mcp-config, on a local launch and over SSH alike.

When claude-code.mcp_config names an operator-supplied file, Sortie reads it, parses its mcpServers object, and inserts the sortie-tools entry into it before writing the merged result. A relative path resolves against the directory containing WORKFLOW.md. If the operator’s file already defines a server named sortie-tools, generation fails with a name-collision error rather than silently overwriting it. If the file is missing, unreadable, or not valid JSON, generation fails with the underlying error.

Session persistence and resume

The adapter passes --session-id <uuid> on the first turn of a session it opened itself. Every other turn carries --resume <session_id> instead: each later turn of that session, and each turn of a session the orchestrator handed back from an earlier attempt, its first turn included. --resume reads the session file Claude Code wrote to disk.

session_persistence: false passes --no-session-persistence, and Claude Code then writes no session file for --resume to read. Sortie refuses that configuration before any run starts, as the agent.kind.session_resume error under validate-time checks.

The refusal is unconditional. It does not depend on agent.max_turns, on the configured reactions, on the retry budgets, or on tracker.handoff_state. A single-turn budget does not avoid the conflict either: Sortie re-dispatches an issue carrying its earlier session after a retry, a continuation, a stall, or a restart, so the first turn of such a dispatch is already a resumed turn.

Leaving session_persistence unset, or setting it to true, resumes normally. agent.max_turns defaults to 20, so a session ordinarily runs more than one turn.

Permission mode

Set permission_mode: bypassPermissions, or leave the field out. Those are the only two configurations that pass validation.

bypassPermissions approves every tool call without prompting. Every run is unattended, so a mode that can stop and prompt has nobody to answer it, and the claude-code.permission_mode.interactive error refuses any other value before the run rather than letting the session reach the prompt. The check is an allowlist rather than a list of known-asking modes, so a mode the CLI adds later is also refused until someone establishes what it does headless.

With the field absent the adapter passes --dangerously-skip-permissions instead, which bypasses the same checks. Which permission modes the CLI itself offers, and what each one does, is Claude Code’s to document; see the external references.

Runtime-denied tool calls

Under the launch flags Sortie passes, Claude Code exposes no route for answering a permission request: the runtime denies the call itself and carries on. The adapter recognizes that denial, reports it as a notification event, and takes one of two paths.

Validate-time checks

When agent.kind is claude-code, the sortie validate pipeline runs two checks over the claude-code block in addition to the generic preflight validation. Neither builds an adapter nor launches a subprocess, and both run at startup and on every workflow reload, so the verdict is identical in all three places. The first is declared by the adapter itself; the second is a generic preflight rule that reads the blocking key this adapter declares.

Errors

An absent permission_mode draws nothing: the adapter passes --dangerously-skip-permissions, which bypasses the same checks.

An absent session_persistence, and the value true, draw nothing. So does a value whose YAML type is not a boolean, such as the quoted string "false": the adapter reads a wrong-typed value as the default true, and the check reads it the same way, so the configuration validates and the flag is not passed. Both checks run for every agent kind the configuration can reach, so a claude-code block that only a dispatch rule routes to is checked as well.

Session lifecycle

Session start

Validates the workspace path and resolves the agent binary. No subprocess is spawned.

1. Validates that the workspace path is a non-empty absolute path pointing to an existing directory.
2. Resolves the command from PATH. In SSH mode, resolves the local ssh binary instead; the agent command resolves on the remote host.
3. Generates a v4 UUID session ID (or adopts the session ID saved from a previous run, for continuation sessions).
4. The session records the workspace path, resolved binary, session ID, and SSH configuration for later turns to use.

Errors:

Turn

Spawns a Claude Code subprocess, reads JSONL events from stdout, and delivers them to the orchestrator as they arrive.

1. Builds the CLI argument list from session state and pass-through configuration.
2. Spawns the subprocess in the workspace path, with the full parent process environment, and with the shutdown behavior described under process shutdown.
3. Reads stdout one line at a time (64 KB initial buffer, 10 MB maximum line length); stderr is drained separately.
4. Parses each line as JSON. A line that fails to parse becomes a malformed event, and reading continues.
5. Reaps the subprocess as soon as it exits and terminates its process group. This does not cut short output collection, since the adapter still holds both pipe ends open. After the reap, stdout and then stderr each get a fixed five seconds to finish, so a descendant process that inherited an output handle and outlived the agent cannot hold the turn open. Stderr is re-emitted at WARN level on any failing turn.
6. Classifies the outcome, ending the turn with a recorded session ID, exit reason, and cumulative token usage.

Session management flags:

Every invocation includes --output-format stream-json and --verbose.

Session stop

Terminates a running subprocess. Safe to call when no subprocess is active.

1. Sends a graceful shutdown signal to the process group (POSIX: SIGTERM; Windows: CTRL_BREAK_EVENT).
2. Waits up to stop_grace_ms for the process to exit.
3. Force-terminates the process tree if still running (POSIX: SIGKILL to process group; Windows: TerminateJobObject).

Process shutdown

By default, stopping a running subprocess sends an immediate kill signal, giving the agent process no chance to flush output buffers, close network connections, or emit final token-usage events. Sortie overrides that default: it sends a graceful shutdown signal instead (POSIX: SIGTERM; Windows: CTRL_BREAK_EVENT via the process group) and waits up to stop_grace_ms before force-killing the process (POSIX: SIGKILL; Windows: TerminateJobObject). This applies whenever Sortie stops the subprocess, whether the orchestrator initiated it (a reconciliation kill, stall detection, or a turn timeout) or Sortie itself received a shutdown signal.

On all platforms, the subprocess runs in its own process group. On Windows, it is additionally assigned to a Job Object with KILL_ON_JOB_CLOSE, so the entire process tree (including MCP servers and other children) is terminated on shutdown or if Sortie crashes. The subprocess starts suspended and is resumed only after that assignment succeeds, so nothing it spawns can run before the job takes effect. A failed assignment logs WARN process group assignment failed and the turn’s subprocess runs without a job; a failed resume logs WARN process resume failed and ends that turn as turn_failed with error kind port_exit. Because Claude Code launches a fresh subprocess every turn, a resume that keeps failing fails each subsequent turn the same way rather than only the first.

Session stop follows the same shape: it sends the graceful signal, waits up to stop_grace_ms, and force-kills the process group if the wait elapses. If the stop request is itself interrupted before the grace period elapses, the process group is still force-killed and the interruption is reported as the error.

Event stream

Claude Code emits one JSON object per line on stdout. The adapter parses each line and maps it onto Sortie’s normalized event vocabulary, so what reaches the orchestrator, the logs, and the dashboard is the same set of events every adapter produces. The CLI’s own message types and result payload are Claude Code’s to define; see external references.

Two mappings carry consequences a user can act on. A tool call the runtime denies becomes a notification, and a denied question to the user also ends the attempt with turn_input_required; see runtime-denied tool calls. A line that fails to parse becomes a malformed event, truncated, rather than failing the turn.

Token accounting

Reported token counts are cumulative over the whole session the orchestrator opened, across every turn of it, and never decrease. The result event at the end of each turn carries the authoritative figure for that turn; assistant events supply a provisional running estimate while the turn is still in flight. For this kind’s declaration beside every other kind’s, see the usage reporting table.

Accumulation logic

1. Each assistant event carrying a usage object contributes a provisional per-message figure, keyed by the message id. Claude Code repeats one message id across every streamed event of the same model request and grows the usage object as the response generates, so the adapter keeps the largest value seen per id rather than summing the repeats.
2. A token_usage event is emitted the first time a message id is seen, and not again for that id, so the count matches API requests rather than stream events.
3. On the result event, the per-model modelUsage breakdown is summed across every model entry, added to the session’s settled total, and the turn’s provisional contribution is cleared. The reported snapshot is raised against the highest snapshot already reported, so settling never lowers a figure the turn already published. The top-level usage object is used only when modelUsage is absent or empty. modelUsage is preferred because the top-level figure excludes sub-agent activity while the breakdown includes it. See how to use sub-agents.
4. In both shapes, input_tokens is the sum of the plain input count, cache-read tokens, and cache-creation tokens; cache_read_tokens carries the cache-read count separately as a subset of input; total_tokens is computed as input_tokens + output_tokens rather than read from any vendor total.

Model tracking

The model field from assistant events (e.g., <model-id>) is captured and included in token_usage events. The orchestrator uses this for per-model cost attribution.

API timing

The adapter measures wall-clock time between events to estimate per-request API latency:

• A monotonic timer starts after system/init (first API call) and after each user event (subsequent API calls).
• The timer stops when the next assistant event with usage data arrives.
• The token_usage event reports this measured duration as how long the API request took.
• If per-request timing is available, the turn-level duration_api_ms from the result event is not re-emitted to avoid double-counting.

Tool call tracking

The adapter observes tool execution by correlating tool_use and tool_result content blocks.

Correlation

1. An assistant message containing a tool_use block records the tool name and a start time, keyed by the block’s id.
2. A user message containing a tool_result block looks up the matching tool_use_id.
3. On a match, the adapter emits a tool_result event carrying the tool name, how long the call took since that start time, and whether it errored (from the is_error field on the content block).

Tool error formatting

When a tool_result carries is_error: true, the adapter extracts the error text and applies three transformations:

1. XML stripping: If the text is wrapped in <tool_use_error>...</tool_use_error>, the envelope is removed.
2. ANSI stripping: VT100/ANSI SGR escape sequences (color codes, formatting) are removed for clean log output.
3. Truncation: Error text exceeding 2048 bytes is truncated to the first line plus the last bytes of the remaining output. This preserves both the exit-code header and CLI failure lines at the tail.

Error handling

Turn outcome

The outcome is not decided by the exit code alone. The shared decision table evaluates evidence in a fixed order and returns on the first match, so a result event outranks the process exit status, and a recognized request for human input outranks both.

The human-input, cancellation, and exit-127 rows are decided before the adapter’s own classifier runs. The work test reads this turn’s own stream rather than the run-cumulative token figure. A message from the agent is a text content block carrying text on an assistant message; a tool call is a tool_use or tool_result block. Stderr from a failing turn is re-emitted at WARN level.

Stdout read failure

If output reading from stdout fails (buffer overflow, broken pipe), the adapter:

1. Sends a graceful shutdown signal to the process group.
2. Waits for exit.
3. Ends the turn as turn_failed with error kind port_exit.

SSH remote execution

When the worker configuration includes ssh_hosts, the adapter launches Claude Code on a remote host via SSH instead of locally.

How it works

1. Session start resolves the local ssh binary from PATH. The agent command is stored for remote execution rather than resolved locally.
2. Each turn builds an SSH command that wraps the remote Claude Code invocation.
3. The remote shell enters the workspace, exports the environment variables the launch carries, and only then runs the configured command with that turn’s arguments. Each step is chained on the success of the one before it, so the agent never starts in the wrong directory or without the variables it was to receive. The workspace path and each argument are individually single-quoted; the agent command is inserted as configured, unquoted, so a multi-token or env-prefixed command (e.g. FOO=bar claude) still runs as intended.
4. This kind declares ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, and CLAUDE_CODE_OAUTH_TOKEN as its credential variables, so a remote launch carries whichever of them Sortie’s own environment sets. A carried value overrides whatever the host holds under the same name.

SSH options

The adapter uses these SSH options:

Shell quoting

The workspace path and each per-turn CLI argument are single-quoted with embedded single-quote escaping (the standard POSIX '\'' pattern) before being placed in the remote command string. This prevents injection when SSH passes the remote command through the remote shell. The configured agent command itself is not quoted this way, since it may legitimately be more than one shell token.

Exit codes

SSH exit code 255 indicates a connection failure (refused, timeout, unreachable) and maps to port_exit. Exit code 127 means the remote agent binary is not in PATH and maps to agent_not_found.

Authentication

Sortie does not manage Claude Code’s API credentials. The adapter spawns the subprocess with the full parent process environment, and Claude Code reads its authentication variables directly.

The adapter runs no credential preflight and reads no credential variable for itself: starting a session succeeds whether or not the environment can authenticate the CLI. Which variables authenticate a given backend (Anthropic’s API, a cloud vendor’s hosted models, or a gateway in front of either) is Claude Code’s to document; see the external references and the environment variables reference.

The kind does declare three names, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, and CLAUDE_CODE_OAUTH_TOKEN, and they serve one purpose: a remote launch carries whichever of them Sortie’s own environment sets, so a build host needs no copy of its own. A local launch inherits all three with everything else, and the declaration changes nothing there.

A credential the CLI rejects therefore surfaces as a failing turn rather than as a session that refuses to start.

External references

• Claude Code overview: Anthropic’s official product documentation
• Claude Code CLI reference: every flag this adapter forwards (--permission-mode, --output-format, --resume, --mcp-config, etc.)
• anthropics/claude-code on GitHub: source repository, releases, and issue tracker
• Model Context Protocol specification: the MCP server protocol consumed via --mcp-config

Related pages

• WORKFLOW.md configuration reference: full agent schema and claude-code extension block
• Environment variables reference: ANTHROPIC_API_KEY, Bedrock, Vertex AI, and proxy variables
• Error reference: all agent error kinds with retry behavior
• How to control agent costs: per-turn budget, turn caps, session caps, and concurrency limits
• How to write a prompt template: template variables, conditionals, and built-in functions
• How to scale agents with SSH: remote execution setup and host pool configuration
• State machine reference: orchestration states, turn lifecycle, and stall detection