A pick in the picker is held (PreModelSwitch deny), then the same project / conversation / everywhere question runs; only Everywhere reaches the native write to user settings.json. A model chosen in that dialog bypasses the cold-read caps but waits while held down.
13 KiB
13 KiB
PLAN r2 — picker-scope (feat)
Contract: .claude/tasks/contracts/2026-10-25-picker-scope-1952.md
Scope rule 7: register.ts + register.test.ts + lib/effort-shift.md (docs README/USAGE/CHANGELOG via doc-sync).
r1 → r2 after 3 lenses: correctness FATAL(5), robustness FATAL(2), simplicity SOLID(3 MINOR). Change named at the finding it closes (C = correctness, R = robustness, S = simplicity).
Files
mods/model-router/hooks/register.tsRoutedtype (besideexplicitEffort?, l.~52):explicitModel?: boolean // the model was chosen by hand in the scope dialog.stickyModel(l.~2095) setsexplicitModel: true.dropStickyModel(l.~2109) builds its effort-only slot WITHOUTexplicitModel(it is the one writer that copies fields, S2). No other writer changes.- HAND PICK BRANCH (closes C1/R1 BLOCKER, C2/R2, C3, R8). New helpers near
decideMain(l.~1386):handPicked(st, wanted): boolean=st.userMain?.explicitModel === true && wanted !== undefined && wanted === <the id the userMain slot resolves to, through the same resolver mainPlan/wantedModel uses>(the check names the TARGET, not only the slot, R8).handCall(st, cur, wanted, read): Call: (a) same alias ascanonical(cur)→keep(cur); (b)st.down.has(canonical(st.cfg, wanted))→keep(cur, 'hand pick down', <once log: model-router: <wanted> is held down; staying on <cur> until it is back>); (c)!fits(st, wanted, read.tokens)→keep(cur, 'no fit', noFit(wanted)); (d) elsemoveTo(cur, wanted, 'hand pick', st.sessionModel).decideMain: right afterif (st.off) return keep(cur), insertif (handPicked(st, wanted)) return handCall(st, cur, wanted, read). It runs BEFOREunknownCall(an unranked session model no longer traps a hand pick, C3), beforewindowReturn, before thecurdown branch (a down current model moves to the hand pick when that one is up, C2/R2).upgradeCall,downgradeCall,leaveDownstay UNCHANGED (r1's bypass inside them is dropped).- verbose transition cause word
hand pickwhere the existingwhywords are mapped (follow theupgrade/downgrademapping).
scopeDialog(S1): replaceanswerScopewithasync function scopeDialog($, st, token, everywhere: () => Promise<CommandRunResult>, warnKey: string): Promise<CommandRunResult>:scopeQuestion($, fullId(st.cfg, token))→askOr($, question, MODEL_SCOPES)→ not in MODEL_SCOPES →{ text: NO_SCOPE }; Everywhere →dropStickyModel(st); return await everywhere(); elseapplyLocalScope(...)→{ text }; the post-answer try/catch keeps its text and useswarnOnce(st, $, warnKey, …)(C8/R6).handleModelCommandkeeps its gates and slot, thenreturn await scopeDialog($, st, token, () => next(e), 'command.run model').- PICKER (new, in the
/model <name>section afterhandleModelCommand):const PICKER_DELAY_MS = 300 // the engine draws nothing while a PreModelSwitch hook runsconst PICKER_DENY = 'model-router asks where this switch applies'const PICKER_BUSY = 'answer the open dialog first'(reuse the existing string constant if one exists at l.~3137)async function handlePicker($, st, e, next): the source filter is a matcher-like first line (e.source !== 'picker'→return next(e); C6: the contract wording is amended to say so); thenawait ensureConfig($, st); gates →return next(e):st.off;typeof e.requested_model !== 'string'(Default);!knownModel(st.cfg, asked);(await $.session.surfaces()).length === 0. Thenst.asking !== null→$.ui.toast(PICKER_BUSY)and return the deny (R3: never native while a dialog is open, the BLK-036 leak). Then, synchronously:st.asking = \picker:${asked}`;const conv = awaitis NOT allowed after this point, so read.session.id()` BEFORE the slot is set and pass it in; `void pickerDialog(, st, asked, conv);return { permissionDecision: 'deny', permissionDecisionReason: PICKER_DENY }`.async function pickerDialog($, st, asked, conv): Promise<void>:try { await $.clock.sleep(PICKER_DELAY_MS); const out = await scopeDialog($, st, asked, () => $.command.run({ command: 'model', args: asked }), 'PreModelSwitch picker', conv-check); … } catch (err) { warnOnce(st, $, 'PreModelSwitch picker', errWord(err)) } finally { st.asking = null }.- stale conversation (C10):
scopeDialoggets an optionalstillHere: () => Promise<boolean>; the picker passesasync () => (await $.session.id()) === conv, checked right after the answer and before any effect; false →{ text: 'model: the conversation changed, nothing applied' }. - logging (C7): log
out.textwith the safe-log helper (tryLog, l.~353) only when the answer was not Everywhere ($.command.runalready prints the native lines); NO_SCOPE and the stale text are logged.
- stale conversation (C10):
- registration (S3): in
registerCommandHook(l.~4002), next tocommand.run model:on('classic.PreModelSwitch', ($, e, next) => handlePicker($, st, e, next)).catch(($, e, next) => { warnOnce(st, $, 'PreModelSwitch', next.error.kind); return next(e) }).
- A native user switch drops a hand pick (C4): in
onModelSwitch(l.~3930), forUSER_SWITCH.has(e.source)and main (e.agent_id === undefined):if (st.userMain?.explicitModel) dropStickyModel(st). So picker Default / unknown name //configrow / Everywhere all leave the native model in charge. Our denied switches raise no PostModelSwitch;/model <name>→ This project/Conversation never runs native. - section comment of the
/model <name>block: one line on the picker (deny now, ask after) and the hand-pick rule.
mods/model-router/hooks/register.test.ts- boot: bottom
on('classic.PreModelSwitch', () => ({}))besideclassic.PostModelSwitch(l.~278). - helper
picker($, requested, source = 'picker')firing$.classic.PreModelSwitch({...})with every required field (mirror the PostModelSwitch helper at l.~727). - World flag
sleepFails(C5/R6): boot swaps the mock clock'sclock.sleepfor one that rejects (same replacement pattern asfailingClock, LRN-229; it keepsclock.now), so pickerDialog's own catch is reached. - native witness: the existing
modelcommand recorder.
- boot: bottom
lib/effort-shift.md: rewrite the/modelparagraph (C9: l.~52 "no args … native, no question" is false now):/model <name>or a pick in the/modelpicker asks the scope (the picker's switch is held first: the engine prints that a hook blocked it, then the question comes); Esc = nothing; Everywhere = the native write to user settings.json; picker Default, an unknown name, a headless run = native, and a native switch drops a hand pick. Hand pick rule: a model chosen in that dialog always switches (no cold-read cap, no switch flag); a model held down keeps main where it is; the window guard needs awindowsentry (none shipped, R4). Residuals:/cleardrops a hand pick until relaunch (R7); the/configModel row still writes user settings.json (R5). ≤ 80 cols.
Approach
- Deny now, ask in a continuation after the hook returned (spike-proven).
- One dialog function (
scopeDialog) for both entries, aneverywherethunk and a warn key per entry. - A hand pick is decided by its own branch in
decideMain, ahead of every automatic rule; the automatic cap functions stay as they are. - The native path stays the only writer of user settings.json (BDR-116).
Edge cases
[1m]picks:knownModelaccepts, the pin keeps[1m], the route uses the bare token (BDR-126).- picker while a dialog is open → deny + toast, no native (R3).
$.command.runrejects on Everywhere → scopeDialog's catch text → logged underPreModelSwitch picker./clearwhile the picker dialog is open → stale check → nothing applied (C10).- hand-picked model marked down → stays on cur with one log; back up → moves (C1/R1).
[deferred 2026-10-25]R3 timeout: a$.ui.askthat never settles keeps the slot (no timeout, same as the first-use dialog); picker picks are then denied with the toast (no leak). R7: hand pick lost at/clear(BDR-126 residual). R5:/configModel row writes user settings (sourcecommand, indistinguishable from Everywhere's native run).
Tests (register.test.ts, "picker" + "hand pick" blocks)
- picker known model → hook result is the deny AND
w.askedis empty at that moment; afterclock.advance(300)+ flush: the three-scope question. - passthrough, no deny, no question: source
command,sdk; requested null;opusplan;claude-opus-5-6; router off; surfaces[]. - slot held (a
/modeldialog gated open) → deny +answer the open dialog firsttoast, no question, native empty. - picker → This project / This conversation / Everywhere (native recorder once with
model <requested>,w.askedlength 1, prior hand pick dropped); dismissed → NO_SCOPE logged, slot freed (a second picker asks again). sleepFails→ warn logged underPreModelSwitch picker, slot freed, nothing applied.- post-answer throw on the picker path →
model failed (logged, native empty, slot freed. - stale conversation:
session.idchanges between deny and answer →conversation changedlogged, nothing written, no route. - hand pick across turns (C1/R1): hand-pick fable, mark fable down, END THE TURN, next turn's first step on the session model → stays on the session model + one log; hold expires → next turn on fable.
- hand pick cur down (C2/R2): session opus marked down, hand-pick fable with usage over
upgradeMaxTokensandmainUpgradeoff → fable. - hand pick bypass: usage over
upgradeMaxTokens→ fable; usage overdowngradeMaxTokens+switch off→ sonnet;/route model=fablesame usage → held (unchanged). - unranked session model (C3): session on an id outside the table, hand pick opus → main on opus.
- native user switch drops a hand pick (C4): hand pick fable, then
PostModelSwitchsourcepickerto sonnet → next step on sonnet. - existing
/model <name>tests green withscopeDialog.
Disposition (STEP 0.6)
- extends BDR-126; amends its held-route residual (hand pick always switches, user pick); keeps its writer rules and full-id pin.
- honors BDR-116: Everywhere = native command; the mod never writes user settings.json.
- honors LRN-203 (
fullId), LRN-228 (viaapplyLocalScope), LRN-229 (sleepFailsfollows its clock-swap pattern), LRN-230 (no new per-model fact; the window guard caveat is documented). - accepts LRN-204's cost (one cold re-read per hand switch), user pick.
- BLK-036: picker leak closed;
/configModel row named as residual (R5), not claimed closed.
r3 — confirmation pass folded inline (FATAL(1) + 6 MINOR; re-challenge budget spent)
These OVERRIDE the r2 text where they conflict.
- K1 BLOCKER (hand pick unusable must not pin a down model):
handCallreturnsCall | undefined. Order: (1)usable = !st.down.has(canonical(st.cfg, wanted)) && fits(st, wanted, read.tokens); (2) not usable → returnundefined; (3) same alias ascanonical(cur)→keep(cur); (4) elsemoveTo(cur, wanted, 'hand pick', st.sessionModel). IndecideMain:if (handPicked(st, wanted)) { const hand = handCall(...); if (hand !== undefined) return hand; held = true; wanted = undefined }then the EXISTING chain runs unchanged with no wanted model (unknownCall / windowReturn / cur down → leaveDown → nextAvailable / keep). Whenheld, the returned call carries aoncelogmodel-router: <wanted> is held down or does not fit; hand pick waits(merge into the call'sonceonly when it has none). Tests add: hand pick == current model (opus pinned, session opus), opus marked down → next step in the SAME turn and on the NEXT turn goes to the next available model (sonnet), never opus; hand pick fable mid-turn after the router moved there, fable fails (StopFailure) → next step leaves fable; hand pick outgrowing a knownwindowsoverride → windowReturn still applies. - K2: the picker's Everywhere thunk is
() => $.command.run({ command: 'model', args: asked }).then(() => ({})); pickerDialog logsout.textwhenever it is defined (so the catch text of a failed Everywhere is logged, the native lines are not printed twice). - K3 fixtures:
failingClock(LRN-229 rig) ALSO answersclock.sleepat once (soclockFailsAfterAskreaches the dialog);sleepFails= a separate whole-clock replacement answeringclock.nowand REJECTINGclock.sleep. Post-answer-throw picker test usesclockFailsAfterAsk; the sleep-throw test usessleepFails. - K4 order in handlePicker: all awaited gates AND
const conv = await $.session.id()first; thenst.asking !== null→ deny + toast; then synchronouslyst.asking = …,void pickerDialog(...), return deny. No await between the asking check and the set. - K5:
onModelSwitchdrop of a hand pick is skipped whilest.asking?.startsWith('picker:')(a PostModelSwitch emitted for a switch the picker denied must not drop the earlier hand pick). Live check item: does the engine emit PostModelSwitch for a denied picker switch. - K6: a hand pick clears its target's breaker mark like a native user switch:
applyLocalScope(both local scopes) callsclearBreaker(st, canonical(st.cfg, fullId-bare))beforestickyModel. - K7: lib/effort-shift.md l.~70-71 ("Fable on main comes only from a skill row, the
routetool or a typed/route") gains "or a hand pick (/model, picker)" in the same edit.