[FEATURE] Mod API: let a mod set and see fast mode per model request (subagents included)

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Mods can already set the model and effort of each model request from turn.step (next({ ...e, model, effort })). That lets a mod control them per subagent. Fast mode has no such control:

• Can't set it: TurnStepInput has model and effort, both rewritable, but no field for speed or fast mode.
• Can't see it: TurnUsage (on turn.step / turn.complete) and ModelUsage carry only the four token counts and the model id. A mod can't tell which requests ran in fast mode, even on the main thread, so any cost estimate it shows is too low.
• Can't read the setting: $.session.model() returns only the model id. Nothing tells a mod whether /fast is on.

My use case: I maintain a mod (workflow-monitor) that shows a live pane of every running subagent and workflow agent, with model, effort, tokens, elapsed time and estimated cost. You can pick the model and effort of an agent's next requests, per agent or for a whole workflow. I'd like to add fast mode the same way, but the API gives me no way to set it, see it or price it.

/fast applies to the whole session: the main thread and every agent. In a large workflow you often want fast mode only on a few critical-path agents (a final judge, a blocking implementer) and standard speed on the rest, to keep cost down.

(Checked against Claude Code 2.1.295's mod API types.)

Proposed Solution

Three small additions to the mod API:

1. TurnStepInput.speed?: 'standard' | 'fast'. The speed the request will be sent with, from the session's /fast setting (or what the engine resolved for that agent). A hook can rewrite it going down, like model and effort:

on('turn.step', async function* ($, e, next) {
  const speed = speedFor(e.agentId)   // the person's pick in the mod's pane
  return yield* next(speed ? { ...e, speed } : e)
})

If the model doesn't support fast mode, the engine sends the request at standard speed (or refuses the rewrite, as it does for pinned fields). Item 2 then reports what actually happened.

2. speed on TurnUsage, and ideally on ModelUsage too. This is the speed the API actually served, so cost is right even when a fast request falls back to standard (for example on a fast-mode rate limit):

on('turn.complete', async ($, e, next) => {
  price(e.usage, e.usage.speed === 'fast' ? FAST_PRICES : PRICES)
  return next(e)
})

3. A way to read the session's setting, e.g. $.session.speed() or a fastMode field next to the model, so a pane can show "Inherit (on)" or "Inherit (off)". An event when the person toggles /fast would be a bonus, so the pane can redraw.

Optional: speed on $.agent.spawn's input, for mods that start their own agents.

UI this enables in my mod:

• ⚡ next to the model name of agents whose requests run in fast mode;
• a Fast mode picker (Inherit / On / Off) beside Model and Effort, per agent and per workflow card;
• cost estimates that use fast-mode prices for the requests that ran fast.

Alternative Solutions

• Toggling /fast for the session from a mod: there's no API for it, and it would still apply to the main thread and every agent, not one agent.
• Guessing fast mode from output speed: unreliable, and it doesn't make cost estimates right.
• Workaround today: none. My mod can't offer fast mode per agent, and its cost estimate is too low whenever /fast is on, because nothing marks those requests.

Priority

Low - Nice to have

Feature Category

Developer tools/SDK

Use Case Example

1. A workflow fans out 12 investigation agents and 1 final judge agent.
2. In the mod's pane I open the judge's settings and set Fast mode: On. The other 12 stay on Inherit, and the session's /fast is off.
3. The mod rewrites only the judge's requests in turn.step with speed: 'fast'.
4. The judge's row shows ⚡ next to its model. Its cost uses fast-mode prices, read from usage.speed. The other rows are priced at standard rates.
5. If a fast request falls back to standard, usage.speed says so, and the estimate stays correct.

Additional Context

• The mod is open source: https://github.com/ivanpajon/dotclaude/tree/main/mods/workflow-monitor
• The turn.step model and effort rewrite already works well for per-agent control. Speed is the one missing knob.