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 domain types. Registered under kind "claude-code".

Each RunTurn call spawns an independent subprocess. The adapter is safe for concurrent use: one adapter instance serves all sessions, with per-session state held in an opaque internal handle.

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. The orchestrator forwards them to the adapter without validation. Each field maps to a Claude Code CLI flag.

claude-code:
  permission_mode: bypassPermissions
  model: claude-sonnet-4-20250514
  fallback_model: claude-sonnet-4-20250514
  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.

Permission mode

When permission_mode is absent, the adapter passes --dangerously-skip-permissions as a legacy fallback. This flag is deprecated by the Claude Code CLI.

For autonomous workflows, set permission_mode: bypassPermissions explicitly.

Session lifecycle

StartSession

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

1. Validates that WorkspacePath is a non-empty absolute path pointing to an existing directory.
2. Resolves the command via exec.LookPath. 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 ResumeSessionID for continuation sessions).
4. Returns an opaque Session handle containing workspace path, resolved binary, session ID, and SSH configuration.

Errors:

RunTurn

Spawns a Claude Code subprocess, reads JSONL events from stdout, and delivers normalized events via the OnEvent callback.

1. Builds the CLI argument list from session state and pass-through configuration.
2. Spawns the subprocess with exec.Command (not exec.CommandContext - see process shutdown for rationale).
3. Sets cmd.Dir to the workspace path and cmd.Env to the full parent process environment.
4. Reads stdout line by line via a buffered scanner (64 KB initial buffer, 10 MB max line).
5. Parses each line as JSON and dispatches to the appropriate event handler.
6. After stdout closes, calls cmd.Wait to collect the exit status.
7. Returns a TurnResult with the session ID, exit reason, and cumulative token usage.

Session management flags:

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

StopSession

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 5 seconds for the process to exit.
3. Force-terminates the process tree if still running (POSIX: SIGKILL to process group; Windows: TerminateJobObject).

EventStream

Returns nil. The adapter delivers all events synchronously through the OnEvent callback in RunTurn.

Process shutdown

The adapter uses exec.Command instead of exec.CommandContext. This is intentional.

exec.CommandContext sends an immediate kill signal on context cancellation by default. The agent process cannot flush output buffers, close network connections, or emit final token-usage events. Instead, the adapter sends a graceful shutdown signal first (POSIX: SIGTERM; Windows: CTRL_BREAK_EVENT via the process group) and escalates to a force kill after 5 seconds (POSIX: SIGKILL; Windows: TerminateJobObject), preserving the agent’s opportunity for a clean exit.

On all platforms, the subprocess is placed in its own process group at launch. On Windows, the subprocess 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.

A dedicated goroutine monitors ctx.Done() and calls the graceful-kill sequence when the context is cancelled. This covers both orchestrator-initiated cancellation (reconciliation kill, stall detection) and shutdown signals.

JSONL event stream

Claude Code emits one JSON object per line on stdout when invoked with --output-format stream-json. The adapter parses each line and maps it to a normalized domain event.

Event type mapping

Result event fields

The result event carries turn-level metadata:

Token accounting

The adapter accumulates token counts across all assistant messages within a turn, because Claude Code reports per-request usage (not cumulative). The orchestrator expects cumulative values for its delta algorithm.

Accumulation logic

1. Each assistant event with a usage field increments the running totals for input_tokens, output_tokens, and cache_read_input_tokens.
2. total_tokens is computed as input_tokens + output_tokens.
3. The cumulative totals are emitted as a token_usage event after each assistant message.
4. If no per-message usage was emitted during the turn, the result event’s usage serves as the fallback. This avoids inflating the orchestrator’s API request counter.

Model tracking

The model field from assistant events (e.g., claude-sonnet-4-20250514) 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 measured duration is emitted in APIDurationMS on the token_usage event.
• 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 monotonic timestamp in an in-flight map, keyed by the block’s id.
2. A user message containing a tool_result block looks up the matching tool_use_id in the in-flight map.
3. When a match is found, the adapter emits a tool_result event with ToolName, ToolDurationMS (elapsed since the tool_use timestamp), and ToolError (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

Exit code mapping

Stdout scanner failure

If the stdout scanner encounters an error (buffer overflow, broken pipe), the adapter:

1. Sends a graceful shutdown signal to the process group.
2. Waits for exit.
3. Returns a turn_failed result 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. StartSession resolves the local ssh binary via exec.LookPath. The agent command is stored for remote execution rather than resolved locally.
2. RunTurn builds an SSH command that wraps the remote Claude Code invocation.
3. The remote command is: cd '<workspace_path>' && '<agent_command>' <args...>

SSH options

The adapter uses these SSH options:

Shell quoting

All arguments in the remote command string are single-quoted with embedded single-quote escaping (the standard POSIX '\'' pattern). This prevents injection when SSH passes the remote command through the remote shell.

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 (cmd.Env = os.Environ()), and Claude Code reads its authentication variables directly.

The required variable depends on the API provider:

See environment variables reference for the full list.

A missing ANTHROPIC_API_KEY is the most common deployment failure. Sortie starts and dispatches workers normally, but every agent session fails at launch. The failure is visible in Sortie’s logs as a worker exit with exit_type=error.

Concurrency safety

The adapter is safe for concurrent use. One ClaudeCodeAdapter instance serves all sessions. Per-session state (workspace path, session ID, process handle) is isolated in the opaque Session.Internal field. A mutex guards the subprocess handle for concurrent access from StopSession and the graceful-kill goroutine.

No adapter-level serialization is needed for RunTurn calls - each spawns an independent subprocess with its own stdout pipe and scanner.

Adapter registration

The adapter registers itself under kind "claude-code" via an init function in internal/agent/claude. Registration metadata declares:

The orchestrator’s preflight validation uses this to produce a specific error message if the binary cannot be found before attempting session creation.

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