The Core Loop#
Carpenter agents follow a simple cycle: observe → generate code → review → execute → persist.
- An event arrives — a chat message, a webhook, a cron fire, or a child arc completing.
- The agent reads whatever it needs: files, state, arc trees, conversation history, skills. All read access is free and unrestricted.
- When the agent wants to do something — write a file, call an API, modify state — it generates Python code and calls
submit_code. - The review pipeline inspects the code: syntax check, injection scan, sanitization, then a separate AI reviewer that sees only the sanitized structure.
- Approved code executes in a sandboxed environment with no direct network access.
- Results are persisted — every code file, every execution log, every state change is written to disk and tracked in the database.
This is the “measure twice, cut once” principle: the agent thinks freely but every action is inspected before it happens. For high-stakes operations, the pipeline extends to multiple independent reviewers, a judge, and separation-of-powers verification — “measure N times, cut once.”
Observe Freely, Act Carefully#
The agent has two modes of interaction:
| Mode | Mechanism | Examples |
|---|---|---|
| Observe (free) | Tool-use read calls | Read files, list arcs, search knowledge base, load skills |
| Act (gated) | submit_code | Write files, mutate state, make web requests, run git, create arcs |
This split is the fundamental design decision. Read-only observation can’t cause harm, so it’s unrestricted — giving the agent full situational awareness. Every side effect is funneled through code review, making the boundary between intent and action explicit and auditable.
Events and the Main Loop#
Everything that happens enters as an event in an append-only log. The main loop combines two rhythms:
- Wake signal — instant processing for chat messages
- 5-second heartbeat — periodic work: cron evaluation, timeout checks, event matcher evaluation
Each cycle: claim work queue items, match events to waiting arcs, check expirations, fire cron entries, run heartbeat hooks.
Persistence#
Every piece of agent-generated Python is saved to a date-partitioned directory:
data/code/2026/03/16/000001_agent_step.py
data/logs/2026/03/16/000001_agent_step.logThe database (SQLite in WAL mode) tracks code files, execution records, review status, arc state, conversation history, and a trust audit log. Nothing is ephemeral — the full history of every agent action is recoverable.