Markdown

Agents overview

ReAct coding agent loop — model decides, kernel authorizes, Zig executes.

Agents

Carina drives a real ReAct coding agent. The model only decides; every side effect is authorized by the Rust capability kernel and executed by the Zig toolchain. The whole run is a tamper-evident audit trail you can replay and roll back. ReAct

Source: docs/agent.md.

flowchart LR
M[Model decides] --> L[Go agent loop]
L --> K[Rust kernel]
K --> Z[Zig tools]
Z -->|observation| L

Decide → authorize → execute → observe.

Typed client sketch

Hover identifiers for types (Twoslash):

session.tstwoslash

type type Profile = "safe-edit" | "read-only" | "full-workspace"Profile = "safe-edit" | "read-only" | "full-workspace";

interface CreateSessionParams {
CreateSessionParams.workspace_root: stringworkspace_root: string;
CreateSessionParams.profile?: Profile | undefinedprofile?: type Profile = "safe-edit" | "read-only" | "full-workspace"Profile;
}

interface CreateSessionResult {
CreateSessionResult.session_id: stringsession_id: string;
CreateSessionResult.workspace_id: stringworkspace_id: string;
CreateSessionResult.profile: Profileprofile: type Profile = "safe-edit" | "read-only" | "full-workspace"Profile;
}

async function function createSession(client: {
    request: (m: string, p: CreateSessionParams) => Promise<CreateSessionResult>;
}, root: string): Promise<CreateSessionResult>createSession(
client: {
    request: (m: string, p: CreateSessionParams) => Promise<CreateSessionResult>;
}client: { request: (m: string, p: CreateSessionParams) => Promise<CreateSessionResult>request: (m: stringm: string, p: CreateSessionParamsp: CreateSessionParams) => interface Promise<T>Represents the completion of an asynchronous operationPromise<CreateSessionResult> },
root: stringroot: string,
): interface Promise<T>Represents the completion of an asynchronous operationPromise<CreateSessionResult> {
return client: {
    request: (m: string, p: CreateSessionParams) => Promise<CreateSessionResult>;
}client.request: (m: string, p: CreateSessionParams) => Promise<CreateSessionResult>request("session.create", {
  CreateSessionParams.workspace_root: stringworkspace_root: root: stringroot,
  CreateSessionParams.profile?: Profile | undefinedprofile: "safe-edit",
});
}

The loop

Each turn the reasoner emits one JSON action — or a batch of read-only actions ({"actions":[…]}, parallel; writes stay one per turn) — and Carina runs it and feeds back an observation:

Action	Goes through	Runs on
`{"tool":"list"}`	FileRead	Zig `carina-scan`
`{"tool":"read","path":"…"}`	FileRead	kernel-gated read
`{"tool":"search","pattern":"…"}`	FileRead	Zig `carina-grep`
`{"tool":"run","command":["…"]}`	CommandExec (risk-classified)	Zig `carina-run`
`{"tool":"patch",…}`	PatchApply	Rust transaction → Zig `carina-patch-native`
`{"tool":"memory",…}`	MemoryWrite	governed long-term memory
`{"tool":"ask_user",…}`	—	structured operator choice
`{"tool":"code.search/symbols/…"}`	FileRead	code-intelligence index (+LSP)
`{"tool":"mcp"}` / `mcp_find`	governed MCP manager	external MCP servers
`{"tool":"spawn",…}`	SubagentSpawn	isolated subagent
`{"tool":"workflow",…}`	PluginLoad	named dependency DAG
`{"tool":"best_of_n",…}`	opt-in	N candidate patches, judge, apply winner
`{"tool":"done","summary":"…"}`	—	ends the task

Destructive commands (rm -rf, curl … | sh) are denied before they run. Risky ones (installs) surface for approval. Secret files (.env, .ssh) are refused. Every file edit is a rollbackable patch transaction.

Hardening

LoopGuard — breaks canonical-signature action repetition
MistakeTracker — breaks consecutive failure streaks
Compaction — folds old turns into a summary (CompactionReceipt audited); user-authored turns keep a verbatim tier
Steering — two-tier (urgent/normal) mailbox drained at turn boundaries

Reasoner backends

go/daemon/reasoner.go defines a pure “think” step:

Backend	Role
model-router	BYOK provider adapters; prompt segments for caching; media parts when catalog allows
claude-cli	Explicit compatibility backend using the local `claude -p` headless mode with tools disabled and an empty cwd
codex-cli	Explicit compatibility backend using `codex exec` with ephemeral JSONL output, tool features disabled, read-only isolation, and fail-closed event parsing
scripted	Fixed decisions for deterministic tests

Wiring:

Auto selects model-router only when an enabled provider is runnable; CLI binaries are never selected by presence
CARINA_REASONER_BACKEND=claude-cli or codex-cli opts into an external CLI explicitly
CARINA_REASONER_MODEL (e.g. openai/gpt-5) pins the selected backend’s model
Optional: CARINA_SUMMARIZER_MODEL, CARINA_VERIFIER_MODEL

Claude uses -p for non-interactive output. Codex uses codex exec; its -p flag selects a profile. Codex’s read-only sandbox is not a hard no-read or no-execution boundary, so Carina also rejects tool and unknown item events and keeps the backend explicit-only.

Run it

cd your-repo
# Interactive TUI auto-starts the daemon; for headless runs you can also:
#   carina daemon start
carina run "fix the failing test in parser.go"
carina audit SESSION
carina audit verify SESSION
carina patch list SESSION
carina patch rollback SESSION PATCH_ID

Surfaces that consume agent state

Surface	Role
TUI (`carina`)	Primary operator experience — slash commands, approvals, plan/build modes
CLI	Headless / CI: `carina run`, `approve`, `audit`, …
VS Code extension	Optional in-repo client under `integrations/vscode` — install from release assets when you need in-editor attach
Web operator	Experimental static shell under `integrations/web` — not a full dashboard product yet

Source of truth

Agent loop: docs/agent.md · reasoner wiring in go/daemon/reasoner.go
CLI: carina run / carina ask · CLI reference
Related: Policy · Tools · Sub-agents

Sub-agents — attenuated delegation
Common workflows — first governed session recipes
Audit — inspect and verify after a run

Was this page helpful?

One vote per page is recorded during this session.

Agents overview

Typed client sketch

The loop

Hardening

Reasoner backends

Run it

Surfaces that consume agent state

Source of truth

Next