# Why CLIO Coder, part 2 of 5: typed tools, never a raw shell

https://akougkas.io/journal/2026/why-clio-coder-2-typed-tools-never-a-raw-shell/

Author: Anthony Kougkas

Published: 2026-09-21

An agent that can type anything into a shell is an agent you have to watch. [CLIO Coder](https://akougkas.io/work/clio-coder/), the terminal coding agent I create and maintain inside [CLIO](https://akougkas.io/work/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.

Diagram: A tool request passes through seven stages in order: the model asks for a tool, the request becomes a typed call with a fixed schema, the safety net returns a verdict, the autonomy mapping allows or parks or denies it, an operator consent decision resolves anything parked, execution runs under declared bounds, and a receipt with an audit row records what happened.

The path a tool request takes from model intent to a recorded receipt, with the safety net, the autonomy mapping, and operator consent in the order they evaluate.

## 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](https://github.com/iowarp/clio-coder), and the install path for your own hardware is in the [GPU tutorial](https://akougkas.io/journal/2026/clio-coder-on-your-own-gpu/).
