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 SIGTERM to the subprocess.
2. Waits up to 5 seconds for the process to exit.
3. Sends SIGKILL if the process has not exited.

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 SIGKILL on context cancellation by default. SIGKILL is immediate and untrappable — the agent process cannot flush output buffers, close network connections, or emit final token-usage events. The adapter sends SIGTERM first and escalates to SIGKILL after 5 seconds, preserving the agent's opportunity for a clean exit.

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-kill signal to the subprocess.
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.

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 write a prompt template — template variables, conditionals, and built-in functions
• How to scale agents with SSH — remote execution setup and host pool configuration
• How to use the file adapter for local testing — test prompts without a live tracker
• State machine reference — orchestration states, turn lifecycle, and stall detection
• Dashboard reference — live monitoring of running sessions and token usage
• Prometheus metrics reference — sortie_agent_turns_total and related counters
• Agent extensions reference — tracker_api tool available during agent sessions