Runtime infrastructure · model-router 0.2.0

Model routing and evidence

Know which choices a hook can make, which remain advice, and what the record actually proves.

Before you begin

First successful run

Install model-router through the marketplace in a compatible hook host. This package has no slash command or agent entry point.
Check Python 3 and a writable ledger location. SessionStart, PreToolUse and SessionEnd hooks use the standard library.
Configure the Vercel AI Gateway credential securely through AI_GATEWAY_API_KEY or the file named by GSTACK_AIGATEWAY_ENV. Do not paste keys into prompts or commit them.
Start a fresh session, make a small authorized request and inspect its opening record and call records. After installation in a cloud session, the first PreToolUse can create a lazy opening record.
Run the score command from the installed model-router package directory. Confirm the files and calls actually read, then inspect the chosen model on a bounded subagent launch. Zero observations are not a passing runtime test.

Install the runtime package

claude plugin install model-router@moxywolf-plugins

Score routing evidence

python3 scripts/route.py score --dir <ledger-dir>

Review one calendar day

python3 scripts/route.py aar --dir <ledger-dir> --date YYYY-MM-DD

Replace placeholders with your actual ledger directory and date. Default ledgers live under ~/.gstack/model-routing/; GSTACK_PEER_REVIEW_DIR selects a different root. Installation does not itself grant data access or action authority.

Choose the right interpretation

Two distinct routing systems

Session and subagent hooks

model-router classifies calls against a committed ontology. Only eligible subagent launches have a model rewritten. Ordinary Read, Grep, Bash and other calls are recorded, not rerouted. Scripts that call LLMs retain their own model selection.

Known classes use the table or ask Jev. Jev answers five questions and deterministic thresholds determine the tier. Explicitly selected launch models are retained; review and Security routing have floor rules. The ledger distinguishes the caller’s choice from advice.

Tiers here: light → Haiku; standard → Sonnet; floor → Opus.

gstack build-item recommendations

MR-001/MR-002 classify an approved build item using trust boundary, cross-file reasoning, documentation-only work, tests and risk. Jev supplies answers; deterministic rules recommend a tier.

Default mode is shadow. Route mode needs at least 20 scored shadow lines and at least 0.90 agreement; overridden and routed lines do not qualify. /gstack-build explicitly does not launch a builder today, so interactive routing is advice unless a separate runner starts the recommended model.

Tiers here: light → Sonnet; standard → Sonnet with an Opus advisor; floor → Opus 5+ per the source policy. These names are not interchangeable with the hook’s mapping.

Return to the engineering workflow

Council decision quorum

Council 0.12.0 adds a three-voice decider for bounded questions. A choice needs a majority of available answers; predicates and scores use the median. Timeouts, errors, refusals and malformed answers are unavailable, and a split or fewer than two available voices is a tie, not an invented decision. Caller code determines what the answers mean.

The decider remains observational until its caller has at least 20 scored lines with at least two available voices per question and a scored majority at least as accurate as Jev alone. Until that gate passes, callers continue acting on Jev. This is separate from the 20-line, 0.90-agreement item-router gate above; source support does not prove either live gate has passed.

Council decision quorum source

Routing is a model choice, not permission to spend, publish, merge or change account access. Release authority still follows the reviewed lane, required gates and current user authorization.

Read the record

Scorecards and after-action reports

Every call contributes a JSONL ledger record. The score report counts classes, tiers, routed calls, Jev consultations and unclassified calls, and states how many files, lines and sessions it read.

Chief of Staff /cos starts a run ID and dispatches carry department, run and applied-model evidence. Claim-check records join those dispatches. A shell export in a separate tool call is not a substitute for the documented standalone cos-run command.

The daily AAR selects records by their timestamps, states its evidence coverage, reports each rate over its own usage count and treats fewer than ten observations as leads. It explicitly notes that harder tasks are routed to stronger models, so the rates do not establish model-caused differences. Untagged records are counted, not silently attributed.

Each report ends in one proposed decision, or no decision when counts are below the bar. It never changes routing automatically. /cos reads the previous calendar day’s report; /cos-brief and /cos-review remain planned.

Read the Chief of Staff run and return contracts

Limits and recovery

What to check before trusting it

Jev unavailable: the hook uses the table default, or leaves an unclassified call unchanged, and records the fallback.
Invalid ontology: routing is off for that session; calls are recorded as refused. Repair the table and start a new session. A mid-session edit does not turn routing back on.
Hook error: the underlying call proceeds unchanged and a hook_error line records the failure. Fail-open behavior preserves work; it is not proof that routing succeeded.
No model savings from ordinary tools: classification and logging do not move those calls to a cheaper model.
Source verified, runtime outstanding: MR-003 live hooks and CS-007 live /cos dispatch tagging are explicitly unverified in DESIGN at this snapshot. Passing repository tests use controlled inputs and do not replace live host validation.

Verified October 25, 2026