Every AIOS session runs on a Claude model, and every spawned worker inherits one. That choice is not cosmetic: on the same trivial prompt, the top and bottom of the ladder below differ by roughly 22× in cost. Most work does not need the top, and some work is wasted on the bottom.
This file answers two separate questions that are easy to conflate:
- Which Claude model should do this task? → § The ladder
- May a non-Claude model do it at all, and if so how? → § The containment boundary
If you only read one section, read the boundary. The ladder costs money when you get it wrong; the boundary costs credentials.
Anthropic's own guidance, expressed as the four rungs AIOS exposes. Pick by the shape of the work, not by importance — "important" is what tempts you to the top rung for a file sweep.
spawn --tier |
Model | Use it for | Effort to start from |
|---|---|---|---|
frontier |
Claude Fable 5.1 | Your hardest problems: long-running agents in production, code migration, multi-step reasoning, and tasks needing creative thinking and full autonomy | high (xhigh/max for the hardest runs) |
judgment (default) |
Claude Opus 5.5 | Reasoning-intensive work — legal, financial analysis, research, other complex domains — and production coding | high |
scale |
Claude Sonnet 5.5 | General-purpose workloads at scale, across coding and knowledge work | medium |
fast |
Claude Haiku 5.5 | High-frequency, latency-sensitive tasks; sub-agents inside an orchestration | low |
Effort is the second knob, and for current models it is the one to turn first. Claude 5-generation models always reason before replying, so "think carefully" in a prompt only adds latency; to get more or less thinking, change effort: claude --effort low|medium|high|xhigh|max (checked against the installed binary, not assumed). The column above is where to start, not a rule. For a spawned worker, spawn --effort <level> (Windows: -Effort); for a subagent, the Agent tool's effort parameter; inside a session, /effort. Omitted, a worker runs at the binary's default.
Fast mode is not a rung. It is the same model, answering faster, at a higher price per token — worth it for back-and-forth work where you read every reply, wasted on an unattended worker. Toggle it with /fast.
A flagged message can move a session to an older model — silently, and for the rest of the session. Opus 5.5 carries stricter safety classifiers, and the check covers the whole conversation, files and search results included, so a turn from much earlier can trigger it. When it fires, Claude Code switches the session to an older model and stays there. A judgment worker can therefore finish its job on a lower rung, and nothing in its launch arguments will say so. Two consequences:
- Check what actually ran, not what you asked for:
/modelshows the session's current model, and each reply's model is recorded in the session transcript. Launch arguments only prove what was requested. - Decide the behaviour for unattended work deliberately. The setting is
/config→ "Switch models when a message is flagged". Interactively, switching keeps you working; for a routine or worker whose output you will trust without watching it, you may prefer it to stop instead of finishing on a model you did not choose. - Let the log tell you. With SETUP's Hook F wired, every switch is appended to
~/.aios/model-switch.jsonl, and/close-sessionand/close-dayname any session that finished on a model it did not ask for.
Omitting --tier gives you judgment. That is deliberate: the default should be the rung that is
right when nobody thought about it, and under-powering a reasoning task fails silently — you get an
answer, it is just worse, and nothing tells you.
judgment is a pin, not an inherit — so it has a maintenance duty. hooks/pipeline/resolve-tier
answers it with an empty --model (the binary's default), but the launcher every AIOS session
starts through passes --model explicitly, at 1M context, because settings.json and /model are
not reliable carriers of that choice to spawned children. In practice the rung is the literal in
install-wrappers.sh / .ps1, and it outranks a model the operator saved with /model. When
Anthropic ships a new Opus, that literal moves in the same PR as this row — tests/model-routing.test.sh
fails the build if the table and the two wrappers stop naming the same model. (It went stale once:
Opus 5.5 shipped while every AIOS session was still launched on Opus 5, and nothing reported it.)
--tier mechanical still works and still resolves to Claude Sonnet 4.6. It predates this
ladder and is kept byte-identical, because changing what an existing flag resolves to would change
the cost and behaviour of work already running in operators' routines. Treat scale as its
successor for new work; mechanical will keep working.
- A spawned worker:
spawn --tier fast transcriber "..."(Windows:-Tier fast) - One specific model, outside the ladder:
spawn --model claude-fable-5-1 name "..."— overrides--tier, exportsCLAUDE_MODELfor that spawn's launcher only. Never exportCLAUDE_MODELin your shell rc to achieve this; miss the revert and every future terminal is pinned. - A subagent inside a session: the Agent tool's
modelparameter takes the same ids, and itseffortparameter sets effort per subagent. - Inside a workflow: per-agent, same ids, and per-agent effort.
- Effort for a spawned worker:
spawn --effort low|medium|high|xhigh|max name "..."(Windows:-Effort). An unknown level is refused rather than ignored. - An advisor for a spawned worker:
spawn --advisor <rung|model> name "..."(Windows:-Advisor). Read § The advisor first: on most rungs it is not worth it.
Model ids churn. An id AIOS does not recognise does not fail loudly — Claude Code reports
[claude-code:unrecognized_model] on stderr and then produces zero tokens at zero cost, which
means "the spawn worked" is worthless as evidence on its own. The check that can actually fail:
# Prompt FIRST, then flags — `--tools` is variadic and will swallow a prompt that
# follows it. `--tools ""` means no tool exists at all; `--setting-sources`,
# `--strict-mcp-config` and the explicit permission mode are each required: see below.
claude -p 'ok' --model "$ID" --output-format json \
--tools "" --setting-sources user,project --strict-mcp-config \
--permission-mode default 2>&1 | head -c 200
# real id → JSON with non-zero total_cost_usd and non-zero input tokens
# bad id → the literal string [claude-code:unrecognized_model]An allowlist is not containment — the tools that exist are. Reported privately by an operator, 2026-09-21, and reproduced on Claude Code 2.1.281 with a canary:
--allowedToolsonly pre-approves, and it is additive to every allow rule in the settings that load..claude/settings.local.jsonis where each interactive "allow always" click accumulates — one daily-used vault had 98 rules, including a home-wideReadandBash(python3 *)— so the previous recipe (--allowedTools NoSuchTool --strict-mcp-config --permission-mode default) read a file outside the project. Measured: that recipe plus one inheritedReadrule → leaked · adding--setting-sources user,project→ held ·--tools ""→ held · the same recipe with no local rule → held (the control: the inherited rule is the whole cause). So:
--tools "<list>"sets which tools exist (""= none). Size it to the job; it is the part an inherited rule cannot widen.
--setting-sources user,projectdrops the local layer where "allow always" accumulates.Keep
ToolSearchin--toolswhenever MCP servers are loaded — without it every MCP schema is inlined and the run dies with "Prompt is too long".A job that must run
Bashneeds the OS sandbox too, configured three ways, because its defaults do not contain a headless run. Reported privately by an operator, 2026-09-24, and reproduced on 2.1.281 with canaries:
"autoAllowBashIfSandboxed": false. It defaults totrue, and then the sandbox approves every Bash command: a command that was not on--allowedToolsran under--permission-mode defaultwithpermission_denials: []. Set tofalse, the same command was denied, as it is with no sandbox."filesystem": {"denyRead": [...]}naming every credential folder. Sandboxed Bash reads outside the project by default. Apermissions.denyrule ofRead(<folder>/**)did not stopcatthere; onlydenyReaddid. Name your secrets folder and every MCP token folder —~/.config/aios-secretsand~/.google_workspace_mcpat least (§ Where credentials live inSECURITY.mdlists the rest). A token folder matters as much as a key: the network allowlist lets the job reach that token's own API, so a read is also a way out.- The same folders in
"denyWrite". Writes outside the project are already denied by default; this keeps them denied if someone later widensallowWrite.{ "sandbox": { "enabled": true, "autoAllowBashIfSandboxed": false, "filesystem": { "denyRead": ["~/.config/aios-secrets", "~/.google_workspace_mcp"], "denyWrite": ["~/.config/aios-secrets", "~/.google_workspace_mcp"] } } }Put it in a file only the job loads —
claude -p … --settings ~/.config/aios-routine-sandbox.json— never in your interactive~/.claude/settings.json. Measured that way, alongside the operator's normal settings, it held: the off-allowlist command was denied and the outside read blocked. In your interactive settings it would cost you: auto-approve is what keeps a sandboxed session from prompting on every command, and denying a token folder breaks whatever reads it from sandboxed Bash, AIOS's own/todaypipeline included. The interactive session is not the exposure; a headless job fed outside text is.A Bash job still inherits the allow rules of BOTH layers it keeps.
--setting-sources user,projectdrops the local layer only. One operator's user settings allowedBash(touch *), and that alone let an off-allowlisttouchrun with auto-approve off; another operator's project settings carriedBash(python3 ~/aios/hooks/:*), which lets a routine run any hook script outside its allowlist. Two ways out, and the trade is yours. Narrow those rules — but in your interactive settings that also means prompts where there were none. Or give the routine its own folder with its own.claude/settings.json(its allow list, its deny rules, the sandbox block above) and run it there with--setting-sources project: measured, a user-levelBash(touch *)no longer applied. Don't simply drop the vault's project layer for a routine that runs in the vault — it carries the deny rules and the PreToolUse guard that routine should keep. For a job that needs Bash, keep--allowedToolsto what it runs and read both allow lists with the same eye. And read-only commands inside the working directory are auto-approved, so run such a job from a directory holding only what it needs.Why a probe that only says
okcarries these flags. Reported by an operator, 2026-08-31, after auditing their own fleet. Any shippedclaude -pinvocation should name the tools it actually needs — this one needs none — because the cost of adding it is a flag and the cost of retrofitting it across a fleet is a weekend. Three of the four obvious ways to do this do not work:--allowedTools ""is swallowed by the variadic flag ·--permission-mode manualdoes not block (Bash still runs) ·--disallowedTools Bashis a denylist, soWrite,EditandAgentsurvive it. (These were written when the allowlist was the recommended form; the note above supersedes it with--tools.)And it holds only if you also pass
--permission-modeexplicitly. Measured 2026-09-04 on a machine whose~/.claude/settings.jsonsetspermissions.defaultMode: "auto": the allowlist form alone created a file, withpermission_denials: []. Adding--permission-mode default(orplan) blocked it. A machine-level auto mode silently outranks the flag — which is consistent with the vendor's own position that auto mode is a convenience feature backed by a best-effort classifier, not a security boundary.You cannot verify any of this by asking the agent what tools it has. Under a restrictive allowlist it still lists
BashandWrite, because it is describing its schema rather than its permissions. Only an absent side effect is evidence — did a file appear, did the command run. Every claim in this note was measured that way.
Note what modelUsage in that JSON is not: it echoes the id you requested, so a bogus id
appears there verbatim and looks confirmed. Cost and token counts are the discriminating signal.
Every id in the table above was verified this way, against a deliberately-bogus control that
failed as expected.
There are two ways to spend a strong model only where it is needed, and AIOS already does one:
- Orchestrator: a strong model holds the loop and delegates the volume down the ladder —
spawn --tier, subagents withmodel, workflow stages. This is the default AIOS shape. - Advisor: a cheaper model holds the loop and consults a stronger one at decision points. Claude Code's advisor tool does this first-party: the worker calls a tool, Anthropic runs the stronger model server-side on the whole transcript, and short advice comes back inside the same request. Nothing new leaves your machine, so the containment boundary below is not engaged.
When it pays: on scale and fast. Anthropic's published measurements put a cheaper worker
with an Opus advisor close to the stronger model's quality, at similar or lower cost. On
judgment it buys about what turning effort up buys, at roughly twice the cost, so raise effort
first. On frontier the only accepted advisor is the same model: a second opinion, not an
economy. No rung has a default advisor, and none should: a default would be a silent spend
increase for every operator. Price the strong model alone at low effort before pairing anything.
It only pays if the worker calls it. Cheaper workers under-call by default. In Anthropic's
measurement, Sonnet and Haiku workers with an Opus advisor and no instruction consulted it on
none of 198 questions, while the tool's definition (about 1,000 tokens) still went out with every
request. So when spawn --advisor launches a Sonnet- or Haiku-class worker, it appends a short
consult instruction to the task: consult before substantive work and before declaring done, save
the work before that call, keep the advice short. Opus and Fable workers call it at a sensible rate
on their own, and the same instruction lowered their pass rates, so spawn leaves them alone.
spawn --advisor <rung|model>(Windows:-Advisor). A rung resolves like--tier; anything else is taken as a model id. It is passed to that worker only, as a settings file (advisorModel).- The advisor must rank at or above the worker's model, and a bad pairing is quiet. The session starts, prints one stderr line saying the advisor cannot advise that model, and runs with no advisor. Read the worker's first screen, or check what ran, as § Verify an id says.
/advisorpersists. Typed once, it is saved to your user settings and applies to every later session, spawned worker and routine that loads them; subagents inherit it. Treat it as a standing spend decision, not a session toggle.- A Fable advisor bills usage credits on plans where Fable does, behind a one-time consent.
- Routines: one that must not pay for an advisor sets
CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1, or runs with--setting-sourcesexcluding the user layer (the form § Verify an id prescribes).
A non-Claude model can be called by an AIOS session. It can never be one. Three rules, in descending order of how much damage getting them wrong does.
There is a class of tool that makes Claude Code believe it is talking to Anthropic while routing elsewhere. They work, which is the problem. Every AIOS session holds live credentials — Gmail, Drive, Slack, a vault with your private context in it — and such a proxy sits in the request path of all of them. This is a no in canonical AIOS, and it is named here rather than left to be discovered, because reaching for one is the natural next step after wanting a cheaper model.
If you want a different model, call it as a tool (§3). That gets you the model without putting anyone between your session and Anthropic.
The same rule covers classifier routers. A cheap classification model is sold as a way to pick the model for each task (usually by a third-party hosted service). It comes in two forms, with two verdicts. As a tool the session calls (it asks "which model fits this?", then launches the helper itself), it is rail-class (§3): the task text leaves your machine on every call, so it is never always-on, and the decision it makes is one the orchestrating session already has the context for. As a proxy between Claude Code and Anthropic that picks the model per message, it is what this rule forbids. The first-party answer to "spend the strong model only where it is needed" is the advisor (§ The advisor), which needs neither.
spawn passes --model straight through to the claude binary, and Claude Code runs Claude
models. So spawn --model claude-fable-5-1 works and spawn --model some-other-vendor-model
cannot.
That is the right shape rather than a limitation to route around. It keeps non-Claude models away from the MCP tool catalog and away from vault writes — which is exactly where the function-calling literature finds they degrade: reported measurements show small and open models losing up to ~91% of function-calling accuracy as the tool catalog grows (LongFuncEval). AIOS sessions carry a large tool catalog. Third-party models get text work; Claude keeps the agentic work.
hooks/pipeline/openrouter.py is the sanctioned way to call a non-Claude model. It takes a prompt, returns
text, and touches nothing else: no MCP tools, no vault writes, no credentials beyond its own key.
It also sends whatever you pass it to a third party. That is not a caveat, it is the whole
mechanism, and it is the one thing in this file that the rest of AIOS is built to avoid — the
vault is local, the MCPs authenticate independently, and nothing ships your context off-machine
unless you ask. So the rail is opt-in and silent until configured: no key present, no calls,
and it says which file to create rather than guessing. Before you pass it something, ask what you
would be comfortable having left your machine. Prose drafts are usually fine. Client
material, anything under an NDA, financial records, and personal context are usually not. See
FORTRESS.md for the containment ladder this sits on the outermost rung of.
The rule has two tiers.
- Context independence, always. Any verifier runs in its own context, sees the output only (never the builder's reasoning or traces), and grades against criteria written before the work started. A critic that shares the builder's context shares its generosity toward its own work: it watched the work being argued for. This holds even when the verifier is the same model.
- Family independence, when the score is about taste or style. When a model's output is being scored on quality, the scorer must come from a different model family than the author. A judge cannot dock points for a systematic tendency it shares. Nothing about the score looks wrong from the inside; the bias is invisible by construction.
Anthropic's own published work on long-running agent harnesses gets its gains from the first tier (a separate evaluator with a written rubric, harsh by design) and concedes the second: a same-family evaluator still leans toward liking model-style output.
Why this is in a framework doc and not a footnote: it is easy to build, it runs for months without complaining, and the same mistake is sitting in public. Reported by an operator who found it in their own verify layer, and checkable by anyone: EQ-Bench, a leading creative-writing leaderboard, uses a Claude model as its judge and ranks a Claude model first. Surge's Hemingway-bench — 5,000+ blind pairwise comparisons judged by professional human writers — asks a similar question with a different judge and produces a different winner. Same question, different ruler, different answer. The point is not which leaderboard is right. It is that a same-family judge cannot be the evidence.
What this means in AIOS, concretely:
- Prefer measurement to judgment. The
voice-gateskill scores prose against the operator's own published corpus by counting — tells per 1,000 words, paragraph bursts, position zones. It is deterministic, so the judge-independence problem cannot arise. Where a countable proxy exists, count it. - When you genuinely need a model to judge, cross the family. That is a use for the rail in §3 — and the reason the de-biasing and the cheap-lane happen to be the same piece of code.
- A verifier that inherits the builder's context is not a verifier. For delegated or overnight
work, use the builder ⇄ evaluator contract in the
orchestration-ladderskill: adone-meansfile agreed before work starts, and an evaluator in its own context that uses the artifact (opens the page, runs the command) rather than reading the diff. - Never
claude -pas the scorer of Claude-authored prose quality. Usingclaude -pas a reader is fine and AIOS does it (hooks/media/video-watch.pycaptions video frames with it). The line is authorship: reading an artifact Claude did not write is measurement; grading one Claude wrote is a family judging itself.
This is a sibling of a class AIOS already carries: an instrument that shares the bias of the thing it measures. The other well-worn form is a check that asserts success from its position in a pipeline rather than from anything about the artifact. Both feel like verification and neither is.
Two cheaper answers to try first, because "route it to another model" is a satisfying conclusion that is often not the cheapest one:
- A lower rung of the same ladder. Most work that feels like it needs a different vendor
actually needs
scaleorfastinstead ofjudgment. - Nothing at all. A deterministic script beats every model on a task with a countable answer,
costs nothing, and cannot drift.
voice-gateis that argument made concrete.
Reach for the rail when the task genuinely wants a different family — a judge that must be independent, or a text lane where another vendor is materially better or cheaper at your volume. "Materially" is worth measuring at your own volume before you build anything: an evaluation that prompted much of this file concluded, for its author's actual output, that moving the prose off Claude would have saved $73 a year — so the prose stayed, and only the routing question survived.
See also: FORTRESS.md (containment ladder) · TOOLS.md (the full
menu) · hooks/_index.md (what each hook is for) ·
CLAUDE.md § Spawning Sessions (the tier flag in context).