# Code Mode agent guide
Parent: [source guide](../AGENTS.md).
Synchronous JavaScript sandbox, internal tool catalog, resource accounting and host-owned execution evidence. Guarded host execution belongs in `../agent/code_mode.rs`.
## Where to look
| Provider definition and protected-output evidence | `../code_mode.rs` |
| Direct/internal tool catalog | `catalog.rs` |
| QuickJS execution and synchronous `call`/`callAll` SDK | `engine.rs` |
| Allocator/native memory/JSON conversion | `engine/{allocator,memory,conversion}.rs` |
| Limits and budget snapshots | `limits.rs`; settings: `../config/settings/tools.rs` |
| Live/interrupted execution evidence | `audit.rs` |
| Direct-call batching guidance | `usage.rs` |
| Guarded calls and nested records | `../agent/code_mode.rs`, `../agent/session_persistence.rs` |
## Local contracts
- QuickJS uses one joined scoped worker and zero-capacity request/response channels. Host tools run through the guarded lifecycle. `callAll` records all entries before dispatch, groups consecutive eligible calls on the shared four-worker inspection path, and commits in order on the caller. Other entries are sequential barriers; configured hooks disable concurrency. Never detach tool execution.
- Scripts are synchronous function bodies, not promises. Filesystem/process/network/environment access comes only through permitted host tools. Capture native bridge/serialization helpers before scripts can replace globals.
- Internal availability comes from `ToolRuntime::for_code_mode`, not direct catalog. Preserve MCP aliases/schemas; recursive `code_mode` and `magi_control` remain unavailable internally.
- Registered client tools remain visible in compact direct catalogs; MCP compact visibility is unchanged. Both surfaces enforce saved client fingerprint ceilings, including nested runtime clones.
- Charge QuickJS allocator and native JSON buffers against shared memory. Bound source, calls, individual/cumulative results, return bytes and computation; zero never means unlimited. Host-tool waiting does not spend JavaScript runtime budget.
- Execution budgets reset per engine call and `SessionPersistence::nested`; only durable session-history space is shared. `tools.budget()` consumes no call, result-byte allowance or history append; history headroom is advisory.
- Resource exhaustion/cancellation terminates even through caught JavaScript exceptions. Retain original cause: session-history exhaustion requires compaction; batch exhaustion requires splitting. Never replay completed mutations automatically.
- `CodeModeAudit` observes host outcomes, not script assertions. Preserve successful/failed/unknown outcomes, bounded changed-path evidence, warnings and interrupted-batch context. Failed/unknown actions take priority in bounded previews. Observed results survive full-record persistence failure through the outer summary; missing results never prove rollback, and shell/external effects may be untracked.
- Warning totals count events independently of the 32-message preview. Interrupted summaries attach only to unambiguous same-turn parent records; shared structured card facts live in `../output/tool_card/execution_facts.rs`.
- Dispatch requires 64 KiB of remaining nested history headroom after call recording. This is a preflight, not a reservation; full results can still exceed append bounds. Keep observed outcomes and persistence warnings when that happens.
- Protected output must retain host evidence. Script completion is separate from inner-tool success; partial mutations survive replay/display. Transcript presentation belongs elsewhere.