Tier Injection
A subagent definition declares a portable tier: low, medium, high or maximum. The kit changes that tier into the model the spawn runs on, at spawn time.
Rules
- Set
CLAUDE_CODE_SUBAGENT_MODELas a machine-wide default. Then no untiered subagent inherits the session model. Since Claude Code 2.1.251 a model the hook writes outranks the variable; on an older Claude Code the variable wins. - Relaunch the whole CLI process after a first install. The host does not watch a directory that did not exist at startup.
/clearreloads neither hooks nor agents. - Remove a
modelpin to let the tier decide. The hook leaves a definition that pins its ownmodel, and a spawn that names one. - Commit
.basicly/core/models/model-map.jsonin the repository. A repository with no map in its own tree gets no rewrite.
What the kit is
The kit is three files in .basicly/core/kit/tier/: install_hook.py, claude_tier_hook.py and tier_resolver.py. It needs no basicly import, nothing on PATH, no third-party package and no network. Copy the three files and .basicly/core/models/model-map.json into any repository, and the kit works there.
| Host | Result |
|---|---|
| Claude Code | A PreToolUse hook on the Agent tool |
| Copilot CLI | Nothing. Copilot selects the model of a subagent in its configuration, and the kit does not write that configuration |
Install
python3 .basicly/core/kit/tier/install_hook.py --dry-run
python3 .basicly/core/kit/tier/install_hook.py
python3 .basicly/core/kit/tier/install_hook.py --user
A second run changes nothing. For every flag (--user, --host, --root, --interpreter, --uninstall) and the command each scope writes, read install.
Check a resolution without a spawn
python3 .basicly/core/kit/tier/tier_resolver.py --host claude --name my-agent
It exits 0 with a model and an alias, or exits 1 with the reason that nothing resolved. Other options: --definition <path>, --tier <tier>, --default-tier <tier>, --vendor <vendor>, --map <path> and --root <path>.
Behaviour to expect
- The hook writes an alias such as
opus, not a model id. Themodelfield of the Agent tool takes an alias. The frontmatter of a definition takes a full model id. - A tier that the map marks
unavailableresolves to nothing, never to the model of another tier.
Choose the model by role
- Owner. One model owns a task from start to finish. Start on the
highmodel. - Delegated work names a tier. Use
mediumby default,highfor a judgement the owner would otherwise repeat, andlowonly to run a test suite or a mechanical search. A dispatch never names a provider model id; the model map resolves the tier. maximumis Fable, and Fable is never a delegated worker. It has two roles. As advisor (/advisor fable), ask it when a problem survived two failed approaches or a decision is hard to undo. As orchestrator, make it the session model for work larger than one context window, or for routine work with a long cost tail.- Raise the effort level before you add a second model.
- A start with no tier and no
modelruns on the session model. Name the model in the call. As a net, setBASICLY_DEFAULT_TIER=mediumin theenvblock of a Claude settings file: the hook then gives an untieredgeneral-purposestart that tier.
For the measured cost of each choice, read roles.