The harness

The turn loop

A turn is a bounded loop, not an open-ended process:

1. accept a user turn;
2. build context from session state and workspace metadata;
3. call the provider through the model client;
4. execute the tools the model requested;
5. append tool results to the session;
6. continue until a final assistant answer or the iteration limit set by --max-iterations;
7. emit a typed event for every important step.

The result is a structured outcome the CLI, and later the desktop and cloud surfaces, can render or replay.

Tools and the workspace boundary

Tools are grouped into sets you opt into with --tool-set: read for inspection, edit for file changes, command for running programs, and git for repository state. Every tool is confined to the workspace root, so a run cannot read or write outside the project directory.

Tools marked concurrency-safecan run together in one batch. Unsafe or unknown tools always run serially and split adjacent safe batches, and the harness preserves the model's original tool-call order when recording results and events.

Permissions

Tool execution runs under a permission mode set with --permission-mode:

• allow — run permitted tools without prompting;
• ask — confirm before sensitive actions, with the option to remember a decision;
• deny — block the tool surface entirely.

The same checks cover external MCP tools, so connectors are governed the same way native tools are.

Events and lifecycle hooks

Every step emits a typed event. With --stream-events you see them live; with --json-events you get them as serialized records after the answer. The same events drive session replay.

The loop also exposes lifecycle hooks so memory, compaction, and approvals can extend a turn without forking it: queue recall before a turn, inject reviewed context before inference, observe tool evidence, extract facts before older transcript is compacted, and queue memory extraction once a turn completes.