From 9a24a6229af41c70185b3de9d840e64da5ffe38a Mon Sep 17 00:00:00 2001 From: bchanot Date: Mon, 2 Nov 2026 15:59:24 +0100 Subject: [PATCH 1/3] feat(model-router): ask before a route lifts main or a rowed spawn onto Fable routing.json askTier (best | false), /route ask-tier on|off, one question per span with origin, phase, about, model and effort: Fable, Opus instead (big tier), stop for the session. The choice is a tier name stamped on the turn and run slots, inherited by same-tier helper routes only; spawns remember one answer per agent type per session; never headless or inside an agent. 28 TIER tests. --- USAGE.md | 4 +- mods/model-router/hooks/register.test.ts | 357 ++++++++++++++++++++++- mods/model-router/hooks/register.ts | 323 +++++++++++++++++--- mods/model-router/routing.json | 3 +- 4 files changed, 647 insertions(+), 40 deletions(-) diff --git a/USAGE.md b/USAGE.md index 97f6a9c..3332526 100644 --- a/USAGE.md +++ b/USAGE.md @@ -170,7 +170,7 @@ Tu veux... | `/guardrails` | Vérifier hébergement, Supabase RLS, consentement SMS/email, fonctions cloud, stockage des mots de passe, injection SQL, exposition navigateur | Scanner déterministe, jugement, rapport `.claude/audits/GUARDRAILS.md`, propositions de correction à valider, re-passe qui prouve chaque correction ; `--live ` sonde en lecture seule ; sonde `exposure` sur un build de production (source maps, corps d'erreur, clés sensibles) | | `/impeccable` | Audit/polish design + détecteur anti-slop déterministe | 23 verbes ; `npx impeccable detect` (exit 0/2) | | `/tour` | Sweep groupé sur un ou plusieurs projets | Sécu + nettoyage + reconcile + doc, boucle jusqu'à un pass propre | -| `/route` | Voir ou fixer la route du mod model-router | show / clear / off / on / reload / pending / ask on\|off / / model=… effort=… / switch on\|off / classify on\|off (classifieur de prompt) / verbose on\|off (transitions seules) | +| `/route` | Voir ou fixer la route du mod model-router | show / clear / off / on / reload / pending / ask on\|off / ask-tier on\|off / / model=… effort=… / switch on\|off / classify on\|off (classifieur de prompt) / verbose on\|off (transitions seules) | | `/profile` | Changer le profil de packs du projet (`set`), ou l'état effectif (`current`) | Profils dans `lib/profiles/*.json`, packs dans `skills/pack-*/` | > Cette table couvre les skills personnels principaux. `/seo` et `/geo` (pack-seo) @@ -196,7 +196,7 @@ l'outil `mcp__model-router__route` (`lib/effort-shift.md`). Les skills externes vendorés (pile design, superpowers, agent-skills, skills scroll MengTo, 21st) ont aussi leur ligne. -Taper un skill qui a une ligne route la boucle principale dessus. Une ligne du tier best (plan, reflect, orchestrate, escalate ; `audit` est une ligne d'agent, jamais tapée) tient d'un tour à l'autre pendant tout le run, jusqu'à `/route clear`, `/route off`, un `/model` tapé ou choisi dans le sélecteur, ou un skill d'un autre tier tapé. Un `/model ` tapé, ou un choix dans le sélecteur `/model`, avec un modèle de la table demande sa portée (Échap ne change rien). Le changement du sélecteur est d'abord retenu (le moteur affiche qu'un hook l'a bloqué), puis la question vient ; un choix fait pendant qu'un autre dialogue est ouvert est refusé (`answer the open dialog first`) : This project écrit l'id complet dans `model` du `.claude/settings.local.json` du projet (créé s'il manque, à garder dans le `.gitignore`) et pose une route de modèle tenue ; This conversation pose la route seule, sans rien écrire ; Everywhere lance le `/model` natif (`settings.json` utilisateur, tous les projets). Default dans le sélecteur, sans argument, avec un nom inconnu, en headless (`-p`) ou mod coupé, le `/model` natif passe sans question. Un modèle choisi dans ce dialogue change toujours : ni plafond de relecture à froid, ni `mainUpgrade` ni `mainModelSwitch`. S'il est en panne, la boucle principale reste où elle est jusqu'à son retour. Un changement natif (ligne Model de `/config` comprise) ou `/clear` l'abandonne ; un `/route model=` tapé garde les plafonds. La ligne Model de `/config` écrit toujours le `settings.json` utilisateur, et un dialogue jamais répondu n'a pas de délai. Pour relancer un tour bloqué : `ultrathink` dans le prompt (plancher d'effort du tour) ou `/route effort=max` (tient jusqu'à `/route clear`). Le `/effort` intégré n'a pas d'effet dans un run : les lignes et les routes passent devant. Les règles de mots-clés du prompt (`plan`, `design`, `architecture`… prennent l'effort de plan ; `pourquoi`, `review`, `audit`… celui de reflect), `ultrathink` et un lancement d'agent par la boucle principale (route `orchestrate` dérivée, tenue jusqu'à la fin de ses agents en arrière-plan) ne fixent que le niveau d'effort du tour, jamais le modèle : ils ne font jamais monter la boucle principale au-dessus du modèle de la session, et un run best tenu garde son modèle. Fable n'arrive sur la boucle principale que par une ligne de skill, l'outil `route`, un `/route` tapé ou un choix à la main (`/model`, sélecteur). Un prompt tapé sans règle, skill ni route en cours passe par un classifieur (un appel au petit modèle, 3 secondes au plus) : le tour prend la route de la phase devinée : son niveau d'effort, et son modèle, jamais au-dessus de celui de la session. Une devinette `coding` ou `bookkeeping` fait descendre la boucle principale vers un modèle moins cher quand `mainModelSwitch` est actif (par défaut) et que la relecture à froid tient sous `downgradeMaxTokens` (120000 tokens par défaut). Cette relecture compte aussi le prompt qui vient d'être envoyé (un token pour 3 caractères), et un document joint bloque la descente pour cette étape. Le cache compte comme chaud pendant le TTL du moteur (`cache_ttl`, 5 ou 60 minutes), 60 minutes par défaut. `/route classify off` ou `"classify": false` dans la config machine le coupe, et un `/effort` tapé entre deux tours annule la devinette pour ce tour seulement. Avant d'envoyer la boucle principale sur un modèle, celui vers lequel elle se déplace comme celui qu'elle garde (le modèle de la session compris), le mod l'essaie une fois (un appel minimal, 8 secondes au plus) : sans réponse, ce modèle est marqué en panne (raison `probe`) et la décision est reprise une fois ; `"probe": false` dans la config machine coupe cet essai, et `/route show` affiche `probe:`. Quand un modèle inférieur remplace la tête de son tier en panne (Opus pour Fable), le niveau propre de la phase monte d'un cran (reflect xhigh, plan max, orchestrate high) ; un niveau demandé explicitement ou un plancher ne bouge jamais. Les sous-agents reçoivent le modèle de leur ligne au lancement (dans leur tier, jamais en dessous de leur frontmatter) et son niveau à chaque étape ; un `model` ou `effort` explicite sur l'appel gagne. Explore tourne en sonnet/medium, Plan en opus/xhigh. Un agent intégré `general-purpose` lancé par la boucle principale sans `model`, pendant que celle-ci tourne sous le modèle de la session (descente, ou repli quand un modèle est en panne), part sur le modèle de la session au lieu d'hériter du modèle inférieur ; les autres types d'agents ne sont jamais épinglés ainsi. `/route show` affiche la route en cours, slot de run compris (`main: run `), et le switch avec son plafond et ce TTL (`switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`). Première utilisation : la première fois qu'un skill avec ligne est tapé, qu'un agent avec ligne est lancé ou qu'une phase est déclarée sur la boucle principale via l'outil `route`, le mod demande une fois si la route convient. La question donne le contexte : la description du skill (première phrase du frontmatter de son `SKILL.md`) ou celle de l'agent, la phase avec sa ligne `about` (champ de la phase dans `routing.json`), puis le modèle et le niveau réels de l'étape suivante ; une phase déclarée dit aussi qui l'utilise. Pour une ligne : Later, Keep ou Change ; pour une phase déclarée : Later ou Keep. Change demande le modèle (fable, opus, sonnet, haiku, chacun avec son tier), puis le niveau parmi ceux des phases de ce modèle (fable : medium, high, xhigh ou max ; sonnet : low, medium, high ou xhigh ; opus et haiku n'en ont qu'un, la question est sautée), puis Everywhere ou This project only (exception rangée sous le remote origin du dépôt réduit à `host/path`, jamais d'identifiants). Une ligne reste un nom de phase : le couple modèle et niveau désigne une phase existante, et la même phase qu'avant vaut Keep. Un couple qu'aucune phase n'offre s'ajoute à la main comme nouvelle phase dans `routing.json`. Après un changement sur un skill, un toast donne le modèle et le niveau réels, et rappelle `/route switch on` quand le switch est coupé, ou nomme le plafond quand la relecture à froid bloque la descente. La réponse est écrite dans `routing.json` ; Later, un texte libre (Other) ou un dialogue fermé redemande à une session suivante. Un seul dialogue à la fois, jamais en headless (`-p`) ni dans un sous-agent, et le modèle n'écrit jamais ce fichier. Chaque réponse laisse le repo de config modifié : commite-le depuis ce repo. `/route pending` liste ce qui reste à confirmer, `/route ask off|on` coupe ou rallume le dialogue, `/route forget ` efface une décision (une ligne changée revient à la phase livrée ; `all` et `projects` demandent d'abord). +Taper un skill qui a une ligne route la boucle principale dessus. Une ligne du tier best (plan, reflect, orchestrate, escalate ; `audit` est une ligne d'agent, jamais tapée) tient d'un tour à l'autre pendant tout le run, jusqu'à `/route clear`, `/route off`, un `/model` tapé ou choisi dans le sélecteur, ou un skill d'un autre tier tapé. Un `/model ` tapé, ou un choix dans le sélecteur `/model`, avec un modèle de la table demande sa portée (Échap ne change rien). Le changement du sélecteur est d'abord retenu (le moteur affiche qu'un hook l'a bloqué), puis la question vient ; un choix fait pendant qu'un autre dialogue est ouvert est refusé (`answer the open dialog first`) : This project écrit l'id complet dans `model` du `.claude/settings.local.json` du projet (créé s'il manque, à garder dans le `.gitignore`) et pose une route de modèle tenue ; This conversation pose la route seule, sans rien écrire ; Everywhere lance le `/model` natif (`settings.json` utilisateur, tous les projets). Default dans le sélecteur, sans argument, avec un nom inconnu, en headless (`-p`) ou mod coupé, le `/model` natif passe sans question. Un modèle choisi dans ce dialogue change toujours : ni plafond de relecture à froid, ni `mainUpgrade` ni `mainModelSwitch`. S'il est en panne, la boucle principale reste où elle est jusqu'à son retour. Un changement natif (ligne Model de `/config` comprise) ou `/clear` l'abandonne ; un `/route model=` tapé garde les plafonds. La ligne Model de `/config` écrit toujours le `settings.json` utilisateur, et un dialogue jamais répondu n'a pas de délai. Pour relancer un tour bloqué : `ultrathink` dans le prompt (plancher d'effort du tour) ou `/route effort=max` (tient jusqu'à `/route clear`). Le `/effort` intégré n'a pas d'effet dans un run : les lignes et les routes passent devant. Les règles de mots-clés du prompt (`plan`, `design`, `architecture`… prennent l'effort de plan ; `pourquoi`, `review`, `audit`… celui de reflect), `ultrathink` et un lancement d'agent par la boucle principale (route `orchestrate` dérivée, tenue jusqu'à la fin de ses agents en arrière-plan) ne fixent que le niveau d'effort du tour, jamais le modèle : ils ne font jamais monter la boucle principale au-dessus du modèle de la session, et un run best tenu garde son modèle. Fable n'arrive sur la boucle principale que par une ligne de skill, l'outil `route`, un `/route` tapé ou un choix à la main (`/model`, sélecteur). Un prompt tapé sans règle, skill ni route en cours passe par un classifieur (un appel au petit modèle, 3 secondes au plus) : le tour prend la route de la phase devinée : son niveau d'effort, et son modèle, jamais au-dessus de celui de la session. Une devinette `coding` ou `bookkeeping` fait descendre la boucle principale vers un modèle moins cher quand `mainModelSwitch` est actif (par défaut) et que la relecture à froid tient sous `downgradeMaxTokens` (120000 tokens par défaut). Cette relecture compte aussi le prompt qui vient d'être envoyé (un token pour 3 caractères), et un document joint bloque la descente pour cette étape. Le cache compte comme chaud pendant le TTL du moteur (`cache_ttl`, 5 ou 60 minutes), 60 minutes par défaut. `/route classify off` ou `"classify": false` dans la config machine le coupe, et un `/effort` tapé entre deux tours annule la devinette pour ce tour seulement. Avant d'envoyer la boucle principale sur un modèle, celui vers lequel elle se déplace comme celui qu'elle garde (le modèle de la session compris), le mod l'essaie une fois (un appel minimal, 8 secondes au plus) : sans réponse, ce modèle est marqué en panne (raison `probe`) et la décision est reprise une fois ; `"probe": false` dans la config machine coupe cet essai, et `/route show` affiche `probe:`. Quand un modèle inférieur remplace la tête de son tier en panne (Opus pour Fable), le niveau propre de la phase monte d'un cran (reflect xhigh, plan max, orchestrate high) ; un niveau demandé explicitement ou un plancher ne bouge jamais. Les sous-agents reçoivent le modèle de leur ligne au lancement (dans leur tier, jamais en dessous de leur frontmatter) et son niveau à chaque étape ; un `model` ou `effort` explicite sur l'appel gagne. Explore tourne en sonnet/medium, Plan en opus/xhigh. Un agent intégré `general-purpose` lancé par la boucle principale sans `model`, pendant que celle-ci tourne sous le modèle de la session (descente, ou repli quand un modèle est en panne), part sur le modèle de la session au lieu d'hériter du modèle inférieur ; les autres types d'agents ne sont jamais épinglés ainsi. `/route show` affiche la route en cours, slot de run compris (`main: run `), et le switch avec son plafond et ce TTL (`switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`). Première utilisation : la première fois qu'un skill avec ligne est tapé, qu'un agent avec ligne est lancé ou qu'une phase est déclarée sur la boucle principale via l'outil `route`, le mod demande une fois si la route convient. La question donne le contexte : la description du skill (première phrase du frontmatter de son `SKILL.md`) ou celle de l'agent, la phase avec sa ligne `about` (champ de la phase dans `routing.json`), puis le modèle et le niveau réels de l'étape suivante ; une phase déclarée dit aussi qui l'utilise. Pour une ligne : Later, Keep ou Change ; pour une phase déclarée : Later ou Keep. Change demande le modèle (fable, opus, sonnet, haiku, chacun avec son tier), puis le niveau parmi ceux des phases de ce modèle (fable : medium, high, xhigh ou max ; sonnet : low, medium, high ou xhigh ; opus et haiku n'en ont qu'un, la question est sautée), puis Everywhere ou This project only (exception rangée sous le remote origin du dépôt réduit à `host/path`, jamais d'identifiants). Une ligne reste un nom de phase : le couple modèle et niveau désigne une phase existante, et la même phase qu'avant vaut Keep. Un couple qu'aucune phase n'offre s'ajoute à la main comme nouvelle phase dans `routing.json`. Après un changement sur un skill, un toast donne le modèle et le niveau réels, et rappelle `/route switch on` quand le switch est coupé, ou nomme le plafond quand la relecture à froid bloque la descente. La réponse est écrite dans `routing.json` ; Later, un texte libre (Other) ou un dialogue fermé redemande à une session suivante. Un seul dialogue à la fois, jamais en headless (`-p`) ni dans un sous-agent, et le modèle n'écrit jamais ce fichier. Chaque réponse laisse le repo de config modifié : commite-le depuis ce repo. `/route pending` liste ce qui reste à confirmer, `/route ask off|on` coupe ou rallume le dialogue, `/route forget ` efface une décision (une ligne changée revient à la phase livrée ; `all` et `projects` demandent d'abord). Avant qu'une route envoie la boucle principale, ou un agent à ligne, sur Fable depuis un autre modèle, le mod pose une question une seule fois par portée (origine, phase et sa ligne `about`, modèle et niveau) : `Fable`, `Opus instead (big tier)` (Opus à la place : le tier big, niveau de la phase inchangé, le label reste vrai : l'option disparaît si Opus est en panne) ou `Stop asking this session` (ne plus demander cette session : rien n'est écrit, `/clear` la réarme). Un skill chargé par le modèle compte comme une ligne de skill ; un agent n'a qu'une réponse par type et par session ; jamais en headless (`-p`) ni dans un sous-agent ; un dialogue fermé lance Fable. Pas de question quand la décision ne tomberait pas sur Fable (`mainUpgrade` coupé, plafond de relecture, fenêtre, Fable en panne) : si la panne cesse plus tard, la boucle monte sans question, comme le disjoncteur le fait déjà. La clé `askTier` de `routing.json` (`best`, ou `false` pour couper) se règle par `/route ask-tier on|off`, la config machine gagne, et `/route show` affiche `ask-tier:`. La config par machine, optionnelle, vit dans `~/.claude/model-router.json` et passe devant `routing.json` ; `"enabled": false` y coupe le mod sur cette machine, `"ask": false` y coupe le dialogue, une ligne à `null` y retire une ligne. Un `.claude/model-router.json` dans un projet n'est jamais lu. Les phases et les lignes se modifient à la main dans `routing.json` ; `/route reload` relit les deux fichiers. diff --git a/mods/model-router/hooks/register.test.ts b/mods/model-router/hooks/register.test.ts index 2f98de9..c7d320d 100644 --- a/mods/model-router/hooks/register.test.ts +++ b/mods/model-router/hooks/register.test.ts @@ -61,6 +61,7 @@ type World = { type Fixture = { ask?: boolean // routing.json `ask` (default false: no dialog) + askTier?: 'best' | false // routing.json `askTier` (default false) edit?: (file: Rec) => void // tweaks the inline routing.json routing?: 'absent' | 'broken' home?: Rec | 'broken' // ~/.claude/model-router.json @@ -107,11 +108,13 @@ const baseRouting = (): Rec => ({ confirmed: {}, changed: {}, ask: false, + askTier: false, }) function newWorld(fx: Fixture = {}): World { const file = baseRouting() file.ask = fx.ask ?? false + file.askTier = fx.askTier ?? false fx.edit?.(file) const files = new Map() if (fx.routing === 'broken') files.set('routing', '{nope') @@ -2335,7 +2338,8 @@ test('writes: only routing.json, 2-space, keys in the documented order', async ( expect(w.written[0]).toMatch(/\/mods\/model-router\/routing\.json$/) expect(w.files.get('routing')).toMatch(/^\{\n {2}"phases"/) expect(Object.keys(routingOf(w))).toEqual([ - 'phases', 'skills', 'agents', 'projects', 'confirmed', 'changed', 'ask', + 'phases', 'skills', 'agents', 'projects', 'confirmed', 'changed', + 'ask', 'askTier', ]) }) @@ -2412,13 +2416,15 @@ test('writes: an out-of-order routing.json is written back in order', async ( $, on) => { const w = asks(['Keep'], { edit: reverseKeys }) expect(Object.keys(routingOf(w))).toEqual([ - 'ask', 'changed', 'confirmed', 'projects', 'agents', 'skills', 'phases', + 'askTier', 'ask', 'changed', 'confirmed', 'projects', 'agents', 'skills', + 'phases', ]) await bootRun($, on, FABLE, w) await typeFeat($) expect(w.written).toHaveLength(1) expect(Object.keys(routingOf(w))).toEqual([ - 'phases', 'skills', 'agents', 'projects', 'confirmed', 'changed', 'ask', + 'phases', 'skills', 'agents', 'projects', 'confirmed', 'changed', + 'ask', 'askTier', ]) }) @@ -6924,3 +6930,348 @@ test('hand pick: a native user switch drops it', async ($, on) => { expect((await stepOn($, h.rig, SONNET)).model).toBe(SONNET) expect(mainLine(await route($, 'show'))).toContain('session defaults') }) + +// ---- tier ask: before a route lifts main or a spawn onto the head -------- + +const INSTEAD = 'Opus instead (big tier)' +const STOP = 'Stop asking this session' +const TIER_OPTIONS = ['Fable', INSTEAD, STOP] + +/** A world with the tier ask on; the first-use `ask` stays off. */ +const asksTier = (answers: string[], fx: Fixture = {}) => + newWorld({ answers, askTier: 'best', ...fx }) + +/** An extra skill row, for the tests that need a second typed skill. */ +const withRows = (rows: Table) => (file: Rec): void => { + Object.assign(file.skills as Rec, rows) +} + +type Table = Record + +const lastStep = async ($: Engine, rig: Rig, model = OPUS) => + stepOn($, rig, model) + +/** Opus is down: an agent ran on it and hit a rate limit. */ +async function opusDown($: Engine): Promise { + await $.agent.spawn(spawnOf('feater', { model: OPUS })) + await failWith($, 'rate_limit', 'a1') +} + +test('TIER: a typed best skill from opus asks, with the reason', async ( + $, on) => { + const w = asksTier(['Fable'], { + edit: setPhase('reflect', { about: 'analysis' }), + }) + await bootRun($, on, OPUS, w) + await typeFeat($) + expect(w.asked).toHaveLength(1) + const q = w.asked[0] as Asked + expect(q.text).toContain('Skill /feat routes main to reflect (analysis): ' + + 'claude-fable-5-1 at high. Run it on fable?') + expect(q.options).toEqual(TIER_OPTIONS) +}) + +test('TIER: Fable runs the route as it is', async ($, on) => { + const rig = await bootRun($, on, OPUS, asksTier(['Fable'])) + await typeFeat($) + expect(await lastStep($, rig)).toEqual({ model: FABLE, effort: 'high' }) +}) + +test('TIER: Opus instead runs the whole run on opus, once asked', async ( + $, on) => { + const w = asksTier([INSTEAD]) + const rig = await bootRun($, on, OPUS, w) + await typeFeat($) + expect(await lastStep($, rig)).toEqual({ model: OPUS, effort: 'high' }) + await $.tool.call({ tool: ROUTE_TOOL, phase: 'orchestrate' }) + expect(await lastStep($, rig)).toEqual({ model: OPUS, effort: 'medium' }) + expect(mainLine(await route($, 'show'))).toContain( + '[tier big (instead of best)]') + await endTurn($) + expect((await lastStep($, rig)).model).toBe(OPUS) + expect(w.asked).toHaveLength(1) +}) + +test('TIER: a work route never inherits big; a typed skill asks again', async ( + $, on) => { + const w = asksTier([INSTEAD, 'Fable'], { + edit: withRows({ bugfix: 'reflect' }), + }) + const rig = await bootRun($, on, OPUS, w) + await typeFeat($) + await $.tool.call({ tool: ROUTE_TOOL, phase: 'implement' }) + expect((await lastStep($, rig)).model).toBe(SONNET) + expect(w.asked).toHaveLength(1) + await endTurn($) + await typed($, '/bugfix a thing') + await skillPrompt($, 'bugfix') + expect(w.asked).toHaveLength(2) + expect((await lastStep($, rig)).model).toBe(FABLE) +}) + +test('TIER: fable down after Opus instead is no stand-in', async ($, on) => { + const w = asksTier([INSTEAD]) + const rig = await bootRun($, on, OPUS, w) + await typeFeat($) + await $.agent.spawn(spawnOf('feater', { model: FABLE })) + await failWith($, 'rate_limit', 'a1') + expect(await lastStep($, rig)).toEqual({ model: OPUS, effort: 'high' }) + expect(await route($, 'show')).not.toContain('stands in for') +}) + +test('TIER: Stop asking silences the session and show says so', async ( + $, on) => { + const w = asksTier([STOP]) + const rig = await bootRun($, on, OPUS, w) + await typeFeat($) + expect(await lastStep($, rig)).toEqual({ model: FABLE, effort: 'high' }) + await typeFeat($) + expect(w.asked).toHaveLength(1) + expect(await route($, 'show')).toContain( + 'ask-tier: best (paused this session)') +}) + +test('TIER: a session already on fable asks nothing', async ($, on) => { + const w = asksTier([INSTEAD]) + const rig = await bootRun($, on, FABLE, w) + await typeFeat($) + expect(w.asked).toEqual([]) + expect((await lastStep($, rig, FABLE)).model).toBe(FABLE) +}) + +test('TIER: headless asks nothing and consumes no answer', async ($, on) => { + const w = asksTier([INSTEAD], { surfaces: [] }) + const rig = await bootRun($, on, OPUS, w) + await typeFeat($) + expect(w.asked).toEqual([]) + expect(w.answers).toEqual([INSTEAD]) + expect((await lastStep($, rig)).model).toBe(FABLE) +}) + +test('TIER: a dismissed dialog runs fable and the span is not re-asked', async ( + $, on) => { + const w = asksTier([REJECT]) + const rig = await bootRun($, on, OPUS, w) + await typeFeat($) + expect(w.asked).toHaveLength(1) + await $.tool.call({ tool: ROUTE_TOOL, phase: 'plan' }) + expect(w.asked).toHaveLength(1) + expect((await lastStep($, rig)).model).toBe(FABLE) +}) + +test('TIER: the route tool asks on main, not inside an agent', async ( + $, on) => { + const w = asksTier([INSTEAD]) + await bootRun($, on, OPUS, w) + await $.tool.call({ tool: ROUTE_TOOL, phase: 'plan', agentId: 'a1' }) + expect(w.asked).toEqual([]) + await $.tool.call({ tool: ROUTE_TOOL, phase: 'plan' }) + expect(w.asked).toHaveLength(1) + expect(w.asked[0]?.text).toContain('Route tool routes main to plan') +}) + +test('TIER: /route assigns the slot only after the answer', async ( + $, on) => { + const w = asksTier([INSTEAD]) + const hold = deferred() + const open = deferred() + w.gate = hold.gate + w.onAsk = open.release + const rig = await bootRun($, on, OPUS, w) + const pending = route($, 'plan') + await open.gate + expect((await lastStep($, rig)).model).toBe(OPUS) + hold.release() + expect(mainLine(await pending)).toContain('user plan') + expect(await lastStep($, rig)).toEqual({ model: OPUS, effort: 'xhigh' }) + expect(w.asked[0]?.text).toContain('/route routes main to plan') +}) + +test('TIER: Stop answered on /route pauses for real; model=fable skips', async ( + $, on) => { + const w = asksTier([STOP]) + await bootRun($, on, OPUS, w) + await route($, 'plan') + await typeFeat($) + expect(w.asked).toHaveLength(1) + await route($, 'clear') + const out = await route($, 'model=fable') + expect(w.asked).toHaveLength(1) + expect(mainLine(out)).toContain('user custom') +}) + +test('TIER: /route model=fable asks nothing', async ($, on) => { + const w = asksTier([INSTEAD]) + await bootRun($, on, OPUS, w) + expect(mainLine(await route($, 'model=fable'))).toContain('user custom') + expect(w.asked).toEqual([]) +}) + +test('TIER: a sticky route outranks the skill slot: no ask', async ($, on) => { + const w = asksTier([INSTEAD]) + const rig = await bootRun($, on, OPUS, w) + await route($, 'model=opus') + await typeFeat($) + expect(w.asked).toEqual([]) + expect((await lastStep($, rig)).model).toBe(OPUS) +}) + +test('TIER: mainUpgrade off means nothing to decide: no ask', async ( + $, on) => { + const w = asksTier([INSTEAD], { home: { mainUpgrade: false } }) + const rig = await bootRun($, on, OPUS, w) + await typeFeat($) + expect(w.asked).toEqual([]) + expect((await lastStep($, rig)).model).toBe(OPUS) +}) + +test('TIER: opus down drops the Opus instead option', async ($, on) => { + const w = asksTier(['Fable']) + await bootRun($, on, SONNET, w) + await opusDown($) + await typeFeat($) + expect(w.asked[0]?.options).toEqual(['Fable', STOP]) +}) + +test('TIER: a skill the model loads on main asks too', async ($, on) => { + const w = asksTier([INSTEAD], { + edit: withRows({ brainstorming: 'plan' }), + }) + const rig = await bootRun($, on, OPUS, w) + await loadSkill($, 'brainstorming') + expect(w.asked).toHaveLength(1) + expect(w.asked[0]?.text).toContain('Skill /brainstorming routes main to plan') + expect(await lastStep($, rig)).toEqual({ model: OPUS, effort: 'xhigh' }) +}) + +/** The verifier on audit, with an `about` line: a best-tier agent row. */ +const auditVerifier = (file: Rec): void => { + (file.agents as Table).verifier = 'audit' + setPhase('audit', { about: 'gates' })(file) +} + +test('TIER: a rowed spawn asks once per type; Opus instead sticks', async ( + $, on) => { + const w = asksTier([INSTEAD], { edit: auditVerifier }) + const rig = await bootRun($, on, OPUS, w) + await $.agent.spawn(spawnOf('verifier')) + expect(w.asked).toHaveLength(1) + expect(w.asked[0]?.text).toContain('Agent verifier runs audit (gates) on ' + + 'claude-fable-5-1 at xhigh') + expect(w.asked[0]?.options).toEqual(TIER_OPTIONS) + await $.agent.spawn(spawnOf('verifier')) + expect(w.asked).toHaveLength(1) + expect(rig.specs).toEqual([OPUS, OPUS]) +}) + +test('TIER: Fable on a spawn runs the head', async ($, on) => { + const rig = await bootRun($, on, OPUS, asksTier(['Fable'], { + edit: auditVerifier, + })) + await $.agent.spawn(spawnOf('verifier')) + await $.agent.spawn(spawnOf('verifier')) + expect(rig.specs).toEqual([FABLE, FABLE]) +}) + +test('TIER: an explicit model, a nested spawn and a work row never ask', async ( + $, on) => { + const w = asksTier([INSTEAD], { edit: auditVerifier }) + await bootRun($, on, OPUS, w) + await $.agent.spawn(spawnOf('verifier', { model: 'opus' })) + await $.agent.spawn(spawnOf('verifier', { parentAgentId: 'a1' })) + await $.agent.spawn(spawnOf('feater')) + expect(w.asked).toEqual([]) +}) + +test('TIER: the first-use dialog runs first, then the tier ask', async ( + $, on) => { + const w = asks(['Keep', INSTEAD], { askTier: 'best' }) + const rig = await bootRun($, on, OPUS, w) + await typeFeat($) + expect(w.asked).toHaveLength(2) + expect(w.asked[0]?.text).toContain('First route for /feat') + expect(w.asked[1]?.text).toContain('routes main to reflect') + expect((await lastStep($, rig)).model).toBe(OPUS) +}) + +test('TIER: a stored spawn answer holds while another dialog is open', async ( + $, on) => { + const w = asks(['Keep', INSTEAD], { askTier: 'best', edit: auditVerifier }) + const rig = await bootRun($, on, OPUS, w) + await $.agent.spawn(spawnOf('verifier')) + const hold = deferred() + const open = deferred() + w.gate = hold.gate + w.onAsk = open.release + w.answers.push('Keep') + const other = $.agent.spawn(spawnOf('feater')) + await open.gate + await $.agent.spawn(spawnOf('verifier')) + hold.release() + await other + expect(w.asked).toHaveLength(3) + expect(rig.specs).toEqual([OPUS, OPUS, SONNET]) +}) + +test('TIER: a dialog in flight routes a typed skill unasked', async ($, on) => { + const w = asks(['Keep'], { askTier: 'best' }) + const hold = deferred() + const open = deferred() + w.gate = hold.gate + w.onAsk = open.release + const rig = await bootRun($, on, OPUS, w) + const other = $.agent.spawn(spawnOf('feater')) + await open.gate + await typeFeat($) + expect(w.asked).toHaveLength(1) + expect((await lastStep($, rig)).model).toBe(FABLE) + hold.release() + await other +}) + +test('TIER: /route ask-tier off and on write the key', async ($, on) => { + const w = asksTier([]) + await bootRun($, on, OPUS, w) + expect(await route($, 'ask-tier off')).toBe('ask-tier off') + expect(routingOf(w).askTier).toBe(false) + await typeFeat($) + expect(w.asked).toEqual([]) + expect(await route($, 'show')).toContain('ask-tier: off') + expect(await route($, 'ask-tier on')).toBe('ask-tier on') + expect(routingOf(w).askTier).toBe('best') +}) + +test('TIER: /route ask-tier takes on or off only', async ($, on) => { + const w = asksTier([]) + await bootRun($, on, OPUS, w) + expect(await route($, 'ask-tier maybe')).toBe('usage: /route ask-tier on|off') + expect(await route($, 'ask-tier')).toBe('usage: /route ask-tier on|off') + expect(w.written).toEqual([]) +}) + +test('TIER: the machine override wins over /route ask-tier', async ($, on) => { + const w = asksTier([INSTEAD], { home: { askTier: false } }) + await bootRun($, on, OPUS, w) + expect(await route($, 'ask-tier on')).toContain('wins here') + await typeFeat($) + expect(w.asked).toEqual([]) +}) + +test('TIER: an invalid askTier reads best and is logged once', async ( + $, on) => { + const logs = recordLogs(on) + const w = asksTier(['Fable'], { edit: f => { f.askTier = 'work' } }) + await bootRun($, on, OPUS, w) + await typeFeat($) + expect(w.asked).toHaveLength(1) + await route($, 'reload') + expect(logs.filter(l => l.includes('askTier must be'))).toHaveLength(1) +}) + +test('TIER: no routing.json means no ask; the route is set', async ($, on) => { + const w = asksTier([INSTEAD], { routing: 'absent' }) + await bootRun($, on, OPUS, w) + await $.tool.call({ tool: ROUTE_TOOL, phase: 'plan' }) + expect(w.asked).toEqual([]) + expect(mainLine(await route($, 'show'))).toContain('model plan') +}) diff --git a/mods/model-router/hooks/register.ts b/mods/model-router/hooks/register.ts index 5f2a13f..0543d68 100644 --- a/mods/model-router/hooks/register.ts +++ b/mods/model-router/hooks/register.ts @@ -44,6 +44,7 @@ type Config = { type Rule = { re: RegExp; phase: string; mode: PromptMode } type Source = | 'user' | 'model' | 'skill' | 'prompt' | 'run' | 'derived' | 'classifier' +type Choice = 'best' | 'big' // the tier a span resolves through type Routed = { phase: string route: Route @@ -51,6 +52,7 @@ type Routed = { label?: string // the skill a skill route came from, for the logs explicitEffort?: boolean // the effort was asked for, not the phase's own explicitModel?: boolean // the model was chosen by hand in the scope dialog + tierChoice?: Choice // the tier-ask answer: the span's tier, once asked } type Served = { at: number; tokens: number } // ms, context tokens type Hold = { until: number; reason: string } // until: ms, Infinity = reload @@ -119,8 +121,10 @@ type State = { pendingEstimate: Estimate | null // same, typed mid-turn: next turn's classifyFails: number // classifier failures in a row classifyUntil: number // classifier paused until (ms); 0 = running - asking: string | null // key of the one first-use dialog in flight + asking: string | null // key of the one dialog in flight (first-use or tier) asked: Set // keys answered (or failed) this session + tierPaused: boolean // "Stop asking this session": no tier ask until /clear + tierSpawn: Map // agent type -> its tier-ask answer writes: Promise // the serialized routing.json write chain } type Log = (text: string) => void @@ -153,6 +157,8 @@ type Memory = { ok: boolean // the file was read: false = no dialog, no write ask: boolean // dialogs on (the machine override wins over the file) askLocal: boolean | undefined // the machine override's own `ask` + askTier: unknown // the file's raw `askTier` (absent = undefined) + askTierLocal: unknown // the machine override's raw `askTier` base: Record // the file's rows, before any project layer confirmed: Record // name -> the phase a Keep endorsed about: Table // phase -> its one-line meaning, shown in the dialog only @@ -186,13 +192,19 @@ const OVERRIDE = '.claude/model-router.json' const ROUTING = 'routing.json' // next to plugin.json: the tracked source // Key order of a written routing.json; other keys follow, untouched. const ROUTING_ORDER: readonly string[] = [ - 'phases', 'skills', 'agents', 'projects', 'confirmed', 'changed', 'ask', + 'phases', 'skills', 'agents', 'projects', 'confirmed', 'changed', + 'ask', 'askTier', ] // First-use dialog: the answers, and what a question may carry of the outside. const LATER = 'Later' const KEEP = 'Keep' const CHANGE = 'Change' const EVERYWHERE = 'Everywhere' +// Tier ask: the answers; INSTEAD_TIER is the tier "Opus instead" resolves by. +const TIER_HEAD = 'Fable' +const TIER_INSTEAD = 'Opus instead (big tier)' +const TIER_STOP = 'Stop asking this session' +const INSTEAD_TIER = 'big' 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. @@ -761,6 +773,8 @@ function emptyMemory(): Memory { ok: false, ask: true, askLocal: undefined, + askTier: false, + askTierLocal: undefined, base: { skills: {}, agents: {} }, confirmed: { skills: {}, agents: {}, phases: {} }, about: {}, @@ -804,6 +818,8 @@ function buildMemory( ok: true, ask: askLocal ?? file.ask !== false, askLocal, + askTier: file.askTier, + askTierLocal: override?.askTier, base: { skills: strTable(file.skills), agents: strTable(file.agents) }, confirmed: { skills: strTable(sure.skills), @@ -1027,6 +1043,8 @@ function newState(cfg: Config, source: string): State { classifyUntil: 0, asking: null, asked: new Set(), + tierPaused: false, + tierSpawn: new Map(), writes: Promise.resolve(), } } @@ -1140,6 +1158,41 @@ function resolveName(st: State, name: string, after?: string) { return availableIn(st, tier) ?? nextAvailable(st, from) } +/** The id of the head of the `best` tier, whatever `askTier` says. */ +function headId(st: State): string | undefined { + const list = hasKey(st.cfg.tiers, BEST) ? st.cfg.tiers[BEST] : undefined + const alias = list?.[0] + return alias === undefined ? undefined : st.cfg.models[alias] +} + +/** + * The head a route is asked about before it applies; undefined = off. The + * machine override wins; an absent key reads best, so does any other value + * (asking is the safe side, `warnAskTier` says so once). + */ +function tierHead(st: State): string | undefined { + const value = st.mem.askTierLocal ?? st.mem.askTier + return value === false ? undefined : headId(st) +} + +/** The `big` tier's models, the head left out, in order. */ +function insteadAliases(st: State): string[] { + const list = hasKey(st.cfg.tiers, INSTEAD_TIER) + ? st.cfg.tiers[INSTEAD_TIER] + : undefined + return (list ?? []).filter(alias => st.cfg.models[alias] !== headId(st)) +} + +/** What "Opus instead" runs: the first non-head `big` model that is up. */ +const insteadName = (st: State): string | undefined => + availableIn(st, insteadAliases(st)) + +/** "Opus instead" is offered only while its model is up (a true label). */ +function insteadOffered(st: State): boolean { + const id = st.cfg.models[insteadAliases(st)[0] ?? ''] + return id !== undefined && !st.down.has(id) +} + function resolveRoute(st: State, route: Route | undefined) { const name = routeName(route) return name === undefined ? undefined : resolveName(st, name) @@ -1546,7 +1599,9 @@ type Verdict = { */ function wantedModel(st: State, cur: string): string | undefined { const slot = mainModelSlot(st) - const name = routeName(slot?.route) + const instead = slot?.tierChoice === 'big' && slot.route.tier === BEST + const name = instead ? insteadName(st) ?? routeName(slot.route) + : routeName(slot?.route) if (name === undefined) return undefined const wanted = resolveName(st, name, canonical(st.cfg, cur)) const above = wanted !== undefined && slot?.source === 'classifier' && @@ -1675,6 +1730,7 @@ function isStandIn( ): boolean { const head = heldHead(st) if (st.off || head === undefined || d.wanted === undefined) return false + if (mainModelSlot(st)?.tierChoice === 'big') return false const id = canonical(st.cfg, d.call.model) return id === d.wanted && ranksAbove(st, head, id) && wouldRunHead(st, cur, head, read) @@ -1866,6 +1922,8 @@ function modelWord(st: State, v: Verdict): string { function tierWord(st: State, word: string): string { const name = mainModel(st) const tier = name !== undefined && hasKey(st.cfg.tiers, name) + const big = mainModelSlot(st)?.tierChoice === 'big' + if (tier && big) return `${word} [tier ${INSTEAD_TIER} (instead of ${name})]` return tier ? `${word} [tier ${name}]` : word } @@ -1925,6 +1983,12 @@ async function snapshot($: Api, st: State) { return { now, ...(await decideFor($, st, cur)) } } +/** `/route show`: the tier ask's state, a Stop answer included. */ +function askTierWord(st: State): string { + if (tierHead(st) === undefined) return 'off' + return st.tierPaused ? 'best (paused this session)' : BEST +} + /** The downgrade switch and, when on, the cold read it is capped at. */ const switchWord = (st: State): string => st.cfg.mainModelSwitch ? `on (downgrade, cap ${st.cfg.downgradeMaxTokens} tokens cold, ttl ${ @@ -1940,7 +2004,8 @@ async function show($: Api, st: State): Promise { `router: ${routerWord(st)} · switch: ${switchWord(st)} · upgrade: ${ flag(c.mainUpgrade)} · verbose: ${ flag(c.verbose)} · classify: ${flag(c.classify)} · probe: ${ - flag(c.probe)} · spinner: ${flag(c.spinner)}`, + flag(c.probe)} · spinner: ${flag(c.spinner)} · ask-tier: ${ + askTierWord(st)}`, downText(st, s.now), `live loops: ${st.loops.size}`, phasesText(st), @@ -2019,6 +2084,8 @@ async function toggle( async function setUserRoute($: Api, st: State, args: string) { const parsed = parseRoute(st.cfg, args) if (typeof parsed === 'string') return parsed + const probe: State = { ...st, userMain: parsed } + await tierAsk($, st, parsed, '/route', probe) st.userMain = parsed refresh($, st) return show($, st) @@ -2032,12 +2099,23 @@ function applyToggles(st: State): void { if (classify !== undefined) st.cfg.classify = classify } +/** `askTier` takes "best" or false; any other value reads best, said once. */ +function warnAskTier(st: State, log: Log): void { + const bad = [st.mem.askTier, st.mem.askTierLocal].some( + v => v !== undefined && v !== BEST && v !== false) + const text = 'model-router: askTier must be "best" or false; read as best' + if (!bad || st.logged.has(text)) return + st.logged.add(text) + log(text) +} + function applyLoaded(st: State, loaded: Loaded, log: Log): void { st.cfg = loaded.cfg st.rules = compileRules(loaded.cfg, log) st.source = loaded.source st.mem = loaded.mem st.override = loaded.override + warnAskTier(st, log) st.loaded = true st.rebuildDue = false applyToggles(st) @@ -2111,7 +2189,9 @@ async function handleCommand($: Api, st: State, args: string): Promise { case 'pending': return pendingText(st) case 'ask': - return askCommand($, st, rest[0]) + return flagCommand($, st, rest[0], ASK_FLAG) + case 'ask-tier': + return flagCommand($, st, rest[0], ASK_TIER_FLAG) case 'forget': return forgetCommand($, st, rest) case 'switch': @@ -2486,8 +2566,11 @@ async function handlePicker( // 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 // project; a change can be a project exception. Only a dialog answer, -// `/route ask` or `/route forget` writes; nothing is asked on the step path -// or in an agent. +// `/route ask`, `/route ask-tier` or `/route forget` writes; nothing is +// asked on the step path +// or in an agent. A route that would lift main, or a rowed spawn, onto the +// head of `askTier` asks first: Fable, Opus instead, or stop for the session; +// nothing is written. const HEADER = 'model-router' const UPDATED = 'routing.json updated: commit it from the config repo ' + @@ -2650,12 +2733,15 @@ function aboutLine(st: State, phase: string): string | undefined { return line === '' ? undefined : line } -/** "Routed to ()": the parenthesis only when about is set. */ -function routedTo(st: State, phase: string): string { +/** " ()": the parenthesis only when about is set. */ +function phaseWord(st: State, phase: string): string { const about = aboutLine(st, phase) - return `Routed to ${phase}${about === undefined ? '' : ` (${about})`}` + return `${phase}${about === undefined ? '' : ` (${about})`}` } +const routedTo = (st: State, phase: string): string => + `Routed to ${phaseWord(st, phase)}` + /** Who uses a phase: its rows, the derived dispatch route, prompt rules. */ function consumers(st: State, phase: string): string { const { skills, agents, prompt } = st.cfg @@ -2900,14 +2986,17 @@ async function runDialog($: Api, st: State, req: Req, text: string) { return saveAnswer($, st, req, answer) } -function failOnce($: Api, st: State, err: unknown): void { - const text = `model-router: first-use dialog failed (${errWord(err)}); ` + - 'default route kept' +function logOnce($: Api, st: State, text: string): void { if (st.logged.has(text)) return st.logged.add(text) $.ui.log(text) } +function failOnce($: Api, st: State, err: unknown): void { + logOnce($, st, `model-router: first-use dialog failed (${errWord(err)}); ` + + 'default route kept') +} + /** * Asks once whether `req.phase` is the right route for this row. At most * one dialog is open per session: any other use finds `asking` set and @@ -2984,12 +3073,14 @@ async function toastChange($: Api, st: State, skill: string) { async function confirmSkill($: Api, st: State, skill: string, row: Picked) { const req: Req = { kind: 'skills', name: skill, phase: row.phase } const say = () => skillQuestion($, st, skill, row.phase) - if (!(await confirmFirst($, st, req, say))) return - const after = skillRow(st, skill) - if (after === undefined) return - routeMainBySkill(st, skill, after, true) - refresh($, st) - if (after.phase !== row.phase) await toastChange($, st, skill) + if (await confirmFirst($, st, req, say)) { + const after = skillRow(st, skill) + if (after === undefined) return + routeMainBySkill(st, skill, after, true) + refresh($, st) + if (after.phase !== row.phase) await toastChange($, st, skill) + } + await tierAsk($, st, st.turnMain, `Skill /${clean(skill, NAME_CAP)}`) } /** Rowed spawn: the route in force after the dialog (changed or not). */ @@ -3003,9 +3094,10 @@ async function routeSpawn($: Api, st: State, e: SpawnIn) { if (!route || !phase || inside) return route const req: Req = { kind: 'agents', name: e.subagentType, phase } const say = async () => spawnQuestion($, st, e, req, route) - return (await confirmFirst($, st, req, say)) + const after = (await confirmFirst($, st, req, say)) ? spawnRoute(st, e, frozen) : route + return spawnTier($, st, e, after) } /** A phase declared through the route tool: confirm-only. */ @@ -3017,6 +3109,138 @@ async function confirmPhase($: Api, st: State, phase: string) { await confirmFirst($, st, req, () => mainQuestion($, st, lead)) } +// ---- tier ask: before a route lifts main or a spawn onto the head -------- +// One question per span at a route event (never in a step, LRN-231): Fable, +// Opus instead (the span resolves through `big`), or stop for the session. +// Headless, a dismissed dialog and a failure all run the route as it is. + +const tierOptions = (st: State): string[] => insteadOffered(st) + ? [TIER_HEAD, TIER_INSTEAD, TIER_STOP] + : [TIER_HEAD, TIER_STOP] + +/** The answer as the span's tier; Stop also pauses the asks. */ +function tierChoiceOf(st: State, label: string | undefined): Choice { + if (label === TIER_STOP) st.tierPaused = true + return label === TIER_INSTEAD ? 'big' : 'best' +} + +/** The answer on the slot and on the run slot of its tier. */ +function stampTier(st: State, slot: Routed, choice: Choice): void { + slot.tierChoice = choice + const run = st.runMain + if (run !== null && run.route.tier === slot.route.tier) { + run.tierChoice = choice + } +} + +/** A helper write keeps the choice of the span it belongs to: same tier. */ +function inheritedChoice(st: State, route: Route): { tierChoice?: Choice } { + const prev = [st.turnMain, st.runMain].find(slot => + slot?.tierChoice !== undefined && slot.route.tier === route.tier) + const choice = route.tier === undefined ? undefined : prev?.tierChoice + return choice === undefined ? {} : { tierChoice: choice } +} + +/** The pure guards, cheapest first: is this slot a candidate for the ask. */ +function tierWanted(st: State, slot: Routed, view: State): boolean { + const head = tierHead(st) + if (st.off || head === undefined || st.tierPaused) return false + if (canonical(st.cfg, st.turnModel ?? st.sessionModel) === head) return false + if (st.asking !== null || slot.tierChoice !== undefined) return false + return slot.route.tier === BEST && slot === mainModelSlot(view) +} + +async function tierQuestion($: Api, st: State, slot: Routed, origin: string) { + const v = await snapshot($, st) + return canonical(st.cfg, v.call.model) !== tierHead(st) ? undefined + : `${origin} routes main to ${phaseWord(st, slot.phase)}: ${ + idWord(st, v.call.model)} at ${effortWord(st, v)}. Run it on fable?` +} + +/** + * Asks before `slot` (just set by `origin`) lifts main onto the head of + * `askTier`. Writes land on `st`; the decision is read from `view` (the + * `/route` path reads a probe, the slot is not assigned yet). The dialog + * holds `asking`; an answer after a /clear is dropped. Never throws. + */ +async function tierAsk( + $: Api, + st: State, + slot: Routed | null, + origin: string, + view: State = st, +): Promise { + if (slot === null || !tierWanted(st, slot, view)) return + st.asking = 'tier:main' + try { + if ((await $.session.surfaces()).length === 0) return + const text = await tierQuestion($, view, slot, origin) + if (text === undefined) return + const sid = await $.session.id() + const label = await askStep($, text, tierOptions(st)) + if ((await $.session.id()) !== sid) return + stampTier(st, slot, tierChoiceOf(st, label)) + if (slot.tierChoice === 'big') refresh($, st) + } catch (err) { + tierFailOnce($, st, err) + } finally { + st.asking = null + } +} + +const tierFailOnce = ($: Api, st: State, err: unknown): void => + logOnce($, st, `model-router: tier dialog failed (${errWord(err)}); ` + + 'route kept') + +/** Opus instead for a spawn: its row's effort on the first non-head model. */ +function insteadRoute(st: State, route: Route): Route { + const model = insteadName(st) + return model === undefined ? route : { effort: route.effort, model } +} + +function spawnTierText(st: State, e: SpawnIn, route: Route): string { + const phase = hasKey(st.cfg.agents, e.subagentType) + ? st.cfg.agents[e.subagentType] + : undefined + const effort = st.explicitEffort.get(e.tool_use_id) ?? route.effort + return `Agent ${clean(e.subagentType, NAME_CAP)} runs ${ + phaseWord(st, phase ?? '?')} on ${tierHead(st)} at ${ + effort ?? 'its own effort'}. Run it on fable?` +} + +/** One question per agent type per session, answered before it spawns. */ +async function spawnTierAsk($: Api, st: State, e: SpawnIn, route: Route) { + const head = tierHead(st) + if (head === undefined || st.tierPaused || st.asking !== null) return + if (spawnTarget($, st, e, route) !== head) return + st.asking = `tier:agent:${e.subagentType}` + try { + if ((await $.session.surfaces()).length === 0) return + const sid = await $.session.id() + const label = await askStep($, spawnTierText(st, e, route), tierOptions(st)) + if ((await $.session.id()) !== sid) return + st.tierSpawn.set(e.subagentType, tierChoiceOf(st, label)) + } catch (err) { + tierFailOnce($, st, err) + } finally { + st.asking = null + } +} + +/** A rowed spawn's route after the tier ask: the type's stored answer. */ +async function spawnTier( + $: Api, + st: State, + e: SpawnIn, + route: Route | undefined, +) { + if (route === undefined || route.tier !== BEST) return route + if (!st.tierSpawn.has(e.subagentType)) await spawnTierAsk($, st, e, route) + return st.tierSpawn.get(e.subagentType) === 'big' + ? insteadRoute(st, route) + : route +} + // ---- first-use commands ---------------------------------------------- /** Rows and phases not confirmed yet, those asked this session first. */ @@ -3038,22 +3262,46 @@ function pendingText(st: State): string { ].join('\n') } -async function askCommand($: Api, st: State, arg: string | undefined) { - if (arg !== 'on' && arg !== 'off') return 'usage: /route ask on|off' - const patch: Patch = file => { file.ask = arg === 'on' } +/** An on|off key of routing.json that `/route on|off` writes. */ +type Flag = { + word: string + key: string + value: (on: boolean) => unknown + local: (m: Memory) => unknown // the machine override's own value +} + +const ASK_FLAG: Flag = { + word: 'ask', key: 'ask', value: on => on, local: m => m.askLocal, +} +const ASK_TIER_FLAG: Flag = { + word: 'ask-tier', + key: 'askTier', + value: on => (on ? BEST : false), + local: m => m.askTierLocal, +} + +async function flagCommand( + $: Api, + st: State, + arg: string | undefined, + flag: Flag, +) { + const { word, key } = flag + if (arg !== 'on' && arg !== 'off') return `usage: /route ${word} on|off` + const patch: Patch = file => { file[key] = flag.value(arg === 'on') } try { if (!(await writeRouting($, st, patch))) { - return `${ROUTING} missing or unreadable: ask unchanged` + return `${ROUTING} missing or unreadable: ${word} unchanged` } } catch (err) { return err instanceof RebuildFailed - ? 'ask saved, config not rebuilt: /route reload' - : failedWrite($, 'ask', err) + ? `${word} saved, config not rebuilt: /route reload` + : failedWrite($, word, err) } - const local = st.mem.askLocal - const note = local === undefined ? '' : `; ~/${OVERRIDE} sets ask ${ - local ? 'on' : 'off'} and wins here` - return `ask ${arg}${note}` + const local = flag.local(st.mem) + const note = local === undefined ? '' : `; ~/${OVERRIDE} sets ${key} ${ + local === false ? 'off' : 'on'} and wins here` + return `${word} ${arg}${note}` } // ---- /route forget: the user takes decisions back ------------------------- @@ -3363,7 +3611,7 @@ async function registerCommand($: Api): Promise { name: 'route', description: 'model-router: show or set the model and effort route', argumentHint: - '[show|clear|off|on|reload|pending|ask on|off|' + + '[show|clear|off|on|reload|pending|ask on|off|ask-tier on|off|' + 'forget ||' + 'model= effort=|switch on|off|verbose on|off|' + 'classify on|off]', @@ -3395,7 +3643,8 @@ function pickRoute(cfg: Config, phase: unknown, effort: unknown) { function applyRoute(st: State, agentId: string | undefined, p: Picked): void { if (agentId === undefined) { st.turnMain = { phase: p.phase, route: p.route, source: 'model', - ...(p.explicitEffort ? { explicitEffort: true } : {}) } + ...(p.explicitEffort ? { explicitEffort: true } : {}), + ...inheritedChoice(st, p.route) } } else { writeLoop(loopOf(st, agentId), p.route, 'route tool') } @@ -3457,6 +3706,7 @@ async function handleRouteTool($: Api, st: State, e: RouteInput) { applyRoute(st, e.agentId, picked) if (e.agentId === undefined && typeof e.phase === 'string') { await confirmPhase($, st, picked.phase) + await tierAsk($, st, st.turnMain, 'Route tool') } return { result: await routedText($, st, e.agentId, picked) } } @@ -3492,7 +3742,8 @@ function routeMainBySkill( ? { effort: row.route.effort } : { ...row.route } const turn: Routed = { phase: row.phase, route, - source: 'skill', label: clean(skill, NAME_CAP) } + source: 'skill', label: clean(skill, NAME_CAP), + ...(typed ? {} : inheritedChoice(st, route)) } st.turnMain = turn if (row.route.tier === BEST) st.runMain = { ...turn, source: 'run' } else if (typed) st.runMain = null @@ -3686,7 +3937,8 @@ function pushOrchestrate(st: State): void { if (st.pushed !== null || !route) return if (src === 'model' || src === 'skill') return st.pushed = { prev: st.turnMain, spawnIds: new Set() } - st.turnMain = { phase: 'orchestrate', route, source: 'derived' } + st.turnMain = { phase: 'orchestrate', route, source: 'derived', + ...inheritedChoice(st, route) } } /** Restores the route from before the dispatch, unless one replaced it. */ @@ -4240,6 +4492,9 @@ function registerSkills(on: On, st: State): void { st.skillCalls += 1 try { safely(st, $, 'Skill', () => onSkillLoad(st, skill, e.agentId)) + if (e.agentId === undefined && skillRow(st, skill)) { + await tierAsk($, st, st.turnMain, `Skill /${clean(skill, NAME_CAP)}`) + } return await next(e) } finally { st.skillCalls -= 1 diff --git a/mods/model-router/routing.json b/mods/model-router/routing.json index c48c563..7ac65a2 100644 --- a/mods/model-router/routing.json +++ b/mods/model-router/routing.json @@ -205,5 +205,6 @@ } }, "changed": {}, - "ask": true + "ask": true, + "askTier": "best" } From 789fd00b235f3250fe1671afd43cafc08a49e134 Mon Sep 17 00:00:00 2001 From: bchanot Date: Mon, 2 Nov 2026 16:06:40 +0100 Subject: [PATCH 2/3] =?UTF-8?q?docs:=20README=20ask-before-Fable=20bullet,?= =?UTF-8?q?=20/route=20list=20and=20config=20keys;=20CHANGELOG=20Unrelease?= =?UTF-8?q?d;=20effort-shift=20toggle=20list=20=E2=80=94=20feat=20router-a?= =?UTF-8?q?sk-tier?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 1 + README.md | 7 ++++--- lib/effort-shift.md | 5 +++-- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 58a6ca5..5a630c5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/) and this project - **model-router prompt classifier**: a plain prompt typed in the composer (12 characters or more, not a slash command, not mid-turn, never under `-p` or in a sub-agent) that no keyword rule, skill, run slot, `/route` or floor covers is labelled by one call to the engine's small model (`design`, `analysis`, `coding`, `bookkeeping`, `chat`), bounded to 3 s. The label maps to plan, reflect, implement or apply and the turn takes that phase's route: its effort, and its model under the switch and the downgrade cap, never above the session model (an `ultrathink` floor raises the effort only, the guess's model holds); no dialog, no file write, gone at the end of the turn, replaced by any route call or typed skill, and dropped for that turn by a `/effort` typed between turns. Three failures in a row pause it for `cooldownMinutes` (one toast, `classifier: paused` in the status line). `"classify": false` in `~/.claude/model-router.json` and `/route classify on|off` turn it off; `/route show` prints `classify:`. The status line reads `route: classifier ` and `/route verbose on` adds `(: classifier)`. - **model-router cold-read caps**: both main-loop caps measure the cold read a switch costs, from a per-model record of main's last step, warm within the engine's prompt-cache TTL (`cache_ttl` 5m or 1h from main's model-switch events, 1 h before the first, kept across `/clear`; records cleared by `/clear` and `/route reload`), plus the submitted prompt the engine's usage may not count yet (code points / 3 of its text, context entries and a typed skill's body, added at the turn's first main step unless usage already grew by half of it; a `document` attachment blocks the switch for that step); `downgradeMaxTokens` (default 120000) joins `upgradeMaxTokens` (200000). A model-loaded helper skill inside a best-tier run moves effort only; main routed onto a model whose window the context outgrew returns to the session model. `/route show` prints `switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`, the status line shows ` · switch off` only when the switch is off, the skip line is logged once per cap crossing and the change toast names a cap hold. A built-in `general-purpose` agent that main spawns with no model while main sits below the session model starts on the session model instead of inheriting the lower one. +- **model-router ask before Fable**: before a route lifts the main loop, or a rowed agent, onto Fable from another model, the mod asks once per span with the origin (skill, agent, `route` tool, `/route`), the phase and its `about` line, the model and the effort: `Fable`, `Opus instead (big tier)` (the span resolves through the `big` tier at the phase's effort, offered only while Opus is up) or `Stop asking this session` (paused until `/clear`). A best-tier skill the model loads counts as a skill row; a spawn keeps one answer per agent type per session. Never headless (`-p`) or inside a sub-agent; a dismissed dialog runs Fable; no answer is written to `routing.json` (`confirmed` included). `routing.json` gains `askTier` (`best`, or `false` to turn it off; the machine config wins), set by `/route ask-tier on|off`; `/route show` prints `ask-tier:`. Known limit: when a Fable breaker hold or a cold-read cap lapses later, main upgrades without asking. Tests: `mods/model-router/hooks/register.test.ts` (TIER). - **/explain-diff skill**: turns a change (commit, range, branch, merge, PR, staged or uncommitted work) into one self-contained HTML page saved outside the repo, under `~/Documents/explanations//YYYY-MM-DD-.html`. The page has a background, an intuition built on toy data with HTML diagrams, a code walkthrough grouped by concern and a 5-question interactive quiz. Adapted from Geoffrey Litt's explain-diff gist. A bundled template (light and dark, works offline) and a checker (`scripts/check_explanation.py`: file name, location, sections, quiz, code escaping, no ASCII art, no em-dash) hold every page to the same floor. Routing row `reflect`; profiles full, max and dev. - **Project path rules (CLAUDE.md split)**: `lib/project-rules.sh` (`check`, `matches`, `sections`, `extract`, `emit`, optional `-C `) is the glob oracle for `.claude/rules/.md` rules, one-line `paths:` frontmatter, loaded on Read of a matching file; suite `lib/tests/project-rules.test.sh`. `/onboard split` classifies an existing project CLAUDE.md section by section behind a gate and moves the path-bound ones into rules on a `chore/claude-md-split` branch. `extract` also moves a `###` subsection (heading passed as `'### '`; a bare heading stays `##`), which ends at the next heading of level 3 or less outside a fence, and `sections --depth 3` lists each `##` section's subsections with their sizes, so `/onboard split` can move a path-bound subsection out of an always-on parent (one `### <title>` row; a row's parent is never itself a move row). `extract` refuses an absolute `<out>`, one with a `..` part, or one that already exists (a dangling symlink included), with rc 2 and the reason on stderr, and leaves the source CLAUDE.md untouched when the rule directory or file cannot be written. `/onboard` and `/init-project` emit `docker`, `testing` and `ci` rules from `templates/project-rules/` when their globs match. This repo's CLAUDE.md now keeps its header, Health Stack and a pointer; four sections load as path rules. - **InstructionsLoaded logger**: `hooks/instructions-loaded.sh`, wired in `settings.json`, appends one JSON line per instruction file loaded to `~/.claude/logs/instructions-loaded.jsonl` (rotated above 5 MB), the proof that a path rule loaded. diff --git a/README.md b/README.md index 713c42b..0489125 100644 --- a/README.md +++ b/README.md @@ -141,12 +141,13 @@ effort, never version. Transcript audit `python3 lib/effort-audit.py`. - 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, a typed `/route` or a hand pick (`/model`, picker). The built-in `/effort` is not a lever inside a run, rows and routes outrank it. - `/model` scope: a pick in the `/model` picker is held first (the engine prints that a hook blocked it), then the same question as `/model <name>` comes. A bare `/model` opens the router's model, variant and scope dialog: fable, opus or sonnet, then Standard or `[1m]`, then the scope, the current model included; `Other model (native picker)` opens the native picker (haiku goes through it or `/model haiku`) and Esc changes nothing. A pick while another dialog is open is refused with `answer the open dialog first`. The picker's Default, an unknown name or a headless run go native, no question. A model chosen in that dialog (a hand pick) always switches: no cold-read cap, no `mainUpgrade` or `mainModelSwitch` flag. A hand pick marked down keeps main where it is until it is back. A native switch (the `/config` Model row included) or `/clear` drops a hand pick; a typed `/route model=` keeps the caps. - 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 <phase>`; `/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 <name|all|projects>` (takes decisions back: a changed row returns to its shipped phase; `all` and `projects` ask first), a phase name, `model=<alias|id> effort=<level>`, `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 <phase>`) 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. +- `/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), `ask-tier on|off` (the ask before Fable, below), `forget <name|all|projects>` (takes decisions back: a changed row returns to its shipped phase; `all` and `projects` ask first), a phase name, `model=<alias|id> effort=<level>`, `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 <phase>`) and prints the switch with its cap and the prompt-cache TTL (`switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`) and `ask-tier:` (`best`, `best (paused this session)` or `off`). 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 <n> tokens over <cap>`) 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. The one other write: `/model <name>`, the bare `/model` dialog or a `/model` picker pick → This project writes the full id as `model` into the session root's `.claude/settings.local.json` (created if absent, keep it gitignored; refused when `.claude` or the file is a link, or the file is over 64 KiB or not a JSON object). Remove its `model` key to undo. +- Ask before Fable: before a route lifts the main loop, or sends a rowed agent, onto Fable from another model, the mod asks once per span. The question names the origin (a skill, typed or loaded by the model, an agent, the `route` tool or `/route`), the phase with its `about` line, and the model and effort the step would run on. `Fable` runs it; `Opus instead (big tier)` runs the span through the `big` tier at the phase's own effort, offered only while Opus is up so the label stays true; `Stop asking this session` pauses the question until `/clear`. A best-tier skill the model loads counts as a skill row, and an agent type gets one answer per session. Nothing is asked in a headless (`-p`) run or inside a sub-agent, a dismissed dialog runs Fable, and no answer is written (`confirmed` included). No question comes when the decision would not land on Fable (`mainUpgrade` off, a cold-read cap, the context window, Fable marked down); when such a Fable hold or cap lapses later, main upgrades without asking, as the breaker already does. `askTier` in routing.json (`best`, or `false` to turn it off) is set by `/route ask-tier on|off`, and the machine config wins. +- Only a first-use dialog answer, `/route ask on|off`, `/route ask-tier 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. The one other write: `/model <name>`, the bare `/model` dialog or a `/model` picker pick → This project writes the full id as `model` into the session root's `.claude/settings.local.json` (created if absent, keep it gitignored; refused when `.claude` or the file is a link, or the file is over 64 KiB or not a JSON object). Remove its `model` key to undo. - 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. +Config layers: `mods/model-router/routing.json` (tracked: phases with their tier, effort and `about` line, rows, decisions, `ask`, `askTier`), 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), `askTier` (overrides routing.json's `askTier` on that machine; `best` or `false`, any other value reads `best` and is said once). 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. Limits: a main-loop switch re-reads cold the part of the context the target model's cache does not hold; a switch whose cold read is over its cap (`upgradeMaxTokens` up, `downgradeMaxTokens` down) is skipped (a `/model` hand pick is exempt) and main keeps its model, and a downgrade also needs `mainModelSwitch`. The prompt estimate is conservative (3 code points per token), so a long pasted prompt can hold back a switch that would have fit. The `/config` Model row still writes user `settings.json` with no scope question; a hand pick is dropped at `/clear`; a scope dialog never answered has no timeout. The hooks send full model ids, so the `models` table has to follow new model versions. A probe costs one small completion per model main runs on, the session's own model included, repeated only after that model is marked down, and holds that step up to 8 seconds when the model does not answer. diff --git a/lib/effort-shift.md b/lib/effort-shift.md index 1bbdfa3..26bed0c 100644 --- a/lib/effort-shift.md +++ b/lib/effort-shift.md @@ -89,8 +89,9 @@ back; the window guard needs a `windows` entry (none shipped). A typed - First use of a row asks once, with context (Later, Keep or Change: model, then effort, then Everywhere or this project only); the answer is kept in `mods/model-router/routing.json`. `/route pending` lists what is still - unconfirmed, `/route ask off|on` toggles the dialog, `/route forget - <name|all|projects>` takes a decision back. + unconfirmed, `/route ask off|on` toggles the dialog, `/route ask-tier + off|on` the ask before a route lifts main or a rowed agent onto Fable, + `/route forget <name|all|projects>` takes a decision back. Measure the split any time: `python3 ~/.claude/lib/effort-audit.py` (thinking/output/cache tokens per scope, model and effort). From 19dc1da424ebb8c7cd8ba8cafd0dde649459f4d3 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Mon, 2 Nov 2026 16:30:56 +0100 Subject: [PATCH 3/3] =?UTF-8?q?chore(memory):=20router=20ask-tier=20?= =?UTF-8?q?=E2=80=94=20BDR-135,=20LRN-254/255,=20EVAL-055,=20journal;=20co?= =?UTF-8?q?ntract=20+=20plan=20r3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/memory/decisions.md | 9 + .claude/memory/evals.md | 7 + .claude/memory/journal.md | 1 + .claude/memory/learnings.md | 10 + .../2026-11-02-router-ask-tier-1434.md | 59 +++ .../plans/2026-11-02-router-ask-tier-1434.md | 392 ++++++++++++++++++ 6 files changed, 478 insertions(+) create mode 100644 .claude/tasks/contracts/2026-11-02-router-ask-tier-1434.md create mode 100644 .claude/tasks/plans/2026-11-02-router-ask-tier-1434.md diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index 038fbe0..9e0a1af 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -1470,3 +1470,12 @@ Branch feature/user-writing-web-rules, UNMERGED (human gate). - **Accepted risks**: `cc.sh` keeps `set -a; . ~/.claude/.env` (all secrets in the claude env, as `dtach_claude` did); `deniedMcpServers` union = `cc x web` on a `dev` project keeps the connectors denied (`set web` in the project fixes it). - **Branch**: feature/phase5-profiles-packs; spec docs/superpowers/specs/2026-11-01-phase5-profiles-packs-design.md; contract .claude/tasks/contracts/2026-11-01-phase5-profiles-packs-1300.md. Supersedes [[BDR-030]]. + +## BDR-135 — model-router askTier: consent before Fable, tier-name choice stamped on turn and run slots, per-type spawn memory [accepted] (2026-11-02) +- **Context**: user ask 2026-11-02: model-router must ask before routing main or a rowed spawn onto Fable. feature/router-ask-tier, contract `.claude/tasks/contracts/2026-11-02-router-ask-tier-1434.md`, plan r3 after 3 lenses + confirmation. +- **Decision**: `routing.json` `askTier` (`best` | `false`, machine override wins, absent = best, missing file = off, bad value logged once + best). Ask fires at route EVENTS only (typed or model-loaded rowed skill, main `route` tool phase, typed `/route <phase>`, rowed spawn from main), never in turn.step (LRN-231). Guards: router on, not paused, cur not head, `asking` free, slot unstamped, slot tier = best, slot = effective `mainModelSlot`, surfaces non-empty, then real decision via `snapshot`/`decideMain` lands on head. Options `Fable` · `Opus instead (big tier)` (dropped when opus down) · `Stop asking this session`. Choice = TIER NAME on `Routed.tierChoice` (`best` | `big`), stamped on turn slot AND run slot; inherited only same-tier, non-typed writes (typed skill = new span, work route never inherits). `big` resolves minus head (opus, else sonnet, head last), phase effort (no stand-in notch). Spawns: one answer per agent type per session (`State.tierSpawn`), stored answer applied before any guard. `/route ask-tier on|off` via `flagCommand` (shared with `ask`); `/route show` `ask-tier:`. Nothing written to `confirmed`. +- **Why**: Fable credits burn on best-tier rows (BLK-030/031); user wants consent per span, not per spawn (audit gates respawn verifier + security-auditor each loop). +- **Alternatives rejected**: stand-in rewrite (`isStandIn` keyed on held head, would print "stands in for" on a user pick); rebuilt decision from parts (diverges from `decideMain`: sticky slot, mainUpgrade off, cap); per-spawn ask (blocking dialog, no timeout, stalls unattended orchestration); generated labels from aliases (contract fixes the exact words); any tier name in `askTier`; `{ model: alias }` on spawn (explicit model bypasses breaker). +- **Residual (user-accepted, F)**: Fable held or cap exceeded at the route event → no question, slot unstamped; hold lapse / compaction → next step upgrades unasked (breaker behaviour today). `/model <x>` while any dialog holds `asking` falls to native (pre-existing, BDR-126). +- **Gates**: r1 correctness FATAL(6) robustness FATAL(6) simplicity CONCERNS(4) → r2 → confirmation CONCERNS(6) → r3; feater DONE 28 TIER tests (590 → 618); GATE 0 MET 5/5; verifier CONFORME 11/11 first pass; security PASS (1 LOW fixed: `clean(skill)`). Commits 9a24a62, docs 789fd00. +- **Refs**: [[BDR-116]], [[BDR-123]], [[BLK-032]], [[LRN-231]], [[LRN-242]], [[LRN-254]]. diff --git a/.claude/memory/evals.md b/.claude/memory/evals.md index 0355323..82e4dbf 100644 --- a/.claude/memory/evals.md +++ b/.claude/memory/evals.md @@ -426,3 +426,10 @@ Dogfood: 3 blind lenses attacked the v1 plan for the plan-challenge feature itse - **Result**: r1 FATAL(11)/FATAL(10)/CONCERNS(5): BLOCKER = plan written on a stale tree (profile backend live); 30 jq per statusline refresh; settings.json procedure that would have discarded user writes; test precedence inverted; doctor abort under pipefail; worktree incompatibility. Confirmation on r2: 2 more BLOCKERs (keep list dropped the tracked `skills/model-router` link; census matched itself). All fixed before Task 1. Execution then needed 4 fix rounds (gates/reviews), none on those aspects. - **Anomalies**: the simplicity lens duplicated two robustness findings; the confirmation pass still found BLOCKERs, so one pass is the floor, not the ceiling. - **Action**: keep the 3+1 shape for plans over ~1000 lines; add "live state verified at Task 0" to the plan template. + +## EVAL-055 — BDR-125 phases 0/1/4a/5 re-verified: gates, SHAs, engine; 0 code defect, 5 stale TODO ticks [keep] (2026-11-02) +- **Checked**: BDR-125 phases ticked in TODO (pre-0, 0, 0b, 4a + minors, 1 + follow-ups, 5) vs original ask (TODO entry, contract REQUEST/CLARIFICATIONS, BDR). +- **Method**: `gates.sh run` on 5 contracts; 22 in-repo SHAs `merge-base --is-ancestor develop`; 9 cross-repo SHAs `cat-file -e` + `branch --contains` in zenquality/game/angelscar356/faunosteo/robin_petier; `reconcile.sh` engine (`reconcile_blk_open`, deferrals, contradiction candidates); direct fs probes (`~/.claude.json` mcpServers, `~/.claude/projects/*/memory/`, v2 markers, `## Index` count, profile NAME_RE, 21st CLI present + suite green). +- **Result**: 0 code defect. Gates: 3 MET, phase 0 UNMET(1), phase 1 UNMET(2), all oracle drift from later gated commits (LRN-255). TODO: 5 done-but-open (proof, mcp remove, auto-memory dirs, profile charset, design-tool-gate hermetic) + BLK-021 TMPDIR resolved by cc.sh + phase 5 follow-up lump (1 of 3 done). Reconcile: open BLK 001/003/017/018/022/029 all known upstream/deferred; 8 flag-overlap contradiction candidates, none real. +- **Anomalies**: `gates.sh run` dirtied two merged contracts (restored by checkout); TODO line 74 and BDR-134 cite purged spec/plan paths (BDR-065 purge); compound Bash with `git config`/`git diff settings.json` denied by permission rules (split calls). +- **Action**: chore/todo-reconcile-bdr125 e58a617 (5 ticks, split follow-ups), merge on user signal. LRN-255. diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index 24c430f..78ef07a 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -684,3 +684,4 @@ rules: ## 2026-11-02 - phase 5 profiles+packs shipped on feature/phase5-profiles-packs (13 tasks SDD, 3-lens challenge, gates MET/CONFORME/PASS after 3 passes): 9 packs, 9 profile fragments, profile.sh one-jq current --plain, cc <name> [profile], census; BDR-134, LRN-248..253, BLK-039/040, EVAL-054; TODO: router ask-before-Fable queued +- BDR-125 re-verification (gates x5, 31 SHAs, reconcile engine): 0 code defect, 5 done-but-open ticks → chore/todo-reconcile-bdr125 e58a617 (merge on signal); EVAL-055, LRN-255. /feat router-ask-tier (feature/router-ask-tier): plan r1 FATAL x2 → r3, feater 28 TIER tests, GATE 0 MET, verifier CONFORME 11/11, security PASS (1 LOW fixed); 9a24a62 + docs 789fd00; BDR-135, LRN-254. Merge on signal. Next: phase 2 guards via /ship-feature. diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md index 33fda44..3dffb62 100644 --- a/.claude/memory/learnings.md +++ b/.claude/memory/learnings.md @@ -1911,3 +1911,13 @@ Rule: when editing a doctrine file under structure locks, grep the test's lock s - **Pattern**: commit a change to a tracked file whose working copy carries uncommitted writes you must keep (settings.json UI writes): `git show HEAD:f | jq '<edit>' > tmp && git update-index --cacheinfo 100644,"$(git hash-object -w tmp)",f && git commit`, then patch the working copy with jq into a temp file and `cp` it back. Never `git checkout -- f`, never `git stash` (pop can take someone else's stash), never `git add -p` (interactive, unavailable), never `jq … > f` (truncates on failure). - **Context**: phase 5 Task 13 listing budget; BLK-039. - **Apply**: any commit to settings.json or another file the harness writes to. + +## LRN-254 — A route-event dialog stamps every slot the event armed; trace slot lifecycle before storing a choice (2026-11-02) +- **Pattern**: a dialog answered at a route event must stamp EVERY slot the event armed, not the one in hand. `armTypedSkill` → `routeMainBySkill` derives `runMain = { ...turn }` BEFORE `confirmSkill` runs; a choice written on `turnMain` after dies at `endMainTurn` (turnMain nulled), run falls back to the choice-less runMain → "Opus instead" lasted one turn. Three blind lenses (correctness, robustness, simplicity) hit the same BLOCKER on plan r1. +- **Context**: feat router-ask-tier plan r1 → r2, `mods/model-router/hooks/register.ts` (`routeMainBySkill` ~3485, `confirmSkill` ~2984, `endMainTurn` ~4042). +- **Apply**: before storing state on a slot, trace its lifecycle: who writes it, who copies it (spread = snapshot, not link), who nulls it, who outranks it (`mainModelSlot` precedence). Stamp the asked slot + the derived one; inherit only same-tier, non-typed. Read the real decision (`snapshot`/`decideMain`) instead of rebuilding it from parts. + +## LRN-255 — gates.sh run rewrites contract evidence; re-audit of merged contracts: attribute drift by git log -S, then restore (2026-11-02) +- **Pattern**: `bash lib/gates.sh run <contract>` REWRITES the `EVIDENCE:` lines of the contract file. Re-running a merged contract's gates for an audit: (1) oracles frozen on a base SHA (`c1-*.sh` vs develop 017a28b) read NOT-MET on later GATED changes (phase 5 added a pack-extras line to `rules/web-building.md`; 3330f0b restored "(dispatcher applies)" → 209/205 chars; 7899670 dropped `memory:`), (2) a CHECK string pinned to a test name goes stale after a review rename (`T10h-no-jq-rc0` → `T10h-empty-path-rc0`, 0b59687). Neither is a repo defect. +- **Context**: 2026-11-02 BDR-125 re-verification, 5 contracts re-gated: phase 5 / memory v2 write / minors MET, phase 0 UNMET(1), phase 1 UNMET(2), all explained by `git log -S`. +- **Apply**: on a re-audit, run gates, attribute each NOT-MET with `git log -S'<text>' -- <file>` to a gated commit, then `git checkout -- <contract>` to keep the ship-time evidence (historical record). Never commit re-run evidence over a merged contract. diff --git a/.claude/tasks/contracts/2026-11-02-router-ask-tier-1434.md b/.claude/tasks/contracts/2026-11-02-router-ask-tier-1434.md new file mode 100644 index 0000000..096d58a --- /dev/null +++ b/.claude/tasks/contracts/2026-11-02-router-ask-tier-1434.md @@ -0,0 +1,59 @@ +# CONTRACT — router-ask-tier +- date: 2026-11-02 | flow: feat | branch: feature/router-ask-tier (to be started off develop) +- status: active + +## REQUEST (verbatim — IMMUTABLE) +/feat « model-router : demander avant de router vers Fable ». La spécification est l'entrée en tête du TODO : +- clé askTier, `/route ask-tier on|off` ; +- une question par span, avec la raison (phase et about, origine) ; +- options : Fable, Opus à la place, ne plus demander cette session ; +- jamais de question en -p. + +(user, 2026-11-02, step 2 of the session brief. The TODO entry it points at, `.claude/tasks/TODO.md` line 73 at develop 3cc4e0d:) +- [ ] **model-router: ask before routing to Fable** (user ask 2026-11-02, after the phase 5 merge: both touch `mods/model-router/routing.json`). `/feat` on the mod: a `routing.json` key `askTier` (default `best`; `/route ask-tier on|off`) makes the router ask, once per span, BEFORE applying a route whose resolved model sits in that tier, with the reason (phase + its `about`, origin: skill row / `/route` / prompt rule / agent row) and the options `Fable` · `Opus instead (big tier)` · `stop asking this session`; no memory in `confirmed` (the existing first-use confirmation stays as is); never asks in `-p` (`askOr` already falls back to LATER). Files: mods/model-router/hooks/register.ts (+ register.test.ts), routing.json, USAGE.md (`/route` section). + +Session constraints (same brief): default model opus; verifier, security-auditor and plan-challengers pinned on opus; never commit a `/model` or UI write of settings.json (LRN-253); plan text through Write/Edit, never a nested heredoc (BLK-039). + +## CLARIFICATIONS +Pass A (gaps): none blocking — outcome, scope and constraints are in the TODO entry. Facts verified in the code before the plan: +- "resolved model sits in that tier": `best` = [fable, opus, sonnet] (DEFAULT_CONFIG.tiers), so opus also "sits in" best. Read as: the resolved model is the HEAD of the `askTier` tier (`tiers[askTier][0]`, fable), and the loop or agent is not on it already. +- prompt rules write effort-only routes (BLK-032 / 786ee13): they never resolve a model, so that origin never asks today; the plan keeps the origin word for a rule that would one day carry a tier. +- `askOr` returns LATER on a rejected `$.ui.ask` (headless `-p`, no surface, dismissed dialog): the plan maps LATER to "apply the route as today" (fable), nothing blocked. +Pass B `[gated 2026-11-02]` (user: "défauts partout", plan r3 § Pass B): A. a dismissed dialog (Esc / free text) runs the span on Fable and is not asked again in that span; B. a best-tier skill the model loads on main asks too (skill row, BDR-123); C. sub-agents: one answer per agent type per session; F. held-head residual accepted (no question when Fable is held or the cold read is over the cap at the route event; a later lapse of the hold upgrades main unasked, today's breaker behaviour, documented in USAGE); D. "Opus instead" runs the phase's own effort; E. `askTier` accepts `best` or `false` only. Plan r3 approved for dispatch. +Executor deviations `[gated 2026-11-02, internal, orchestrator]`: (1) the invalid-`askTier` log is emitted by `warnAskTier(st, log)` from `applyLoaded`, deduped through `st.logged` (buildMemory has no state; AC1 "once per session" holds); (2) the derived `orchestrate` route (`pushOrchestrate`) inherits the span's `tierChoice` like any same-run helper slot, so a dispatch after "Opus instead" never lifts main unasked; (3) `inheritedChoice` takes the first of [turnMain, runMain] holding a choice for the same tier (a choice-less derived slot does not hide the run's); `failOnce` shares a `logOnce` helper with `tierFailOnce`; `routedTo` is `phaseWord` plus its prefix. + +## ACCEPTANCE CRITERIA +1. `routing.json` carries a top-level `askTier` key (shipped value `"best"`), serialized after `ask` (ROUTING_ORDER); the machine override `~/.claude/model-router.json` `askTier` wins over it like `ask`; accepted values `"best"` and `false` (r2: other tier names are out of scope, the option labels are the user's exact words); an absent key reads `best` silently, a missing or unreadable routing.json reads off, any other value is logged once per session and read as `best` (asking is the safe side). + CHECK: cd /home/bchanot/Documents/claude && jq -e '.askTier == "best"' mods/model-router/routing.json >/dev/null && grep -q "'ask', 'askTier'" mods/model-router/hooks/register.ts && echo ASKTIER-KEY-OK + EXPECT: ASKTIER-KEY-OK + EVIDENCE: MET exit=0 marker-found :: ASKTIER-KEY-OK +2. Main loop: when a route is set on main by a rowed skill (typed, or loaded by the model through the Skill tool), a main-loop `route` tool call with a phase, or a typed `/route <phase>`, and the real decision (`decideMain`, as `snapshot` reads it) would move the main loop onto the head model of the `askTier` tier from a model that is not it, one `$.ui.ask` opens BEFORE the route takes effect at the next step (for `/route`, the sticky slot is assigned only after the answer), with: the origin (`Skill /<name>`, `Route tool`, `/route`), the phase and its `about` line, the head id and the effort the step would run; options exactly `Fable`, `Opus instead (big tier)`, `Stop asking this session` (the second dropped when opus is marked down: the label must be true when answered). No question when the decision would not land on the head (`mainUpgrade` off, cold-read cap, window, held head), when the slot is not the effective one (a sticky route outranks it), when the route names an explicit model (`/route model=…`, `/model` hand picks), from the prompt classifier, or when `$.session.surfaces()` is empty (headless, `-p`). +3. Answers: `Fable` applies the route as today. `Opus instead (big tier)` makes the span resolve through the `big` tier minus the head (opus; sonnet only as the mid-span fallback when opus goes down later; the head only when nothing else is up) at the phase's own effort (no stand-in notch); the choice is a tier name on the slot (`Routed.tierChoice`), stamped on the turn slot AND the run slot the event armed and inherited by every later main route of that run that names the same tier (a work or cheap route never inherits it; a typed rowed skill opens a new span and asks again), so a run asks once and survives the turn end; `/route show` names the choice. `Stop asking this session` silences the ask until the session ends (`resetSession`; `/clear` re-arms), nothing written. A dismissed dialog or a free-text answer applies the route as today and stamps the span (not asked again in that span); an answer arriving after `$.session.id()` changed is dropped. +4. Sub-agents: a rowed spawn from main (no explicit `model`, not inside an agent, not a fork or workflow) whose resolved target is the head model asks the same question with origin `Agent <type>`, once per agent type per session (`State.tierSpawn`, cleared with the session); `Opus instead (big tier)` spawns it on the first non-head model of `big` that is up (resolved at each spawn); the first-use dialog, when it fires on the same spawn, runs first and the tier ask runs whatever it returned. Never inside an agent, never headless. +5. One dialog at a time: the ask holds the existing `asking` slot; a concurrent use finds it set and routes unasked (fable), like the first-use dialog. +6. `/route ask-tier on|off` writes `askTier` (`"best"` / `false`) into routing.json through `writeRouting` (serialized, capped, refused when the file is missing), answers `ask-tier on|off` with the override note when the machine file wins; any other argument answers `usage: /route ask-tier on|off`; `/route show` prints `ask-tier: best|off` plus ` (paused this session)` after a Stop answer; the `/route` argument hint names `ask-tier on|off`. +7. Nothing is written to `confirmed`, `changed` or `projects` by this dialog; `/route pending` and the first-use dialog are unchanged (their tests stay green). +8. Tests in `mods/model-router/hooks/register.test.ts` (fixture default `askTier: false`, opt-in per test like `ask`) cover the plan's D7 list: question text and exact options on a typed skill from an opus session; `Fable` → fable; `Opus instead` → opus at the phase effort, no second ask on a later route-tool call, still opus after the turn end; `Stop asking` → silent + `show` paused; already on fable → no ask; headless (no surface) → no ask; dismissed → fable, span not re-asked; route tool main asks, `agentId` does not; `/route plan` asks and assigns after the answer, `/route model=fable` does not; sticky `/route model=opus` → no ask; `mainUpgrade` off → no ask; opus down → two options; model-loaded `Skill` on main asks; rowed spawn (verifier on audit) asks once per type, `Opus instead` → opus spec, explicit model and nested spawn never ask, a work-tier spawn never asks; first-use then tier ask on one event with the outcome asserted; `asking` held → unasked; `/route ask-tier off|on` writes and silences, bad arg → usage, override wins note; invalid value logged once and read as best; absent routing.json → no ask; the existing `/route ask` and key-order tests stay green with `askTier` added to the order. + CHECK: cd /home/bchanot/Documents/claude && for n in 'ask-tier' 'Opus instead (big tier)' 'Stop asking this session' 'paused this session'; do grep -qF -- "$n" mods/model-router/hooks/register.test.ts || exit 1; done && a=$(make test suite=lib/tests/mods.test.sh 2>&1) && printf '%s\n' "$a" | grep -q 'all suites green' && echo MOD-TESTS-OK + EXPECT: MOD-TESTS-OK + EVIDENCE: MET exit=0 marker-found :: MOD-TESTS-OK +9. The repo suites that read routing.json stay green (`lib/tests/model-routing.test.sh`, `lib/tests/effort-routing.test.sh`, `lib/tests/doctrine-citers.test.sh`); `make test` all suites green. + CHECK: cd /home/bchanot/Documents/claude && t=$(make test 2>&1) && printf '%s\n' "$t" | grep -q 'all suites green' && echo MAKE-TEST-OK + EXPECT: MAKE-TEST-OK + EVIDENCE: MET exit=0 marker-found :: MAKE-TEST-OK +10. Docs: USAGE.md `/route` row and the model-router paragraph name `ask-tier on|off` and the question (one sentence each); the code's own comment block "first use" gains the ask-tier rule. README.md and CHANGELOG `[Unreleased]` follow through the doc-sync step. + CHECK: cd /home/bchanot/Documents/claude && grep -q 'ask-tier' USAGE.md && echo USAGE-OK + EXPECT: USAGE-OK + EVIDENCE: MET exit=0 marker-found :: USAGE-OK +11. settings.json is untouched by the branch (no UI write, no `model`), the contract and plan ride the memory commit. + CHECK: cd /home/bchanot/Documents/claude && [ -z "$(git diff develop...HEAD --stat -- settings.json)" ] && echo SETTINGS-UNTOUCHED + EXPECT: SETTINGS-UNTOUCHED + EVIDENCE: MET exit=0 marker-found :: SETTINGS-UNTOUCHED + +## FILE SCOPE +- mods/model-router/hooks/register.ts +- mods/model-router/hooks/register.test.ts +- mods/model-router/routing.json (`askTier` key only) +- USAGE.md (`/route` row + model-router paragraph) +- README.md, CHANGELOG.md through STEP 6 doc-sync only +- .claude/tasks/contracts/2026-11-02-router-ask-tier-1434.md, .claude/tasks/plans/2026-11-02-router-ask-tier-1434.md (run artifacts, memory commit) diff --git a/.claude/tasks/plans/2026-11-02-router-ask-tier-1434.md b/.claude/tasks/plans/2026-11-02-router-ask-tier-1434.md new file mode 100644 index 0000000..7dd433c --- /dev/null +++ b/.claude/tasks/plans/2026-11-02-router-ask-tier-1434.md @@ -0,0 +1,392 @@ +# /feat router-ask-tier — PLAN r3 (2026-11-02) + +r3 after the confirmation pass on r2 (correctness CONCERNS(6), no BLOCKER). +Named changes: inheritance of a choice only between slots of the SAME tier +and only for helper (non-typed) writes, so a typed run is a new span and a +work route never inherits 'big'; `tierAsk` writes on the real `st` and +reads a probe view (the `/route` path); "Opus instead" is offered only when +opus itself is up, sonnet is the mid-span fallback only; a stored per-type +spawn answer is applied BEFORE any ask guard and the spawn dialog holds +`asking`; `isStandIn` is false on a 'big' span; the pure `cur !== head` +guard runs first; question texts drop the "Routed to" prefix; `tierWord` +names a 'big' span; `flagCommand` takes one descriptor; the "first use" +comment block and the `asking` field comment are the ones edited; three +key-order assertions; the held-head lift (fable held at the route event, +hold lapses later) is a residual put to the gate (pass B F). + +r2 after 3 lenses on r1 (correctness FATAL(6), robustness FATAL(6), +simplicity CONCERNS(4)). Unanimous BLOCKER: r1 wrote the answer on +`turnMain` after `armTypedSkill` had already derived `runMain`, so "Opus +instead" lasted one turn and a run re-asked. r2 changes: the choice is a +TIER NAME stamped on every slot the event armed (turn + run), resolution +goes through `resolveName` (no stand-in rewrite), the ask reads the real +decision (`snapshot` / `decideMain`) instead of rebuilding it, a 4th call +site covers model-loaded best-tier skills, spawns remember one answer per +agent type per session, the "instead" option is offered only when its +model is up and never falls back onto the head, headless is guarded by +`$.session.surfaces()`, `/route <phase>` assigns after the answer. +Pass-B choices are listed at the end; defaults taken are marked (default). + +FEAT: model-router asks before a route lifts the main loop, or sends a rowed +spawn, onto Fable — rule 7, 4 files (register.ts, register.test.ts, +routing.json, USAGE.md), README/CHANGELOG through doc-sync. +Contract: `.claude/tasks/contracts/2026-11-02-router-ask-tier-1434.md`. + +## Facts (verified in `mods/model-router/hooks/register.ts` at develop 3cc4e0d) +- Tiers (DEFAULT_CONFIG ~283): `best` = [fable, opus, sonnet], `big` = + [opus, fable, sonnet]. "Resolved model sits in that tier" = resolves to the + HEAD of the `askTier` tier (`tiers.best[0]` → `models.fable`). +- Main-loop route writers: `routeMainBySkill` (~3485; typed via + `armTypedSkill` 3537 in skill.prompt 4254, BEFORE `confirmSkill` 4259; + model-loaded via `onSkillLoad` 3502 in tool.call Skill 4242), `applyRoute` + (route tool, ~3395), `setUserRoute` (`/route`, 2019; `/route` is + `immediate: true`, 3370: it runs mid-turn). `mainModelSlot` (1466) = + userMain ?? turnMain ?? runMain; `wantedModel` (1547) resolves its tier; + `decideMain` (1445) is the ONE decision "used by the step and every text"; + `snapshot` (1922) = `decideFor` on `turnModel ?? sessionModel`. +- `endMainTurn` (4042) nulls turnMain; `userMovedEffort` (3976) nulls it + mid-turn; `resetSession` (1043) keeps `asking` but NOT `asked`. +- Dialogs render in skill.prompt (T1), tool.call (`confirmPhase`, + route tool; the Skill tool.call hook is the same hook kind), agent.spawn + (T2) and command.run (`/model`, LRN-243); never in turn.step (LRN-231). + `askOr` (2532) → LATER on a rejected ask; the `/model` paths guard first on + `$.session.surfaces()` empty (2409, 2472); `askStep` (2684) maps Later / + unrecognised / headless. `pickerDialog` checks `$.session.id()` before + applying a late answer (`stillHere`, ~2452). +- `confirmSkill` (2984) returns early when `confirmFirst` is false, and + re-runs `routeMainBySkill` (2990) when it is true. `routeSpawn` (2996) + returns the route from a ternary on `confirmFirst`. +- `resolveName` (1135): a tier skips down aliases then walks the chain; an + alias/id is explicit and never skipped. `availableIn` (1115). + `spawnTarget` (3630) → `inTier` picks the first alias not down at or above + the tier's head; an explicit `e.model` wins; `routeSpawn` already returns + early for frozen / unrowed / inside spawns. +- `askCommand` (3041) + `writeRouting` (2865) is the `/route ask` writer; + ROUTING_ORDER (189) is 74 columns: appending `'askTier'` needs a wrap. +- `buildMemory` (790) takes no cfg; callers `assemble` (939) and + `refreshMemory` (2527). `assemble` logs "routing.json missing; … no asks" + and uses `emptyMemory()`. +- Prompt rules and the classifier write effort-only routes (BLK-032): they + never resolve a model, so never ask; the classifier writes only when no + route is in force (`classifierIdle`), so it never reaches a call site. + +## Design +### D1 config, memory, state +- routing.json: `"askTier": "best"` after `"ask": true`. `ROUTING_ORDER` + gains `'askTier'`: the line is rewrapped as `'phases', 'skills', 'agents', + 'projects', 'confirmed', 'changed',` / `'ask', 'askTier',` (≤ 80 cols). +- `Memory.askTier: unknown` (raw file value, absent = undefined) and + `Memory.askTierLocal: unknown` (override). `buildMemory` copies both raw, + no new parameter. `emptyMemory()` → `askTier: false` (no file = no ask, + matching the "no asks" load log). +- `tierHead(st): string | undefined` — the one reader: value = + `st.mem.askTierLocal ?? st.mem.askTier`; `undefined` → `'best'` silently; + `false` → undefined (off); `'best'` → `st.cfg.models[st.cfg.tiers.best[0]]`; + any other value → `best`. The validation log line `model-router: askTier + must be "best" or false; read as best` is emitted by `buildMemory` + through its `log` parameter (live at `assemble`, silent at + `refreshMemory`), the same way `aboutOf` logs an overlong `about`: once + per config load, never on the hot path. (Default E: other tier names are + out of scope — the labels are the user's exact words.) +- `headId(st)` = `st.cfg.models[st.cfg.tiers.best[0]]` (the head whatever + the key says; used by `insteadName` so a span keeps avoiding fable after + `/route ask-tier off`). +- `State` gains `tierPaused: boolean` (Stop; `newState` false; NOT in + `resetSession`'s kept list → /clear re-arms) and `tierSpawn: Map<string, + Choice>` (agent type → answer; not kept either). +- `Routed.tierChoice?: Choice` where `type Choice = 'best' | 'big'` — the + TIER the span resolves through: `'best'` = Fable accepted (or Later / + Stop / headless), `'big'` = Opus instead. Constants `TIER_HEAD = 'Fable'`, + `TIER_INSTEAD = 'Opus instead (big tier)'`, `TIER_STOP = 'Stop asking this + session'`, `INSTEAD_TIER = 'big'` next to LATER/KEEP/CHANGE (192). + +### D2 resolution of a chosen span +- `wantedModel` (1547): `const name = slot.tierChoice === 'big' && + slot.route.tier === BEST ? (insteadName(st) ?? routeName(slot.route)) : + routeName(slot.route)`. `insteadName(st)` = `availableIn(st, + tiers.big.filter(a => models[a] !== headId(st)))` → the first non-head + alias of `big` that is up (opus, else sonnet); `undefined` only when + nothing but the head is up → the normal tier resolution (the span runs, + on whatever the breaker leaves; silent: the status line and `show` name + the model). Otherwise never the head: the model the user declined is not + the fallback of their refusal. +- Offer rule (one rule everywhere, D3/D5/AC2/AC8/test 11): the `Opus + instead` option is offered only when `models[tiers.big[0]]` (opus) is not + down — the label must stay true at answer time; sonnet is only the + mid-span fallback when opus goes down later. +- Effort: the phase's own (default D). `isStandIn` (1670) gains one guard: + `mainModelSlot(st)?.tierChoice === 'big'` → false (a chosen opus is not a + stand-in: no notch, no "stands in for" text). `standInEffort`, + `standInWord`, `heldHead` otherwise unchanged. +- Inheritance (`applyRoute` 3395 and `routeMainBySkill` 3485 for a + model-loaded skill, `typed === false` only): the new turnMain copies + `tierChoice` from the slot it replaces (`st.turnMain`) or else from + `st.runMain`, ONLY when `prev.route.tier === new.route.tier`. A typed + rowed skill (`typed === true`) never inherits: it opens a new span, so a + typed `/bugfix` after an answered `/feat` run asks again, and a work or + cheap route (`route phase=implement`, `gitflow`) never carries 'big'. + `routeMainBySkill` copies the turn's `tierChoice` into the run slot it + derives (the spread does it once the field is on `turn`). +- `tierWord` (1866): a slot with `tierChoice === 'big'` prints `[tier big + (instead of best)]` so `/route show` names the span's choice. + +### D3 when to ask (main loop) — `tierAsk($, st, slot, origin, view = st)` +`st` is the real state (every write: `asking`, `tierPaused`, `logged`); +`view` is the state the decision is read from (`st` everywhere except the +`/route` path, D4.4, where it is the probe copy). Pure cheap guards first, +in this order, all required: `!st.off`; `head = tierHead(st)` defined; +`!st.tierPaused`; `canonical(st.turnModel ?? st.sessionModel) !== head` +(main already on fable: a helper Skill inside a fable run costs nothing); +`st.asking === null`; `slot.tierChoice === undefined`; `slot.route.tier === +BEST` (an explicit `model` route never asks: `/route model=fable`, `/model` +hand picks; another tier never resolves to the head unless opus is held, +and then the breaker already decided); `slot === mainModelSlot(view)` (a +sticky slot that outranks it decides, not this one). Then the two awaits: +`(await $.session.surfaces()).length > 0` (headless asks nothing, like +`/model`), and `v = await snapshot($, view)`; ask only when +`canonical(v.call.model) === head` (so `mainUpgrade: false`, the cold-read +cap, a window miss or a held head → no question, nothing to decide; the +slot stays unstamped, see pass B F). +- The dialog holds `st.asking = 'tier:main'` (finally null) and records + `sid = await $.session.id()` first; an answer arriving after `$.session. + id()` changed (a /clear) is dropped. +- Text (main): `${origin} routes main to ${phaseWord(st, slot.phase)}: + ${idWord(st, v.call.model)} at ${effortWord(view, v)}. Run it on fable?` + where `phaseWord` = `phase` + ` (${about})` when `aboutLine` is set (the + body of `routedTo` without its "Routed to" prefix; `routedTo` calls it); + origin ∈ `Skill /feat` (typed or model-loaded), `Route tool`, `/route`. + Options: `[TIER_HEAD, TIER_INSTEAD, TIER_STOP]`, or `[TIER_HEAD, + TIER_STOP]` when opus is down (offer rule, D2). Answers via `askStep` + (Later / unrecognised / rejected → undefined): `TIER_HEAD` or undefined → + stamp `'best'`; `TIER_INSTEAD` → stamp `'big'`; `TIER_STOP` → + `st.tierPaused = true`, stamp `'best'`. (Default A: a dismissed dialog + stamps the span.) +- Stamp = write `tierChoice` on `slot` AND on `st.runMain` when + `st.runMain !== null && st.runMain.route.tier === slot.route.tier` + (the run derived from this event, or the run this route serves). After + a `'big'` stamp, `refresh($, st)` so the status line follows. +- Fail-open: everything inside try/catch; a throw logs once (`failOnce` + text pattern: `model-router: tier dialog failed (…); route kept`) and the + route applies as today. + +### D4 call sites +1. `confirmSkill` (typed rowed skill): restructured as `const changed = + await confirmFirst(...); if (changed) { re-route as today; toast }; await + tierAsk($, st, st.turnMain, `Skill /${skill}`)` — the tier ask runs on + both branches, after the re-route, so the stamp survives. +2. tool.call Skill on main (`registerSkills`, `e.agentId === undefined`): + after `onSkillLoad`, when `skillRow` exists → `await tierAsk($, st, + st.turnMain, `Skill /${skill}`)` (default, pass B B: a model-loaded + best-tier skill — brainstorming, writing-plans, requesting-code-review, + subagent-driven-development, writing-skills — is a skill-row lift, BDR-123). + Inside a run already on fable, the cheap guards end it at once (cur === + head), so helper skills cost nothing. +3. `handleRouteTool` main path: after `confirmPhase`, `await tierAsk($, st, + st.turnMain, 'Route tool')`. +4. `setUserRoute`: `parsed` is computed; `probe: State = { ...st, userMain: + parsed }` (the `wouldRunHead` pattern, read-only) is the `view` of + `tierAsk($, st, parsed, '/route', probe)`: guards and `snapshot` read + the probe, `asking` / `tierPaused` land on the real `st`, the answer + stamps `parsed`; THEN `st.userMain = parsed` (never assigned before the + answer: `/route` runs mid-turn and a step meanwhile would upgrade). + `show` follows. + +### D5 sub-agents — in `routeSpawn`, after its early returns and after the +first-use block (both branches of the ternary; `phase` re-read from +`st.cfg.agents[type]` after `confirmFirst`, a Change may have moved it) +Order: +1. Stored answer first, before any ask guard: `const kept = + st.tierSpawn.get(e.subagentType)`; `kept === 'big'` and the route is + best-tier → return `{ ...route, tier: undefined, model: insteadName(st) + ?? <route unchanged> }` (opus, else sonnet, never the head; re-resolved + at every spawn); `kept === 'best'` → return the route as is. A stored + answer applies whatever `tierPaused`, `asking` or the key say (like a + stamped main slot). +2. Ask guards: `tierHead` defined, `!st.tierPaused`, `st.asking === null`, + `e.parentAgentId === undefined`, `e.model === undefined`, `route.tier === + BEST`, `spawnTarget($, st, e, route)` is the head id, then surfaces + non-empty. (Default C: one answer per agent type per session: the audit + gates spawn verifier and security-auditor at every loop iteration, a + per-spawn dialog with no timeout would stall unattended orchestration.) +3. The dialog holds `st.asking = 'tier:agent:<type>'` (finally null), + records `sid` like D3. Text: `Agent ${type} runs ${phaseWord(st, phase)} + on ${head id} at ${explicitEffort.get(tool_use_id) ?? route.effort ?? + 'its own effort'}. Run it on fable?`; same options (instead dropped when + opus is down). Answer → `st.tierSpawn.set(type, choice)`, then step 1's + rule gives this spawn its route; Stop → `tierPaused` + `'best'` stored. + +### D6 command and show +- `handleCommand`: `case 'ask-tier': return flagCommand($, st, rest[0], + ASK_TIER_FLAG)` and `case 'ask': return flagCommand($, st, rest[0], + ASK_FLAG)` — `askCommand` generalized into `flagCommand($, st, arg, flag: + Flag)` with `type Flag = { word: string; key: string; value: (on: boolean) + => unknown; local: (m: Memory) => unknown }` (4 params): usage `usage: + /route ${word} on|off`, answer `${word} ${arg}`, override note `; + ~/.claude/model-router.json sets ${key} ${on|off} and wins here` when + `local(st.mem)` is defined. The `/route ask` strings locked by the + existing tests are unchanged. +- `registerCommand` argumentHint gains `ask-tier on|off`. +- `show`: router line gains ` · ask-tier: ${word}` with word `best` | `off` + | `best (paused this session)` (invalid value prints `best` too). +- Comments: the "first use" block (~2485) gains one sentence ("a route that + would lift main, or a rowed spawn, onto the head of `askTier` asks first: + Fable, Opus instead, or stop for the session; nothing written"), and the + `asking` field comment (line 122) reads "key of the one dialog in flight + (first-use or tier ask)". AC10 names the 2485 block. + +### D7 tests (register.test.ts) +Fixture: `baseRouting()` gains `askTier: false` (the fixture's `ask` +convention: no dialog by default); `Fixture.askTier?: 'best' | false`; +`asksTier(answers, fx?) = newWorld({ answers, askTier: 'best', ...fx })` +(first-use `ask` stays false unless a test sets it). The THREE key-order +assertions (test.ts ~2337, ~2408 reversed pre-write list, ~2414) gain +`'askTier'` at its place. A `verifier → audit` row and an `about` line on +`reflect`/`audit` go through per-test `edit:`. Tests, names `TIER:`: +1. typed /feat on OPUS, `edit` adds `phases.reflect.about = 'analysis'` → + one ask; text contains `Skill /feat routes main to reflect (analysis): + claude-fable-5-1 at high. Run it on fable?`; options equal exactly + `['Fable', 'Opus instead (big tier)', 'Stop asking this session']`. +2. `Fable` → next main step FABLE/high. +3. `Opus instead` → main step OPUS/high (phase's own effort, no notch); + then `$.tool.call route phase=orchestrate` in the same turn → no second + ask, step OPUS/medium; then `turn.complete` + a new turn's step → still + OPUS (run slot stamped); `/route show` main line contains `[tier big + (instead of best)]`. +3b. after `Opus instead`, `$.tool.call route phase=implement` → step SONNET + (a work route never inherits 'big'); a typed `/bugfix` (fixture row + `bugfix: 'reflect'`) after the answered `/feat` → a second ask (new span). +3c. fable marked down after an `Opus instead` answer → step stays OPUS at + high (no stand-in notch, no "stands in for" in `show`). +4. `Stop asking` → step FABLE; a second typed rowed best skill → no ask; + `/route show` contains `ask-tier: best (paused this session)`. +5. session already on FABLE → `w.asked` empty, step FABLE. +6. headless (`surfaces: []`) → `w.asked` empty, step FABLE (no REJECT + consumed); dismissed (`REJECT` answer with a surface) → step FABLE, a + later route-tool call of the span asks nothing. +7. route tool `phase: 'plan'` from main on OPUS → asks with `Route tool`; + with `agentId` → nothing. +8. `/route plan` → asks; the slot is set only after the answer (a step + recorded while the dialog is held — `gate` — stays OPUS); `Stop asking + this session` answered there → `tierPaused` real (a later typed /feat + asks nothing); `/route model=fable` → nothing, route set. +9. sticky `/route model=opus` then typed /feat → no ask (slot is not the + effective one), step OPUS. +10. `mainUpgrade: false` (home override) → typed /feat asks nothing, step + OPUS. +11. SONNET session, opus marked down (a `rate_limit` StopFailure charged + to OPUS through an earlier spawn), then typed /feat → the ask offers + `['Fable', 'Stop asking this session']` (instead dropped). +12. model-loaded skill: `$.tool.call Skill brainstorming` on main (row + `brainstorming: 'plan'` in the fixture edit) from OPUS → asks with + `Skill /brainstorming`; `Opus instead` → step OPUS/xhigh. +13. spawn: fixture `edit: f => { f.agents.verifier = 'audit'; + f.phases.audit.about = 'gates' }`, OPUS session, `spawnOf('verifier')` + → asks with `Agent verifier runs audit (gates) on claude-fable-5-1 at + xhigh`; `Opus instead` → `rig.specs` = [OPUS]; a second + `spawnOf('verifier')` → no ask, [OPUS] again; the same with a first-use + dialog held open (`gate`) on another type → still [OPUS], no second + dialog; `Fable` → [FABLE]; explicit `model` → no ask; nested + (`parentAgentId`) → no ask; `spawnOf('feater')` (work) → no ask. +14. first-use on (`ask: true`) + askTier: typed /feat with answers + `['Keep', 'Opus instead (big tier)']` → two asks in order (`First route + for /feat`, then the tier question) and the step is OPUS. +15. a dialog in flight (`gate` held on a first-use spawn ask) → a typed + rowed skill routes fable unasked. +16. `/route ask-tier off` → `routingOf(w).askTier === false`, typed /feat + asks nothing; `ask-tier on` → `'best'`; `ask-tier maybe` → `usage: /route + ask-tier on|off`, `w.written` empty; home `{ askTier: false }` → `/route + ask-tier on` answer contains `wins here` and no ask fires. +17. `edit: f => { f.askTier = 'work' }` → one ui.log line, the ask fires + (read as best); the line is not repeated on `/route reload`. +18. `routing: 'absent'`, OPUS session, `$.tool.call route phase=plan` on + main → no ask (emptyMemory false), route set. +19. `/route ask` tests unchanged and green (flagCommand refactor). + +### D8 docs +USAGE.md: `/route` row (173) gains `ask-tier on|off`; the model-router +paragraph (199) gains: before a route lifts the main loop, or sends a rowed +agent, onto Fable, the mod asks once per span (origin, phase and its +`about`, model and effort): `Fable`, `Opus à la place` (le tier big, effort +de la phase inchangé), `ne plus demander cette session` ; un skill chargé +par le modèle compte comme une ligne de skill ; une réponse par type +d'agent et par session ; jamais en `-p` ni dans un sous-agent ; la clé +`askTier` (`best` ou `false`) de `routing.json`, `/route ask-tier on|off`, +l'override machine gagne. README.md 144-146 + CHANGELOG `[Unreleased]` → +doc-sync STEP 6. + +## Plan (checklist, dispatch-ready) +- [ ] mods/model-router/routing.json — `"askTier": "best"` after `"ask": true`. +- [ ] register.ts — constants (TIER_*, INSTEAD_TIER, Choice), ROUTING_ORDER + rewrap, `Memory.askTier/askTierLocal` raw + `emptyMemory` false, + `State.tierPaused` + `tierSpawn` (not kept by resetSession), + `Routed.tierChoice`, `tierHead`, `insteadName`. +- [ ] register.ts — `wantedModel` branch (D2), inheritance in `applyRoute` + and `routeMainBySkill`. +- [ ] register.ts — `tierAsk` + `tierQuestion` + stamp (D3); call sites D4 + 1-4 (`confirmSkill` restructured, Skill tool.call on main, + `handleRouteTool`, `setUserRoute` assign-after-answer). +- [ ] register.ts — `routeSpawn` tier ask with `tierSpawn` memory (D5). +- [ ] register.ts — `flagCommand` (ask + ask-tier), `handleCommand` case, + argumentHint, `show` segment, header sentence (D6). +- [ ] register.test.ts — fixture + key-order assertions + TIER tests 1-19. +- [ ] USAGE.md — row + paragraph (D8). +- [ ] Executor runs `make test suite=lib/tests/mods.test.sh` and `make test`; + reports the first-use tests untouched and green. +- Style: new functions ≤ 25 logic lines, ≤ 5 params, 80 cols (the file keeps + 3 pre-existing long lines; add none). + +## Edge cases +- Opus held during a `'big'` span → `insteadName` → sonnet (never fable), + silently; opus back → opus again at the next step (resolution is per + step, like a tier). Opus AND sonnet held → the tier's normal resolution + (the span runs rather than stalls). +- RESIDUAL for the gate (pass B F): the ask fires at route events only + (a step cannot ask, LRN-231). When fable is HELD at the event (billing, + BLK-030/031) or the cold read is over the cap, no question fires and the + slot stays unstamped; when the hold lapses (`prune`) or a compaction + brings the context under `upgradeMaxTokens`, the next step upgrades main + to fable unasked. Alternative: treat an unstamped best slot as + `insteadName` until a route event asks (changes today's routing in the + held-head case: main would stay on opus after the hold lapses instead of + returning to fable). +- `[1m]`: comparisons on `canonical()`; `moveTo` carries the variant. +- `sessionModel === ''` cannot happen after session.start (4149 reads it); + if it does, `canonical('') !== head` → the decision decides (snapshot). +- Stop then `/route ask-tier on` → still paused this session (`show` says + so); `/clear` re-arms. +- A `/route forget` or first-use write never touches `askTier` + (serializeRouting keeps unknown keys; the key is in ROUTING_ORDER). +- Write failure of `ask-tier` → `failedWrite` text, like `ask`. +- Residual accepted (robustness 13): `/model <x>` typed while any dialog + holds `asking` falls to native (pre-existing path, BDR-126); not widened + by this feature beyond the dialog's open time. + +## Pass B (open choices, asked at the gate; defaults taken in r3) +A. Dismissed dialog (Esc / free text) → the span runs on Fable and is not + asked again (default) — or re-asked at the next route event of the span. +B. Model-loaded best-tier skill on main (brainstorming, writing-plans…) asks + too (default, BDR-123 "skill row") — or typed skills only. +C. Sub-agents: one answer per agent type per session (default) — or one + question per spawn. +F. Held-head residual (Edge cases): accept it (default: today's breaker + behaviour, documented) — or keep an unasked best slot off fable until a + route event asks. +Settled as defaults, not asked (internal or fixed by the request's words): +D. "Opus instead" runs the phase's own effort, shown in the question. +E. `askTier` accepts `best` or `false` only. + +## Disposition (STEP 0.6 RELATED MEMORY) +IN FORCE: BDR-116 (routing.json single source; `/route ask` writer; one +dialog at a time; never in `-p` or a sub-agent) — D1/D3/D6; BDR-123 / +BLK-032 (Fable on main only via skill row, route tool, `/route`, hand pick; +prompt rules effort-only) — D4 covers typed AND model-loaded skill rows, the +route tool and `/route <phase>`; BDR-126/127/132 (hand picks always switch) +— explicit-model routes never ask; LRN-242 (2-4 options) — 3 or 2; LRN-231 +(no dialog in a step hook) — asks at route-setting events only; LRN-243 +(interactive behaviour proven before building) — every hook kind used +already renders `$.ui.ask` in the shipped code. +ALREADY SEEN: LRN-229 (kit: forcing a throw after an answer), BLK-030/031 +(Fable without credits is the breaker's job, not this ask). +NON-BINDING: BDR-107, BDR-115, LRN-211, LRN-226. +SELECTION: scanned 4 registries, surfaced 14 = in-force 8 + seen 3 + +non-binding 4 (BLK-032 counted in two groups).