@alexeiled/claude-router 1.8.1 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -21,6 +21,7 @@ import { resolveCredentials } from '../lib/classifier-contract.mjs';
21
21
  import {
22
22
  ACTIVITY_MODES,
23
23
  activeClassifier,
24
+ CLASSIFY,
24
25
  DEFAULTS,
25
26
  editActivity,
26
27
  effectiveActivities,
@@ -79,7 +80,27 @@ import {
79
80
  SAVINGS_PREFIX,
80
81
  SAVINGS_RESET_KEY,
81
82
  sessionCacheTtl,
83
+ subagentCacheTtl,
82
84
  } from '../lib/savings.mjs';
85
+ import {
86
+ addAgentReply,
87
+ agentFrontmatter,
88
+ classifiedAlias,
89
+ coreModelOf,
90
+ emptySubagentStore,
91
+ flushedAgent,
92
+ mergeSubagentStores,
93
+ passReason,
94
+ RESPAWN_WINDOW_MS,
95
+ readSubagentStore,
96
+ recordAgent,
97
+ SPAWN_DEADLINE_MS,
98
+ SUBAGENT_PREFIX,
99
+ spawnPrompt,
100
+ spawnRecord,
101
+ subagentsAfterReset,
102
+ typeRoute,
103
+ } from '../lib/subagents.mjs';
83
104
  import { CLEARED_READINGS, continuationView, healthOf, initialView, responseMetrics } from '../lib/view.mjs';
84
105
 
85
106
  // The engine follows $ only into functions declared in this file, never across an import: every helper that takes $
@@ -91,6 +112,7 @@ const PANE = 'jev-router';
91
112
  const PANE_TITLE = 'Router';
92
113
  const BAND_DETAIL = 'band:detail';
93
114
  const MODE_PREFIX = 'mode:';
115
+ const isSet = (value) => /^(1|true|yes|on)$/i.test(String(value ?? '').trim());
94
116
 
95
117
  // Everything the hooks change between events, in one object `register()` creates and passes to its helpers. Module
96
118
  // variables, not $.state: a reload starts them over, and the view is written through to $.state as it changes.
@@ -129,6 +151,14 @@ function createRouter(options) {
129
151
  metricsOthers: null,
130
152
  // Bumped by Reset activity stats, so a store write that read the counts before the reset skips.
131
153
  statsResets: 0,
154
+ // Each spawned agent's record by agentId (spawnRecord), and when each parent loop last finished an agent of a type,
155
+ // for respawns. The subagent totals kept across sessions, held as the savings records are.
156
+ agents: new Map(),
157
+ finished: new Map(),
158
+ // Each agent type's definition frontmatter by provider and type, read once per session (agentDefinition).
159
+ definitions: new Map(),
160
+ subagentsOwn: null,
161
+ subagentsOthers: null,
132
162
  };
133
163
  }
134
164
 
@@ -231,6 +261,32 @@ async function otherMetrics($, sessionId, resetAt) {
231
261
  return mergeMetrics(await Promise.all(keys.map((key) => $.store.get(key))), resetAt);
232
262
  }
233
263
 
264
+ // This session's subagent record and the last reset, as ownSavings: Reset stats clears it with the same marker.
265
+ async function ownSubagents($, router) {
266
+ const sessionId = await $.session.id();
267
+ const resetAt = await $.store.get(SAVINGS_RESET_KEY);
268
+ if (router.subagentsOwn?.sessionId !== sessionId) {
269
+ const record = readSubagentStore(await $.store.get(`${SUBAGENT_PREFIX}${sessionId}`));
270
+ if (router.subagentsOwn?.sessionId !== sessionId) router.subagentsOwn = { sessionId, record };
271
+ }
272
+ router.subagentsOwn.record = subagentsAfterReset(router.subagentsOwn.record, resetAt);
273
+ return { own: router.subagentsOwn, resetAt };
274
+ }
275
+
276
+ // Every other session's subagent record since the last reset, added up.
277
+ async function otherSubagents($, sessionId, resetAt) {
278
+ const own = `${SUBAGENT_PREFIX}${sessionId}`;
279
+ const keys = (await $.store.keys()).filter((key) => key.startsWith(SUBAGENT_PREFIX) && key !== own);
280
+ return mergeSubagentStores(await Promise.all(keys.map((key) => $.store.get(key))), resetAt);
281
+ }
282
+
283
+ // The view's subagent totals, this session's and the others', from what the router holds; nothing until a read
284
+ // succeeded.
285
+ const subagentView = (router) =>
286
+ router.subagentsOthers
287
+ ? { subagentStore: mergeSubagentStores([router.subagentsOthers, router.subagentsOwn?.record]) }
288
+ : {};
289
+
234
290
  const metricsView = (router) => mergeMetrics([router.metricsOthers, router.metricsOwn?.record]);
235
291
 
236
292
  // The view's totals kept across sessions, from what the router holds; nothing until a read succeeded.
@@ -254,6 +310,11 @@ async function storeView($, router) {
254
310
  const { own, resetAt } = await ownSavings($, router);
255
311
  router.savingsOthers = await otherSavings($, own.sessionId, resetAt);
256
312
  } catch {}
313
+ try {
314
+ const { own, resetAt } = await ownSubagents($, router);
315
+ router.subagentsOthers = await otherSubagents($, own.sessionId, resetAt);
316
+ Object.assign(out, subagentView(router));
317
+ } catch {}
257
318
  return out;
258
319
  }
259
320
 
@@ -371,6 +432,19 @@ function openKeySettings($) {
371
432
  $.clock.after(0, () => $.command.run({ command: 'plugin', args: `configure ${$.plugin.name}` }).catch(() => {}));
372
433
  }
373
434
 
435
+ // Whether this session's provider gives each effort its own prompt cache (effortSharesCache in lib/cost.mjs): Amazon
436
+ // Bedrock, Google Cloud, Microsoft Foundry, a custom ANTHROPIC_BASE_URL (it may be a Claude apps gateway) or
437
+ // CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS. A HIPAA configuration is not visible to a Mod. $.env.get takes literal names.
438
+ async function effortSplitsCacheOf($) {
439
+ const flags = [
440
+ await $.env.get('CLAUDE_CODE_USE_BEDROCK'),
441
+ await $.env.get('CLAUDE_CODE_USE_VERTEX'),
442
+ await $.env.get('CLAUDE_CODE_USE_FOUNDRY'),
443
+ await $.env.get('CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS'),
444
+ ];
445
+ return flags.some(isSet) || Boolean(await $.env.get('ANTHROPIC_BASE_URL'));
446
+ }
447
+
374
448
  async function loadNativeConfig($) {
375
449
  for (const source of ['project', 'local']) {
376
450
  const settings = await $.settings.read({ source });
@@ -381,7 +455,7 @@ async function loadNativeConfig($) {
381
455
  const profile = (await $.env.get('CLAUDE_CONFIG_DIR')) ?? `${home}/.claude`;
382
456
  const path = `${profile}/router.json`;
383
457
  const userFile = (await $.fs.exists(path)) ? JSON.parse(await $.fs.read(path)) : null;
384
- return { ...loadConfig({ userFile }), nativePath: path };
458
+ return { ...loadConfig({ userFile }), nativePath: path, effortSplitsCache: await effortSplitsCacheOf($) };
385
459
  }
386
460
 
387
461
  // Writes router.json through `change(previousFile)` once the result validates. Returns the new config or an error
@@ -392,7 +466,7 @@ async function saveConfig($, path, change) {
392
466
  return { error: 'Not saved: router.json is a symlink. Edit its maintained source instead.' };
393
467
  const { config, text } = rewrittenConfig((await $.fs.exists(path)) ? await $.fs.read(path) : null, change);
394
468
  await $.fs.write(path, text);
395
- return { config: { ...config, nativePath: path } };
469
+ return { config: { ...config, nativePath: path, effortSplitsCache: await effortSplitsCacheOf($) } };
396
470
  } catch (error) {
397
471
  return { error: notSaved(error) };
398
472
  }
@@ -456,7 +530,7 @@ async function* passMain($, e, next, loop, version, nativeModel, reason, router)
456
530
  const sessionId = await $.session.id();
457
531
  const response = yield* next(e);
458
532
  if (!next.signal.aborted && (await $.session.id()) === sessionId) {
459
- const observed = observeResponse(loop, {
533
+ const observed = observeResponse(router.config, loop, {
460
534
  usage: response.usage,
461
535
  requestedModel: e.model,
462
536
  effort: e.effort ?? null,
@@ -616,7 +690,7 @@ async function publishReply($, router, turnId, response, tier, route, routedUsd)
616
690
  // A routed reply written to the loop at `loopVersion`, then published: the view's metrics and the routing-vs-your-model
617
691
  // totals. A lost write publishes nothing.
618
692
  async function observeRouted($, router, { turnId, cfg, loop, loopVersion, request, response, nativeModel }) {
619
- const observed = observeResponse(loop, {
693
+ const observed = observeResponse(cfg, loop, {
620
694
  usage: response.usage,
621
695
  requestedModel: request.model,
622
696
  effort: request.effort ?? null,
@@ -789,6 +863,210 @@ async function flushRun($, run) {
789
863
  } catch {}
790
864
  }
791
865
 
866
+ // The frontmatter of the agent file a spawn starts (agentFrontmatter), or null when it cannot be found or read. Read
867
+ // once per provider and type in a session, and never for a built-in, whose definition is not on disk.
868
+ async function agentDefinition($, router, e) {
869
+ const plugin = e.provider?.plugin;
870
+ if (typeof plugin !== 'string' || plugin === 'engine' || typeof e.subagentType !== 'string') return null;
871
+ const key = `${plugin} ${e.subagentType}`;
872
+ if (!router.definitions.has(key)) router.definitions.set(key, await findDefinition($, plugin, e.subagentType));
873
+ return router.definitions.get(key);
874
+ }
875
+
876
+ // A plugin agent (provider `plugin@marketplace`) is looked up under each install path installed_plugins.json gives
877
+ // that plugin, the files Claude Code itself loads; any other agent under the session's .claude/agents, then the
878
+ // profile's agents. Every match must agree on the model, or the definition is unknown. Limit: a plugin that keeps its
879
+ // agents outside `agents/` reads as unknown, so its agents pass through.
880
+ async function findDefinition($, plugin, type) {
881
+ try {
882
+ const home = await $.env.get('HOME');
883
+ const profile = (await $.env.get('CLAUDE_CONFIG_DIR')) ?? `${home}/.claude`;
884
+ const name = type.slice(type.indexOf(':') + 1);
885
+ const fromPlugin = plugin.includes('@');
886
+ const dirs = fromPlugin
887
+ ? (JSON.parse(await $.fs.read(`${profile}/plugins/installed_plugins.json`)).plugins?.[plugin] ?? []).map(
888
+ (entry) => `${entry.installPath}/agents`,
889
+ )
890
+ : [`${await $.session.cwd()}/.claude/agents`, `${profile}/agents`];
891
+ const found = [];
892
+ for (const dir of dirs) {
893
+ if (!(await $.fs.exists(dir))) continue;
894
+ for (const entry of await $.fs.list(dir)) {
895
+ if (entry.kind === 'dir' || !entry.name.endsWith('.md')) continue;
896
+ const definition = agentFrontmatter(await $.fs.read(`${dir}/${entry.name}`));
897
+ if (definition && (definition.name ?? entry.name.slice(0, -3)) === name) found.push(definition);
898
+ }
899
+ // A project agent replaces a user agent of the same name.
900
+ if (found.length && !fromPlugin) break;
901
+ }
902
+ const agree = found.every((d) => d.model === found[0].model && d.modelRouting === found[0].modelRouting);
903
+ return found.length && agree ? found[0] : null;
904
+ } catch {
905
+ return null;
906
+ }
907
+ }
908
+
909
+ // The spawn path's classifier client: a breaker of its own, so spawn failures never pause main-turn routing, and no
910
+ // in-flight slot, so a parent that spawns several agents at once gets an answer for each.
911
+ function spawnClientOf(router, id) {
912
+ const key = `spawn:${id}`;
913
+ if (!router.clients.has(key)) router.clients.set(key, new ClassifierClient({ exclusive: false }));
914
+ return router.clients.get(key);
915
+ }
916
+
917
+ // A listed spawn's model: the models key its type names, or the classifier's pick for a `classify` type from the task
918
+ // text alone. `choice: 'core'` keeps core's model: no advice (`failed`), or a model availableModels blocks.
919
+ async function decideSpawn($, router, cfg, e, definition, signal) {
920
+ let alias = typeRoute(cfg, e, definition).route;
921
+ let failed = false;
922
+ if (alias === CLASSIFY) {
923
+ const entry = activeClassifier(cfg);
924
+ const credentials = await resolveCredentials(entry, (name) => settingOf($, router.options, name));
925
+ // The wait delays the subagent's start, so it is the classifier's deadline capped at SPAWN_DEADLINE_MS.
926
+ const timeoutMs = Math.min(entry.timeoutMs, SPAWN_DEADLINE_MS);
927
+ const result = await spawnClientOf(router, cfg.classifier).ask({
928
+ request: (url, init) => $.http.fetch(url, init),
929
+ sleep: (ms, args) => $.clock.sleep(ms, args),
930
+ config: { ...cfg, classifiers: { ...cfg.classifiers, [cfg.classifier]: { ...entry, timeoutMs } } },
931
+ apiKey: credentials.apiKey,
932
+ endpoint: credentials.endpoint,
933
+ prompt: spawnPrompt(cfg, e),
934
+ turns: [],
935
+ signal,
936
+ });
937
+ alias = classifiedAlias(cfg, result.advice);
938
+ failed = !result.advice;
939
+ }
940
+ // The full id, not an alias: a family alias would resolve to the parent's exact model when the families match.
941
+ const model = alias ? cfg.models[alias].id : null;
942
+ const settings = await $.settings.read().catch(() => ({}));
943
+ if (!model || !isModelAllowed(model, settings.availableModels, e.parentModel))
944
+ return { choice: 'core', model: null, failed };
945
+ return { choice: alias, model, failed };
946
+ }
947
+
948
+ // One model per subagent, chosen before its cache exists. `on` waits for the decision and sends its model, which
949
+ // Claude Code uses in place of the Agent call's `model` and the agent's frontmatter. `shadow` spawns as Claude Code
950
+ // would at once and records the decision once it is in, so it never delays an agent's start. Routing off or
951
+ // unavailable keeps every model Claude Code chooses, and records nothing.
952
+ async function spawnAgent($, router, e, next) {
953
+ const cfg = router.config;
954
+ const mode = cfg.subagentRouting;
955
+ if (mode === 'off') return next(e);
956
+ const view = router.view ?? (await readView($, router));
957
+ if (view.phase === 'unavailable' || (await modeOf($, router, view.mode)) === 'manual') return next(e);
958
+ const definition = await agentDefinition($, router, e);
959
+ const pass = passReason(cfg, e, definition);
960
+ const deciding = pass ? null : decideSpawn($, router, cfg, e, definition, next.signal).catch(() => null);
961
+ const decided = mode === 'on' ? await deciding : null;
962
+ const routed = Boolean(decided?.model);
963
+ const result = await next(routed ? { ...e, model: decided.model } : e);
964
+ if (!result.agentId) return result;
965
+ // In shadow the agent may reply, and even finish, before the decision lands: a pending entry keeps its replies.
966
+ if (mode !== 'on' && deciding !== null)
967
+ router.agents.set(result.agentId, { pending: true, usages: [], finished: false });
968
+ try {
969
+ const decision = mode === 'on' ? decided : await deciding;
970
+ if (pass || decision) await noteSpawn($, router, { cfg, mode, e, pass, decision, routed, result, definition });
971
+ else router.agents.delete(result.agentId);
972
+ } catch {
973
+ if (router.agents.get(result.agentId)?.pending) router.agents.delete(result.agentId);
974
+ }
975
+ return result;
976
+ }
977
+
978
+ // The spawn's record, kept until the session ends. In `on` core's model is an estimate (coreModelOf); otherwise it is
979
+ // the model the agent started on.
980
+ async function noteSpawn($, router, { cfg, mode, e, pass, decision, routed, result, definition }) {
981
+ const parentKey = `${e.parentAgentId ?? 'main'} ${e.subagentType}`;
982
+ const finishedAt = router.finished.get(parentKey);
983
+ const ttl = await subagentTtlOf($).catch(() => null);
984
+ const coreModel = routed
985
+ ? coreModelOf(cfg, e, {
986
+ envModel: await $.env.get('CLAUDE_CODE_SUBAGENT_MODEL'),
987
+ force: isSet(await $.env.get('CLAUDE_CODE_SUBAGENT_MODEL_FORCE')),
988
+ definition,
989
+ })
990
+ : result.model;
991
+ const record = spawnRecord({
992
+ sessionId: await $.session.id(),
993
+ mode,
994
+ spawn: e,
995
+ pass,
996
+ choice: decision?.choice ?? null,
997
+ routedModel: decision?.model ?? result.model,
998
+ coreModel,
999
+ failed: decision?.failed,
1000
+ respawn: Number.isFinite(finishedAt) && Date.now() - finishedAt < RESPAWN_WINDOW_MS,
1001
+ });
1002
+ // Read after the last await, so no reply lands in the pending entry after its replay.
1003
+ const pending = router.agents.get(result.agentId);
1004
+ const replies = pending?.pending ? pending.usages : [];
1005
+ router.agents.set(
1006
+ result.agentId,
1007
+ replies.reduce((agent, usage) => addAgentReply(cfg, agent, usage, ttl), { ...record, parentKey }),
1008
+ );
1009
+ if (pending?.finished) await finishAgent($, router, result.agentId);
1010
+ }
1011
+
1012
+ // A subagent's prompt-cache lifetime, by Claude Code's rule for requests outside the main conversation.
1013
+ async function subagentTtlOf($) {
1014
+ const settings = await $.settings.read();
1015
+ return subagentCacheTtl({
1016
+ force5m: await $.env.get('FORCE_PROMPT_CACHING_5M'),
1017
+ envTtl: await $.env.get('CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL'),
1018
+ settingTtl: settings.subagentPromptCacheTtl,
1019
+ enable1h: await $.env.get('ENABLE_PROMPT_CACHING_1H'),
1020
+ });
1021
+ }
1022
+
1023
+ // A subagent's step runs exactly as Claude Code sent it: a model switch between its steps would rewrite its context
1024
+ // cold. Its reply is added to its spawn record; the record never breaks the step.
1025
+ async function* stepAgent($, router, e, next) {
1026
+ const response = yield* next(e);
1027
+ if (router.agents.has(e.agentId) && response?.usage) {
1028
+ try {
1029
+ const ttl = await subagentTtlOf($);
1030
+ const agent = router.agents.get(e.agentId);
1031
+ if (agent?.pending) agent.usages.push(response.usage);
1032
+ else if (agent) router.agents.set(e.agentId, addAgentReply(router.config, agent, response.usage, ttl));
1033
+ } catch {}
1034
+ }
1035
+ return response;
1036
+ }
1037
+
1038
+ // A subagent's turn ended: its counts since the last flush go to this session's record kept across sessions.
1039
+ async function finishAgent($, router, agentId) {
1040
+ const agent = router.agents.get(agentId);
1041
+ if (!agent) return;
1042
+ // A pending agent is flushed when its decision lands (noteSpawn).
1043
+ if (agent.pending) {
1044
+ agent.finished = true;
1045
+ return;
1046
+ }
1047
+ router.finished.set(agent.parentKey, Date.now());
1048
+ router.agents.set(agentId, flushedAgent(agent));
1049
+ await flushSubagents($, router, [agent]);
1050
+ }
1051
+
1052
+ // Agents' counts added to this session's record, with the guard flushSavings uses: counts read before a reset are not
1053
+ // written back. Stats never break a turn: a failed read or write loses these counts.
1054
+ async function flushSubagents($, router, agents) {
1055
+ try {
1056
+ const resets = router.statsResets;
1057
+ const { own, resetAt } = await ownSubagents($, router);
1058
+ const mine = agents.filter((agent) => agent.sessionId === own.sessionId);
1059
+ if (!mine.length) return;
1060
+ if (!router.subagentsOthers || subagentsAfterReset(router.subagentsOthers, resetAt) !== router.subagentsOthers)
1061
+ router.subagentsOthers = await otherSubagents($, own.sessionId, resetAt);
1062
+ if (router.statsResets !== resets) return;
1063
+ const now = Date.now();
1064
+ own.record = mine.reduce((record, agent) => recordAgent(record, agent, now), own.record);
1065
+ await $.store.set(`${SUBAGENT_PREFIX}${own.sessionId}`, own.record);
1066
+ if (router.statsResets === resets) await updateView($, router, subagentView(router));
1067
+ } catch {}
1068
+ }
1069
+
792
1070
  // The pane's handlers. `view` is the view the pane was drawn from; a handler reads `router.view` first, which holds
793
1071
  // any press since.
794
1072
  function paneActions($, router, view) {
@@ -944,6 +1222,7 @@ function paneActions($, router, view) {
944
1222
  router.run = null;
945
1223
  router.afterDown = null;
946
1224
  router.turnSavings.clear();
1225
+ for (const [id, agent] of router.agents) if (!agent.pending) router.agents.set(id, flushedAgent(agent));
947
1226
  const clear = (key, value) =>
948
1227
  $.store
949
1228
  .set(key, value)
@@ -954,14 +1233,16 @@ function paneActions($, router, view) {
954
1233
  // Written first, so a session still holding its record from before the reset drops it, unless that record's
955
1234
  // first reading has the reset's millisecond or the clock moved back across the reset.
956
1235
  await $.store.set(SAVINGS_RESET_KEY, Date.now());
957
- const keys = (await $.store.keys()).filter(
958
- (key) => key.startsWith(SAVINGS_PREFIX) || key.startsWith(METRICS_PREFIX),
1236
+ const keys = (await $.store.keys()).filter((key) =>
1237
+ [SAVINGS_PREFIX, METRICS_PREFIX, SUBAGENT_PREFIX].some((prefix) => key.startsWith(prefix)),
959
1238
  );
960
1239
  await Promise.all(keys.map((key) => $.store.delete(key)));
961
1240
  router.savingsOwn = null;
962
1241
  router.savingsOthers = emptySavingsStore();
963
1242
  router.metricsOwn = null;
964
1243
  router.metricsOthers = emptyMetrics();
1244
+ router.subagentsOwn = null;
1245
+ router.subagentsOthers = emptySubagentStore();
965
1246
  return true;
966
1247
  };
967
1248
  const [stats, records] = await Promise.all([clear(STORE_KEY, emptyStore()), clearRecords().catch(() => false)]);
@@ -969,7 +1250,9 @@ function paneActions($, router, view) {
969
1250
  activityStats: null,
970
1251
  savingsBy: {},
971
1252
  ...(stats ? { activityStore: emptyStore() } : {}),
972
- ...(records ? { activityMetrics: emptyMetrics(), savingsStore: emptySavingsStore() } : {}),
1253
+ ...(records
1254
+ ? { activityMetrics: emptyMetrics(), savingsStore: emptySavingsStore(), subagentStore: emptySubagentStore() }
1255
+ : {}),
973
1256
  notice:
974
1257
  stats && records
975
1258
  ? 'Stats reset: activity and routing vs your model, this session and saved.'
@@ -1027,10 +1310,47 @@ function paneActions($, router, view) {
1027
1310
  };
1028
1311
  }
1029
1312
 
1313
+ // The session's turns, open run and running agents end with it; the view starts the next session from the counts kept
1314
+ // across sessions.
1315
+ async function endSession($, router) {
1316
+ for (const controller of router.controllers) controller.abort();
1317
+ router.decisions.clear();
1318
+ router.prompts.clear();
1319
+ router.turnConfigs.clear();
1320
+ router.turnActivities.clear();
1321
+ router.turnSavings.clear();
1322
+ const run = router.run;
1323
+ router.run = null;
1324
+ router.afterDown = null;
1325
+ if (run) await flushRun($, run);
1326
+ // Agents still running when the session ends: what they did so far is counted.
1327
+ const agents = [...router.agents.values()];
1328
+ router.agents.clear();
1329
+ router.finished.clear();
1330
+ await flushSubagents($, router, agents);
1331
+ router.view = {
1332
+ ...initialView(router.view?.nativeModel ?? ''),
1333
+ // The effort carries over /clear until the next turn reads it again, so "your model" keeps its effort.
1334
+ nativeEffort: router.view?.nativeEffort ?? null,
1335
+ mode: 'auto',
1336
+ credentials: router.view?.credentials ?? null,
1337
+ // Counts kept across sessions: the next session starts from them.
1338
+ activityStore: router.view?.activityStore ?? null,
1339
+ activityMetrics: router.view?.activityMetrics ?? null,
1340
+ savingsStore: router.view?.savingsStore ?? null,
1341
+ subagentStore: router.view?.subagentStore ?? null,
1342
+ health: healthOf(clientOf(router, router.config.classifier), router.config.classifier),
1343
+ configPath: router.config.nativePath,
1344
+ phase: router.view?.phase === 'unavailable' ? 'unavailable' : 'ready',
1345
+ error: router.view?.phase === 'unavailable' ? router.view.error : null,
1346
+ };
1347
+ }
1348
+
1030
1349
  export function register(on, options) {
1031
1350
  const router = createRouter(options);
1032
1351
 
1033
1352
  on('session.start', async ($, e, next) => {
1353
+ router.definitions.clear();
1034
1354
  await $.command.register({
1035
1355
  name: 'router',
1036
1356
  description: 'Open the Router pane, or switch routing: auto, off, pin <tier>, activities <mode>.',
@@ -1105,8 +1425,14 @@ export function register(on, options) {
1105
1425
  return next(e);
1106
1426
  });
1107
1427
 
1428
+ // A hook failure spawns the agent as Claude Code would; next(e) replays a spawn already made. agent.spawn and a
1429
+ // catchable on() are in the 2.1.293 build types, not checked on 2.1.289: an engine without them still loads routing.
1430
+ try {
1431
+ on('agent.spawn', ($, e, next) => spawnAgent($, router, e, next)).catch((_$, e, next) => next(e));
1432
+ } catch {}
1433
+
1108
1434
  on('turn.step', async function* ($, e, next) {
1109
- if (e.agentId) return yield* next(e);
1435
+ if (e.agentId) return yield* stepAgent($, router, e, next);
1110
1436
  const cfg = router.turnConfigs.get(e.turnId) ?? router.config;
1111
1437
  const sessionId = await $.session.id();
1112
1438
  const nativeModel = await $.session.model();
@@ -1179,6 +1505,10 @@ export function register(on, options) {
1179
1505
  });
1180
1506
 
1181
1507
  on('turn.complete', async ($, e, next) => {
1508
+ if (e.agentId) {
1509
+ await finishAgent($, router, e.agentId);
1510
+ return next(e);
1511
+ }
1182
1512
  router.turnConfigs.delete(e.turnId);
1183
1513
  router.turnControllers.get(e.turnId)?.abort();
1184
1514
  if (router.view?.activeTurnId === e.turnId && router.view.phase === 'choosing') {
@@ -1214,31 +1544,7 @@ export function register(on, options) {
1214
1544
  });
1215
1545
 
1216
1546
  on('session.end', async ($, e, next) => {
1217
- for (const controller of router.controllers) controller.abort();
1218
- router.decisions.clear();
1219
- router.prompts.clear();
1220
- router.turnConfigs.clear();
1221
- router.turnActivities.clear();
1222
- router.turnSavings.clear();
1223
- const run = router.run;
1224
- router.run = null;
1225
- router.afterDown = null;
1226
- if (run) await flushRun($, run);
1227
- router.view = {
1228
- ...initialView(router.view?.nativeModel ?? ''),
1229
- // The effort carries over /clear until the next turn reads it again, so "your model" keeps its effort.
1230
- nativeEffort: router.view?.nativeEffort ?? null,
1231
- mode: 'auto',
1232
- credentials: router.view?.credentials ?? null,
1233
- // Counts kept across sessions: the next session starts from them.
1234
- activityStore: router.view?.activityStore ?? null,
1235
- activityMetrics: router.view?.activityMetrics ?? null,
1236
- savingsStore: router.view?.savingsStore ?? null,
1237
- health: healthOf(clientOf(router, router.config.classifier), router.config.classifier),
1238
- configPath: router.config.nativePath,
1239
- phase: router.view?.phase === 'unavailable' ? 'unavailable' : 'ready',
1240
- error: router.view?.phase === 'unavailable' ? router.view.error : null,
1241
- };
1547
+ await endSession($, router);
1242
1548
  return next(e);
1243
1549
  });
1244
1550
 
package/lib/band.mjs CHANGED
@@ -271,7 +271,16 @@ function hoverSegments(view, actions, routing) {
271
271
  export function renderBand({ Box, Text, Button }, config, view, usage, { columns, agentId }, actions) {
272
272
  const draw = (p) => (p.button ? Button(p.button) : Text({ ...p.style, children: p.text }));
273
273
  const row = (parts) => Box({ children: parts.map(draw) });
274
- if (agentId) return row([part('○ Router · subagents keep their own model', { dimColor: true })]);
274
+ // A subagent's model is chosen once, at spawn, and never changes between its steps.
275
+ if (agentId)
276
+ return row([
277
+ part(
278
+ config.subagentRouting === 'on'
279
+ ? '○ Router · subagent model chosen at spawn'
280
+ : '○ Router · subagents keep their own model',
281
+ { dimColor: true },
282
+ ),
283
+ ]);
275
284
  const kept = fitSegments(bandSegments(config, view, usage, actions), Math.max(0, columns - ROUTER_BUTTON));
276
285
  const line = kept.flatMap((s, i) => (i ? [part(SEPARATOR, { dimColor: true }), ...s.parts] : s.parts));
277
286
  line.push(part(' '), button({ key: 'details', label: 'Router', plain: true, onPress: actions.open }));
@@ -19,10 +19,13 @@ class AdviceError extends Error {
19
19
  }
20
20
  }
21
21
 
22
- // Owned by one Mod activation. It survives history resets; the host cancels its work on unload.
22
+ // Owned by one Mod activation. It survives history resets; the host cancels its work on unload. An exclusive client
23
+ // (the main turn's) answers `busy` while a request is in flight, so a late answer never overlaps the next turn's; the
24
+ // spawn path's client is not exclusive, so a parent that spawns several agents at once gets an answer for each.
23
25
  export class ClassifierClient {
24
- constructor({ now = Date.now, health = null } = {}) {
26
+ constructor({ now = Date.now, health = null, exclusive = true } = {}) {
25
27
  this.now = now;
28
+ this.exclusive = exclusive;
26
29
  this.pending = null;
27
30
  this.active = false;
28
31
  this.restore(health);
@@ -43,7 +46,7 @@ export class ClassifierClient {
43
46
  if (!endpoint) return { advice: null, error: 'missing-account' };
44
47
  if (signal?.aborted) return { advice: null, error: 'cancelled' };
45
48
  if (this.now() < this.pausedUntil) return { advice: null, error: 'paused' };
46
- if (this.active || this.pending) return { advice: null, error: 'busy' };
49
+ if (this.exclusive && (this.active || this.pending)) return { advice: null, error: 'busy' };
47
50
  this.active = true;
48
51
  try {
49
52
  const advice = await this.complete({ request, sleep, config, apiKey, endpoint, prompt, turns, signal });
package/lib/config.mjs CHANGED
@@ -8,6 +8,11 @@ export const ACTIVITY_VALUES = [...ACTIVITIES, 'uncertain'];
8
8
  // `off` asks nothing new and routes as 1.5; `shadow` asks and records but keeps the 1.5 route; `on`, the default since
9
9
  // 1.7, applies overrides.
10
10
  export const ACTIVITY_MODES = ['off', 'shadow', 'on'];
11
+ // `subagentRouting` takes the same modes: `off` asks and records nothing, `shadow` decides and records but keeps core's
12
+ // model, `on` applies the decision at agent.spawn.
13
+ export const SUBAGENT_MODES = ACTIVITY_MODES;
14
+ // A `subagents.types` value that asks the classifier instead of naming a model.
15
+ export const CLASSIFY = 'classify';
11
16
  const SONNET_HIGH = { model: 'sonnet', effort: 'high' };
12
17
  export const DEFAULTS = {
13
18
  baselineTier: 'low',
@@ -38,6 +43,20 @@ export const DEFAULTS = {
38
43
  review: { low: SONNET_HIGH },
39
44
  ops: { medium: { model: 'haiku', effort: 'high' } },
40
45
  },
46
+ // Subagents get one model at agent.spawn, never between their steps. An agent whose definition names no model, says
47
+ // `inherit`, or sets `modelRouting: auto` gets `light`, `standard` or `heavy` from the classifier; a pinned one keeps
48
+ // its model. `types` overrides by agent type: a models key, `classify`, or null to never route it. A key without a
49
+ // colon matches only the built-in of that name, whose definition is not readable, so only the listed built-ins route.
50
+ // A listed type is routed even if it pins a model. docs/plans/2026-10-10-subagent-routing-plan.md.
51
+ subagentRouting: 'on',
52
+ subagents: {
53
+ types: { Explore: 'haiku', Plan: CLASSIFY, 'general-purpose': CLASSIFY },
54
+ light: 'haiku',
55
+ standard: 'sonnet',
56
+ heavy: 'opus',
57
+ // The classifier's probability of `high` a task needs to run on `heavy`.
58
+ heavyMass: 0.8,
59
+ },
41
60
  // `id` selects the native model. List prices in USD per million tokens; `cacheRead` is absolute,
42
61
  // not a multiplier (Opus 5.5 reads at 0.05x input, the rest at the standard 0.1x). `longContext` multiplies every
43
62
  // rate of a request whose prompt (input, cache read and cache write) is over `above` tokens: Haiku 5.5 lists its
@@ -426,7 +445,7 @@ function checkShape(file) {
426
445
  if (file && typeof file === 'object' && Object.hasOwn(file, 'jev'))
427
446
  throw new Error(`router.json uses the 1.1 jev section; ${MIGRATION_HINT}`);
428
447
  checkObject(file, 'router.json', Object.keys(DEFAULTS));
429
- const { routes, activities, models, cache, policy, classifiers, context } = file;
448
+ const { routes, activities, models, cache, policy, classifiers, context, subagents } = file;
430
449
  if (routes !== undefined) {
431
450
  checkObject(routes, 'routes', TIERS);
432
451
  for (const [tier, route] of Object.entries(routes)) checkObject(route, `routes.${tier}`, ROUTE_KEYS);
@@ -459,6 +478,10 @@ function checkShape(file) {
459
478
  for (const [id, entry] of Object.entries(classifiers)) checkObject(entry, `classifiers.${id}`, CLASSIFIER_KEYS);
460
479
  }
461
480
  if (context !== undefined) checkObject(context, 'context', Object.keys(DEFAULTS.context));
481
+ if (subagents !== undefined) {
482
+ checkObject(subagents, 'subagents', Object.keys(DEFAULTS.subagents));
483
+ if (subagents.types !== undefined) checkObject(subagents.types, 'subagents.types');
484
+ }
462
485
  }
463
486
 
464
487
  // `allowed` null: an open map.
@@ -518,6 +541,19 @@ function validate(config) {
518
541
  for (const [id, entry] of Object.entries(config.classifiers)) validateClassifier(`classifiers.${id}`, entry);
519
542
  if (typeof config.classifier !== 'string' || !Object.hasOwn(config.classifiers, config.classifier))
520
543
  throw new Error('classifier is not in classifiers');
544
+ if (!SUBAGENT_MODES.includes(config.subagentRouting))
545
+ throw new Error(`subagentRouting must be one of ${SUBAGENT_MODES.join(', ')}`);
546
+ const { subagents } = config;
547
+ for (const [type, route] of Object.entries(subagents.types)) {
548
+ if (route !== null && route !== CLASSIFY && !(typeof route === 'string' && Object.hasOwn(config.models, route)))
549
+ throw new Error(`subagents.types.${type} must be a models key, ${CLASSIFY} or null`);
550
+ }
551
+ for (const field of ['light', 'standard', 'heavy']) {
552
+ if (!(typeof subagents[field] === 'string' && Object.hasOwn(config.models, subagents[field])))
553
+ throw new Error(`subagents.${field} is not in models`);
554
+ }
555
+ if (!(isNumber(subagents.heavyMass, 0) && subagents.heavyMass <= 1))
556
+ throw new Error('subagents.heavyMass must be between 0 and 1');
521
557
  for (const field of ['recentTurns', 'maxTextChars']) {
522
558
  if (!isNumber(context[field], 1, { integer: true })) throw new Error(`context.${field} must be a positive integer`);
523
559
  }
package/lib/cost.mjs CHANGED
@@ -1,7 +1,18 @@
1
1
  import { EFFORTS, routeSpec } from './config.mjs';
2
2
 
3
- export function cacheKey(modelId, effort) {
4
- return effort ? `${modelId}@${effort}` : modelId;
3
+ // Models that keep one prompt cache across effort levels with an API key or a Claude subscription
4
+ // (code.claude.com/docs/en/prompt-caching, "Changing effort level"). A dated snapshot or a `[1m]` suffix is the same
5
+ // model. `config.effortSplitsCache`, set by the hook from the session's provider, gives every effort its own cache.
6
+ const EFFORT_SHARED_CACHE = ['claude-opus-5-5', 'claude-sonnet-5-5', 'claude-haiku-5-5', 'claude-fable-5-1'];
7
+
8
+ export function effortSharesCache(config, modelId) {
9
+ if (config.effortSplitsCache || typeof modelId !== 'string') return false;
10
+ const bare = modelId.replace(/\[[^\]]*\]$/, '').replace(/-\d{8}$/, '');
11
+ return EFFORT_SHARED_CACHE.includes(bare);
12
+ }
13
+
14
+ export function cacheKey(config, modelId, effort) {
15
+ return effort && !effortSharesCache(config, modelId) ? `${modelId}@${effort}` : modelId;
5
16
  }
6
17
 
7
18
  export function clampEffort(wanted, supported) {
@@ -38,7 +49,7 @@ export function routeEffort(config, route, sentEffort) {
38
49
  }
39
50
 
40
51
  export function routeCacheKey(config, route, sentEffort) {
41
- return cacheKey(routeSpec(config, route).id, routeEffort(config, route, sentEffort));
52
+ return cacheKey(config, routeSpec(config, route).id, routeEffort(config, route, sentEffort));
42
53
  }
43
54
 
44
55
  export function isWarm(state, now, cache) {