feat(router): /model <name> 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.
This commit is contained in:
1 parent
5ee74bbb81
commit
1fde5bbc76
6 files changed
+804
-11
No files matched your search
@@ -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 <name>` 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 `<root>/.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 <name>` 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`: `<root>/.claude/settings.local.json` holds `"model": "<full id>"` (`[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 (<kind>); … 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)
|
||||
@@ -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 <fullId> 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 <that id> 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 <errWord>`):
|
||||
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 <errWord>`); `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 <errWord>`); `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 <errWord>`); `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 <errWord(err)>`). 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<string, { kind: 'dir' | 'file' | 'other'; isLink: boolean }>` 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 <name>` 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 <name>` → 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.
|
||||
Reference in new issue
Block a user