From 1fde5bbc765ee7149351485c2b2a73b5919d71e5 Mon Sep 17 00:00:00 2001 From: bchanot Date: Sun, 25 Oct 2026 16:21:39 +0100 Subject: [PATCH] feat(router): /model asks its scope: project, conversation, everywhere This project writes model into .claude/settings.local.json and sets a sticky route; This conversation sets the sticky route only; Everywhere runs the native write. Links refused in the project tree, native never runs after an answer. --- .../2026-10-25-model-scope-dialog-1450.md | 58 +++ .../2026-10-25-model-scope-dialog-1450.md | 74 ++++ README.md | 4 +- lib/effort-shift.md | 15 +- mods/model-router/hooks/register.test.ts | 412 +++++++++++++++++- mods/model-router/hooks/register.ts | 252 ++++++++++- 6 files changed, 804 insertions(+), 11 deletions(-) create mode 100644 .claude/tasks/contracts/2026-10-25-model-scope-dialog-1450.md create mode 100644 .claude/tasks/plans/2026-10-25-model-scope-dialog-1450.md diff --git a/.claude/tasks/contracts/2026-10-25-model-scope-dialog-1450.md b/.claude/tasks/contracts/2026-10-25-model-scope-dialog-1450.md new file mode 100644 index 0000000..e07df21 --- /dev/null +++ b/.claude/tasks/contracts/2026-10-25-model-scope-dialog-1450.md @@ -0,0 +1,58 @@ +# CONTRACT — model-scope-dialog +- date: 2026-10-25 | flow: feat | branch: feature/model-scope-dialog (from develop) +- status: active + +## REQUEST (verbatim — IMMUTABLE) +/model scope dialog in model-router (TODO "Before phase 0"). Fact (docs model-config): `/model ` always writes `model` to user settings.json (tracked here); picker key `s` = session only; project `model` honored at launch. Mod: `command.run` on `model` with args → `$.ui.ask` "This project / This conversation / Everywhere": project = `model` in `.claude/settings.local.json` + sticky route now; conversation = sticky route only (`/route model=`); everywhere = native passthrough. No args → native picker untouched; `-p` or no surface → passthrough. Files: register.ts, register.test.ts, lib/effort-shift.md. Doctor keeps the tracked ≠ opus warning. + +## CLARIFICATIONS +- Pass A: none — request complete (outcome, scope, constraints all named). +- Verified before planning: `command.run` fires on core commands too ("Core is the engine's command", types 2.1.306 l.4365-4378); a guard that fails is skipped and the command runs (fail-open = passthrough, matches BDR-125 "injections fail open"). `$.fs.write` creates the file and its directories. `$.session.root()` = project root (a shell `cd` never moves it). `$.config.set` has no scope argument, so the per-project write goes through `$.fs.write` on `/.claude/settings.local.json`. +- [gated 2026-10-25] Dismissed vs headless = SPLIT (user pick): `$.session.surfaces()` empty (plain `-p`, no surface) → native passthrough BEFORE any dialog; the dialog rejected (Esc, dismissed) or answered with free text → cancel: nothing written, nothing routed, output `model: no scope chosen, nothing changed`. +- [gated 2026-10-25] A name the router does not know (`isModelName` false: `default`, `opusplan`, free text) → native passthrough, no dialog (user pick). +- [gated 2026-10-25] The id written to `.claude/settings.local.json` is the FULL id (alias resolved through `cfg.models`; a full id or a `[1m]` variant kept verbatim) (user pick, LRN-203). +- [after the challenge, 2026-10-25] "known name" = the router's TABLE (alias or a full id listed in `cfg.models`, `[1m]` stripped for the test); a shape-only id (`claude-opus-5-6`) is unknown → native (C10). The two non-native answers mirror a native user switch: sticky model route + run slot dropped, a prior sticky effort kept (C6/R4/R11). Everywhere drops a prior sticky model first (C4/R3). Project tree treated as untrusted: links refused (R5). Cause words fixed, never error messages (R6). Fail-open to native only before an answer (C3/R1). Confirmation pass K1-K14 folded (created = success, FsStat kind `dir`, `[1m]` note, bare token routed, no shared flag, partial-state text, absent = exists false, own reader with fixed words, pin note before the question, tier dropped too, kit `dirs` map, awaited show, `haiku[1m]` native, worktree limit documented). Deferred: engine gitignore behaviour on a created settings.local.json (R13), live hot-switch on a local `model` change (R15/C12) → LRN-212 live check. + +## ACCEPTANCE CRITERIA +1. `/model ` typed by the person (origin `composer`), one token whose `[1m]`-stripped form is an alias of `cfg.models` or one of its full ids, opens one `$.ui.ask` with exactly the options `This project`, `This conversation`, `Everywhere` (that order), header `model-router`; the question names the full id (alias resolved through `cfg.models`, `[1m]` kept) and ends with "where?"; when the local settings file already holds a string `model`, a line before the final question says that at launch here the project pin wins over Everywhere (value through `clean()`). +2. Answer `This project`: `/.claude/settings.local.json` holds `"model": ""` (`[1m]` verbatim), every other key preserved (2-space indent, trailing newline), the file created when absent (success text + `file created: keep it gitignored`, no toast), an existing `.claude` directory (`kind: 'dir'`) accepted; `st.userMain.route.model` = the bare token (as `/route model=` stores it), a prior sticky effort kept, `st.runMain` = null; the native command does NOT run; the output names the file, says how to undo (remove the `model` key), and never promises `[1m]` on the route (note `[1m] follows the session's variant` when the token or the session carries it). +3. Answer `This conversation`: same sticky slot change as 2, no file written anywhere, native does not run. +4. Answer `Everywhere`: `next(e)` passthrough with args unchanged; any sticky model OR tier from an earlier answer or `/route` is dropped first (its effort kept); no file written. +5. Passthrough with no dialog: no args; more than one token; origin not `composer`; a name not in the table (`default`, `opusplan`, shape-only `claude-opus-5-6`, free text, `haiku[1m]`); `st.off`; `st.asking !== null`; `$.session.surfaces()` empty. `ensureConfig` runs before the gates. A dismissed dialog (`askOr` → `Later`) or a free-text answer = cancel: nothing written, nothing routed, output `model: no scope chosen, nothing changed`. +6. The project write refuses, without throwing: a `.claude` or `settings.local.json` that is a symlink or not a directory/regular file; a file that is not JSON or not a JSON object; a read over `MAX_CONFIG_BYTES`; an fs error (a rejecting `stat` or `read` on an existing path is an fs error, never "absent"). Then: toast + output with a FIXED cause word (never `err.message` or `String(err)`), the sticky route still set, the file untouched. "Absent" = `$.fs.exists` false AND `$.fs.stat` rejecting; a path whose `stat` answers `isLink` (a dangling link included) is refused as a link, never "absent" (GATE 2 MEDIUM, 2026-10-25: `exists` may follow links). Same order for `.claude`. +7. The `model` hook's `.catch` uses the warnOnce key `command.run model` and passes through (`next(e)`); the post-answer section runs inside its own try/catch that returns `{ text: 'model failed (); … check /route show and .claude/settings.local.json' }`, so native never runs after an answer. +8. Tests in `register.test.ts` cover each line of criteria 1-7 (the plan's list), including `fable[1m]` and `claude-fable-5-1[1m]`, the conversation → everywhere sequence, the post-answer throw, and the kit carve-out: `installWrite` accepts exactly `${ROOT}/.claude/settings.local.json` and stays loud for every other path. +9. Mod suite green: validate --strict and `claude plugin test`. + CHECK: make test suite=lib/tests/mods.test.sh 2>&1 | tail -1 + EXPECT: all suites green + EVIDENCE: MET exit=0 marker-found :: all suites green +10. `lib/effort-shift.md` documents the dialog (scopes, what each writes, the two non-native answers set a sticky route and drop the run slot, Esc = nothing, no args / unknown name / headless = native) and l.53 is amended; lines ≤ 80 columns. + CHECK: a=$(grep -c 'This conversation' lib/effort-shift.md); b=$(awk 'length($0)>80' lib/effort-shift.md | wc -l); echo "doc=$a/$b" + EXPECT: doc=1/0 + EVIDENCE: MET exit=0 marker-found :: doc=1/0 +11. README.md: l.139 names the scope dialog beside "a user `/model`" and the routing.json writes bullet names the `/model` → This project write of `.claude/settings.local.json`. + CHECK: a=$(grep -c 'this project, this conversation, everywhere' README.md); b=$(grep -c 'This project writes `model` into' README.md); echo "readme=$a/$b" + EXPECT: readme=1/1 + EVIDENCE: MET exit=0 marker-found :: readme=1/1 +12. Full suite green. + CHECK: make test 2>&1 | tail -1 + EXPECT: all suites green + EVIDENCE: MET exit=0 marker-found :: all suites green +13. The diff touches only the FILE SCOPE. + CHECK: git diff --name-only develop -- . ':!.claude' | grep -vcE '^(mods/model-router/hooks/register.ts|mods/model-router/hooks/register.test.ts|lib/effort-shift.md|README.md)$' | sed 's/^/n=/' + EXPECT: n=0 + EVIDENCE: MET exit=0 marker-found :: n=0 +14. No new lint or test suppression in the diff. + CHECK: git diff -U0 develop -- . ':!.claude' | grep -E '^\+' | grep -cE 'eslint-disable|@ts-ignore|@ts-expect-error|shellcheck disable' | sed 's/^/n=/' + EXPECT: n=0 + EVIDENCE: MET exit=0 marker-found :: n=0 +15. `canonical()` is not used on the `/model` path (it strips `[1m]`); `fullId()` resolves the written id. + CHECK: python3 -I -c "import re;s=open('mods/model-router/hooks/register.ts').read();i=s.index('async function handleModelCommand');j=s.index('\n}\n',i);print('canon=%d'%s[i:j].count('canonical('))" + EXPECT: canon=0 + EVIDENCE: MET exit=0 marker-found :: canon=0 + +## FILE SCOPE +- mods/model-router/hooks/register.ts +- mods/model-router/hooks/register.test.ts +- lib/effort-shift.md +- README.md (l.139 and the routing.json writes bullet) diff --git a/.claude/tasks/plans/2026-10-25-model-scope-dialog-1450.md b/.claude/tasks/plans/2026-10-25-model-scope-dialog-1450.md new file mode 100644 index 0000000..0544157 --- /dev/null +++ b/.claude/tasks/plans/2026-10-25-model-scope-dialog-1450.md @@ -0,0 +1,74 @@ +# PLAN r3 — model-scope-dialog (feat) +Contract: `.claude/tasks/contracts/2026-10-25-model-scope-dialog-1450.md` +Scope rule: 7 (PROCEED), 4 files, logic in one mod hook + tests + docs. +r1 → r2 after 3 lenses (correctness FATAL(6), robustness CONCERNS(7), +simplicity CONCERNS(3)); r2 → r3 after the confirmation pass (CONCERNS(3), K1-K14). +Every change below is named at the finding it closes. + +## Files +- `mods/model-router/hooks/register.ts` + - `registerCommandHook` (l.3758): a second hook beside the `route` one: + `on('command.run', { command: 'model' }, async ($, e, next) => handleModelCommand($, st, e, next))` + `.catch(($, e, next) => { warnOnce(st, $, 'command.run model', next.error.kind); return next(e) })`. + Own warnOnce key (C7/R1). The `.catch` can only be reached BEFORE an answer: the whole post-answer section runs inside its own try/catch that returns `{ text }` (K5: no shared flag). Fail-open to native only before an answer (C3/R1/S9). + - `handleModelCommand($, st, e, next)` near `handleCommand` (l.2019), in this order: + 1. `await ensureConfig($, st)` (C2/R8/S7). + 2. gates, each `return next(e)`: `st.off`; `e.origin.kind !== 'composer'`; `tokens = e.args.trim().split(/\s+/)`, `tokens.length !== 1 || tokens[0] === ''` (no args or extra tokens: native owns its syntax); `bare = tokens[0].replace(ONE_M, '')`, `!knownModel(st.cfg, bare)`; `(await $.session.surfaces()).length === 0` (headless) BEFORE the slot check; then `st.asking !== null`; then `st.asking = \`model:${tokens[0]}\`` synchronously (R9 TOCTOU). + 3. `try { … } finally { st.asking = null }`. + - `knownModel(cfg, token)`: `bare = token.replace(ONE_M, '')`; `hasKey(cfg.models, bare) || Object.values(cfg.models).includes(bare)`, AND NOT (`ONE_M.test(token)` and the resolved id starts with `HAIKU`) (K13: haiku has no `[1m]` tier, `haiku[1m]` goes to native). An alias or a full id IN THE TABLE. A shape-only `isFullId` (`claude-opus-5-6`) is NOT known → native (C10; refines the gated pick "unknown name → native": known = the router's table). `fullId(cfg, token)`: `hasKey(cfg.models, bare) ? cfg.models[bare] + (ONE_M.test(token) ? '[1m]' : '') : token`. NEVER `canonical()` (it strips `[1m]`, C11/R14/S6). + - dialog: `askOr($, question, MODEL_SCOPES)` (S1: its LATER on a rejected dialog is the cancel; headless is already gated). Question text (ends with "where?"): `Switch main to where?` preceded by one line per option: `This project: .claude/settings.local.json of this repo (wins at launch) + route now · This conversation: route now, nothing written · Everywhere: user settings.json, every project`; when the local file already holds a string `model` (read inside the slot through `readLocalSettings`, a cause word = no note, value through `clean(v, 60)`), one more line BEFORE the final question line: `Note: this project pins in .claude/settings.local.json: at launch here, the project pin wins over Everywhere` (C4b/R7, K9). Answer not in `MODEL_SCOPES` (LATER, free text) → `{ text: 'model: no scope chosen, nothing changed' }`. + - `MODEL_SCOPES = [PROJECT_SCOPE, CONVERSATION, EVERYWHERE] as const` with `PROJECT_SCOPE = 'This project'` (comment: differs from `THIS_PROJECT` 'This project only', the first-use dialog's label; both fixed by their contracts) and `CONVERSATION = 'This conversation'`; reuse `EVERYWHERE` (S5). + - branches (after `st.modelAnswered = true` for the first two): + - `This conversation` → `stickyModel(st, bare)`; text = `model: sticky route ${bareFull} for this conversation` + ONE_M note + `\n` + `await show($, st)`. `bareFull` = the table id without `[1m]`; ONE_M note = ` ([1m] follows the session's variant)` whenever the token or the session model carries `[1m]` (K3: `route.model` cannot hold `[1m]`, `moveTo` carries the SESSION's variant, so the headline never promises `[1m]` the route cannot deliver; the file keeps the verbatim id). + - `This project` → `const w = await writeLocalModel($, fullId)`; `stickyModel(st, bare)`; `ok = w === 'written' || w === 'created'`; text = (ok ? `model: ${fullId} written to .claude/settings.local.json (remove its "model" key to undo)` + (`w === 'created'` ? `, file created: keep it gitignored` : '') : `model: .claude/settings.local.json not written (${w})`) + `; sticky route ${bareFull} set` + ONE_M note (K3, below) + `\n` + `await show($, st)` (K12: awaited). On a cause word also `$.ui.toast(\`settings.local.json not written: ${w}\`)`. + - `Everywhere` → `dropStickyModel(st)` (C4a/R3: a sticky model from an earlier answer would route main back after the native switch) then `return next(e)`; runMain is dropped by the native PostModelSwitch as today. + - Post-answer section (the three branches) inside `try { … } catch (err) { failOnce or warnOnce; return { text: \`model failed (${errWord(err)}); the file write or the sticky route may have landed: check /route show and .claude/settings.local.json\` } }` (K5/K6). + - `stickyModel(st, bare)`: `st.userMain = { phase: 'custom', route: { model: bare, ...(effort kept) }, source: 'user', ...(explicitEffort kept) }` where effort/explicitEffort come from the previous `st.userMain` (R11: a `/route effort=max` survives, native `/model` never touched effort); `st.runMain = null` (C6/R4: the two non-native answers mirror the native user switch, so "a user `/model` drops the run slot" stays true); `refresh($, st)`. `bare` routes without `[1m]`: `moveTo` (l.1206) carries the variant from the session model (C1). + - `dropStickyModel(st)`: drop `route.model` AND `route.tier` from `st.userMain` (K10: `routeName = tier ?? model`, a sticky `/route plan` tier would upgrade main back); keep the effort if any, else `st.userMain = null`. + - `writeLocalModel($, id): Promise<'written' | 'created' | string>` (string = a FIXED cause word, never `err.message`/`String(err)`: R6; causes: `project root unknown`, `.claude is a link`, `not a regular file`, `not JSON`, `not an object`, `too large`, `fs error `): + 1. `root = await $.session.root()` (throw → `project root unknown`). + 2. `dir = ${root}/.claude`, `path = ${dir}/${LOCAL_SETTINGS_NAME}` (`LOCAL_SETTINGS_NAME = 'settings.local.json'`). `if (await $.fs.exists(dir))`: `st = await $.fs.stat(dir)` (reject → `fs error `); `st.isLink` → `.claude is a link`; `st.kind !== 'dir'` (FsStat kinds are `file | dir | other`, K2) → `.claude is not a directory`. Absent → OK (`$.fs.write` creates it) (R5: the project tree is untrusted, BDR-116(3)). + 3. `readLocalSettings($, path)` (shared with the pre-dialog Note, K9; never throws, returns `{ data, created } | string`): `!(await $.fs.exists(path))` → `{ data: {}, created: true }` (absent is ONLY a false `exists`, K7); `stat = await $.fs.stat(path)` (reject → `fs error `); `stat.isLink` → `settings.local.json is a link`; `stat.kind !== 'file'` → `not a regular file`; `stat.size > MAX_CONFIG_BYTES` → `too large`; `text = await $.fs.read(path)` (reject → `fs error `); `JSON.parse` throw → `not JSON`; `!isRecord` → `not an object`. Own small reader instead of `readLayer` (K8: its log text folds I/O and syntax errors; the cause words here are fixed by the checks themselves). + 4. `data.model = id`; `await $.fs.write(path, JSON.stringify(data, null, 2) + '\n')` (fs throw → `fs error `). Return `created ? 'created' : 'written'`. SUCCESS = `'written' || 'created'` (K1); the toast fires only on a cause word. +- `mods/model-router/hooks/register.test.ts` (kit changes NAMED, C5/R12/S3): + - `installWrite`: allow exactly `${ROOT}/.claude/settings.local.json` with or without a prior read; every other non-routing path stays loud (`expect(...)` unchanged for them). `slot()` maps that path to `'local'`. + - `World`/`Fixture`: `surfaces: readonly string[]` (default `['terminal']`), `installWorld` adds `on('session.surfaces', () => ({ value: w.surfaces }))`; a `dirs: Map` the world's `fs.exists`/`fs.stat` answer for paths WITHOUT file text (K11: today stat throws for them), so `${ROOT}/.claude` can be an existing dir, a link, or a file. + - a bottom `on('command.run', { command: 'model' }, () => ({ text: 'native' }))` installed per test (or a `NATIVE` plugin like `PROBE`) to witness the passthrough; `modelCmd($, args, origin?)` helper mirroring `route()`. +- `lib/effort-shift.md`: l.40 "a user `/model` drop it" → keep, then add to "Run slot and levers": `/model ` typed asks the scope (This project = `.claude/settings.local.json` + sticky model route, This conversation = sticky route only, Everywhere = the native write to user settings.json, every project); the two non-native answers set a sticky model route and drop the run slot like a native switch; Esc = nothing changes; no args, an unknown name or a headless run = native. l.53 "A user `/model` only moves the baseline" gets "(Everywhere; the two other scopes set a sticky route, which the classifier never overrides)". ≤ 80 cols. +- `README.md` (S8, in scope, two edits): l.139 "a user `/model`" → "a user `/model` (typed with a name it asks the scope: this project, this conversation, everywhere)"; the writes bullet ("Only a dialog answer, `/route ask on|off` or `/route forget` writes `routing.json`") gains ", and `/model ` → This project writes `model` into the project's `.claude/settings.local.json`". +- `register.ts` l.75 comment (`only a skill, /route clear|off or a user /model write or drop it`) stays true (runMain dropped on every answer path). + +## Edge cases +- `/model fable[1m]`, `/model claude-fable-5-1[1m]`: bare `fable`/`claude-fable-5-1` is known → dialog; file gets `claude-fable-5-1[1m]`; `stickyModel(st, bare)` stores the BARE TOKEN as `/route model=` does (`fable` or `claude-fable-5-1`, K4); the session's `[1m]` is carried by `moveTo`, the token's is not promised. Tests for both (C1/R2). +- `haiku[1m]` → native (K13). +- Worktree session: `$.session.root()` follows the worktree, so "This project" writes that worktree's `.claude/settings.local.json`; named as a limit in effort-shift.md (K14), not handled. +- `.claude/settings.local.json` holds `null`, `[]`, `"x"` → `not an object`, nothing overwritten, route only (C8/S2). +- `.claude` or the file is a symlink → refused, nothing written, route only (R5). +- Dialog answered, then `show` throws → `.catch` returns `{ text: 'model failed …' }`, native never runs (C3). +- Free text under Other → cancel, same text as Esc. +- Headless (`surfaces()` = `[]`) → passthrough, no dialog. +- The sticky route may be HELD by `decideMain` caps (switch off, cold read > cap): the output never claims "routed now"; the appended `show` line tells the truth (C9/R10). +- `[deferred 2026-10-25]` R13: whether the engine gitignores a `settings.local.json` it creates is unverified; the output's "keep it gitignored" note stands in. R15 / C12: whether a live `model` change in the local file hot-switches the session (ConfigChange `local_settings`) is unverified → LRN-212 live check after the suite: after "This project", no PostModelSwitch, no down mark; output wording stays neutral ("written to", never "next launch"). + +## Tests (register.test.ts, "model command" block) +- asks the three scopes in order with header `model-router` for `/model fable` and for `/model claude-fable-5-1[1m]`; question names the full id; native not run. +- This project: writes `model` (full id, `[1m]` verbatim), keeps other keys (`permissions` fixture), `userMain.route.model` = bare token, `runMain` null, native not run, output names the file. Positive control with `${ROOT}/.claude` present as `{ kind: 'dir' }` (K2). +- This project: in a `[1m]` session and in a plain session, the output carries the `[1m] follows the session's variant` note only when the token or the session has it (K3). +- This project: creates the file when absent (success text + `file created: keep it gitignored`, no toast) (K1). +- This project: `null` / array file → `not an object`, file unchanged, route set, toast. +- This project: `.claude` link / `.claude` regular file / settings file link → refused with the matching cause word, file untouched; `exists` true but `stat` rejecting → `fs error`, file untouched (K7). +- This project: fs.write throws → `fs error …`, route set. +- This conversation: route = `/route model=` equivalent, sticky effort from a prior `/route effort=max` kept, nothing written, native not run. +- Everywhere: native run with args unchanged; a prior sticky model dropped (sequence: conversation X → everywhere Y → `userMain.route.model` undefined). +- passthrough, no question: no args; two tokens; `default`; `claude-opus-5-6` (shape only); `haiku[1m]`; sdk origin; `st.off`; `st.asking` set; `surfaces = []`. +- question carries the project-pin note when the local file holds `model`, not otherwise (K9). +- Everywhere after `/route plan` (sticky tier) drops the tier too (K10). +- dismissed → cancel text, nothing written, nothing routed, native not run. +- post-answer throw → `model failed …` text naming `/route show`, native not run (make `ui.status` throw from the world: `refresh` inside `stickyModel`; `session.usage` is swallowed by `readTokens`, K12). + +## Disposition (STEP 0.6) +- honors BDR-116 (composer-only writers; model never writes; project tree untrusted) by gating on `origin.kind === 'composer'`, refusing links, writing only the file the user chose. +- honors BDR-125 amendment 8 by making `.claude/settings.local.json` the "This project" target and leaving the native user-settings write to "Everywhere". +- honors BDR-115/LRN-203 (full ids in anything a hook writes) via `fullId()`; never `canonical()`. +- honors LRN-098 (`/model` rewrites settings.json) by naming the user-settings write in the Everywhere option and by never reaching native after an answer. +- applies LRN-212 (hot-loaded working-tree mod) for the live check named above. diff --git a/README.md b/README.md index 71d522c..f1a9555 100644 --- a/README.md +++ b/README.md @@ -136,13 +136,13 @@ effort, never version. Transcript audit `python3 lib/effort-audit.py`. `mods/model-router/` is a Claude Code mod (a function-hooks plugin) that applies this table per request. It loads in every session through the tracked symlink `skills/model-router`, as `model-router@skills-dir`. -- Main loop: every request gets the route in force. A typed skill with a row routes the main loop to it; a best-tier row (`plan`, `reflect`, `orchestrate`, `escalate`; `audit` is an agent row, never typed) holds across turns in a run slot until `/route clear`, `/route off`, a user `/model` or a typed skill on a non-best row. A skill without a row leaves the route as it is. A rowed skill the model loads inside a best-tier run moves effort only when its row ranks below the run's model. Main routed onto a model whose context window the conversation outgrew returns to the session model. Before main runs on a model, the one it moves to or the one it keeps (the session's own model included), the mod probes it with one small completion bounded to 8 seconds; the step (and `/route show`, the route tool's answer) waits for it. A timeout or an error marks the model down (reason `probe`, held for `cooldownMinutes` like any breaker hold) and the decision is taken again once. A model already marked down is never probed, and a model that answered is not probed again, `/clear` included, until it is marked down. When a lower model stands in for its tier's head held down (Opus for Fable on a best-tier phase), the phase's own effort goes one notch up: `reflect` xhigh, `plan` max, `orchestrate` high, `escalate` stays max. An effort asked explicitly (`/route ... effort=`, the `route` tool's `effort`) or set by a floor is never raised. `/route show` and the route tool's answer print the level with `(opus stands in for fable)`; the verbose transition line names `stand-in` as a cause. +- Main loop: every request gets the route in force. A typed skill with a row routes the main loop to it; a best-tier row (`plan`, `reflect`, `orchestrate`, `escalate`; `audit` is an agent row, never typed) holds across turns in a run slot until `/route clear`, `/route off`, a user `/model` (typed with a name it asks the scope: this project, this conversation, everywhere) or a typed skill on a non-best row. A skill without a row leaves the route as it is. A rowed skill the model loads inside a best-tier run moves effort only when its row ranks below the run's model. Main routed onto a model whose context window the conversation outgrew returns to the session model. Before main runs on a model, the one it moves to or the one it keeps (the session's own model included), the mod probes it with one small completion bounded to 8 seconds; the step (and `/route show`, the route tool's answer) waits for it. A timeout or an error marks the model down (reason `probe`, held for `cooldownMinutes` like any breaker hold) and the decision is taken again once. A model already marked down is never probed, and a model that answered is not probed again, `/clear` included, until it is marked down. When a lower model stands in for its tier's head held down (Opus for Fable on a best-tier phase), the phase's own effort goes one notch up: `reflect` xhigh, `plan` max, `orchestrate` high, `escalate` stays max. An effort asked explicitly (`/route ... effort=`, the `route` tool's `effort`) or set by a floor is never raised. `/route show` and the route tool's answer print the level with `(opus stands in for fable)`; the verbose transition line names `stand-in` as a cause. - Sub-agents: a routed agent gets its row's model at spawn, within its tier and only upward from its frontmatter model, and the row's effort on every step. Explicit `model` / `effort` params on the Agent call win; a project-defined agent of the same name keeps its own definition. Built-ins: Explore runs on sonnet/medium, Plan on opus/xhigh. A built-in `general-purpose` agent that main spawns with no `model` param, while main runs below the session model (a downgrade or a breaker fallback), starts on the session model instead of inheriting the lower one; it is not pinned when the session model is marked down, for a fork, a workflow or a nested spawn, or when a project or user definition shadows the built-in. Other agent types are never pinned this way: the hook cannot see their frontmatter model. - Levers inside a run: `ultrathink` in a prompt sets the turn's minimum effort; `/route effort=max` holds until `/route clear`. Keyword prompt rules (`plan`, `design`, `architecture`… take plan's effort; `why`, `review`, `audit`… reflect's), `ultrathink` and a main Agent dispatch (the derived `orchestrate` route, held until its background agents end) set the turn's effort only, never a model: they never lift main above the session model, and a held best-tier run keeps its model. Fable on main comes only from a skill row, the `route` tool or a typed `/route`. The built-in `/effort` is not a lever inside a run, rows and routes outrank it. - Prompt classifier: a plain prompt typed in the composer (12 characters or more, not a slash command) that no keyword rule, skill, run slot, `/route` or floor covers is sent to the engine's small fast model, one call, bounded to 3 seconds (the prompt waits for it, typically under a second). The label (`design`, `analysis`, `coding`, `bookkeeping`, `chat`) maps to plan, reflect, implement or apply (`chat` routes nothing), and the turn takes that phase's route: its effort becomes the turn's default, and its model may move the main loop, never above the session model. A `coding` or `bookkeeping` guess moves main down only when `mainModelSwitch` is on and the cold read fits `downgradeMaxTokens`; an `ultrathink` floor in the same turn raises the effort only, the guess's model holds. No dialog opens and no file is written. The route is gone at the end of the turn, a later route call or typed skill replaces it, and a `/effort` you type between turns drops the guess for that turn only. A typed best-tier skill holds its run slot across turns, so nothing is classified there until `/route clear`. Long prompts are sampled (first 500 and last 1500 code points), so pasted text at the end can steer one turn's route. Three failures in a row pause it for `cooldownMinutes` (one toast, `classifier: paused` in the status line). Never in a sub-agent, mid-turn or under `-p`. Off per session with `/route classify off`, per machine with `"classify": false`. The status line reads `route: classifier `; `/route verbose on` adds the transition line. - `/route` (user command) shows or sets the route: `show`, `clear`, `off`, `on`, `reload`, `pending` (rows and phases not confirmed yet), `ask on|off` (first-use dialog on or off), `forget ` (takes decisions back: a changed row returns to its shipped phase; `all` and `projects` ask first), a phase name, `model= effort=`, `switch on|off`, `classify on|off` (the prompt classifier, below), `verbose on|off` (logs transitions only: each change of model or effort, with a few words of cause). `/route show` names the run slot when one holds (`main: run `) and prints the switch with its cap and the prompt-cache TTL (`switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`). The model sets routes through a `route` tool. - First use: the first time a rowed skill is typed, a rowed agent is spawned or a phase is declared on the main loop through the `route` tool, the mod asks once whether the route is right. The question gives context: the skill's description (first sentence of its `SKILL.md` frontmatter) or the agent's, the phase with its `about` line, and the model id and effort the next step really runs on; a declared phase also says what uses it (rows, prompt rules). A row offers Later, Keep or Change; a declared phase offers Later or Keep. Change asks the model (fable, opus, sonnet, haiku, each shown with the tier it heads), then the effort among those the phases on that model use (shipped table: fable medium, high, xhigh or max; sonnet low, medium, high or xhigh; opus and haiku have one level each, so no question), then Everywhere or This project only. Rows stay phase names, so the pair maps to an existing phase: the row's current phase wins a tie and the same phase counts as Keep; a pair no phase offers needs a new phase added by hand in routing.json. Everywhere moves the row and records the shipped phase under `changed`; This project only stores an exception under `projects`, keyed by the origin remote reduced to `host/path` (no credentials, no local paths; a remote that cannot be read that way offers no project choice). Keep lands under `confirmed`; Later, a dismissed dialog or a free-text answer asks again next session. After a skill row changes, a toast names the model and effort that skill now runs on, plus a hint when the main loop holds back a downgrade: `/route switch on` when the switch is off, the cap hold (`held: downgrade skipped: cold read tokens over `) when the cold read is over `downgradeMaxTokens`. One dialog at a time, never in a headless (`-p`) run, never inside a sub-agent. -- Only a dialog answer, `/route ask on|off` or `/route forget` writes `routing.json`, never the model. Writes are serialized, capped at 64 KiB, and refused when the file is missing (it is never created). Each write leaves the config repo dirty; a toast reminds you to commit it from there. +- Only a dialog answer, `/route ask on|off` or `/route forget` writes `routing.json`, never the model. The one other write: `/model ` → This project writes `model` into the project's `.claude/settings.local.json`. Writes are serialized, capped at 64 KiB, and refused when the file is missing (it is never created). Each write leaves the config repo dirty; a toast reminds you to commit it from there. - The spinner suffix and the status line under the prompt show the route in force; the status line adds ` · switch off` when the downgrade switch is off. Config layers: `mods/model-router/routing.json` (tracked: phases with their tier, effort and `about` line, rows, decisions, `ask`), then the optional per-machine `~/.claude/model-router.json`, which wins. A `.claude/model-router.json` inside a project is never read. Machine keys: `models` (alias → full id), `windows` (context window per full id), `tiers` (ordered alias lists per tier: `best` fable>opus>sonnet, `big` opus>fable>sonnet, `work` sonnet>opus, `cheap` haiku>sonnet; the first alias not down is used), `fallback` (the rank order of the aliases, best first, used by the breaker), `cooldownMinutes` (how long a model stays marked down after an availability error, 15 by default, doubling per episode up to 300), `mainUpgrade` (default `true`: the main loop may move up to a phase's tier), `upgradeMaxTokens` (default 200000: the largest cold read a main-loop upgrade may cost), `downgradeMaxTokens` (default 120000: the same cap for a downgrade; the cold read is the context minus what the target model's prompt cache already holds, taken from main's last step on that model within the prompt-cache TTL, forgotten by `/clear` and `/route reload`. The TTL follows the engine's `cache_ttl` (5 or 60 minutes) carried by main's model-switch events, is 60 minutes until the first one and survives `/clear`. The context also counts the prompt just submitted, which the engine's usage may not include yet: code points / 3 of its text, its context entries and a typed skill's body, summed and added at the turn's first main step unless usage already grew by half of it. A `document` attachment makes the size unknown, and an unknown context size blocks the switch; the step, `/route show`, the first-use dialog and the toast read the same adjusted size), `phases`, `agents`, `skills`, `prompt` (rules), `mainModelSwitch` (default `true`: the main loop may move down to a cheaper model; a value that is not a boolean turns it off and says so), `classify` (default `true`; `false` stops the prompt classifier on that machine), `probe` (default `true`: the model main runs on, moved to or kept, is tried once, 8 seconds at most, before main is sent to it; `false` skips the probe on that machine; a non-boolean value is ignored and said; `/route show` prints `probe:`), `verbose` (default `false`; `true` logs transitions only, a non-boolean value falls back to `false`), `spinner` (default `true`), `enabled` (default `true`; `false` turns the mod off on that machine), `ask` (overrides routing.json's `ask` on that machine). A `null` value in `agents` or `skills` drops a row. Edit phases and rows by hand in routing.json (a phase's `about`, 120 characters at most, is read from there only and shown in the dialog; a model and effort pair no phase offers needs a new phase there); without it the mod runs the code's default phases, with no rows and no dialog. `/route reload` re-reads both files. diff --git a/lib/effort-shift.md b/lib/effort-shift.md index 3ca0fb3..0764b32 100644 --- a/lib/effort-shift.md +++ b/lib/effort-shift.md @@ -42,6 +42,16 @@ relaunch: `ultrathink` in the prompt (turn floor) or `/route effort=max` (sticky, `/route clear` after). Builtin `/effort` is NOT a lever inside a run: rows and routes outrank it. +`/model ` typed with a name the router knows asks the scope (Esc +changes nothing). This project writes the full id as `model` into +`.claude/settings.local.json` (created if absent: keep it gitignored) and +sets a sticky model route. This conversation sets the sticky route only, +nothing written. Everywhere is the native command: user `settings.json`, +every project. The two non-native answers drop the run slot like a native +switch and keep a sticky effort; Everywhere drops an earlier sticky model. +No args, an unknown name or a run with no surface (`-p`) go native, no +question. The file is the session root's: in a worktree, that worktree's. + ## Limits - A skill typed while a background agent is live routes only through the @@ -51,8 +61,9 @@ Builtin `/effort` is NOT a lever inside a run: rows and routes outrank it. model: the guessed phase sets the turn's effort and, under `mainModelSwitch` and `downgradeMaxTokens` (max cold read, default 120000), may move main DOWN, never up. A user `/model` only moves the - baseline the guess starts from (`/route classify off` to stop guessing; - never `-p`). + baseline the guess starts from (Everywhere; the two other scopes set a + sticky route, which the classifier never overrides) (`/route classify + off` to stop guessing; never `-p`). - Keyword prompt rules (`plan|design|architecture…`, `why|review|audit…`), `ultrathink` and a background agent dispatch (derived `orchestrate`) set the turn's effort only, never diff --git a/mods/model-router/hooks/register.test.ts b/mods/model-router/hooks/register.test.ts index b693684..2dae7da 100644 --- a/mods/model-router/hooks/register.test.ts +++ b/mods/model-router/hooks/register.test.ts @@ -39,11 +39,20 @@ type World = { gate: Promise | undefined // holds a dialog open until it settles writeGate: Promise | undefined // holds an fs.write open failWrite: boolean // fs.write rejects + clockFailsAfterAsk: boolean // clock.now rejects once a dialog opened onAsk: (() => void) | undefined // called when a dialog opens onWrite: (() => void) | undefined // called when an fs.write starts repo: { root: string; remote: string | null } | null | 'fail' env: string | undefined // HOME as env.get answers it (undefined = unset) kinds: Map // per-path stat kind override + dirs: Map + // paths fs.exists/fs.stat answer for, with or without file text + brokenStat: Set // paths that exist but whose stat rejects + surfaces: readonly string[] // what session.surfaces answers ([] = headless) complete: (model: string) => unknown // what a completion resolves to completions: string[] // every model a completion was asked of } @@ -56,6 +65,8 @@ type Fixture = { answers?: string[] repo?: World['repo'] noHome?: boolean // HOME unset: env.get answers undefined + surfaces?: readonly string[] // default ['terminal'] + clockFailsAfterAsk?: boolean // see World; the rig gets no MockClock } /** @@ -117,18 +128,25 @@ function newWorld(fx: Fixture = {}): World { gate: undefined, writeGate: undefined, failWrite: false, + clockFailsAfterAsk: fx.clockFailsAfterAsk ?? false, onAsk: undefined, onWrite: undefined, repo: fx.repo === undefined ? { root: ROOT, remote: REMOTE } : fx.repo, env: fx.noHome ? undefined : HOME, kinds: new Map(), + dirs: new Map(), + brokenStat: new Set(), + surfaces: fx.surfaces ?? ['terminal'], complete: () => PROBE_OK, completions: [], } } +const LOCAL_FILE = `${ROOT}/.claude/settings.local.json` + const slot = (path: string): string => { if (path.endsWith('/routing.json')) return 'routing' + if (path === LOCAL_FILE) return 'local' // the engine resolves a relative path against its cwd: `undefined/...` // (a HOME read as unset and not guarded) comes back absolute const rel = /\/(undefined\/\.claude\/.*)$/.exec(path) @@ -146,18 +164,23 @@ const routingOf = (w: World): Rec => function installWorld(on: On, w: World): void { on('env.get', () => ({ value: w.env })) on('fs.exists', (_a, e) => ({ - value: w.files.has(slot(e.path)) || e.path === ROOT, + value: w.dirs.get(e.path)?.exists === false ? false : + w.files.has(slot(e.path)) || e.path === ROOT || w.dirs.has(e.path), })) on('fs.stat', (_a, e) => { const text = w.files.get(slot(e.path)) - if (text === undefined && e.path !== ROOT) throw new Error('ENOENT') + const known = w.dirs.get(e.path) + if (w.brokenStat.has(e.path)) throw new Error('EIO') + if (text === undefined && e.path !== ROOT && known === undefined) { + throw new Error('ENOENT') + } return { value: { - kind: w.kinds.get(e.path) ?? + kind: known?.kind ?? w.kinds.get(e.path) ?? (text === undefined ? 'dir' as const : 'file' as const), size: text?.length ?? 0, mtimeMs: 0, - isLink: false, + isLink: known?.isLink ?? false, ...(e.resolve ? { realPath: REAL_ROOT } : {}), }, } @@ -170,6 +193,7 @@ function installWorld(on: On, w: World): void { }) installWrite(on, w) on('session.root', () => ({ value: ROOT })) + on('session.surfaces', () => ({ value: w.surfaces as never })) on('session.repo', () => { if (w.repo === 'fail') throw new Error('no repo') return { value: w.repo === null ? null : { @@ -180,13 +204,19 @@ function installWorld(on: On, w: World): void { installDialog(on, w) } +/** The paths the world's fs.write accepts: see installWrite. */ +const worldServes = (w: World, path: string): boolean => + path === LOCAL_FILE || (slot(path) === 'routing' && w.reads.includes(path)) + /** * The world's fs.write. Loud: a write anywhere but the routing.json the mod * read fails the test (never a project tree, never the machine override). + * One carve-out: the project's .claude/settings.local.json, which the + * /model scope dialog writes, read or not (a missing file is created). */ function installWrite(on: On, w: World): void { on('fs.write', async (_a, e) => { - expect(slot(e.path) === 'routing' && w.reads.includes(e.path), + expect(worldServes(w, e.path), `the world never served ${e.path}`).toBe(true) w.written.push(e.path) w.onWrite?.() @@ -217,6 +247,15 @@ function installDialog(on: On, w: World): void { }) } +/** A clock that rejects once a dialog opened (no MockClock: never advanced). */ +function failingClock(on: On, w: World): MockClock { + on('clock.now', () => { + if (w.asked.length > 0) throw new Error('boom') + return { value: 0 } + }) + return undefined as unknown as MockClock +} + /** * Fires session.start so the mod loads its config and registers /route. * The bottom hooks the router reads are in place before the first `$` call: @@ -231,7 +270,9 @@ async function boot( tokens: number | null = 1000, world: World = newWorld(), ): Promise { - const clock = mock.clock(on) + const clock = world.clockFailsAfterAsk + ? failingClock(on, world) + : mock.clock(on) on('session.model', () => ({ value: model })) on('classic.StopFailure', () => ({})) on('classic.PostModelSwitch', () => ({})) @@ -5918,3 +5959,362 @@ test('keyword cap: a dispatch outside a run keeps main on the session model', as await dispatch($) expect(await stepOn($, rig, OPUS)).toEqual({ model: OPUS, effort: 'medium' }) }) + +// ---- /model : the scope dialog ------------------------------------- + +const SCOPES = ['This project', 'This conversation', 'Everywhere'] +const FABLE_1M = `${FABLE}[1m]` +const NO_SCOPE = 'model: no scope chosen, nothing changed' + +type ModelRig = { + w: World + ran: string[] // the args the native /model got + toasts: string[] + rig: Rig +} + +/** Boots with a bottom native /model that records its args. */ +async function bootModel( + $: Engine, + on: On, + answers: string[], + session: string = OPUS, + fx: Fixture = {}, +): Promise { + const ran: string[] = [] + on('command.run', { command: 'model' }, (_a, e) => { + ran.push(e.args) + return { text: 'native' } + }) + const toasts = recordToasts(on) + const w = newWorld({ answers, ...fx }) + const rig = await bootRig($, on, session, 1000, w) + return { w, ran, toasts, rig } +} + +/** Runs `/model ` as typed (or from another origin). */ +async function modelCmd( + $: Engine, + args: string, + kind: 'composer' | 'sdk' = 'composer', +): Promise { + const out = await $.command.run({ + command: 'model', + args, + origin: { kind }, + presentation: { isFullscreen: false, columns: 80 }, + }) + return out.text ?? '' +} + +const localOf = (w: World): Rec => + JSON.parse(w.files.get('local') ?? '{}') as Rec + +test('model command: asks the three scopes, the full id, native not run', async ( + $, on) => { + const m = await bootModel($, on, ['Later', 'Later']) + await modelCmd($, 'fable') + await modelCmd($, 'claude-fable-5-1[1m]') + expect(m.w.asked.map(q => q.options)).toEqual([SCOPES, SCOPES]) + expect(m.w.asked.map(q => q.header)).toEqual(['model-router', 'model-router']) + const [plain, long] = m.w.asked as [Asked, Asked] + expect(plain.text.endsWith(`Switch main to ${FABLE} where?`)).toBe(true) + expect(long.text.endsWith(`Switch main to ${FABLE_1M} where?`)).toBe(true) + expect(m.ran).toEqual([]) +}) + +test('model command: This project writes the full id and keeps the keys', async ( + $, on) => { + const m = await bootModel($, on, ['This project']) + m.w.files.set('local', JSON.stringify({ permissions: { allow: ['Bash'] } })) + m.w.dirs.set(`${ROOT}/.claude`, { kind: 'dir', isLink: false }) + const out = await modelCmd($, 'fable') + expect(localOf(m.w)).toEqual({ + permissions: { allow: ['Bash'] }, model: FABLE, + }) + expect(m.w.files.get('local')).toBe( + JSON.stringify(localOf(m.w), null, 2) + '\n') + expect(out).toContain(`${FABLE} written to .claude/settings.local.json`) + expect(out).toContain('remove its "model" key to undo') + expect(out).not.toContain('file created') + expect(m.toasts).toEqual([]) + expect(m.ran).toEqual([]) + expect((await stepOn($, m.rig, OPUS)).model).toBe(FABLE) +}) + +test('model command: This project keeps [1m] verbatim in the file', async ( + $, on) => { + const m = await bootModel($, on, ['This project', 'This project']) + await modelCmd($, 'fable[1m]') + expect(localOf(m.w).model).toBe(FABLE_1M) + await modelCmd($, 'claude-fable-5-1[1m]') + expect(localOf(m.w).model).toBe(FABLE_1M) + expect((await stepOn($, m.rig, OPUS)).model).toBe(FABLE) +}) + +test('model command: the [1m] note shows only for a token or session [1m]', async ( + $, on) => { + const m = await bootModel($, on, ['This project', 'This project']) + expect(await modelCmd($, 'fable')).not.toContain('[1m] follows') + expect(await modelCmd($, 'fable[1m]')).toContain( + "[1m] follows the session's variant") + expect(m.ran).toEqual([]) +}) + +test('model command: a [1m] session adds the note to a plain token', async ( + $, on) => { + await bootModel($, on, ['This project'], `${OPUS}[1m]`) + expect(await modelCmd($, 'fable')).toContain('[1m] follows') +}) + +test('model command: This project creates the file when absent', async ( + $, on) => { + const m = await bootModel($, on, ['This project']) + const out = await modelCmd($, 'opus') + expect(localOf(m.w)).toEqual({ model: OPUS }) + expect(out).toContain('file created: keep it gitignored') + expect(m.toasts).toEqual([]) +}) + +const BAD_TEXT: [string, string, string][] = [ + ['null', 'null', 'not an object'], + ['an array', '[]', 'not an object'], + ['a string', '"x"', 'not an object'], + ['broken JSON', '{nope', 'not JSON'], + ['over the size cap', JSON.stringify({ pad: 'x'.repeat(70000) }), + 'too large'], +] + +for (const [name, text, cause] of BAD_TEXT) { + test(`model command: This project refuses a file: ${name}`, async ( + $, on) => { + const m = await bootModel($, on, ['This project']) + m.w.files.set('local', text) + expect(await modelCmd($, 'fable')).toContain(`not written (${cause})`) + expect(m.w.files.get('local')).toBe(text) + expect(m.w.written).toEqual([]) + expect(m.toasts).toEqual([`settings.local.json not written: ${cause}`]) + expect(mainLine(await route($, 'show'))).toContain('user custom') + }) +} + +const refusals: [string, (w: World) => void, string][] = [ + ['.claude link', w => w.dirs.set(`${ROOT}/.claude`, + { kind: 'dir', isLink: true }), '.claude is a link'], + ['.claude file', w => w.dirs.set(`${ROOT}/.claude`, + { kind: 'file', isLink: false }), '.claude is not a directory'], + ['settings link', w => { + w.files.set('local', '{}') + w.dirs.set(LOCAL_FILE, { kind: 'file', isLink: true }) + }, 'settings.local.json is a link'], + ['.claude dangling link', w => w.dirs.set(`${ROOT}/.claude`, + { kind: 'other', isLink: true, exists: false }), '.claude is a link'], + ['settings dangling link', w => w.dirs.set(LOCAL_FILE, + { kind: 'other', isLink: true, exists: false }), + 'settings.local.json is a link'], + ['settings dir', w => { + w.files.set('local', '{}') + w.dirs.set(LOCAL_FILE, { kind: 'dir', isLink: false }) + }, 'not a regular file'], + ['stat error', w => { + w.files.set('local', '{}') + w.brokenStat.add(LOCAL_FILE) + }, 'fs error HooksError'], +] + +for (const [name, setup, cause] of refusals) { + test(`model command: This project refuses: ${name}`, async ($, on) => { + const m = await bootModel($, on, ['This project']) + setup(m.w) + const before = m.w.files.get('local') + const out = await modelCmd($, 'fable') + expect(out).toContain(`not written (${cause})`) + expect(m.w.files.get('local')).toBe(before) + expect(m.w.written).toEqual([]) + expect(m.toasts).toEqual([`settings.local.json not written: ${cause}`]) + expect(mainLine(await route($, 'show'))).toContain('user custom') + expect(m.ran).toEqual([]) + }) +} + +test('model command: a failing write reports an fs error, route set', async ( + $, on) => { + const m = await bootModel($, on, ['This project']) + m.w.failWrite = true + const out = await modelCmd($, 'fable') + expect(out).toContain('not written (fs error') + expect(m.toasts).toHaveLength(1) + expect(out).not.toContain('EACCES') + expect(mainLine(await route($, 'show'))).toContain('user custom') +}) + +test('model command: This conversation sets the route, writes nothing', async ( + $, on) => { + const m = await bootModel($, on, ['This conversation']) + await route($, 'effort=max') + const out = await modelCmd($, 'fable') + expect(out).toContain(`sticky route ${FABLE} for this conversation`) + expect(m.w.written).toEqual([]) + expect(m.w.files.has('local')).toBe(false) + expect(m.ran).toEqual([]) + const line = mainLine(await route($, 'show')) + expect(line).toContain('user custom') + expect(line).toContain('effort max') + expect((await stepOn($, m.rig, OPUS)).model).toBe(FABLE) +}) + +test('model command: the local scopes drop the run slot', async ($, on) => { + on('command.run', { command: 'model' }, () => ({ text: 'native' })) + await bootRun($, on, OPUS, newWorld({ answers: ['This conversation'] })) + await loadSkill($, 'feat') + await endTurn($) + expect(await modelCmd($, 'sonnet')).toContain('sticky route') + expect(await route($, 'clear')).not.toContain('run slot dropped') +}) + +test('model command: Everywhere runs native, args unchanged', async ( + $, on) => { + const m = await bootModel($, on, ['Everywhere']) + expect(await modelCmd($, 'opus')).toBe('native') + expect(m.ran).toEqual(['opus']) + expect(m.w.written).toEqual([]) +}) + +test('model command: Everywhere drops an earlier sticky model', async ( + $, on) => { + const m = await bootModel($, on, ['This conversation', 'Everywhere']) + await modelCmd($, 'fable') + expect(mainLine(await route($, 'show'))).toContain('user custom') + await modelCmd($, 'opus') + expect(mainLine(await route($, 'show'))).toContain('session defaults') + expect(m.ran).toEqual(['opus']) +}) + +test('model command: Everywhere drops a sticky tier too, keeps effort', async ( + $, on) => { + const m = await bootModel($, on, ['Everywhere']) + await route($, 'plan') + await modelCmd($, 'opus') + const line = mainLine(await route($, 'show')) + expect(line).toContain('effort xhigh') + expect(line).not.toContain(FABLE) + expect(m.ran).toEqual(['opus']) +}) + +test('model command: no dialog for a call native owns', async ($, on) => { + const m = await bootModel($, on, []) + const args = ['', 'fable opus', 'default', 'opusplan', 'claude-opus-5-6', + 'haiku[1m]', 'whatever'] + for (const a of args) expect(await modelCmd($, a)).toBe('native') + expect(m.ran).toEqual(args) + expect(m.w.asked).toEqual([]) +}) + +test('model command: no dialog from another origin', async ($, on) => { + const m = await bootModel($, on, []) + expect(await modelCmd($, 'fable', 'sdk')).toBe('native') + expect(m.w.asked).toEqual([]) +}) + +test('model command: no dialog when the router is off', async ($, on) => { + const m = await bootModel($, on, []) + await route($, 'off') + expect(await modelCmd($, 'fable')).toBe('native') + expect(m.w.asked).toEqual([]) +}) + +test('model command: no dialog without a surface', async ($, on) => { + const m = await bootModel($, on, [], OPUS, { surfaces: [] }) + expect(await modelCmd($, 'fable')).toBe('native') + expect(m.w.asked).toEqual([]) +}) + +test('model command: a second /model while one is open goes native', async ( + $, on) => { + const m = await bootModel($, on, ['This conversation']) + const held = deferred() + const open = deferred() + m.w.gate = held.gate + m.w.onAsk = open.release + const first = modelCmd($, 'fable') + await open.gate + expect(await modelCmd($, 'opus')).toBe('native') + held.release() + expect(await first).toContain('sticky route') + expect(m.w.asked).toHaveLength(1) +}) + +test('model command: the question notes a project pin only when set', async ( + $, on) => { + const m = await bootModel($, on, ['Later', 'Later']) + await modelCmd($, 'fable') + m.w.files.set('local', JSON.stringify({ model: OPUS })) + await modelCmd($, 'fable') + const [bare, pinned] = m.w.asked as [Asked, Asked] + expect(bare.text).not.toContain('pins') + const lines = pinned.text.split('\n') + const note = lines[lines.length - 2] ?? '' + expect(note).toContain( + `this project pins ${OPUS} in .claude/settings.local.json`) + expect(note).toContain('the project pin wins') + expect(lines[lines.length - 1]).toBe(`Switch main to ${FABLE} where?`) +}) + +test('model command: Esc or free text cancels, nothing changes', async ( + $, on) => { + const m = await bootModel($, on, []) + expect(await modelCmd($, 'fable')).toBe(NO_SCOPE) + m.w.answers.push('maybe') + expect(await modelCmd($, 'fable')).toBe(NO_SCOPE) + expect(m.ran).toEqual([]) + expect(m.w.written).toEqual([]) + expect(mainLine(await route($, 'show'))).toContain('session defaults') +}) + +test('model command: Everywhere: native runs once, its throw is reported, not re-run', async ( + $, on) => { + const ran: string[] = [] + on('command.run', { command: 'model' }, (_a, e) => { + ran.push(e.args) + throw new Error('boom') + }) + await bootRig($, on, OPUS, 1000, newWorld({ answers: ['Everywhere'] })) + const out = await modelCmd($, 'opus') + expect(out).toContain('model failed (') + expect(out).toContain('/route show') + expect(out).not.toContain('boom') + expect(ran).toEqual(['opus']) +}) + +for (const scope of ['This conversation', 'This project']) { + test(`model command: ${scope}: a throw after the answer never reaches native`, async ( + $, on) => { + // the dialog is answered, then the status text reads the clock + const m = await bootModel($, on, [scope], OPUS, { + clockFailsAfterAsk: true, + }) + const out = await modelCmd($, 'fable') + expect(out).toContain('model failed (') + expect(out).toContain('/route show') + expect(out).not.toContain('boom') + expect(m.ran).toEqual([]) + }) +} + +test('writes: kit: only the project settings.local.json is carved out', { + plugins: [PROBE], +}, async ($, on) => { + const m = await bootModel($, on, []) + const out = await $.command.run({ + command: 'probe', + args: LOCAL_FILE, + origin: { kind: 'composer' }, + presentation: { isFullscreen: false, columns: 80 }, + }) + expect(out.text).toBe('written') + for (const path of [`${ROOT}/.claude/settings.json`, + `${LOCAL_FILE}.bak`, `${ROOT}/other/settings.local.json`, HOME_FILE]) { + expect(worldServes(m.w, path), path).toBe(false) + } + expect(worldServes(m.w, LOCAL_FILE)).toBe(true) +}) diff --git a/mods/model-router/hooks/register.ts b/mods/model-router/hooks/register.ts index 887c604..a2cc96f 100644 --- a/mods/model-router/hooks/register.ts +++ b/mods/model-router/hooks/register.ts @@ -7,7 +7,10 @@ // DEFAULT_CONFIG; ~/.claude/model-router.json overrides both per machine. // One writer per concern: the Agent tool's own params are never rewritten, // the spawn hook sets an agent's model once, turn.step sets efforts. -import type { EngineInterface, On, Register, TurnStepInput } from 'claude-code' +import type { + CommandRunInput, CommandRunResult, EngineInterface, Next, On, Register, + TurnStepInput, +} from 'claude-code' type Api = EngineInterface type Level = 'low' | 'medium' | 'high' | 'xhigh' | 'max' @@ -190,6 +193,15 @@ const KEEP = 'Keep' const CHANGE = 'Change' const EVERYWHERE = 'Everywhere' const THIS_PROJECT = 'This project only' +// `/model ` scope dialog. PROJECT_SCOPE differs from THIS_PROJECT, the +// first-use label: both are fixed by their own contracts. +const PROJECT_SCOPE = 'This project' +const CONVERSATION = 'This conversation' +const MODEL_SCOPES: readonly string[] = [ + PROJECT_SCOPE, CONVERSATION, EVERYWHERE, +] +const NO_SCOPE = 'model: no scope chosen, nothing changed' +const LOCAL_SETTINGS = '.claude/settings.local.json' const CHOICE_ALIASES: readonly string[] = ['fable', 'opus', 'sonnet', 'haiku'] const MAX_DESC = 140 // chars of a skill or agent description in a question const MAX_ABOUT = 120 // chars of a phase `about` @@ -2054,6 +2066,238 @@ async function handleCommand($: Api, st: State, args: string): Promise { } } +// ---- /model : the scope of a switch --------------------------------- +// A typed `/model ` of a model the table knows asks where it applies. +// Everywhere is the native command (user settings.json); the two others set +// a sticky model route, This project also pins `model` in the project's +// settings.local.json. Fail-open to native only before an answer. + +type ModelNext = Next<'command.run'> +type Local = { data: Rec; created: boolean } +type Unreadable = { cause: string } + +/** An alias or a full id of the table; haiku has no `[1m]` variant. */ +function knownModel(cfg: Config, token: string): boolean { + const bare = token.replace(ONE_M, '') + const id = hasKey(cfg.models, bare) ? cfg.models[bare] ?? bare : bare + if (!Object.values(cfg.models).includes(id)) return false + return !(ONE_M.test(token) && id.startsWith(HAIKU)) +} + +/** The id a token stands for, `[1m]` kept; never `canonical` (it strips). */ +function fullId(cfg: Config, token: string): string { + const bare = token.replace(ONE_M, '') + if (!hasKey(cfg.models, bare)) return token + return `${cfg.models[bare] ?? bare}${ONE_M.test(token) ? '[1m]' : ''}` +} + +/** A user switch by hand: sticky model, the run slot dropped, effort kept. */ +function stickyModel($: Api, st: State, bare: string): void { + const prev = st.userMain + const effort = prev?.route.effort + st.userMain = { + phase: 'custom', + route: { model: bare, ...(effort === undefined ? {} : { effort }) }, + source: 'user', + ...(prev?.explicitEffort ? { explicitEffort: true } : {}), + } + st.runMain = null + refresh($, st) +} + +/** Everywhere: a sticky model or tier would route main back after native. */ +function dropStickyModel(st: State): void { + if (st.userMain === null) return + const effort = st.userMain.route.effort + st.userMain = effort === undefined + ? null + : { ...st.userMain, phase: 'custom', route: { effort } } +} + +async function localPath($: Api): Promise { + try { + return `${await $.session.root()}/${LOCAL_SETTINGS}` + } catch { + return undefined + } +} + +/** The file's text; null when absent (`stat` rejects and `exists` false). */ +async function localText( + $: Api, + path: string, +): Promise { + try { + let info + try { + info = await $.fs.stat(path) + } catch (err) { + if (!(await $.fs.exists(path))) return null + return { cause: `fs error ${errWord(err)}` } + } + if (info.isLink) return { cause: 'settings.local.json is a link' } + if (info.kind !== 'file') return { cause: 'not a regular file' } + if (info.size > MAX_CONFIG_BYTES) return { cause: 'too large' } + const text = await $.fs.read(path) + return text.length > MAX_CONFIG_BYTES ? { cause: 'too large' } : text + } catch (err) { + return { cause: `fs error ${errWord(err)}` } + } +} + +/** The local settings as an object, or a fixed cause word; never throws. */ +async function readLocalSettings( + $: Api, + path: string, +): Promise { + const text = await localText($, path) + if (text === null) return { data: {}, created: true } + if (typeof text !== 'string') return text.cause + let data: unknown + try { + data = JSON.parse(text) + } catch { + return 'not JSON' + } + return isRecord(data) ? { data, created: false } : 'not an object' +} + +/** The project's `.claude`: absent is fine, a link or a file is not. */ +async function claudeDirCause($: Api, path: string): Promise { + const dir = path.slice(0, path.lastIndexOf('/')) + try { + let info + try { + info = await $.fs.stat(dir) + } catch (err) { + if (!(await $.fs.exists(dir))) return null + return `fs error ${errWord(err)}` + } + if (info.isLink) return '.claude is a link' + return info.kind === 'dir' ? null : '.claude is not a directory' + } catch (err) { + return `fs error ${errWord(err)}` + } +} + +/** 'written', 'created', or a fixed cause word (never an error message). */ +async function writeLocalModel($: Api, id: string): Promise { + const path = await localPath($) + if (path === undefined) return 'project root unknown' + const bad = await claudeDirCause($, path) + if (bad !== null) return bad + const local = await readLocalSettings($, path) + if (typeof local === 'string') return local + local.data.model = id + try { + await $.fs.write(path, `${JSON.stringify(local.data, null, 2)}\n`) + } catch (err) { + return `fs error ${errWord(err)}` + } + return local.created ? 'created' : 'written' +} + +/** The question: the id, the three scopes, the project pin if any. */ +async function scopeQuestion($: Api, id: string): Promise { + const path = await localPath($) + const local = path === undefined ? '' : await readLocalSettings($, path) + const pin = typeof local === 'string' ? undefined : local.data.model + const note = typeof pin === 'string' + ? `Note: this project pins ${clean(pin, 60)} in ${LOCAL_SETTINGS}: ` + + 'at launch here, the project pin wins over Everywhere\n' + : '' + return `${PROJECT_SCOPE}: ${LOCAL_SETTINGS} of this repo (wins at ` + + `launch) + route now · ${CONVERSATION}: route now, nothing written · ` + + `${EVERYWHERE}: user settings.json, every project\n${note}` + + `Switch main to ${id} where?` +} + +/** The route cannot hold `[1m]`: the session's variant is what carries. */ +function variantNote(st: State, token: string, bareFull: string): string { + const long = ONE_M.test(token) || ONE_M.test(st.sessionModel) + return long && !bareFull.startsWith(HAIKU) + ? " ([1m] follows the session's variant)" + : '' +} + +function writtenText(id: string, wrote: string): string { + if (wrote !== 'written' && wrote !== 'created') { + return `model: ${LOCAL_SETTINGS} not written (${wrote})` + } + return `model: ${id} written to ${LOCAL_SETTINGS} (remove its "model" key ` + + `to undo)${wrote === 'created' ? ', file created: keep it gitignored' : ''}` +} + +/** This project (file + route) or This conversation (route only). */ +async function applyLocalScope( + $: Api, + st: State, + token: string, + toFile: boolean, +): Promise { + const id = fullId(st.cfg, token) + const wrote = toFile ? await writeLocalModel($, id) : undefined + const bare = token.replace(ONE_M, '') + stickyModel($, st, bare) + if (wrote !== undefined && wrote !== 'written' && wrote !== 'created') { + $.ui.toast(`settings.local.json not written: ${wrote}`) + } + const route = `sticky route ${fullId(st.cfg, bare)}` + const head = wrote === undefined + ? `model: ${route} for this conversation` + : `${writtenText(id, wrote)}; ${route} set` + const note = variantNote(st, token, fullId(st.cfg, bare)) + return `${head}${note}\n${await show($, st)}` +} + +/** After an answer native never runs on a failure: a text says what to do. */ +async function answerScope( + $: Api, + st: State, + e: CommandRunInput, + next: ModelNext, + answer: string, +): Promise { + try { + if (answer === EVERYWHERE) { + dropStickyModel(st) + return await next(e) + } + const text = await applyLocalScope( + $, st, e.args.trim(), answer === PROJECT_SCOPE) + return { text } + } catch (err) { + warnOnce(st, $, 'command.run model', errWord(err)) + return { text: `model failed (${errWord(err)}); the file write or the ` + + `sticky route may have landed: check /route show and ${LOCAL_SETTINGS}` } + } +} + +async function handleModelCommand( + $: Api, + st: State, + e: CommandRunInput, + next: ModelNext, +): Promise { + await ensureConfig($, st) + const tokens = e.args.trim().split(/\s+/) + const token = tokens[0] ?? '' + if (st.off || e.origin.kind !== 'composer' || tokens.length !== 1 || + !knownModel(st.cfg, token) || + (await $.session.surfaces()).length === 0 || st.asking !== null) { + return next(e) + } + st.asking = `model:${token}` + try { + const question = await scopeQuestion($, fullId(st.cfg, token)) + const answer = await askOr($, question, MODEL_SCOPES) + if (!MODEL_SCOPES.includes(answer)) return { text: NO_SCOPE } + return await answerScope($, st, e, next, answer) + } finally { + st.asking = null + } +} + // ---- first use: one dialog per row, the answer kept in routing.json ----- // The first time a row routes (a typed skill, an agent spawn, a phase // declared through the route tool) the user confirms it once, for every @@ -3756,6 +4000,12 @@ function registerCwd(on: On, st: State): void { } function registerCommandHook(on: On, st: State): void { + on('command.run', { command: 'model' }, async ($, e, next) => + handleModelCommand($, st, e, next) + ).catch(($, e, next) => { + warnOnce(st, $, 'command.run model', next.error.kind) + return next(e) + }) on('command.run', { command: 'route' }, async ($, e) => { if (e.origin.kind !== 'composer') { return { text: 'route: user-only command' }