dsh-switchman 1.7.1 → 1.8.1

package/host/config.js

@@ -12,6 +12,7 @@
  * - pool/rank    dispatch pools and capability ranking (Phase 2)
  * - wm*          context watermark control (Phase 3)
  * - teams*       Agent Teams doctrine mode + whitelist sync (teams mode)
+ * - intent*      intent-routing "auto" pseudo-model (classifier + candidates)
  *
  * Ported from opencode-switchman's opencode-switchman.jsonc surface
  * (oc/src/config.ts:23-51, oc/src/types.ts:281-344) onto DSH settings.
@@ -44,6 +45,34 @@ export const EffortEntrySchema = z.object({
 	effort: z.string().min(1).required(),
 });
 
+/** One intent-routing candidate: a real model route the classifier may pick,
+ *  plus an optional reasoning-effort pin and a capability note the classifier
+ *  reads. Every row carries a stable id; preset rows (id owned by
+ *  host/intent-presets.js) keep a code-owned immutable note, while enabled /
+ *  provider / model / effort are user-configured — provider/model may be
+ *  empty while a preset waits for its route. effort/note follow
+ *  RankEntrySchema.tier's optional style (no `.required()`: schemastery
+ *  passes undefined through, so entries may omit either key). */
+export const IntentCandidateSchema = z.object({
+	id: z.string(),
+	preset: z.boolean(),
+	enabled: z.boolean(),
+	provider: z.string(),
+	model: z.string(),
+	effort: z.string(),
+	note: z.string(),
+});
+
+/** One intent-layer route reference (classifier or fallback). Unlike
+ *  ModelRouteSchema this accepts the "unset" `{provider:"", model:""}`
+ *  pair the settings page round-trips — ModelRouteSchema's `.min(1)`
+ *  would reject that exact declared default on every settings write.
+ *  Consumers validate non-empty before trusting the route. */
+const IntentRouteSchema = z.object({
+	provider: z.string(),
+	model: z.string(),
+});
+
 /** All dsh-switchman settings. Field names are the settings mutation paths. */
 export const Config = z.object({
 	// --- Phase 0: UI locale ------------------------------------------------
@@ -99,13 +128,13 @@ export const Config = z.object({
 
 	// --- Phase 3: context watermark control --------------------------------
 	/** Soft watermark: advisory banner + delegation nudge (tokens). */
-	wmSoftTokens: z.number().min(1000).default(50000).volatile(),
+	wmSoftTokens: z.number().min(1000).default(80000).volatile(),
 	/** Hard watermark: read budget tightens, wrap-up advised (tokens). */
-	wmHardTokens: z.number().min(2000).default(90000).volatile(),
+	wmHardTokens: z.number().min(2000).default(120000).volatile(),
 	/** Force watermark: backup + compaction handover (tokens). */
-	wmForceTokens: z.number().min(3000).default(130000).volatile(),
+	wmForceTokens: z.number().min(3000).default(150000).volatile(),
 	/** Per-call read budget for read/glob/grep (tokens). */
-	wmReadBudgetTokens: z.number().min(200).default(1500).volatile(),
+	wmReadBudgetTokens: z.number().min(200).default(3000).volatile(),
 	/** Hard-tier behavior: cap reads and advise, or deny outright. */
 	wmDenyMode: z.union(["cap", "deny"]).default("cap").volatile(),
 	/** Force tier triggers backup + compaction automatically. */
@@ -132,6 +161,66 @@ export const Config = z.object({
 	 *  wholesale. The whitelist only applies to top-level sessions composed
 	 *  afterwards. */
 	syncWhitelist: z.boolean().default(false).volatile(),
+
+	// --- Intent recognition: classifier-routed "auto" model ----------------
+	/** Master switch for intent routing (design: .dsh-switchman/plans/
+	 *  intent-routing.md §2). The adapter stays mounted either way; OFF
+	 *  only hides the catalog entry (listModels returns [], the selector
+	 *  drops the empty group) — a session already on Auto routes through
+	 *  the documented fallback chain (routedCurrent → intentFallbackRoute
+	 *  → first candidate) with NO classifier call. */
+	intentEnabled: z.boolean().default(false).volatile(),
+	/** Small-model route that classifies the conversation against the
+	 *  candidates. Empty = unset; classification is skipped (fail-open). */
+	intentClassifierRoute: IntentRouteSchema.default({ provider: "", model: "" }).volatile(),
+	/** Optional reasoning-effort pin for the classifier call ("" = adapter
+	 *  default). */
+	intentClassifierEffort: z.string().default("").volatile(),
+	/** Classifier channel; must be an explicit choice. "chat" calls the
+	 *  intentClassifierRoute above through its provider's standard chat
+	 *  API with a strict-JSON instruction. "systemone" = direct HTTP to a
+	 *  hand-configured ollama /v1/systemone decision endpoint — no
+	 *  provider, uses intentClassifierEndpoint +
+	 *  intentClassifierSystemoneModel. */
+	intentClassifierKind: z.union(["chat", "systemone"]).default("chat").volatile(),
+	/** Full URL of the ollama /v1/systemone endpoint for kind "systemone"
+	 *  (e.g. http://127.0.0.1:11434/v1/systemone). Empty = unset; that
+	 *  kind fails open to the fallback chain. */
+	intentClassifierEndpoint: z.string().default("").volatile(),
+	/** Model name sent to the decision endpoint for kind "systemone"
+	 *  (free text, e.g. tev1:4b-mxfp8). Independent of the llm provider
+	 *  catalog — no provider registration needed. Empty = unset; that
+	 *  kind fails open to the fallback chain. */
+	intentClassifierSystemoneModel: z.string().default("").volatile(),
+	/** Independent candidate list the "auto" pseudo-model may route to (NOT
+	 *  poolMain). Each entry: {id, preset?, enabled?, provider, model,
+	 *  effort?, note?}; readers merge the built-in presets from
+	 *  host/intent-presets.js (see mergeIntentCandidates). */
+	intentCandidates: z.array(IntentCandidateSchema).default([]).volatile(),
+	/** Provider prompt-cache reuse window: while the current route stays
+	 *  below the switch-confidence threshold, keep it for this many
+	 *  seconds since the last applied routing. */
+	intentCacheTtlSeconds: z.number().min(0).default(300).volatile(),
+	/** Classifier confidence (0-100) required to leave the current model. */
+	intentSwitchConfidence: z.number().min(0).max(100).default(80).volatile(),
+	/** Classification-call budget in ms; timeout/abort fails open to the
+	 *  fallback chain. */
+	intentTimeoutMs: z.number().min(200).default(60000).volatile(),
+	/** Recent user/assistant messages fed to the classifier. */
+	intentHistoryMessages: z.number().min(1).max(20).default(6).volatile(),
+	/** Total character budget for that conversation excerpt. */
+	intentHistoryMaxChars: z.number().min(200).max(20000).default(2400).volatile(),
+	/** Context window (tokens) declared by the "auto" pseudo-model. Purely
+	 *  advisory metadata: drives the usage popover and the auto-compaction
+	 *  pressure math for sessions routed through Auto. While wmAutoHandover
+	 *  is on, the effective declared value is floored at
+	 *  ceil(wmForceTokens / 0.8) so the smooth handover always fires before
+	 *  the 0.8×-window auto-compaction (see effectiveContextWindow in
+	 *  host/intent.js). */
+	intentContextWindow: z.number().min(1024).default(200000).volatile(),
+	/** Optional last-resort route when the classifier fails and no previous
+	 *  routed model exists; empty = the first candidate. */
+	intentFallbackRoute: IntentRouteSchema.default({ provider: "", model: "" }).volatile(),
 });
 
 /** The six dispatch lanes, in display order. */

package/host/context-watch.js

@@ -4,11 +4,17 @@
  * src/index.ts:386-459 (banner rendering) and 2066-2110 (auto-handover with
  * its anti-deadlock lesson) onto DSH services:
  *
- * - One dynamic systemPrompt section 'switchman:watermark' (order 10500)
- *   renders the `[SWITCHMAN:WATERMARK]` banner from the live token meter
- *   (ctx.tokenMeter.measure(agent.session).totalTokens). Root sessions get
- *   the tiered banner (ok/soft/hard/force/paused); subagent sessions get a
- *   compact cap-aware banner. The text function is side-effect free.
+ * - KV-cache invariant: the systemPrompt section 'switchman:watermark'
+ *   (order 10500) carries only byte-stable protocol text (root/subagent
+ *   variants, no live numbers), so the request head never changes
+ *   mid-session; the live tier + bucketed used reading travel as the
+ *   'switchman:watermark' runtime context (ctx.systemPrompt.context,
+ *   order 300, required) — DSH renders contexts into the tail-appended
+ *   "Current runtime context" snapshot, which is emitted as a new trailing
+ *   user message only when its text changes, preserving the cached prefix
+ *   by construction. Root sessions get tiers ok (silent)/soft/hard/force
+ *   plus a static paused line; subagent sessions get soft/hard/force with
+ *   their own force cap. Both text functions are side-effect free.
  * - Read budget double gate: `tools/post-execute` accounts read/glob/grep/
  *   bash result text (~len/3.5 tokens) per session per turn; `tools/
  *   pre-execute` denies or caps read/glob/grep once the budget is exhausted
@@ -133,9 +139,9 @@ function isRoot(ctx, agent) {
 /** Live threshold snapshot from the volatile settings. */
 function readThresholds(config) {
 	return {
-		soft: readNumber(config.wmSoftTokens, 50000),
-		hard: readNumber(config.wmHardTokens, 90000),
-		force: readNumber(config.wmForceTokens, 130000),
+		soft: readNumber(config.wmSoftTokens, 80000),
+		hard: readNumber(config.wmHardTokens, 120000),
+		force: readNumber(config.wmForceTokens, 150000),
 	};
 }
 
@@ -150,64 +156,89 @@ function measureNow(ctx, agent) {
 	}
 }
 
-// ---- banner rendering (pure given state + measurement) ---------------------
+// ---- watermark rendering (pure given state + measurement) ------------------
 
-/** Root-session banner: byte-stable anchor line + tier advice lines plus
+/** Bucket width for the live used reading. 5k steps keep the tail snapshot
+ * emission rate low (the snapshot re-emits only when its joined text
+ * changes); tier crossings change the line immediately regardless. */
+const USED_BUCKET_TOKENS = 5000;
+
+/** `~50k`-style bucketed reading for the live watermark line. */
+function bucketKilo(tokens) {
+	return `${Math.round(tokens / USED_BUCKET_TOKENS) * (USED_BUCKET_TOKENS / 1000)}k`;
+}
+
+/** Byte-stable protocol text for root sessions: no live numbers, so the
+ * request head stays byte-identical for the whole session (KV-cache
+ * invariant); the numbers live in the tail context line only. */
+const PROTOCOL_ROOT_TEXT = [
+	"[SWITCHMAN:WATERMARK] protocol: this session is guarded by a context watermark measured every step.",
+	"ok tier is silent. soft tier: prefer delegating lightweight work (subagent/workflow) over reading more context yourself. hard tier: stop broad reading (read/glob/grep are budget-limited and may be denied) and start wrapping up. force tier: MANDATORY wrap-up now — produce the final answer from what you already hold; an automatic context handover (backup + document + compaction + continuation) may run and will tell you to end the turn.",
+	"The live tier and the bucketed used-token reading (against the soft/hard/force budget) arrive ONLY as [SWITCHMAN:WATERMARK] lines inside the appended runtime-context snapshot at the conversation tail; a tier change is announced on the step it happens. /ctx-pause pauses every watermark enforcement (measurement continues), /ctx-resume restores it, /ctx-handover starts a handover immediately.",
+].join("\n");
+
+/** Byte-stable protocol text for subagent sessions (same invariant). */
+const PROTOCOL_SUB_TEXT = [
+	"[SWITCHMAN:WATERMARK] protocol: this subagent session is guarded by a context watermark measured every step.",
+	"ok tier is silent. soft tier: keep reads narrow and drop bulky raw output. hard tier: stop broad reading; wrap toward the final summary. force tier: stop reading and return the final summary now — end the FINAL message with a HANDOFF block: completed / key findings (file:line) / remaining / next steps.",
+	"The live tier and the bucketed used-token reading arrive ONLY as [SWITCHMAN:WATERMARK] lines inside the appended runtime-context snapshot; a tier change is announced on the step it happens.",
+].join("\n");
+
+/** Static paused line (numbers omitted on purpose: enforcement is off, and a
+ * frozen string emits once and never churns the snapshot again). */
+const PAUSED_LINE =
+	"[SWITCHMAN:WATERMARK] paused — measurement continues, but every watermark enforcement stays off until /ctx-resume.";
+
+/** Root-session live line: "" at ok (token economy), tier advice lines plus
  * the live handover progress (phase/attempt) and auto-cooldown state. */
-function renderRootBanner(level, used, th, status) {
+function renderRootWatermark(level, used, th, status) {
+	if (level === "ok") return "";
 	const head =
-		`[SWITCHMAN:WATERMARK] level=${level} used=${kilo(used)}` +
-		` budget=${kilo(th.soft)}/${kilo(th.hard)}/${kilo(th.force)}`;
-	if (level === "ok") return head;
-	if (level === "paused")
-		return `${head}\nPAUSED by /ctx-pause — measurement continues, but every watermark enforcement stays off until /ctx-resume.`;
-	const lines = [head];
-	if (level === "soft") lines.push(`soft tier: prefer delegating lightweight work (subagent/workflow) over reading more context yourself.`);
-	if (level === "hard") lines.push(`hard tier: stop broad reading (read/glob/grep are budget-limited this turn) and start wrapping up.`);
-	if (level === "force") {
-		lines.push(`force tier: MANDATORY wrap-up now — produce the final answer from what you already hold.`);
-		const phase = status?.phase;
-		if (phase === "backup") {
-			lines.push(`context handover running: forking the backup session and writing the handover document…`);
-		} else if (phase === "compacting") {
-			lines.push(`context handover running: compaction attempt ${status?.attempt ?? "?"} (retries while the turn is still running)…`);
-		} else if (phase === "continuation") {
-			lines.push(`context handover completing: waking this session to fill in the document and continue the task…`);
-		} else if (status?.autoHandover) {
-			lines.push(
-				status?.cooldownMin > 0
-					? `automatic handover cooldown: ${status.cooldownMin} min left; run /ctx-handover${status?.tool ? " or call the ctx_handover tool" : ""} to force one now.`
-					: `an automatic context handover (backup + document + compaction + continuation) is armed and will fire at the next step boundary${status?.tool ? "; calling the ctx_handover tool triggers it immediately" : ""}.`,
-			);
-		} else {
-			lines.push(`run /ctx-handover${status?.tool ? " or call the ctx_handover tool" : ""} to trigger a manual context handover.`);
-		}
+		`[SWITCHMAN:WATERMARK] ${level} tier — used ~${bucketKilo(used)}` +
+		` of budget ${kilo(th.soft)}/${kilo(th.hard)}/${kilo(th.force)}`;
+	if (level === "soft") return `${head}\nsoft tier: prefer delegating lightweight work (subagent/workflow) over reading more context yourself.`;
+	if (level === "hard") return `${head}\nhard tier: stop broad reading (read/glob/grep are budget-limited this turn) and start wrapping up.`;
+	const lines = [head, "force tier: MANDATORY wrap-up now — produce the final answer from what you already hold."];
+	const phase = status?.phase;
+	if (phase === "backup") {
+		lines.push(`context handover running: forking the backup session and writing the handover document…`);
+	} else if (phase === "compacting") {
+		lines.push(`context handover running: compaction attempt ${status?.attempt ?? "?"} (retries while the turn is still running)…`);
+	} else if (phase === "continuation") {
+		lines.push(`context handover completing: waking this session to fill in the document and continue the task…`);
+	} else if (status?.autoHandover) {
+		lines.push(
+			status?.cooldownMin > 0
+				? `automatic handover cooldown: ${status.cooldownMin} min left; run /ctx-handover${status?.tool ? " or call the ctx_handover tool" : ""} to force one now.`
+				: `an automatic context handover (backup + document + compaction + continuation) is armed and will fire at the next step boundary${status?.tool ? "; calling the ctx_handover tool triggers it immediately" : ""}.`,
+		);
+	} else {
+		lines.push(`run /ctx-handover${status?.tool ? " or call the ctx_handover tool" : ""} to trigger a manual context handover.`);
 	}
 	return lines.join("\n");
 }
 
-/** Subagent-session banner: the same soft/hard/force absolute-token tiers
- *  as the root banner ("" while ok — token economy), with subagent-flavored
+/** Subagent-session live line: the same soft/hard/force absolute-token tiers
+ *  as the root line ("" while ok — token economy), with subagent-flavored
  *  advice and the HANDOFF block due at the force tier. Pausing never applies
  *  to subagents (oc index.ts:187-190). */
-function renderSubBanner(used, th) {
+function renderSubWatermark(used, th) {
 	const level = levelOf(used, th);
-	const head =
-		`[SWITCHMAN:WATERMARK] subagent level=${level} used=${kilo(used)}` +
-		` budget=${kilo(th.soft)}/${kilo(th.hard)}/${kilo(th.force)}`;
 	if (level === "ok") return "";
-	if (level === "soft")
-		return `${head}\nsoft tier: keep reads narrow and drop bulky raw output.`;
-	if (level === "hard")
-		return `${head}\nhard tier: stop broad reading; start wrapping toward the final summary.`;
+	const head =
+		`[SWITCHMAN:WATERMARK] subagent ${level} tier — used ~${bucketKilo(used)}` +
+		` of budget ${kilo(th.soft)}/${kilo(th.hard)}/${kilo(th.force)}`;
+	if (level === "soft") return `${head}\nsoft tier: keep reads narrow and drop bulky raw output.`;
+	if (level === "hard") return `${head}\nhard tier: stop broad reading; start wrapping toward the final summary.`;
 	return (
 		`${head}\nforce tier: stop reading and return the final summary now.\n` +
 		`End the FINAL message with a HANDOFF block: completed / key findings (file:line) / remaining / next steps.`
 	);
 }
 
-/** Whole banner for one assembly; "" whenever anything needed is missing. */
-function renderBanner(ctx, config, state, agent) {
+/** Whole live line for one assembly (the tail context); "" whenever anything
+ * needed is missing or the session sits at the silent ok tier. */
+function renderWatermarkContext(ctx, config, state, agent) {
 	try {
 		const sessionId = sessionIdOf(agent);
 		if (sessionId === null || agent.session === undefined) return "";
@@ -220,16 +251,18 @@ function renderBanner(ctx, config, state, agent) {
 			// (enabled by the wmSubagentCap toggle, 0/0 = follow the root set).
 			const subForce = readBool(config.wmSubagentCap, true) ? readNumber(config.wmSubagentForceTokens, 0) : 0;
 			const subTh = subForce > 0 ? { ...th, force: subForce } : th;
-			return renderSubBanner(used, subTh);
+			return renderSubWatermark(used, subTh);
 		}
-		const level = state.paused.has(sessionId) ? "paused" : levelOf(used, th);
+		if (state.paused.has(sessionId)) return PAUSED_LINE;
 		const live = handoverOf(sessionId);
 		const elapsed = Date.now() - (state.lastHandover.get(sessionId) ?? 0);
-		return renderRootBanner(level, used, th, {
+		// Cooldown quantized to 5-minute steps so the emitted line stays
+		// byte-stable between steps (snapshot re-emits only on change).
+		return renderRootWatermark(levelOf(used, th), used, th, {
 			autoHandover: readBool(config.wmAutoHandover, true),
 			phase: live?.phase,
 			attempt: live?.attempt,
-			cooldownMin: Math.max(0, Math.ceil((HANDOVER_COOLDOWN_MS - elapsed) / 60_000)),
+			cooldownMin: Math.max(0, Math.ceil((HANDOVER_COOLDOWN_MS - elapsed) / 300_000) * 5),
 			tool: state.handoverTool ?? undefined,
 		});
 	} catch {
@@ -298,13 +331,40 @@ function applyContextWatch(ctx, config) {
 	};
 	const warn = (message) => ctx.logger?.warn?.(`dsh-switchman: ${message}`);
 
-	// --- A. watermark banner -------------------------------------------------
+	// --- A. watermark: byte-stable head protocol + live tail context --------
+	// KV-cache invariant (see the file header): everything before the
+	// conversation history must stay byte-identical for the whole session,
+	// so the head section carries only static protocol text while ALL live
+	// numbers travel as runtime context. DSH joins contexts into the
+	// "Current runtime context" snapshot and appends it at the tail as a new
+	// user message only when its text changes — append-only by construction,
+	// the cached prefix is never touched.
 	ctx.systemPrompt.section({
 		name: "switchman:watermark",
 		order: 10500,
 		interpolate: false,
-		text: (context) => renderBanner(ctx, config, state, context?.agent),
+		text: (context) => (isRoot(ctx, context?.agent) ? PROTOCOL_ROOT_TEXT : PROTOCOL_SUB_TEXT),
 	});
+	// Capability check first: on a host without the runtime-context API an
+	// optional chain would short-circuit silently — the live watermark line
+	// would vanish with no log at all. Warn once so it stays diagnosable.
+	if (typeof ctx.systemPrompt?.context !== "function") {
+		warn("systemPrompt.context API unavailable on this DSH host — live watermark line disabled (static head protocol remains)");
+	} else {
+		try {
+			ctx.systemPrompt.context({
+				name: "switchman:watermark",
+				// After the core placements (WORKING_DIRECTORY 100 … WEB_SURFACE
+				// 210), so the watermark line closes the snapshot.
+				order: 300,
+				required: true,
+				interpolate: false,
+				text: (context) => renderWatermarkContext(ctx, config, state, context?.agent),
+			});
+		} catch (error) {
+			warn(`watermark context registration failed: ${error?.message ?? error}`);
+		}
+	}
 
 	// --- C. handover execution: borrow the session's own /compact -----------
 	// The desktop profile provides compaction ONLY inside each preset's
@@ -805,7 +865,7 @@ function applyContextWatch(ctx, config) {
 			if (sessionId !== null && ACCOUNT_TOOLS.has(exec?.name ?? "")) {
 				const entry = accountRead(state, sessionId, resultTokens(result));
 				if (GATED_TOOLS.has(exec.name) && !state.paused.has(sessionId)) {
-					const budget = readNumber(config.wmReadBudgetTokens, 1500);
+					const budget = readNumber(config.wmReadBudgetTokens, 3000);
 					const ceiling = budget * CEILING_MULTIPLE;
 					const used = measureNow(ctx, exec.agent);
 					const th = readThresholds(config);
@@ -841,7 +901,7 @@ function applyContextWatch(ctx, config) {
 			if (!GATED_TOOLS.has(exec?.name ?? "")) return next();
 			const sessionId = sessionIdOf(exec?.agent);
 			if (sessionId === null || state.paused.has(sessionId)) return next();
-			const budget = readNumber(config.wmReadBudgetTokens, 1500);
+			const budget = readNumber(config.wmReadBudgetTokens, 3000);
 			if (turnUsed(state, sessionId) < budget * CEILING_MULTIPLE) return next();
 			const used = measureNow(ctx, exec.agent);
 			if (used === null) return next();
@@ -957,4 +1017,12 @@ function applyContextWatch(ctx, config) {
 	}
 }
 
-export { applyContextWatch };
+export {
+	applyContextWatch,
+	bucketKilo,
+	PAUSED_LINE,
+	PROTOCOL_ROOT_TEXT,
+	PROTOCOL_SUB_TEXT,
+	renderRootWatermark,
+	renderSubWatermark,
+};

package/host/dispatch.js

@@ -7,6 +7,16 @@
  * `tools/pre-execute` waterfall listener denies `subagent` calls that name
  * a provider+model outside every configured pool and modelRank.
  *
+ * The same listener also runs an annotation sanitation pass in EVERY mode:
+ * a model id copied verbatim off the rendered table can embed its
+ * display-only `(TIER)`/`@effort` annotations (the recommendation table is
+ * the one string an LLM is most tempted to copy), which DSH's exact-match
+ * child-route whitelist then rejects with a generic binding error that
+ * pushes the caller back to implicit dispatch — silently losing the lane's
+ * route. The sanitation denies such calls with the exact corrected
+ * arguments instead (exec.arguments is deep-frozen by the runtime, so a
+ * deny is the only correction channel `tools/pre-execute` offers).
+ *
  * Model-facing text is English and byte-stable for a given configuration
  * (the anchor line never varies with UI locale). All reads go through the
  * live volatile references, so settings edits apply without a plugin
@@ -177,6 +187,103 @@ function effortMapOf(pool) {
 	return effortOf;
 }
 
+/** Trailing display annotations renderPoolsBlock appends to a pool entry:
+ *  the `(S)/(A)/(B)/(C)` capability-grade parenthetical (uppercase only —
+ *  that is what renderRoute emits), the `@effort` pin, and the
+ *  `⚠not-authorized` drift marker. */
+const TRAILING_EFFORT = /@([A-Za-z0-9._-]+)$/;
+const TRAILING_TIER = /\([SABC]\)$/;
+const TRAILING_MARKER = /\s*⚠not-authorized$/u;
+
+/** Strip every trailing display annotation from a model id
+ *  ("m(A)@high" → "m"), looped so any order reduces; an unannotated id
+ *  round-trips unchanged. */
+function stripTrailingAnnotations(model) {
+	let s = model.trim();
+	for (;;) {
+		const next = s.replace(TRAILING_MARKER, "").replace(TRAILING_EFFORT, "").replace(TRAILING_TIER, "").trim();
+		if (next === s) return s;
+		s = next;
+	}
+}
+
+/** Folded-key → first configured {provider, model} route over every lane
+ *  and modelRank — the enforce gate's matcher, factored out so the
+ *  sanitation pass shares it. Empty when nothing is configured. */
+function configuredRoutes(config) {
+	const routes = new Map();
+	const add = (route) => {
+		if (!isModelRoute(route)) return;
+		const key = normalizeModelKey(route.provider, route.model);
+		if (key !== "" && !routes.has(key)) routes.set(key, { provider: route.provider, model: route.model });
+	};
+	for (const lane of LANES) for (const route of readList(config[laneField(lane)])) add(route);
+	for (const entry of readList(config.modelRank)) add(entry);
+	return routes;
+}
+
+/** First effort pin configured for one folded route key, across every
+ *  lane's effort list (null when the route carries no pin) — completes a
+ *  corrective hint whose copied id kept only the (TIER) annotation. */
+function configuredEffortPin(config, key) {
+	for (const lane of LANES) {
+		for (const entry of readList(config[laneEffortsField(lane)])) {
+			if (!isEffortEntry(entry)) continue;
+			if (normalizeModelKey(entry.provider, entry.model) === key) return entry.effort;
+		}
+	}
+	return null;
+}
+
+/** Corrective deny reason for one delegation call whose model argument
+ *  embeds pool-table display annotations, or null to pass through. The
+ *  stripped id must match a configured route (folded, like the enforce
+ *  gate) — an unknown id is left to DSH's own route validation, so an
+ *  exotic-but-real id that merely looks annotated never gets denied.
+ *  Covers the plain suffix copy ("m(A)", "m(A)@high"), the whole-cell copy
+ *  including the ⚠not-authorized drift marker, and the provider-combined
+ *  copy ("provider/m(A)" with provider left empty). The reasoning_effort
+ *  hint rides along when the copied string carried the @effort annotation
+ *  or the matched route holds a configured pin, and the call did not
+ *  already set reasoning_effort itself. */
+function annotationFixOf(args, config) {
+	const model = typeof args?.model === "string" ? args.model.trim() : "";
+	if (model === "") return null;
+	const providerGiven = typeof args?.provider === "string" && args.provider.trim() !== "";
+	let provider = providerGiven ? args.provider.trim() : "";
+	let modelPart = model;
+	if (!providerGiven && modelPart.includes("/")) {
+		const cut = modelPart.lastIndexOf("/");
+		provider = modelPart.slice(0, cut).trim();
+		modelPart = modelPart.slice(cut + 1).trim();
+	}
+	modelPart = modelPart.replace(TRAILING_MARKER, "").trim();
+	const effortMatch = TRAILING_EFFORT.exec(modelPart);
+	const stripped = stripTrailingAnnotations(modelPart);
+	if (stripped === modelPart || stripped === "") return null;
+	const key = normalizeModelKey(provider, stripped);
+	const matched = key === "" ? undefined : configuredRoutes(config).get(key);
+	if (matched === undefined) return null;
+	// The re-dispatch must name BOTH fields whenever the original call left
+	// provider empty (provider+model go together on these tools), even when
+	// the provider was recoverable from a combined "provider/model(…)" copy.
+	// A provider-given whole-cell copy still carries its "provider/" prefix
+	// inside the stripped id — the matched route's clean model is the only
+	// suggestion DSH's exact-match whitelist will actually accept.
+	const modelFix = stripped.includes("/") ? matched.model : stripped;
+	const fields = providerGiven
+		? `model "${modelFix}"`
+		: `provider "${provider !== "" ? provider : matched.provider}", model "${modelFix}"`;
+	const hasExplicitEffort = typeof args?.reasoning_effort === "string" && args.reasoning_effort.trim() !== "";
+	const pinned = effortMatch !== null ? effortMatch[1] : configuredEffortPin(config, key);
+	const effort = hasExplicitEffort || pinned === null ? "" : ` and reasoning_effort "${pinned}"`;
+	return (
+		`[SWITCHMAN:POOLS] the model argument "${args.model}" embeds pool-table display annotations — ` +
+		`the (S/A/B/C) capability grade and any @effort suffix are annotations, NOT parts of the model id. ` +
+		`Re-dispatch this call with ${fields}${effort}, keeping every other argument unchanged.`
+	);
+}
+
 /** The `[SWITCHMAN:POOLS]` block: anchor line, one line per configured lane,
  *  then the guidance lines (byte-stable for a given configuration). Routes
  *  outside the session's DSH-authorized child models carry a ⚠not-authorized
@@ -207,7 +314,8 @@ function renderPoolsBlock(state) {
 		`When delegating via subagent/workflow, pick a model from the lane matching the task category; spawn_teammate takes no model argument (lanes do not apply to it).`,
 		`Lanes marked * are in manual order: dispatch follows the listed order exactly (the head is the first choice).`,
 		`effort: economy=medium mechanical=medium main=medium (high for complex tasks) hard=high vision=multimodal-capable model review=high; an unconfigured lane uses the system default model.`,
-		`A route suffixed @effort has a manually pinned reasoning effort — pass it as reasoning_effort when delegating to that model (it overrides the lane default).`,
+		`Entries render as provider/model(TIER)@effort: (TIER) is the S/A/B/C capability grade and @effort a manually pinned reasoning effort — both are display-only annotations, NEVER parts of the model id.`,
+		`Decompose before dispatching: provider/model(TIER)@effort → provider=provider, model=model, reasoning_effort=effort (a pin overrides the lane default); a route without @effort carries no per-route pin — fall back to the lane's default effort above.`,
 		`Review delegations: anchor independence on the code AUTHOR's model, not the main session's (author = the agent that produced the diff: its explicit dispatch route, or the inherited session model when unspecified). Prefer a reviewer model different from the author's; also avoiding the session model is a bonus (its integration pass already covers that angle). If no pool entry differs from the author, same-model review is allowed — declare DOWNGRADED and state whether it is relative to the author or the session.`,
 		`Explicit provider/model/effort on subagent/workflow calls is validated against this session's DSH-authorized child models (DSH Settings: allow agents to choose subagent models) — NOT against this table; when denied, discover allowed routes via list_subagent_models, or dispatch implicitly by omitting all three fields (the child then uses configured defaults or inherits the parent route).`,
 	);
@@ -253,34 +361,38 @@ function applyDispatch(ctx, config) {
 		},
 	});
 
-	// Enforce gate (tools/pre-execute waterfall): deny decisions are returned
-	// directly WITHOUT calling next() — { kind: "deny", reason } — while every
-	// other path must call and return next(). Only subagent calls that name
-	// both provider and model are checked; model-less calls use the system
-	// default and pass through untouched.
+	// Annotation sanitation (every mode) + enforce gate (enforce mode only).
+	// Both are tools/pre-execute waterfall listeners in one registration:
+	// deny decisions are returned directly WITHOUT calling next() —
+	// { kind: "deny", reason } — while every other path must call and
+	// return next(). The sanitation covers subagent and subagent_fork; the
+	// enforce gate below stays subagent-only with both provider and model
+	// named; model-less calls use the system default and pass through.
 	ctx.on("tools/pre-execute", (exec, next) => {
 		try {
+			if (exec?.name !== "subagent" && exec?.name !== "subagent_fork") return next();
+			const args = exec.arguments;
+
+			// Annotation sanitation: a model id copied verbatim off the
+			// rendered table embeds its display-only (TIER)/@effort/⚠
+			// annotations; DSH's exact-match whitelist would reject it with
+			// a generic binding error that pushes the caller back to
+			// implicit dispatch, losing the lane's route. Deny with the
+			// exact corrected arguments instead — one immediate retry on
+			// the intended route.
+			const fix = annotationFixOf(args, config);
+			if (fix !== null) return { kind: "deny", reason: fix };
+
+			// Enforce gate: unchanged semantics, now sharing the factored
+			// configuredRoutes matcher (same folded keys as before).
 			if (readField(config.dispatchEnforce) !== "enforce") return next();
 			if (exec?.name !== "subagent") return next();
-			const args = exec.arguments;
 			if (typeof args?.provider !== "string" || args.provider === "") return next();
 			if (typeof args?.model !== "string" || args.model === "") return next();
 			const key = normalizeModelKey(args.provider, args.model);
 			if (key === "") return next();
 
-			const allowed = new Set();
-			for (const lane of LANES) {
-				for (const route of readList(config[laneField(lane)])) {
-					if (!isModelRoute(route)) continue;
-					const routeKey = normalizeModelKey(route.provider, route.model);
-					if (routeKey !== "") allowed.add(routeKey);
-				}
-			}
-			for (const entry of readList(config.modelRank)) {
-				if (!isModelRoute(entry)) continue;
-				const rankKey = normalizeModelKey(entry.provider, entry.model);
-				if (rankKey !== "") allowed.add(rankKey);
-			}
+			const allowed = configuredRoutes(config);
 			if (allowed.size === 0 || allowed.has(key)) return next();
 
 			const state = readDispatchState(ctx, config);