---
title: "Agents overview"
description: "ReAct coding agent loop — model decides, kernel authorizes, Zig executes."
source: https://carina.nebutra.com/agents/overview/
---

# Agents overview

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

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. <Badge variant="accent">ReAct</Badge>

Source: `docs/agent.md`.

## Typed client sketch

Hover identifiers for types (Twoslash):

## 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

```bash title="agent-loop.sh"
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 |

  See [Sub-agents](/agents/sub-agents/) for attenuated delegation and [Policy](/concepts/policy/) for capability profiles.

## Source of truth

- Agent loop: `docs/agent.md` · reasoner wiring in `go/daemon/reasoner.go`
- CLI: `carina run` / `carina ask` · [CLI reference](/reference/cli/)
- Related: [Policy](/concepts/policy/) · [Tools](/tools/overview/) · [Sub-agents](/agents/sub-agents/)

## Next

- [Sub-agents](/agents/sub-agents/) — attenuated delegation
- [Common workflows](/getting-started/common-workflows/) — first governed session recipes
- [Audit](/concepts/audit/) — inspect and verify after a run

---
Source: https://carina.nebutra.com/agents/overview/
Markdown: https://carina.nebutra.com/agents/overview/index.md