tutti/docs/architecture/claude-code-sdk-runtime.md

# Claude Code SDK Runtime

Claude Code has one supported runtime path: the daemon starts the
`@tutti-os/claude-sdk-sidecar` package, and the sidecar talks to the Claude Agent
SDK.

The product-fidelity and acceptance contract is maintained in
[Claude Code SDK Refactor Fidelity Requirements](./claude-code-sdk-requirements.md).

## Boundary

```mermaid
flowchart LR
    Service["tuttid agent services"] --> Adapter["Go Claude SDK adapter"]
    Adapter <-->|"versioned NDJSON over stdio"| Sidecar["TypeScript SDK sidecar"]
    Sidecar --> SDK["Claude Agent SDK"]
    Adapter --> Activity["normalized agent activity"]
    Activity --> Consumers["Agent GUI and other consumers"]
```

The public boundary is normalized agent activity and capability data. The GUI
must branch on capabilities or event semantics, not on the Claude Code provider
name. Claude-specific SDK messages, tool shapes, session cursors, and transport
details stay behind the daemon adapter and sidecar.

## Daemon ownership

The Go runtime under `packages/agent/daemon/runtime` is split by responsibility:

| Module                         | Ownership                                                |
| ------------------------------ | -------------------------------------------------------- |
| `claude_sdk_adapter.go`        | Adapter construction, shared state, and sink wiring      |
| `claude_sdk_lifecycle.go`      | Session start, resume, close, and live-session release   |
| `claude_sdk_execution.go`      | Prompt validation, execution, guidance, and cancellation |
| `claude_sdk_settings.go`       | Live settings and permission-mode application            |
| `claude_sdk_transport.go`      | Sidecar process and NDJSON transport                     |
| `claude_sdk_protocol.go`       | Protocol version and envelope validation                 |
| `claude_sdk_session.go`        | Session storage, command/env helpers, and state payloads |
| `claude_sdk_events.go`         | Sidecar event dispatch and lifecycle routing             |
| `claude_sdk_turn.go`           | Per-turn event lifecycle via shared `acpTurnNormalizer`  |
| `claude_sdk_activity.go`       | Conversion into normalized activity events               |
| `claude_sdk_live_state.go`     | Live message, task, and usage state reconciliation       |
| `claude_sdk_interactive.go`    | Approval and interactive prompt handling                 |
| `claude_sdk_goal.go`           | Goal and plan lifecycle projection                       |
| `normalized_session_events.go` | Protocol-neutral session activity projection             |

The descriptor selects the SDK runtime kind; these adapter modules own the
process/session lifecycle and normalization behind that selection. They must not expose
raw SDK envelopes to services or GUI packages. Service-layer provider catalogs,
composer profiles, targets, status probes, and identity projections consume the
same `ProviderDescriptor` instead of re-registering Claude Code locally.
Provider preparation may inject system-prompt and plugin paths that exist only
in the sidecar runtime filesystem. The Go adapter treats those environment
values as opaque and forwards them unchanged; `options.ts` reads and validates
the referenced files after the sidecar starts. Daemon code must not inspect
those paths because remote transports do not share its filesystem.
Claude modules do not call ACP _protocol_ helpers (session-update decoding,
standard ACP tool-call envelopes, and similar). Open tool-call bookkeeping and
turn `Finish*` settlement reuse the shared adapter turn lifecycle
(`acpTurnNormalizer`), the same entity Codex and standard ACP already use, so
cancel/fail/complete close dangling tool cards instead of leaving them
in progress. Protocol-neutral session and interactive activity projection have
their own modules, while Claude goal, command, usage, and interaction decoding
stay inside the Claude SDK boundary.
Claude Goal state comes only from provider-owned Goal observations. The
sidecar normalizes both SDK `active_goal` messages and native `/goal`
`goal_status` transcript attachments into one `goal_observed` event. Local
Claude Agent SDK `0.3.220` streams omit those attachment records from the
public `SDKMessage` iterator. The root `system/init` message supplies the
provider Session ID and cwd; `goalTranscript.ts` mirrors the pinned SDK's local
project-key algorithm to locate its JSONL. Restore starts from the already
known provider Session ID, while a generation-scoped `SessionStart` callback
can still supply the SDK-provided exact `transcript_path`. The reader consumes
only rows appended after observation began, drains once before the root result
settles, and continues following the file because Claude's native evaluator
may flush the final `goal_status` just after the SDK result. Starting at the
existing end of file prevents a restored session from replaying an old active
or completed Goal. A
non-null `active_goal` or `goal_status.met=false` keeps the condition active;
`goal_status.met=true` completes it. A null `active_goal` is interpreted as
explicit clear or completion using the exact command action and previous Goal
observation. Ordinary Turn completion has no Goal semantics.
Command-consumption evidence travels as the internal `goal.control_applied`
event to the Host Goal lane and must never be embedded in session runtime
context.
New normalized session updates use `sessionUpdateKind`; the former ACP-named
metadata key is accepted only while reading imported or durable historical
events.

Context usage is published only when the provider reports a context-window
limit or the live Session already has a provider-reported limit for the same
model. Token deltas from a new Session do not synthesize a 200k or 1M
denominator from the model name; AgentGUI keeps usage hidden until the first
authoritative window arrives. Restore/resume must not await that snapshot
before `session_started`: Host Resume/Send completes on the start handshake,
and usage may refresh asynchronously afterward.

Model selection preserves requested and resolved state separately. The model
config option's `currentValue` remains the user's selection, including
`default`, while `effectiveValue` is the concrete model reported by the
per-user SDK runtime. The sidecar begins consuming the Query after
`session_started` so the SDK's `system/init.model` can publish that fact before
the first prompt; root assistant messages continuously reconcile it. A live
switch back to `default` clears the previous effective value until the SDK
reports the newly resolved model. Hosts and renderers must not derive the
effective model from the advertised Default option's label or description.

Claude credential-sensitive operations share the process-wide gate owned by
`services/tuttid/service/claudecode`. Real session startup, hidden model
discovery, and `claude auth status` acquire this same gate. The AgentGUI's
initial provider demand only checks local availability; Anthropic usage is
queried after the user opens a usage surface or explicitly refreshes it.

Composer model discovery uses an account-level scope made from provider,
agent-target identity, and a non-secret auth fingerprint. It intentionally does
not include workspace or caller cwd for Claude Code, so switching workspaces
cannot create duplicate discovery processes. The process runs from the
daemon-owned discovery directory. A composer request waits at most 20 seconds,
but that wait does not cancel the SDK initialization: the background lifecycle
may continue for up to ten minutes so OAuth refresh state can be persisted.
Transient failures before a session starts remain retryable. Auth invalidation
marks in-flight results superseded and clears caches, but never closes a hidden
discovery session early; the original ten-minute lifecycle remains responsible
for teardown so credential refresh has time to finish persisting.
The descriptor's `CLAUDE_CONFIG_DIR` root override is honored consistently by
runtime endpoint discovery, status/custom-config inspection, and auth watching.

## Sidecar ownership

`packages/agent/claude-sdk-sidecar/src/main.ts` is only the stdio server and
request router. `sessionRuntime.ts` coordinates a session through focused
collaborators:

- `protocol.ts` and `eventSink.ts`: versioned wire envelopes and event emission.
- `sessionConfiguration.ts`, `sessionSettings.ts`, and `options.ts`: SDK query
  configuration and mutable session settings.
- `promptQueue.ts` and `turnLifecycle.ts`: prompt ordering and turn ownership.
- `goalExecQueue.ts`: queued Goal command ordering and supersession.
- `goalProjection.ts` and `goalTranscript.ts`: provider Goal normalization and
  narrow recovery of SDK-omitted transcript evidence.
- `queryGeneration.ts` and `queryHooks.ts`: one SDK Query execution generation,
  its prompt/abort resources, and generation-scoped SDK hooks.
- `messageRouter.ts`, `messageProjection.ts`, `assistantStream.ts`, and
  `sdkMessages.ts`: SDK message routing and assistant output projection.
- `toolActivity.ts`, `toolEvents.ts`, `toolActivityTypes.ts`, `taskPlan.ts`, and
  `taskNotification.ts`: normalized tool, delegated-task, and plan activity.
- `interactive.ts` and `interactiveTurnResolver.ts`: approvals, interactive
  questions, and canonical Turn ownership resolution.
- `compaction.ts` and `usage.ts`: context compaction and usage reporting.
  Restore/resume publishes `session_started` before refreshing context usage;
  `getContextUsage()` runs in the background and must not gate Host Resume.
- `authDiagnostics.ts`, `errors.ts`, and `runtimeValues.ts`: diagnostics and
  small runtime value helpers.
- `testDriver.ts`: isolated deterministic sidecar-driver behavior used by
  runtime integration tests.

The dependency direction is from `main.ts` to `sessionRuntime.ts`, then to these
collaborators. Collaborators must not import `main.ts` or own the stdio loop.
Projection modules emit typed sidecar events; they do not call daemon or GUI
code.

The outbound root user UUID is correlation evidence, not provider identity.
Normally the live SDK iterator returns the persisted root user message and the
sidecar binds its UUID before projecting the provider Turn. A successful query
may omit that echo and begin with assistant output or an interactive tool.
Every root assistant, stream, tool, approval, user-input, and result path enters
one shared single-flight identity barrier before projection. The barrier reads
the official provider transcript, resolves exactly one root user message by the
opaque correlation UUID, and emits `provider_turn_identity_resolved` with the
latest persisted checkpoint. A bounded cancellable retry handles short
transcript write delay; absence at the deadline and ambiguity fail explicitly.

The Go adapter converts the resolved identity into a durable acceptance
receipt. Its event reader blocks until the Host atomically persists the
canonical Turn, provider Session, and provider Turn mapping. The canonical
`root_provider_turn.started` is published exactly once before streaming or
interactive activity is released. Provider start, checkpoint, and completion
never derive identity from the outbound UUID alone.

Raw sidecar stderr is never copied into activity, logs, or user-visible errors.
The Go transport retains only a bounded failure classification; explicitly
prefixed auth diagnostics are separately sanitized before structured logging.

SDK Query lifetime is narrower than durable provider-session lifetime. The
sidecar owns Query termination; an RPC caller deadline alone is never treated
as cancellation because it cannot stop an already-dispatched SDK control
request. A user cancel carries the exact canonical Turn, a cooperative
interrupt budget, and a consumer-drain budget, and returns one structured disposition:
`pre_accept`, `provider_active`, `absent`, or `mismatch`. An undispatched queue
entry can be removed locally. Once the prompt has been dispatched, cancel first
revokes the current Query generation and requests the SDK interrupt. If Claude
Code acknowledges within the cooperative budget, shutdown remains graceful. If
the acknowledgment is missing or fails, the sidecar closes the owned SDK Query
transport; the pinned SDK then ends stdin and escalates its Claude Code child
from `SIGTERM` to `SIGKILL`. The sidecar waits only for the separate drain budget
for its consumer to settle. A drain timeout is an explicit bounded failure and
never leaves the request pending. Revocation fences message routing, hooks, and
`canUseTool` before permission-mode handling, including `bypassPermissions`;
background-task notifications from the canceled generation therefore cannot
start a synthetic continuation or execute another tool. Every Turn already
handed to the retired Query's prompt queue settles after that same authoritative
shutdown boundary, including a drained Goal command that can no longer execute;
a Goal command still in the sidecar's deferred queue is independent and remains
eligible for exact local removal. For a
`provider_active` response, the Go adapter also waits for the exact Turn's
durable provider-acceptance outcome before confirming cancellation. `absent`
is the only authoritative not-found result; mismatches, unknown dispositions,
drain failures, and acceptance failures remain fail-closed. The next real
user prompt creates a fresh Query with
`resume: providerSessionId` and generation-local prompt/abort resources. If the
SDK replays the canceled generation's terminal task notification and paired
result during resume, the new generation consumes that tail without attaching
it to the new canonical Turn. Session close remains permanent and closes the
current generation without creating a resumable successor.

The Go adapter also tracks each accepted-but-not-started typed Goal command by
its operation, revision, repair epoch, action, and previous optimistic Goal
mirror. A Goal-generation fence targets both those pending commands and Turns
that already have provider bindings. When the sidecar confirms an exact pending
Goal cancellation, the adapter removes its bookkeeping and restores the
previous mirror only while that same identity is still current, so a stale
cancellation cannot overwrite a newer Goal. `goal_command_started` records
provider progress but does not commit the optimistic mirror; an authoritative
Goal observation or successful command terminal commits it, while cancellation,
failure, or supersession closes the exact pending transaction.

Guidance preempts a provider response without ending its canonical Turn. The
sidecar captures the already-active Query and calls its SDK `interrupt()` before
the guidance handler first yields; it never waits for query creation or pending
configuration while the old response continues. As soon as that interrupt
succeeds, the sidecar emits `guidance_interrupted`, and only then queues the
guidance prompt. The daemon uses that response boundary to settle open thinking,
assistant, and tool projections without emitting a Turn terminal. Claude's
later matching `error_during_execution` is bookkeeping only. Output produced
for the guidance then starts a fresh response projection on the same canonical
Turn.

Background-task lifecycle uses the SDK's `background_tasks_changed` system
message as a level signal. Its `tasks` array fully replaces the previous live
set. An empty set means the background children have quiesced; it does not mean
the root Turn is complete. When a successful ordinary root result arrives while
a background continuation is already pending, the sidecar retains the original
root Turn until session idle instead of emitting a terminal/start pair. If the
root result already settled before the pending signal, the sidecar reserves a
synthetic continuation. It remains in the existing running phase,
and results with `origin.kind = task-notification` confirm background
follow-up output without settling it by notification/result count. The SDK's
`session_state_changed: idle` event is the authoritative turn-over edge after
the held-back result and background-agent loop drain. The sidecar does not
start a post-result settlement timer: queued follow-ups may legitimately begin
several seconds apart, and interrupting that queue fabricates provider errors.
If root output does not begin within 30 seconds, the sidecar emits the
`continuation_delayed` warning, completes the synthetic reservation with
`background_agent_continuation_timeout`, interrupts the pending SDK query, and
rejects that continuation's late output so it cannot attach to a later Turn.

Exact task terminal events and the level signal are not ordered by contract.
The sidecar therefore waits for a short quiescence grace after the live set
becomes empty. Exact terminal edges received during that window win; after the
window, the daemon marks only still-unresolved asynchronous child Turns as
interrupted. Background-level diagnostics record aggregate counts for tasks
observed by the SDK level signal and exact delegated-task states known to Tutti.
This makes missing terminal edges visible in logs while leaving the GUI's
existing running/processing presentation unchanged.

The background-task level tracker owns its quiescence timer and continuation
reservation state. Query cancellation clears both before interrupting the SDK.
A failed or canceled root result fences later empty-level and task-notification
signals from opening a synthetic continuation, while those signals may still
report diagnostics or settle their exact child lifecycle.

The daemon resolves one owner for each Claude tool event before both closed-Turn
admission and activity projection. A delegation call belongs to the Session
that launched the child; an ordinary tool executed by a child belongs to that
child. Settling the child therefore cannot suppress a later completion of its
still-open parent Agent call, and repeated parent updates cannot move a terminal
child back to running.

The SDK may also report one completed child twice: first as `task_updated` with
only its task description, then as `task_notification` with the actual result.
The first edge settles the child lifecycle; the later notification updates the
same child assistant-message snapshot and marks its root continuation pending.
Several queued notifications may be coalesced into fewer follow-up results, so
they share the currently active root provider Turn or one reserved synthetic
Turn. Result origin identifies those follow-ups; session idle, rather than a
cardinality comparison, terminates the shared continuation.

## Protocol and compatibility

The daemon and sidecar exchange newline-delimited JSON over standard input and
output. Every request and event carries the current protocol version. Missing
or unsupported versions fail explicitly. Change both
`claude_sdk_protocol.go` and `src/protocol.ts` together and cover the change on
both sides. Version 10 makes the cooperative-interrupt and consumer-drain
budgets required cancel-request fields. Version 9 makes the cancel disposition, exact canonical Turn ID,
provider Turn ID, and dispatch phase correctness-required response fields.

Capability and composer contracts are intentionally stable across this runtime
split. Imported historical metadata may still be read for display compatibility
without affecting runtime selection.

Desktop packaging runs the deterministic sidecar protocol smoke twice: once
after production dependencies are vendored, and again from the final Electron
Resources directory after symlinks have been replaced. Both checks must complete
`start`, `exec`, and `close` without reading repository sources.

The vendored bundle excludes the native `claude` executable (it still carries
the SDK's JS, type metadata, and `manifest.json`). The binary the SDK spawns
is provisioned at runtime by tuttid from the CDN (npm mirrors as fallback),
pinned and verified against the vendored SDK's `manifest.json` (see
`services/tuttid/service/agentstatus/claude_binary.go`). The sidecar picks the
executable in `src/executablePath.ts`: an explicit `CLAUDE_CODE_EXECUTABLE`
always wins, a native package next to the SDK (dev tree) comes next, and
`TUTTI_CLAUDE_CODE_FALLBACK_EXECUTABLE` — the provisioned binary or a
PATH-installed claude, chosen by `runtimeprep.ClaudeCodePreparer` — covers the
packaged app.

`close` is a request/ack boundary, not a fire-and-forget signal. The sidecar
awaits SDK query shutdown before replying `ok`; the daemon only then closes
stdin and the process. Transport reads are context-aware so a request timeout
can stop waiting without implicitly killing a provider process.

## Code health and validation

Production business files follow the repository limit of at most 800 lines.
Before adding another responsibility to a file near that limit, extract a
named collaborator with one owner and a directed dependency. Tests are grouped
by session, assistant streaming, delegated tasks, nested tasks, interaction,
and lifecycle behavior rather than collected in one fixture file.

Run these focused checks after changing the runtime:

```sh
cd packages/agent/claude-sdk-sidecar
pnpm typecheck
pnpm test
pnpm exec oxlint src

cd ../daemon
go test ./runtime
golangci-lint run ./runtime/...
```

Also run `pnpm check:changed` from the repository root for cross-package
contracts and packaging checks.