claude/.claude/tasks/plans/2026-10-08-model-router-floor-1835.md

# PLAN — model-router wave 1-B1: user effort floor for the turn (dispatch-ready)
Contract: .claude/tasks/contracts/2026-10-08-model-router-floor-1835.md
Code: mods/model-router/hooks/register.ts (read it in full first) and
register.test.ts. API truth: the engine-laid declarations under
mods/model-router/.claude-plugin/types/ (claude-code/index.d.ts,
claude-code-tools/index.d.ts).

## Why
Today the prompt rule (`ultrathink` → escalate) and a typed `/effort-<l>`
share ONE slot (`turnMain`) with the model's `route` calls and the
`Skill(effort-*)` bridge: last writer wins, and a later skill load resets
the slot to the session default. A user's explicit level is therefore lost
mid-turn. The user chose FLOOR semantics: their level is a minimum for the
whole main turn; derived routes may go above it, never below; it also
lifts a lower sticky `/route`.

## Precedence after the change (main loop only)
- model axis (unchanged order, floor last): `userMain ?? turnMain ?? turnFloor`
  route's `model`, applied only with `mainModelSwitch` and the window guard.
- effort axis: `base = (userMain ?? turnMain)?.route.effort ?? e.effort`;
  `effort = floored(base, turnFloor?.route.effort)`.
- `floored(effort, floor)`: no floor → `effort`; `effort` is a Level whose
  LEVELS index ≥ the floor's → `effort`; otherwise (lower Level, a number,
  or undefined) → `floor`.
- The haiku omission (`effort: undefined` when the model sent starts with
  `claude-haiku`) still runs AFTER flooring.
- Sub-agent steps (`e.agentId` set) never read `turnFloor`.

## Changes in register.ts (names as in the current file)
1. `State`: add `turnFloor: Routed | null` with the comment `user-explicit
   level for this turn (prompt rule, typed /effort-<l>): a floor, main loop
   only`; reword the `turnMain` comment to `model route tool, skill table
   row, Skill(effort-*) bridge; dropped at turn end`. `newState`:
   `turnFloor: null`.
2. Helpers (new, small): `const rank = (l: Level): number => LEVELS.indexOf(l)`;
   `function floored(effort: StepIn['effort'], floor: Level | undefined)`
   per the rule above. A helper `floorLevel(st)` returning
   `st.turnFloor?.route.effort` is allowed if it keeps call sites short.
3. `mainPlan`: compute `base` and `effort = floored(base, floorLevel(st))`;
   `wanted = set?.route.model ?? st.turnFloor?.route.model`; the rest
   (switch, window guard) unchanged.
4. `registerPrompt` / `prompt.submit`: the non-queued branch writes
   `st.turnFloor = routed` (instead of `st.turnMain`); the queued branch
   (`e.turnId !== undefined && e.wait`) keeps writing `st.pendingPrompt`.
5. `slashEffort`: write `st.turnFloor = { phase: skill, route: { effort:
   level }, source: 'slash' }`; returned text line becomes `Effort floor
   <level> set by model-router for this turn: nothing below it runs.`
   followed by `\n` + the original text (prepend, never replace).
6. `onSkillLoad` (main branch): `st.turnMain = null` unconditionally (the
   slot no longer holds prompt or slash routes), then the table row as now.
   `turnFloor` is never touched there.
7. `clearRoutes` (`/route clear`): also `st.turnFloor = null`.
   `clearLoop` (model `route({clear})`, main branch): `turnMain` only, as now.
8. `endMainTurn`: `st.turnFloor = st.pendingPrompt; st.pendingPrompt =
   null; st.turnMain = null;` then the existing resets.
9. Truthful answers (main branch only; agent branches unchanged):
   - `effortBridge`: keep the sticky sentence when `st.userMain` is set;
     else when the floor ranks above `level`: `model-router: <skill>
     recorded, but the user's floor <f> for this turn keeps main at <f>;
     the <skill> skill text was not loaded.`; else the current sentence.
   - `routedText`: keep the sticky branch; else when `p.route.effort` is
     set and the floor ranks above it, print the effort as `<f> (user
     floor; asked <asked>)`.
10. Display: `mainText` appends ` · floor <f> (<phase>)` when `turnFloor` is
    set (also after `main: session defaults`); `statusLine` appends
    ` · floor <f>`.

## Tests in register.test.ts (keep every existing test; adapt only what
the new slot changes, e.g. the `ultrathink` test now expects the floor on
the `main:` line). Add at least six tests whose names contain `floor`,
using the existing boot helper, full typed inputs and bottom hooks, and
asserting on the `main:` line or on what the bottom `turn.step` hook
receives (drain the stream with `for await`, then `.result`):
- `floor: ultrathink survives a model route` — prompt `ultrathink`
  (composer, `wait: false`, no `turnId`) then route tool `orchestrate` →
  a main step with engine effort `high` reaches the bottom at `max`.
- `floor: a typed /effort-medium floors a lower route and allows a higher
  one` — `$.skill.prompt({ skill: 'effort-medium', text: 'x' })` (no Skill
  call in flight) → route tool `mechanical` → main step at `medium`;
  then route tool `escalate` → main step at `max`.
- `floor: survives a skill load` — ultrathink, route tool `orchestrate`,
  then a non-effort `Skill` call (bottom `tool.call` hook registered) →
  main step at `max`, and `main:` line no longer names `orchestrate`.
- `floor: lifts a lower sticky route, then ends with the turn` — `/route
  effort=low` then ultrathink → main step at `max`; fire a main
  `turn.complete` → next main step at `low`.
- `floor: main only` — ultrathink, spawn `Explore` (bottom `agent.spawn`
  hook returning an `agentId`), then a step for that `agentId` → reaches
  the bottom at `medium`, not `max`.
- `floor: /route clear removes it` — ultrathink, `/route clear` → main
  step keeps the engine effort.
Optional seventh: the bridge context line names the floor when it wins.

## Constraints
- Style: ≤ 25 logic lines per function, 80 chars per line, no `any`, no
  module-level mutable state, doc comments state intent.
- Do not touch: the agent axis, the spawn table, config loading, the
  hardening (caps, warnOnce, safely), the route tool schema.
- Verify (paste outputs): `claude plugin validate .`, the contract's tsc
  command, `claude plugin test .`, then from the repo root
  `bash ~/.claude/lib/gates.sh run .claude/tasks/contracts/2026-10-08-model-router-floor-1835.md`.

## Disposition
- honors BDR-115 (one writer per axis, calling-loop writes, truthful
  answers) and the wave plan's routing rule (explicit user choice beats the
  derived phase); supersedes the 1-A contract's one-slot precedence for
  prompt and slash sources.
- LRN-206 (kit facts) applies to every new test.

## r2 — challenge round (3 lenses, 0 BLOCKER, 4 MAJOR): BINDING, overrides the sections above where they conflict
R1. ONE decision helper, used by `mainPlan` AND by every answer text:
    `mainEffort(st, engine: StepIn['effort'])` → `{ effort, by }` with
    `by` ∈ `'floor' | 'sticky' | 'turn' | 'engine'`.
    `base = (st.userMain ?? st.turnMain)?.route.effort
            ?? st.turnFloor?.route.effort ?? engine`
    `effort = floored(base, st.turnFloor?.route.effort)`; `by = 'floor'`
    when the floor raised or supplied the value, else the slot it came from.
    The user's level is therefore BOTH the turn's default (when no sticky
    or turn route names an effort) AND its minimum: a typed `/effort-low`
    lowers a turn that has no route (engine `high` → `low`), and a route
    can still go higher. No text function compares ranks on its own.
R2. Model axis, one rule written once (contract updated):
    `st.userMain?.route.model ?? st.turnMain?.route.model ?? st.turnFloor?.route.model`,
    switch and window guard unchanged.
R3. Prompt rule with `e.turnId !== undefined` (typed while a turn runs;
    `wait` is IGNORED: the engine queues every mid-turn prompt either way):
    write the floor NOW (higher of the existing floor and the new one)
    AND set `pendingPrompt` to it, so the turn that reads the prompt has it
    whichever it is. No `turnId` → write the floor (higher of two).
    `endMainTurn` promotes `pendingPrompt` into `turnFloor`. Two floors in
    one turn always keep the higher one (prompt rule and typed slash).
R4. Truthful texts, all phrased from `mainEffort` (main branch only):
    - Skill bridge, route tool, typed `/effort-<l>`: when `by === 'floor'`
      and the result differs from what was asked, name the floor and its
      source (`ultrathink rule` or `typed /effort-<l>`) and add
      `/route clear to drop it`; when `by === 'sticky'`, the sticky
      sentence; the old fixed "sticky wins" sentences go.
    - `/effort-<l>` text: `Effort <l> set by model-router for the main loop
      this turn (minimum; a higher route still applies).` plus the floor
      or sticky outcome when one changes it.
    - main loop on a haiku model: print `effort - (haiku takes none)`.
    - model `route({clear})` on main with a floor set: append `; user floor
      <f> (<source>) still holds — /route clear drops it`.
R5. Display: `mainText` / `statusLine` show ` · floor <f>` only when the
    floor carries an effort AND the router is on; the `skill.prompt` hook
    calls `refresh($, st)` after the slash write.
R6. Persistent per-machine off switch (wiring challenge, user's "configurable"):
    config key `enabled: boolean` (default `true`) in
    `~/.claude/model-router.json` (untracked, per machine). `false` →
    `st.off = true` after every config load (session start, `/route
    reload`); `/route on` re-enables for the session only; `show` and the
    status line say `off (config)` vs `off`. Merged with `pickBool` like
    the other scalars; `DEFAULT_CONFIG.enabled = true`.
R7. Tests (replace the list above where it differs): `runStep` takes a
    full `TurnStepInput` (from 'claude-code'); every floor test steps with
    engine effort `high` (or `xhigh`); every `test('…', async (` line ≤ 80
    chars with `floor` in the single-line name. At least 8 floor tests:
    ultrathink survives a model route · typed /effort-medium clamps low,
    lets max pass · typed /effort-low lowers an unrouted turn (engine high
    → low) · survives a skill load · lifts a lower sticky then ends with
    the turn · main only (agent step unaffected) · /route clear removes it
    · mid-turn prompt (turnId + wait) is applied now AND promoted after the
    main turn.complete · mandatory text test: sticky `/route effort=low`,
    ultrathink, route tool `plan` → the answer names the floor.
    `enabled: false` cannot be reached in the kit (no fs, LRN-206): cover
    the off path through `/route off` and say so in a comment.
R8. Residuals accepted (logged in TODO, not built): floor expiry depends on
    a main `turn.complete` reaching this mod (another plugin answering it
    without `next` would keep it); `skill.prompt` cannot tell a typed
    `/effort-<l>` from a sub-agent preload (no agentId; no repo agent
    preloads one); an incidental "ultrathink" in pasted text floors the
    turn (mitigated by R4 naming the source and the `/route clear` hint).