An agent that can type anything into a shell is an agent you have to watch. CLIO Coder, the terminal coding agent I create and maintain inside CLIO, gives the model a catalog of 30 typed tools instead, each carrying an action class that src/tools/policy.ts asserts at bootstrap so the classifier and the registered schemas cannot drift apart. A shell is in that catalog. It is the most heavily governed entry in it.
The catalog is the surface
The 30 tools sit in eight planes. OBSERVE holds read, grep, find, ls, code_nav, and the rest of the inspection set, all read class. MUTATE holds write and edit. EXECUTE holds bash, verify, and run_script, plus git, which carries the read class because its operations are fixed command vectors on the safe-exec spine. A tool that a target’s capabilities hide is never shown to the model; a tool that is shown still passes every gate below before it runs.
A typed tool means a contract you can read before you run it. Take read. Each call is capped at 2000 lines or safety.limits.readBytesPerCall, whichever hits first, and the per-turn observation budget can shrink that further. Text files of any size are read through bounded windows, so size is a paging problem rather than a refusal. Exact line counting stops at a 32 MiB file-size budget and larger files report an unknown total as N+. Images keep a separate 20 MB ceiling. NUL bytes and invalid UTF-8 in the inspected bytes are refused with zero-based byte offsets rather than decoded into plausible-looking garbage, and a truncated result carries next: offset=<first unshown line> so the model continues from a stated position instead of guessing one. Those bounds shipped in v0.4.9 on September 17, 2026, and the documentation states the matching limit: a bounded read does not validate the regions it did not read.
bash is where the difference is sharpest. Commands spawn as /bin/bash -o pipefail -c, so a failure upstream of a filter such as tail survives into the result and a verification receipt cannot report success because the filter succeeded; a caller that wants the old behavior writes set +o pipefail and says so. The policy engine then tags the command recognized or unrecognized. Recognized covers a narrow built-in set (pwd, simple ls, git status, bounded git diff and git log, the repository test runners) plus whatever a reviewed project policy declares. Everything else parks at the default auto-edit level for one operator decision. Command substitution is a confirm rail at every level, full-auto included, because the net cannot scan what it will execute until runtime.
Two axes, and neither is a warning
Permission in Clio is a dial and a net, and they are independent. The safety.autonomy dial takes read-only, suggest, auto-edit, or full-auto, and it decides one thing: which action classes run immediately, which park for approval, and which are denied outright. The safety net is the damage-control rule packs, path policy, protected artifacts, the loop guard, and dispatch scope admission. It is identical at every level. A net block is final and is never downgraded, so zero-access paths such as .git/config and credentials.yaml stay blocked at full-auto, and a malformed project policy cannot disable the built-in path protection.
Operator approval is one-shot by construction. Approving a command or a write authorizes that single presented call, keyed to its request id; it does not loosen the level, and it cannot promote anything the net blocked. Project configuration is consented to rather than trusted by proximity: since v0.4.5 on September 7, 2026, project safety, hooks, and settings are ignored until an operator reviews them with clio-coder config trust safety|hooks|settings, which prints the exact source bytes and a full SHA-256 digest, and approves that digest with --hash. Consent binds one canonical workspace and one surface, so approving a repository’s safety policy never quietly extends to its hooks or to another checkout. --revoke withdraws it.
Repetition is handled without weakening any of that. v0.5.0 scoped worker approval reuse to the same run, the exact arguments, the approval axis, the action class, and the policy identity. An identical call under identical conditions reuses the operator’s prior decision; a changed argument or a different asking rail earns a fresh card. Worker approvals are human-only by construction, because a model approving its own fleet’s asks would collapse the audit trail the receipts exist to carry.
The honest limit belongs in the same paragraph as the claim. These policies classify and admit tool calls. They are not an OS sandbox, and child tools run with the host user’s filesystem and process access, so untrusted execution still belongs in a separate account, container, or machine.
Knowing the budget before it refuses you
The same stance applies to the quota that ends a session early. v0.5.1, on September 21, 2026, added adapters that read the stored credentials of Claude Code, anthropic-max, the Codex CLI, and Antigravity and normalize every reported window into one model of consumed percentage, so one provider’s percentages and another’s remaining fractions are never read interchangeably. The reads are strictly read-only: no token refresh, no credential write, no sign-in flow. Readings cache for about five minutes and refresh lazily when a surface that shows them renders, never on a background timer, and a failed refresh keeps the last good reading and marks it stale instead of blanking the account. Two credentials on one Anthropic subscription fold into a single account so the apparent budget is not doubled.
/usage replaces /cost, with no alias. It keeps the session token and cost accounting and adds four views: Accounts for the subscription and credit meters with reset countdowns in an explicit time zone, Session for the token, cost, cache, reasoning, and background-call breakdown, Models for each model’s share of recorded processed tokens, and Workers for tokens, cost, and context per run beside the shared account limit. Every percentage carries a direction in its own label, so a weekly window at 9% used and a footer badge reading weekly 91% left are the same number. Worker quota is presented as shared account headroom rather than a measured per-worker share, because per-target token attribution does not exist yet.
A tool whose contract you can read is a tool you can trust with one GPU and a twenty-minute build. That is the whole argument for typing the surface instead of opening a shell.
Try it
Install the agent and check the installation:
npm install -g @iowarp/clio-coder
clio-coder doctor
Review a repository’s project safety policy before anything in it can apply, then approve the exact digest the review prints:
clio-coder config trust safety
clio-coder config inspect
Watch a bounded read and a refusal in the same posture, where every mutating call is denied by the dial rather than by a prompt:
clio-coder run --autonomy read-only "Read the first 40 lines of package.json, then read .git/index and report exactly what the read tool returned."
The text file comes back as a bounded window with a continuation offset; the binary comes back as a refusal naming a zero-based byte offset, not as decoded text. Inside an interactive session, /settings opens the Permissions & Limits section that owns the autonomy dial, and /usage opens the four views above. clio-coder usage report is the cross-session command and is unaffected by the overlay.
What is left for you
The part of this model that is still open is the boundary the documentation admits: admission is not isolation, and detect-and-rollback on write boundaries is not a read-only mount. CLIO Coder is experimental by design and pre-1.0, and closing that gap honestly means OS-level isolation with receipts that say which guarantee actually held for a given run, per platform, without overclaiming on any of them. On a cluster, where the host user’s access is a far larger blast radius than on a laptop, the design of that boundary is worth arguing about in the open. The tool catalog, the policy engine, and the safety documentation are all at github.com/iowarp/clio-coder, and the install path for your own hardware is in the GPU tutorial.
Next in the series Part 3: The agent writes its own handoff