akougkas.io

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

CLIO Coder hands the model a catalog of typed tools with declared action classes instead of a shell prompt. Bounded reads, an enforced autonomy dial, per-workspace consent, and, since v0.5.1, a quota reading you can see before a provider refuses you.

Published
Reading
8 min read
Topics
agents, systems, building

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.

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. model asks for a tool typed call, fixed schema safety net verdict autonomy mapping operator consent bounded execution receipt and audit row
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, 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

Sources, code, and records

  1. source

    CLIO Coder v0.5.1 release

    Subscription quota readings normalized into one consumed-percentage model and the unified /usage overlay, September 21, 2026.

  2. source

    CLIO Coder repository

    Source, changelog, and the safety model documentation this entry draws on.

  • 2023–present
    active

    CLIO Coder

    A local-first coding agent with typed tools, bounded workers, and receipts

  • 2025–present
    active

    CLIO

    A context layer for scientific AI agents and workflows

More on CLIO Coder

  1. essay

    Reliable work from unreliable agents

    A coding agent is a system built around one brilliant, persuasive, unreliable component. The argument of my November 9, 2026 lecture on agentic engineering: five ideas for building trustworthy work around that component, what they could do for science, and the problems still open.

    14 min
  2. essay

    CLIO as the entry point

    CLIO should become the single place a developer starts with IOWarp, built as an application SDK with deployment profiles rather than an umbrella package or a gateway service. This is the direction for 2027; the API and the scope are still open.

    6 min
  3. essay

    A capable model in a capable harness

    Claude 3.5 Sonnet brought me back to writing code. A capable model still needs a harness that makes its progress checkable and its cost visible, and CLIO Coder is the one I built around models that many people can afford to use.

    4 min