Crate supercode 

Backwards-compatible composition facade for Supercode.

New integrations should select the narrow package they need: supercode-interchange for session glue, supercode-reduce for reversible token reduction, supercode-runtime for provider/runtime primitives, or supercode-harness for the complete native Supercode agent and tool loop. This crate preserves the historical supercode import by re-exporting the complete harness surface.

Modules

acp_frontend

First-class ACP client implementation of the canonical SDK runtime.

acp_server

Inbound Agent Client Protocol adapter for the SDK-owned Supercode runtime.

audit

Corpus coverage audit.

background

Compatibility path for native background-job state.

catalog

Compatibility path for session catalogs and durable locators.

checkpoint

§2 module 20 checkpoint (COMPOSABLE-HARNESS-DESIGN.md line 470): file checkpointing / shadow-git; D4-adjacent revert; D3 turn-diff tracking. Line 1504: “restores FILES, not context — pairs with, never replaces, the reduction sidecar.”

claude_compat

Claude Code project compatibility helpers.

claude_peer

Live Claude Code peer sessions: registry discovery and message delivery.

claude_runtime_scheduler

Deterministic execution cursor for imported Claude cron and wakeup state.

claude_runtime_state

Lossless, non-executing reconstruction of Claude Code runtime state.

codex_peer

Live stock-Codex session discovery.

configfile

§3 “The Single Config File” (docs/composable-harness/COMPOSABLE-HARNESS-DESIGN.md) — P1 of the composable-harness migration (design §5.2, phase P1).

fidelity

Compatibility path for canonical interchange fidelity measurements.

formatters

§2 module 29 formatters (COMPOSABLE-HARNESS-DESIGN.md line 479): “D10/oc§10 format-on-write” — reuses the EXACT crate::tools::WriteObserver seam P5-9 built for checkpoint (D-5: “write-path interception seam shared with checkpoint”), rather than a second interception point.

frontend

Protocol-neutral frontend contract for one SDK-owned Supercode runtime.

git_metadata

P4e (COMPOSABLE-HARNESS-DESIGN.md §1.6/§3.1 core.session.git_metadata, catalog:331 “Git integration (metadata, diff, PR)”): a persisted, TYPED record of the git branch/sha/dirty state a session was RUNNING under, captured ONCE at session start (closes the loop catalog:331 flags — supercode already preserves a foreign session’s own git-shaped fields byte-for-byte on IMPORT via Session::raw’s verbatim capture; this is the WRITE half: supercode’s OWN sessions get the same provenance). Deliberately flat/typed (not a formatted string), the exact same rationale as crate::usage_log::UsageRecord/ crate::model_change::ModelChangeRecord (§1.13): a translatable, lossless session-data channel, not a lossy notice — so it survives a save/load round trip byte-for-byte, and a future reader (a translator, doctor/inspect stats) can consume it without re-parsing prose.

harness_service

Versioned, language-neutral service over persisted harness sessions.

human_export

P4e (COMPOSABLE-HARNESS-DESIGN.md §1.6/§3.1 core.session.export_format, catalog:283 “transcript export for humans”): a READ-ONLY rendering of a crate::Session’s conversation into text a human reads directly (terminal/file/clipboard) or opens in a browser — CC’s /export+/copy, CX’s Ctrl+O copy-last. This is core, not gated by the session.share module (§1.6: “export-to-human is universal while share links … are the OC+PI-only part session.share actually narrows to”).

interop_settings

Harness-owned controls that materially affect Supercode interoperability.

live_runtime

Trusted local receipts for attachable Supercode runtimes.

lsp

§2 module 28 lsp (COMPOSABLE-HARNESS-DESIGN.md line 478): “D1 LSP diagnostics in edit path + query tool” — this module ships the WEAKEST FORM that satisfies D1: server LIFECYCLE for a HANDFUL of user-configured language servers, and diagnostics surfaced in the edit/write TOOL RESULT via the shared D-5 write-path seam (crate::tools::WriteObserver, P5-9/P5-11).

mcp

P5-2 (COMPOSABLE-HARNESS-DESIGN.md §2 module 15 mcp.client, D7 rows 1-8): full Model Context Protocol client support — stdio (P5-1 baseline, GROWN not rewritten), remote HTTP/SSE transports, resources + templates, prompts-as-commands, server instructions, and elicitation — plus the handle_request / serve_stdio harness-as-MCP-server direction (module 16).

mcp_oauth

P5-2 (COMPOSABLE-HARNESS-DESIGN.md §2 module 15 D7 row 2 “OAuth”; §2.1 dep “model.oauth → trust-grade token storage” — the same security class applies here): OAuth PROTOCOL support for authenticated remote MCP servers.

model_catalog

§2 module 26 model.catalog (docs/composable-harness/ COMPOSABLE-HARNESS-DESIGN.md §3.1 [capabilities.model_catalog]) — P4 of the composable-harness migration (design §5.2 phase P4: “aliases + fallback chains (userconfig.rs:386-411) promoted into core” + the small_model knob).

model_change

P4c (COMPOSABLE-HARNESS-DESIGN.md §5.2 “P4” core NEW-significant item, §1.10/§3.1 core.model_switch.allow_switch, D9 row): a persisted, TYPED record of a mid-session model switch — pi’s model_change precedent (design §1.10: “persisted change records … pi’s model_change is the cleanest precedent”). Deliberately flat/typed (not a formatted string), mirroring crate::usage_log::UsageRecord’s exact rationale: a translatable, lossless session-data channel (§1.13), not a lossy notice — so it survives a save/load round trip byte-for-byte in the fields that matter, and a future reader (a translator emitting this same session under another harness’s format, a doctor/inspect stats command) can consume it without re-parsing prose.

modules

§2 “The Bolt-on Capability Taxonomy” (docs/composable-harness/ COMPOSABLE-HARNESS-DESIGN.md) — P3 of the composable-harness migration (design §5.2, phase P3: “A ModuleId enum (the 35 names) + resolved activation set on Config”).

permissions

P5-1 (COMPOSABLE-HARNESS-DESIGN.md §2 modules 10-11, §2.1 D-3, §2.2 C5, §5.3 risk 1): the permissions engine — command canonicalization + rule algebra + approval policy/cache + oc/cx import translators.

plugins

P5-12 (COMPOSABLE-HARNESS-DESIGN.md §2 module 18 plugins, D7 “in-process extension API, packaging/marketplaces, custom tools from files, provider injection, extension UI, plugin/package installation”; §2.1 D-10: “config-borne code execution without a trust gate is an injection hole”).

presets

§4 “Presets” (docs/composable-harness/COMPOSABLE-HARNESS-DESIGN.md) — P2 of the composable-harness migration (design §5.2, phase P2).

pricing_ref

Reference pricing constants used only to translate measured byte/token savings into a dollar figure in test logs and docs (D15). These are stated constants for one Opus-class API list price (July 2026) — not a live lookup, and not used anywhere on the request path.

reduce

Compatibility facade for optional reversible reduction.

runtime

Primitive live-runtime contracts and the Codex app-server reference adapter.

runtime_lease

Transport-neutral observer and controller leases for live SDK runtimes.

runtime_registry

Authenticated inventory and attachment for live and persisted sessions.

sandbox

P5-10 (COMPOSABLE-HARNESS-DESIGN.md §2 module 12 permissions.sandbox, ~row 462): the OS-level enforcement BACKSTOP permissions.rules’ rule-layer floor and the file-tool crate::tools::SandboxPolicy both defer to for full coverage (crate::permissions module doc: “complete OS-level write confinement of arbitrary bash… is capabilities. permissions.sandbox’s job (P5 module 10, a later unit), not this one’s” — this IS that unit).

schema

Typed schemas for the on-disk session formats.

sdk

Versioned public SDK contract shared by every Supercode surface.

server

§2 module 31 server (COMPOSABLE-HARNESS-DESIGN.md, D7 “full programmatic RPC/HTTP server”, D8 “remote attach”, D10 “daemon”; §1.9 Obligation 9’s out-of-process half — the in-process SDK already meets the core commitment via crate::EventSink).

session

Compatibility path for canonical sessions and native codecs.

session_activity

Protocol-neutral activity for persisted and live harness sessions.

session_index

Revisioned session-list subscriptions for latency-sensitive frontends.

session_title

P4b (COMPOSABLE-HARNESS-DESIGN.md §5.2 “P4”, §1.6/§3.1 core.session.auto_title, catalog:150, D-9): auto-title / session summary — a small-model side-call that titles a session, mirroring crate::reduce::summarize’s plumbing exactly: an injectable trait (real implementations call out to a model; this crate’s own tests only ever inject deterministic fakes — no real network/model call anywhere in this crate, same posture as crate::reduce::summarize::SpanSummarizer), a fixed versioned prompt, and a “never blocks, never fails the caller” contract.

session_tree

Compatibility path for canonical session trees.

sidecar

Compatibility path for native interchange sidecars.

store

A directory-backed store for supercode’s own sessions — naming, titles, listing, archiving, and deletion. The analog of claude --name / the Codex resume/archive/delete session lifecycle.

subagents

P5-3 (COMPOSABLE-HARNESS-DESIGN.md §2 module 9 subagents: “D1 spawn tool; D3 sub-agents/named-defs/background+resume/teams; D5 subagent transcripts”; §2.1 D-1 “subagents → core.session(lineage), core.tools; background-mode → permissions.approvals”; §2.2 C6): the data shapes and pure-function resource-bound checks the spawn/join/background machinery in crate::agent::Agent builds on. Kept separate from agent.rs so the depth/concurrency-cap arithmetic and the lineage record shape are unit-testable without a full Agent/mock-Provider harness — the same “pure config → set, testable without the loop” precedent P3’s crate::modules module documents for itself.

support

Canonical implementation inventory for external coding harnesses.

tokens

Compatibility path for native runtime token budgeting.

tools

Tools the agent can call.

tui

P5-4 (COMPOSABLE-HARNESS-DESIGN.md §2 module 30 tui; §1.9 recorded deviation; §2.1 tools.question/permissions.approvals(ask-UI) → tui|server): the full-screen interactive TUI, AND — because §2.1 names it as the interactive surface three EARLIER phases explicitly deferred here — the home for the three handlers that close those deferred chains:

usage_log

P4b (COMPOSABLE-HARNESS-DESIGN.md §5.2 “P4”, §1.6/§3.1, catalog §4a “Turn/step usage records surfaced per turn”): persisted per-turn token/usage records. crate::AgentEvent::Usage already streams this data live (UX-23); this module makes it DURABLE session data — a typed, serde-round-trippable record, not a lossy display-only channel (§1.13’s lossless/sidecar discipline: this is typed session data, exactly like crate::reduce::ReductionLog, not a text notice).

watch

Compatibility path for passive session following.

Structs

AcpFrontendCheckpoint

Durable delivery cursor for restarting an ACP frontend without replaying events it already consumed.

AcpFrontendConnectOptions

Connection parameters for one ACP frontend attachment.

AcpFrontendRuntime

ACP transport implementing the same SdkRuntime consumed by local and HTTP frontends.

AcpRuntimeBackend

Generic ACP v1 client backend for any ACP agent command.

Agent

A stateful agent: configuration, a model transport, a tool set, and the running conversation. Drive it with Agent::send.

ChatMessage

A single message in a conversation.

ChatRequest

A single model-completion request.

ClaudeBackgroundChild

Latest known state of a Claude Agent tool call.

ClaudeCodeRuntimeBackend

Claude Code live-runtime backend using bidirectional stream-json print mode. It can create/resume sessions and cancel the running turn through the stream-json control channel; the print-mode protocol still exposes no permission-response primitive to this adapter.

ClaudeCronJob

One active Claude Cron job.

ClaudeCronScheduleState

Persisted execution cursor for one Claude cron.

ClaudePeerDelivery

Successful hand-off of one message to a live session.

ClaudePeerEndpoint

Opaque addressing string published on a discovered descriptor.

ClaudePeerRefusalError

A refusal paired with the detail that names it.

ClaudePeerSession

One live Claude Code session: a registry record whose pid answered kill(pid, 0) during the read that produced this value.

ClaudePeerSettings

The user-settings portion Supercode can inspect without pretending to know a target process’s complete managed/project/CLI precedence stack.

ClaudeQueueState

End-of-transcript queue state.

ClaudeRuntimeDeliveryState

Persisted claimed-but-unacknowledged prompt.

ClaudeRuntimeManifest

A pure, serializable reconstruction of runtime state in a Claude transcript.

ClaudeRuntimePosture

Latest Claude CLI mode and permission posture.

ClaudeRuntimeResidue

Verbatim evidence for one runtime-affecting source record.

ClaudeRuntimeSchedulerState

Persisted scheduler cursor. Empty/default state keeps pre-scheduler manifests backward compatible and inert.

ClaudeRuntimeTrigger

One prompt made executable by an explicit scheduler claim.

ClaudeWakeup

One scheduled one-shot wakeup that has not yet observably fired.

ClaudeWakeupScheduleState

Persisted execution cursor for one Claude scheduled wakeup.

CodexRuntimeBackend

Codex live-runtime backend using the official codex app-server JSONL protocol (initialize, thread/start|resume, turn/start|interrupt).

Config

Everything that shapes an crate::Agent: the model and endpoint, the credentials, sampling parameters, the system prompt, and per-tool overrides.

ConfigBuilder

Fluent builder for Config.

ConfigFile

A config file: a set of named profiles (the analog of Codex -p/--profile). This is the SDK/embedder config surface; the supercode CLI uses a separate TOML config (userconfig::FileConfig in the cli crate) and does not expose this file or a --profile flag.

ConfigProfile

The serializable subset of a Config that can live in a config file. (Callbacks/handlers are code-only and are not represented here.)

ContextInjectionBlock

P4e (§1.4/§3.1 core.context_injections): one named ambient context block – see Config::context_injection_blocks.

CoordinatedRuntime

Shared transport-neutral owner of a runtime and its client leases.

CoordinatedRuntimeClient

Authenticated client projection of one coordinated SDK runtime.

DiscoveryPage

One stable newest-first discovery page.

DiscoveryQuery

Filters and roots used for one catalog scan.

FidelityMetric

Result of measuring one actual translation cell.

FidelityResidue

Measured residue of one actual export/reload cell.

FrontendActions

Actions the current runtime adapter can actually perform.

FrontendAttachSnapshot

Serializable half of an attachment returned by an out-of-process runtime. The live receiver is transport-owned and joined to this snapshot locally.

FrontendAttachment

Atomic history/replay/live attachment to one runtime.

FrontendCommandDescriptor

One runtime-provided command surfaced by a composer.

FrontendDisplayCapabilities

Display semantics emitted by the runtime.

FrontendEvent

Canonical event before a wire transport adds subscription metadata.

FrontendOperationDescriptor

One operation the runtime can genuinely invoke.

FrontendRequest

One pending interactive request, emitted as a sequenced frontend event.

FrontendRuntimeDescriptor

Complete frontend-facing description of one SDK-owned runtime.

FrontendRuntimeMetadata

Source/emulation identity supplied by the session-loading surface.

FunctionCall

The function payload of a ToolCall.

GeneratedFrontendClient

Generated typed Rust client over any facade transport.

HarnessCatalog

Read-only entry point for discovering, loading, and following persisted harness sessions.

HarnessConfig

The top-level schema (§3.1): one TOML/JSON document that fully determines the harness’s shape (§3.0: “Everything the harness does is a function of the resolved file”).

HarnessEvent

Protocol-neutral envelope around a native live event.

HarnessHomes

Configurable session roots for the built-in harnesses.

HarnessId

Extensible identifier for a coding harness.

HarnessInteropAdvisory

Actionable finding derived from native harness configuration.

HarnessInteropControl

One harness-owned setting that Supercode can inspect or configure.

HarnessInteropSettingsReport

Canonical, revisioned snapshot shared across CLI, RPC, SDK, and UI.

HarnessSessionService

Stateful persisted-session service. Each instance owns its follow subscriptions; discovery and loading remain read-only.

HarnessSettingChange

Requested change to one stable interoperability control.

HarnessSettingChoice

One allowed value for an interoperability control.

HarnessSettingRecommendation

Concrete, reviewable remediation for an advisory.

HarnessSupportDescriptor

One compiled harness implementation descriptor.

HttpFrontendRuntime

Authenticated HTTP implementation of FrontendRuntime.

LiveRuntimeEndpoint

Browser-safe reference to a trusted local runtime receipt.

LiveRuntimeMetadata

Static runtime metadata recorded at registration. Dynamic state, actions, controller, and observers are queried from the authenticated SDK endpoint.

LiveRuntimeRecord

Browser-safe inventory record for one reconciled live receipt.

LiveRuntimeRegistration

RAII registration for one live runtime. Dropping it removes only the receipt created by this registration, leaving persisted chat data intact.

LiveRuntimeSource

Stable source identity through which a hosted continuation is discovered.

LocalRuntimeRegistry

Local authenticated registry backed by harness discovery and private live-runtime receipts.

ModuleActivation

The resolved activation set for all 35 modules (§5.2 P3: “a resolved activation set on Config”) — pure HarnessConfig → set, no loop required (§5.3 risk 2’s testability mitigation). Also carries tools_search’s three per-tool sub-flags, since crate::tools::ToolRegistry::from_config needs them to decide which of glob/search/list_dir to register — and (P4c) tools_web’s two, for web_fetch/web_search.

NativeSupport

Persisted-session and translation implementation facts.

OpenAiProvider

An OpenAI-compatible HTTP provider. The composition layer supplies its endpoint, credentials, and headers from runtime configuration.

OpenCodeRuntimeBackend

OpenCode live-runtime backend using its official HTTP API and SSE event stream. OpenCodeRuntimeBackend::connect can join the server embedded in an already-running TUI when that TUI was launched with a known host/port.

PiRuntimeBackend

Pi live-runtime backend using pi --mode rpc JSONL.

ProcessCourierRunner

Real courier spawner.

PromptTokensDetails

The cache portion of Usage::prompt_tokens_details.

ResolvedLiveRuntime

Secret host-side information recovered from a verified receipt.

RpcEngine

The out-of-process RPC driver: wraps one already-constructed crate::Agent with the submit/interrupt/status/shutdown method set (§ module doc). Shared by both transports (run_stdio, run_http) so the method semantics — including the fail-closed permission behavior — can never drift between them.

RuntimeAttachRequest

Request to resume or attach through a new adapter connection.

RuntimeAuthorization

Permissions carried by one authenticated runtime client.

RuntimeCapabilities

Mechanical facts an adapter can guarantee.

RuntimeClientId

Opaque identity scoped to one authenticated frontend connection.

RuntimeControllerLease

Controller lease visible through runtime describe/list operations.

RuntimeHandle

Identity returned after a live session is started or resumed.

RuntimeInput

User input accepted by a live runtime.

RuntimeLaunch

Executable configuration used to launch one adapter endpoint.

RuntimeLeaseCoordinator

One-controller, many-observer coordination state for a live runtime.

RuntimeLeaseSnapshot

Serializable ownership snapshot included in registry descriptors.

RuntimeObserverLease

One attached observer and its last authenticated activity.

RuntimeRegistryEntry

Stable joined descriptor returned by the registry.

RuntimeRegistryOwner

Process and controller ownership for one live entry.

RuntimeRegistryQuery

Filters controlling one joined live/persisted inventory read.

RuntimeRegistryWatch

Bounded watch subscription. Dropping it stops the polling task.

RuntimeStartRequest

Request to create a fresh runtime session.

RuntimeSupport

Live runtime wiring known without launching the real executable.

SdkAgent

SDK-owned emulation runtime component.

SdkCapabilities

Capability inventory for the complete v1 SDK, independent of transport.

SdkEvent

Canonical event before a wire transport adds subscription metadata.

SdkRequest

One typed SDK request before a transport adds its envelope.

SdkRuntimeEvent

One runtime event paired with its durable SDK identity.

Session

A normalized, replayable conversation loaded from a tool’s session log.

SessionActivity

Normalized lifecycle state for one harness-native session.

SessionActivityEvidence

Provenance for one normalized activity observation.

SessionDescriptor

Lightweight metadata returned by catalog discovery.

SessionFollower

Poll-based follower for one persisted Claude Code, Codex, Pi, OpenCode, or Grok session.

SessionIndexDelta

One subscription poll result. Revisions start at one for the initial snapshot and increase by exactly one for each non-empty delta batch.

SessionIndexKey

Stable public identity for a session-index change. Persistence paths remain inside the trusted host and are sent only as part of complete descriptors.

SessionInfo

Lightweight metadata about a stored session.

SessionLocator

Stable identity for a persisted harness session.

SessionMeta

Metadata recovered from a session log.

SessionStore

A filesystem session store rooted at a directory.

SupercodeHttpRuntimeBackend

Adapter that joins one authenticated Supercode SDK runtime without taking ownership of the process or creating a second model loop.

SupportRegistryReport

Machine-readable compiled support inventory.

ToolCall

A request from the model to invoke a tool.

ToolContext

Ambient context passed to every tool invocation.

ToolOverride

Per-tool customization: enable/disable a tool and/or override the description the model sees for it.

ToolOverrideProfile

A single tool’s file-settable overrides — the ConfigProfile mirror of ToolOverride (COMPOSABLE-HARNESS-DESIGN.md §3.1 [core.tools.<name>], §3.2 mapping row core.tools.enabled + [core.tools.<n>].*).

ToolRegistry

An ordered set of tools offered to the model.

ToolSchema

A tool advertised to a model.

Usage

Token accounting returned with a completion.

Enums

AgentEvent

Streaming events emitted by a native runtime agent as a turn unfolds.

ApprovalPolicy

When the agent must seek approval before running a tool — the analog of Codex’s -a untrusted|on-request|never and Claude’s permission modes.

CachePlan

Prompt-caching plan applied while building a provider request.

ClaudeBackgroundState

Lifecycle state recovered for a Claude background child.

ClaudeCrossSessionInbound

User-level policy Claude Code applies to messages from other sessions.

ClaudePeerRefusal

Why a message could not be delivered into a live session.

ClaudePeerSettingsError

Failure to read or safely update Claude Code’s user settings.

ClaudePeerStatus

Activity a live Claude Code session reports for itself.

ClaudeRuntimeExecutionState

Execution posture for imported Claude runtime state.

ClaudeRuntimeTriggerKind

Stable trigger ordering: due time, then kind, then source id.

Error

Errors that can arise while configuring or running an crate::Agent.

Fidelity

How faithfully a reconstruction reproduces its source.

FrontendApprovalDecision

Typed approval decision accepted by FrontendRuntime::respond.

FrontendConnectionState

Frontend-visible runtime connection state.

FrontendElicitationAction

MCP elicitation outcome accepted by a frontend response.

FrontendFacadeMethod

One method in the versioned language-neutral frontend facade.

FrontendOperationInvocation

Typed invocation accepted by FrontendRuntime::invoke.

FrontendOperationKind

Stable family for an explicitly invocable frontend operation.

FrontendOperationResult

Typed result returned by FrontendRuntime::invoke.

FrontendRequestKind

Kind of interactive request surfaced by the SDK runtime.

FrontendResponse

Typed response to one SDK-owned interactive request.

FrontendRuntimeError

Typed failure returned by every SDK adapter and compatibility projection.

FrontendTurnState

Whether a model/tool turn currently owns the runtime.

HarnessAdvisorySeverity

Importance of an interoperability advisory.

HarnessInteropSettingsError

Failure while inspecting or changing harness interoperability controls.

HarnessSettingScope

Native configuration layer from which a control was read.

ImplementationKind

How a primitive is wired into the compiled core.

LiveRuntimeReceiptError

Receipt registration or resolution failure.

LiveRuntimeSupervisor

Optional local process supervisor for an attachable runtime.

ModuleId

The 35 §2 capability modules, numbered exactly as the design’s module table (§2, rows 1-35).

Role

Who authored a ChatMessage.

RuntimeEndpoint

Observable endpoint backing a runtime connection.

RuntimeLeaseError

Stable coordination failure shared by every transport projection.

RuntimePermission

Capability independently granted to an authenticated runtime client.

RuntimeRegistryEvent

Change emitted by RuntimeRegistryWatch.

RuntimeRegistryState

Reconciled lifecycle state reported by list/describe/watch.

RuntimeSubmitError

Typed turn failure shared by local, HTTP, ACP, CLI, and language adapters.

SandboxEnvPolicy

capabilities.permissions.sandbox.env_policy (§3.1): child-process environment sanitization for the spawned bash/shell subprocess. Inherit (the default) is today’s behavior — the parent’s environment (plus core.shell_env_snapshot, if configured) passes through unchanged. Filtered strips a sensitive-variable denylist (tokens, keys, cloud credentials). None keeps only PATH and a couple of universally-needed variables (HOME, TERM, LANG) — nearest to a bare-metal shell with nothing extra.

SandboxEscalation

capabilities.permissions.sandbox.escalation (§3.1): what happens when a confining fs tier is requested but this platform/kernel cannot actually enforce it. Deny (the default) refuses to run the subprocess at all — the cardinal “never silently unsandboxed” rule. Ask routes the decision through crate::permissions::PermissionsApprovalHandler (P5-1’s permissions.approvals seam, wired here per this module’s build brief). Allow auto-permits an unconfined run with a loud, one-time warning.

SandboxPolicy

Filesystem confinement applied to write-capable tools — the analog of Codex’s read-only / workspace-write / danger-full-access sandbox modes.

SchemaTier

How verbose an advertised tool schema is. Full is today’s behavior — byte-identical to the tool’s own description()/parameters(). Builtins default to Full (small, load-bearing); the win target is fat activated MCP tools (set via the global knob or a per-tool override, see crate::Config::tool_schema_tier / crate::config::ToolOverride::schema_tier).

SdkError

Typed failure returned by every SDK adapter and compatibility projection.

SdkErrorCode

Stable machine-readable SDK failure categories.

SdkOperation

One operation owned by the SDK facade.

SessionFormat

An on-disk session format supercode can both read and write.

SessionIndexChange

One complete replacement in a revisioned index delta.

SessionPresence

Whether a durable session currently has a proven live owner.

SessionSnapshotReason

Why a watcher emitted a complete session snapshot.

SessionSource

Which tool produced a session log.

SessionTurnState

Turn activity, independent of presence and frontend attention.

SessionWatchEvent

A normalized event emitted while following a local session.

SteeringMode

How queued steering/follow-up messages are drained (S1.7, pi3 steeringMode/followUpMode).

StorageLocator

Durable storage address for a persisted session.

ToolAdvertising

How tools are advertised to the model (B6, D16).

ToolOutcome

The structural outcome known for a tool-result message.

Constants

CLAUDE_CROSS_SESSION_INBOUND_KEY

Stable key for Claude Code’s native crossSessionInbound preference.

CLAUDE_RUNTIME_MANIFEST_VERSION

Version of the persisted Claude runtime-state manifest schema.

DEFAULT_RUNTIME_LEASE_TTL_MS

Default controller duration. Successful mutations and explicit heartbeats renew it; disconnect and detach release it immediately.

DEFAULT_SYSTEM_PROMPT

A default, deliberately small system prompt. Override it freely.

FRONTEND_REPLAY_CAPACITY

Maximum sequenced events retained between canonical history snapshots.

FRONTEND_RUNTIME_SCHEMA_VERSION

Frontend contract schema version.

HARNESS_INTEROP_SETTINGS_SCHEMA

Stable report schema shared by Rust, JSON-RPC, SDKs, and UIs.

HARNESS_SERVICE_VERSION

Protocol namespace implemented by this service.

RUNTIME_EVENT_METHOD

Notification method emitted for live runtime events.

SDK_SCHEMA_VERSION

Current language-neutral SDK schema.

SESSION_ACTIVITY_EVENT_METHOD

Notification method emitted for normalized session-activity transitions.

SESSION_EVENT_METHOD

Notification method emitted for followed-session changes.

SESSION_INDEX_EVENT_METHOD

Notification method emitted for revisioned session-list changes.

SUPPORT_REGISTRY_SCHEMA

Schema emitted by harness_support_registry.

TOOL_ERROR_METADATA_KEY

Canonical metadata key marking a tool result as a structured error.

TOOL_OUTCOME_UNKNOWN_METADATA_KEY

Canonical metadata key marking a tool result whose outcome is unknown.

UNKNOWN_MODEL_CONTEXT_FLOOR

Conservative fallback context limit for an unrecognized model.

Traits

CourierRunner

Spawner seam for the courier process.

FrontendFacadeTransport

Transport seam consumed by the generated Rust facade client.

FrontendRuntime

Canonical live-runtime contract owned by the SDK.

Provider

Legacy provider abstraction preserved by the composition facade.

RuntimeBackend

Factory for starting, resuming, and (where the native protocol permits it) joining one harness’s already-running runtime endpoint.

RuntimeConnection

One connected harness-native runtime session.

SdkPromptSource

Renderable prompt source configured on an SDK emulation component.

SdkRuntime

Canonical live-runtime contract owned by the SDK.

SdkService

Stateful SDK facade consumed by public transport adapters.

Tool

A callable capability.

WriteObserver

P5-9 (design §2 module 20 checkpoint, §2.1 D-5 “write-path interception seam shared with formatters”): the ONE well-defined interception point around every file-mutating built-in tool (write_file/edit_file/apply_patch) — installed on ToolContext::write_observer, None by default. Both hooks fire AFTER ToolContext::check_write has already approved the call (so an observer never sees a write the sandbox itself refused) and BEFORE/AFTER the actual mutation:

Functions

claude_user_settings_path

Claude Code’s user settings file for the configured Claude home.

configure_harness_interop_settings

Apply a revision-checked set of changes and return the resulting snapshot.

core_messages

Canonical messages participating in cross-format fidelity scoring.

create_agent

Construct the emulation component inside the SDK ownership boundary.

discover_live_runtime

Find the newest live receipt matching a discovered source session.

discover_session_page

Discover one persisted-session page with its opaque successor cursor.

discover_sessions

Discover persisted sessions through the canonical SDK catalog owner.

find_live_runtime

Resolve one stable runtime id, requiring an explicit choice if stale or concurrent registrations would otherwise make attachment ambiguous.

forget_live_runtime

Remove only a stale attachment receipt. Canonical, sidecar, source-native, and exported session data are never addressed by this operation.

format_reply

Format an agent’s final reply for output. json wraps it as {"result": "..."}; otherwise the reply is returned as-is. The stream-json form is the live AgentEvent stream via an EventSink.

harness_support

Look up one harness in the compiled registry.

harness_support_registry

Return the single compiled inventory used by product surfaces and audits.

inspect_harness_interop_settings

Inspect the interoperability controls exposed by one harness adapter.

is_tool_error

Whether a message carries the canonical structured-error marker.

landlock_available

Whether real Landlock filesystem confinement is available on THIS process’s kernel — a genuine, side-effect-free (beyond dropping one ruleset file descriptor) PARENT-PROCESS probe: it builds a CompatLevel::HardRequirement ruleset requiring exactly the write-access rights apply_linux_confinement would later request and checks whether Ruleset::create() succeeds — it deliberately never calls restrict_self() (that confines the CALLING process/thread permanently and every future child of it — calling it here would confine supercode ITSELF, exactly the “confinement targets the child, not supercode” invariant this module must never violate). Cached for the process lifetime (the kernel’s Landlock support can’t change at runtime).

list_live_runtimes

List every reconciled live runtime without exposing its bearer token or loopback address. Dead-process receipts are removed as part of the read.

load_session

Load one durable locator through the canonical SDK catalog owner.

load_session_path

Load an explicit transcript/store path through the SDK import boundary. An OpenCode selector is accepted only for its SQLite store.

mark_tool_error

Stamp a tool-result message as a structured error.

mark_tool_outcome_unknown

Stamp a tool-result message as having no structurally known outcome.

measure_fidelity

Measure an export/reload cell without applying a regression floor.

message_claude_peer

Resolve session_id in the registry and deliver text into it.

messages_equal

Compare semantic message fields shared by the supported harnesses.

messages_equal_multimodal

Compare semantics plus multimodal parts and tool names.

model_context_limit

Look up a model’s context-window size by its full provider slug.

netns_available

Whether an unprivileged, self-contained network namespace cut-off is available on THIS process’s kernel — a real probe, but one that (unlike landlock_available) genuinely can’t be done risk-free in the calling process itself (unshare(2) acts on the CALLING process/thread, so probing it directly would isolate supercode’s own network, not just check availability). Instead this forks a disposable, single-purpose child that does nothing but attempt the unshare and immediately _exit() with the result — never touches the allocator, locks, or any other state the parent might hold mid-fork (the standard safe shape for a post-fork child that never execs), so it carries none of pre_exec’s usual multi-threaded-fork hazards. Cached for the process lifetime.

read_claude_peer_registry

Read every LIVE session from a Claude registry directory.

read_claude_peer_settings

Inspect only the user-level inbound setting. The report deliberately does not claim to be Claude’s effective value because managed, project, and command-line settings can have higher precedence in a particular target.

register_live_runtime

Register an authenticated loopback runtime and return its opaque endpoint.

register_live_runtime_with_metadata

Register a runtime with the static fields used by list/describe output.

replay_eligible

The replayable subsequence of a canonical transcript.

resolve_live_runtime

Resolve an opaque endpoint and verify that it belongs to expected.

resume_agent

Resume canonical history inside a fresh SDK-owned emulation component.

shell_sandbox_unenforceable

True when the requested sandbox policy cannot be enforced for shell subprocesses: a confining policy, a platform without an OS sandbox primitive wired up (only macOS/seatbelt is, via sandbox-exec), and at least one shell tool ("bash" or "shell") enabled.

submit_agent

Submit one text turn through the SDK-owned emulation loop.

submit_agent_with_images

Submit one multimodal turn through the SDK-owned emulation loop.

tool_outcome

Return the canonical structural outcome for a tool-result message.

update_claude_peer_settings

Set or reset Claude Code’s user-level inbound policy. expected_revision prevents an explicit UI action from overwriting settings inspected before another process changed the file.

write_claude_peer_settings

Explicitly update Claude Code’s user-level inbound policy while preserving every unrelated setting. The write is atomic, refuses symlinks, and aborts when it observes an edit between its initial read and commit.

Type Aliases

EventSink

A sink for AgentEvents.

Result

Result alias used throughout the crate.

StopGateHook

A stop-gate hook: receives the would-be-final assistant message; returns Some(reason) to veto termination and continue the loop (the reason is injected as a new user message), or None to allow the stop. See Config::stop_gate.