dsh-llm-fallbacks 0.3.5 → 0.4.0

package/dist/index.d.ts

@@ -16,8 +16,9 @@
  *   cooldown + failure bookkeeping, then return
  *   `{ kind: 'retry' }` (own recovery, no `next()`).
  * - `agent/request` waterfall: apply a pending switch after `await next()`
- *   (provider/model override, inherited `reasoningEffort` dropped — the
- *   `installModelSelection` `withoutInheritedEffort` pattern); a
+ *   (provider/model override; the inherited `reasoningEffort` follows the
+ *   upstream routeChanged rule — dropped on a route change unless explicitly
+ *   named, preserved on a same-route override; spec D3); a
  *   root-origin `FallbacksChain/Auto` seed then overrides to the
  *   effective chain's first exact head (select-is-primary, plan
  *   fallbacks-virtual-chain Task 2); then the always-mode cap check (count
@@ -36,7 +37,7 @@ import { detectLegacyKeys, validateFallbacksConfig, type FallbacksConfig } from
 import { Config } from './schema.ts';
 import { resolveChain } from './chains.ts';
 import { resolveRole } from './roles.ts';
-import { FallbackStateStore } from './state.ts';
+import { FallbackStateStore, type BlockedSwitchAttempt, type EffectiveChainHead } from './state.ts';
 import { type EffectiveRolesReadback, type SeedDeclaration, type SeedDeclareOutcome, type SeedRevertOutcome } from './seeds.ts';
 /** The plugin row id mounted by the profile bundle patch. */
 export declare const name = "llm-fallbacks";
@@ -82,7 +83,9 @@ export { Config };
 /** The plugin's composition config — the `fallbacks` settings schema (spec §4). */
 export type Config = FallbacksConfig;
 export type { FallbackSwitchReason, FallbacksSwitchEventData } from './events.ts';
-export type { AgentFallbackState, FallbackStateStore, PendingSwitch, StepFailures } from './state.ts';
+export type { AgentFallbackState, BlockedSwitchAttempt, FallbackStateStore, PendingSwitch, StepFailures } from './state.ts';
+/** @internal T5 test-seam types (mirrors `BlockedSwitchAttempt`; not public API). */
+export type { ChainHeadSource, EffectiveChainHead } from './state.ts';
 export { resolveRole, type AgentLike, type Origin, } from './roles.ts';
 export { annotateCandidates, createCandidateFilter, hasWildcardEntry, resolveCandidate, resolveChain, resolveChainViews, selectCandidates, type AnnotatedCandidate, type CandidateFilterOptions, type CandidateSkipReason, type FailingModel, } from './chains.ts';
 export { defaultFallbacksConfig, detectLegacyKeys, INHERIT_ROLE_ID, ROLE_ID_PATTERN, validateFallbacksConfig, type FallbacksConfig, type FallbacksConfigLogger, type FallbacksRole, type FallbacksRoles, type FallbacksRoleRule, type FallbackStrategy, type RevertPolicy, type RecoveryPolicy, } from './config.ts';
@@ -96,6 +99,23 @@ export { presetRoles } from './presets.ts';
  * request must not grow the store) without reaching into the closure.
  */
 export declare function stateStore(ctx: Context): FallbackStateStore | undefined;
+/**
+ * @internal Test seam (mirrors `stateStore`): the per-agent blocked-switch
+ * attempts recorded by the T3 allowlist gate for the plugin applied to `ctx`
+ * (spec D1; in-memory only, issue #52). Not part of the plugin's public
+ * surface; lets tests (and the T5 gateway projection) read blocked attempts
+ * without reaching into the closure. `undefined` when no plugin is applied.
+ */
+export declare function blockedAttempts(ctx: Context): ReadonlyMap<string, BlockedSwitchAttempt> | undefined;
+/**
+ * @internal Test seam (mirrors `blockedAttempts`): the per-agent effective
+ * chain heads recorded by the T2 inject path (source `authorized` |
+ * `injected`) for the plugin applied to `ctx` (spec D4 / T2 M3). Not part
+ * of the plugin's public surface; lets tests and the T5 gateway projection
+ * read the head without reaching into the closure. `undefined` when no
+ * plugin is applied.
+ */
+export declare function chainHeads(ctx: Context): ReadonlyMap<string, EffectiveChainHead> | undefined;
 /**
  * Count durable `llm/retry` events for the current (turn, step, provider) in
  * **always mode** (ADR-2; spec §2 clause 5). Normal-mode retries belong to

package/dist/index.js

@@ -1,5 +1,4 @@
 import { createRequire } from "node:module";
-import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
 import z from "@deepseek-ai/schemastery";
 import { LlmAdapter, LlmError, createUserMessage } from "@deepseek-ai/dsh-llm";
 import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
@@ -695,6 +694,98 @@ function firstExactCandidate(all, wildcard) {
 	for (let index = 0; index < all.length; index += 1) if (!wildcard[index]) return all[index];
 }
 //#endregion
+//#region .build/host/authorized-route.js
+function completeRoute(source) {
+	if (typeof source !== "object" || source === null || typeof source.provider !== "string" || source.provider.length === 0 || typeof source.model !== "string" || source.model.length === 0) return;
+	return {
+		provider: source.provider,
+		model: source.model
+	};
+}
+function lastModelSelection(entries) {
+	if (entries === void 0) return void 0;
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
+		const candidate = entries[index];
+		if (candidate?.type !== "model/selection") continue;
+		const route = completeRoute(candidate.data);
+		if (route !== void 0) return route;
+	}
+}
+function detectAuthorizedRoute(session) {
+	const { events, requestHeader, options, inherited } = session;
+	const selected = lastModelSelection(events);
+	if (selected !== void 0) return selected;
+	const route = completeRoute(requestHeader) ?? completeRoute(options);
+	if (route === void 0) return void 0;
+	const baseline = completeRoute(inherited);
+	if (baseline !== void 0 && route.provider === baseline.provider && route.model === baseline.model) return;
+	return route;
+}
+//#endregion
+//#region .build/host/route-allowlist.js
+function resolvedRoutes(candidates) {
+	const routes = [];
+	for (const candidate of candidates) {
+		if (candidate.model === void 0) continue;
+		routes.push({
+			provider: candidate.provider,
+			model: candidate.model
+		});
+	}
+	return routes;
+}
+function routeOnAllowlist(route, allowedModels) {
+	return allowedModels.some((allowed) => allowed.provider === route.provider && allowed.model === route.model);
+}
+function firstAllowedCandidate(resolved, allowedModels) {
+	return resolved.find((route) => routeOnAllowlist(route, allowedModels));
+}
+//#endregion
+//#region .build/host/subagent-policy.js
+function parseRoutes(value) {
+	if (!Array.isArray(value)) return void 0;
+	const routes = [];
+	for (const candidate of value) {
+		if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate) || !("provider" in candidate) || typeof candidate.provider !== "string" || candidate.provider.length === 0 || !("model" in candidate) || typeof candidate.model !== "string" || candidate.model.length === 0) return;
+		routes.push({
+			provider: candidate.provider,
+			model: candidate.model
+		});
+	}
+	return routes;
+}
+function readSessionPolicyEvent(events) {
+	const event = events.find((candidate) => candidate.type === "subagent/model-selection-policy");
+	if (event === void 0) return {
+		ok: false,
+		present: false
+	};
+	const data = event.data;
+	const routes = parseRoutes(typeof data === "object" && data !== null && "allowedModels" in data ? data.allowedModels : void 0);
+	if (routes === void 0 || routes.length === 0) return {
+		ok: false,
+		present: true
+	};
+	return {
+		ok: true,
+		allowedModels: routes
+	};
+}
+function effectivePolicy(event, settings) {
+	if (event.ok) return {
+		state: "enabled",
+		allowedModels: event.allowedModels
+	};
+	if (event.present) return { state: "unprovable" };
+	if (settings === void 0 || settings.enabled !== true) return { state: "disabled" };
+	const routes = parseRoutes(settings.allowedModels);
+	if (routes === void 0 || routes.length === 0) return { state: "unprovable" };
+	return {
+		state: "enabled",
+		allowedModels: routes
+	};
+}
+//#endregion
 //#region .build/host/cooldown.js
 var CooldownStore = class {
 	entries = new Map();
@@ -839,8 +930,29 @@ var FallbackStateStore = class {
 	}
 };
 //#endregion
+//#region .build/host/override.js
+function overrideConfigWithRouteRule(seed, to, explicitEffort) {
+	if (explicitEffort !== void 0) return {
+		...seed,
+		reasoningEffort: explicitEffort,
+		provider: to.provider,
+		model: to.model
+	};
+	if (!(to.provider !== seed.provider || to.model !== seed.model)) return {
+		...seed,
+		provider: to.provider,
+		model: to.model
+	};
+	const { reasoningEffort: _routeOwned, ...withoutRouteOwnedEffort } = seed;
+	return {
+		...withoutRouteOwnedEffort,
+		provider: to.provider,
+		model: to.model
+	};
+}
+//#endregion
 //#region .build/host/gateway.js
-const FALLBACKS_SETTINGS_NAMESPACE = settingsNamespace("fallbacks");
+const FALLBACKS_SETTINGS_NAMESPACE = "fallbacks";
 const CONFIG_KEYS = {
 	enabled: true,
 	triggerCodes: true,
@@ -874,10 +986,12 @@ var FallbacksConfigGateway = class extends TypertRemoteService {
 	bridge;
 	seeds;
 	settings;
-	constructor(ctx, bridge, seeds) {
+	subagentPolicy;
+	constructor(ctx, bridge, seeds, subagentPolicy) {
 		super(ctx, "fallbacks");
 		this.bridge = bridge;
 		this.seeds = seeds;
+		this.subagentPolicy = subagentPolicy;
 		ctx.inject(["settings"], (sctx) => {
 			this.settings = sctx.settings;
 			return () => {
@@ -923,11 +1037,14 @@ var FallbacksConfigGateway = class extends TypertRemoteService {
 	}
 	readResult() {
 		const source = this.bridge.source();
-		return {
+		const result = {
 			config: this.readConfig(source),
 			legacyKeys: detectLegacyKeys(source),
 			seeds: this.seeds.wireStatus(this.seedsIo())
 		};
+		const projected = projectSubagentPolicy(this.subagentPolicy);
+		if (projected !== void 0) result.subagentPolicy = projected;
+		return result;
 	}
 	seedsIo() {
 		const settings = this.settings;
@@ -940,6 +1057,41 @@ var FallbacksConfigGateway = class extends TypertRemoteService {
 		};
 	}
 };
+function projectSubagentPolicy(snapshot) {
+	if (snapshot === void 0) return void 0;
+	let captured;
+	try {
+		captured = snapshot();
+	} catch {
+		return { state: "unprovable" };
+	}
+	const { policy, head, blockedAttempt } = captured;
+	if (policy.state === "disabled") return { state: "disabled" };
+	if (policy.state === "unprovable") return { state: "unprovable" };
+	const wire = {
+		state: "enabled",
+		allowedModels: policy.allowedModels.map((route) => ({
+			provider: route.provider,
+			model: route.model
+		}))
+	};
+	if (head !== void 0) wire.head = {
+		route: {
+			provider: head.route.provider,
+			model: head.route.model
+		},
+		source: head.source
+	};
+	if (blockedAttempt !== void 0) wire.blockedAttempt = {
+		at: blockedAttempt.at,
+		route: {
+			provider: blockedAttempt.route.provider,
+			model: blockedAttempt.route.model
+		},
+		reason: blockedAttempt.reason
+	};
+	return wire;
+}
 function normalizeRoles(value) {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) return value;
 	const roles = {};
@@ -2040,6 +2192,15 @@ var FallbacksChainAdapter = class extends LlmAdapter {
 			name: model
 		};
 	}
+	imageRequestPricing(_provider, _model) {
+		try {
+			const head = effectiveHeadOf(this.readConfig(), new Date());
+			if (head === void 0 || head.provider === "FallbacksChain") return void 0;
+			return this.getLlm()?.imageRequestPricing(head.provider, head.model);
+		} catch {
+			return;
+		}
+	}
 	stream(options) {
 		const config = this.readConfig();
 		const now = new Date();
@@ -2101,6 +2262,19 @@ const stateStores = new WeakMap();
 function stateStore(ctx) {
 	return stateStores.get(ctx);
 }
+const blockedAttemptStores = new WeakMap();
+function blockedAttempts(ctx) {
+	return blockedAttemptStores.get(ctx);
+}
+const chainHeadStores = new WeakMap();
+function chainHeads(ctx) {
+	return chainHeadStores.get(ctx);
+}
+function latestByAt(map) {
+	let latest;
+	for (const value of map.values()) if (latest === void 0 || value.at >= latest.at) latest = value;
+	return latest;
+}
 async function makeModelExists(ctx, providers) {
 	const llm = ctx.get("llm");
 	if (llm === void 0 || typeof llm.listModels !== "function") return () => true;
@@ -2117,7 +2291,7 @@ async function makeModelExists(ctx, providers) {
 }
 function countRetryEvents(session, turn, step, provider) {
 	let count = 0;
-	const events = session.events;
+	const events = session.snapshotEvents();
 	for (let index = events.length - 1; index >= 0; index -= 1) {
 		const event = events[index];
 		const data = event.data;
@@ -2137,12 +2311,49 @@ function slotWinnerKey(winner) {
 	if (winner === "all-day") return "all-day";
 	return winner.kind === "preset" ? `preset:${winner.preset}` : `custom:${winner.start}-${winner.end}`;
 }
-function overrideConfig(seed, to) {
-	const { reasoningEffort: _inherited, ...withoutInheritedEffort } = seed;
+function overrideConfig(seed, to, explicitEffort) {
+	return overrideConfigWithRouteRule(seed, to, explicitEffort);
+}
+function readSubagentSettings(ctx) {
+	const service = ctx.get("subagentModelSelection");
+	return service === void 0 ? void 0 : service.current();
+}
+function readGuardedPolicySettings(ctx, agentId, lastKnown, warn) {
+	try {
+		const service = ctx.get("subagentModelSelection");
+		if (service === void 0) return {
+			ok: true,
+			settings: lastKnown.get(agentId)
+		};
+		const settings = service.current();
+		lastKnown.set(agentId, settings);
+		return {
+			ok: true,
+			settings
+		};
+	} catch (error) {
+		warn("llm-fallbacks: agent \"%s\" subagent model-selection settings read failed — %s", agentId, error?.message ?? String(error));
+		const known = lastKnown.get(agentId);
+		return known === void 0 ? { ok: false } : {
+			ok: true,
+			settings: known
+		};
+	}
+}
+function authorizedRouteView(ctx, agent) {
+	const header = agent.session?.header;
+	const parentId = header?.origin === "subagent" ? header.parentSession : void 0;
+	const parent = parentId === void 0 ? void 0 : ctx.get("agents")?.get(parentId);
+	const parentHeader = parent?.session.requestHeader()?.config;
+	const parentOptions = parent?.options;
 	return {
-		...withoutInheritedEffort,
-		provider: to.provider,
-		model: to.model
+		requestHeader: agent.session?.requestHeader()?.config,
+		events: agent.session?.snapshotEvents(),
+		options: agent.options,
+		inherited: parentHeader ?? (typeof parentOptions?.provider === "string" && typeof parentOptions?.model === "string" ? {
+			provider: parentOptions.provider,
+			model: parentOptions.model
+		} : void 0)
 	};
 }
 function apply(ctx, config = defaultFallbacksConfig) {
@@ -2191,21 +2402,40 @@ function apply(ctx, config = defaultFallbacksConfig) {
 	if (legacyKeys.length > 0) logger.warn("llm-fallbacks: legacy config keys detected (chains/roles.default/undeclared role refs); see docs/configuration.md migration table — %o", legacyKeys);
 	let roleIds = new Map(entry.roles.list.map((role) => [role.id.trim(), role.id]));
 	let hasChains = entry.rootChain.length > 0 || entry.roles.list.some((role) => (role.chain?.length ?? 0) > 0);
-	installSettingsSection(ctx, FALLBACKS_SETTINGS_NAMESPACE, Config, entry, {
-		setSource: (current) => {
-			source = current;
-		},
-		onChange: () => {
-			const current = source();
-			roleIds = new Map(current.roles.list.map((role) => [role.id.trim(), role.id]));
-			hasChains = current.rootChain.length > 0 || current.roles.list.some((role) => (role.chain?.length ?? 0) > 0);
-			reconcileFallbacksAdapter();
-			slotWinners.clear();
-		}
+	ctx.inject(["settings"], (sctx) => {
+		sctx.settings.installSection(ctx, FALLBACKS_SETTINGS_NAMESPACE, Config, entry, {
+			setSource: (current) => {
+				source = current;
+			},
+			onChange: () => {
+				const current = source();
+				roleIds = new Map(current.roles.list.map((role) => [role.id.trim(), role.id]));
+				hasChains = current.rootChain.length > 0 || current.roles.list.some((role) => (role.chain?.length ?? 0) > 0);
+				reconcileFallbacksAdapter();
+				slotWinners.clear();
+			}
+		});
 	});
 	const bridge = { source: () => source() };
+	const chainHeadMap = new Map();
+	chainHeadStores.set(ctx, chainHeadMap);
+	const blockedAttemptMap = new Map();
+	blockedAttemptStores.set(ctx, blockedAttemptMap);
 	try {
-		new FallbacksConfigGateway(ctx, bridge, seeds);
+		new FallbacksConfigGateway(ctx, bridge, seeds, () => {
+			try {
+				return {
+					policy: effectivePolicy({
+						ok: false,
+						present: false
+					}, readSubagentSettings(ctx)),
+					head: latestByAt(chainHeadMap),
+					blockedAttempt: latestByAt(blockedAttemptMap)
+				};
+			} catch {
+				return { policy: { state: "unprovable" } };
+			}
+		});
 	} catch (error) {
 		if (!(error instanceof Error) || !error.message.includes("has been registered")) throw error;
 		ctx.logger("llm-fallbacks").debug("fallbacks gateway already registered — no gateway on this fiber (multi-fiber dedupe)");
@@ -2223,6 +2453,7 @@ function apply(ctx, config = defaultFallbacksConfig) {
 	stateStores.set(ctx, states);
 	const dispatchInjected = new Set();
 	const slotWinners = new Map();
+	const lastKnownPolicySettings = new Map();
 	async function decide(agent, turn, step, current, reason, state) {
 		const config = source();
 		if (state !== void 0) {
@@ -2241,8 +2472,40 @@ function apply(ctx, config = defaultFallbacksConfig) {
 			cooldown,
 			failed
 		}), modelExists);
-		const target = surviving[0];
-		if (target === void 0 || target.model === void 0) return null;
+		const first = surviving[0];
+		let target;
+		if (first !== void 0 && first.model !== void 0) target = {
+			provider: first.provider,
+			model: first.model
+		};
+		if (agent.session?.header?.origin === "subagent" && target !== void 0) {
+			const settingsRead = readGuardedPolicySettings(ctx, agent.id, lastKnownPolicySettings, logger.warn);
+			const policy = settingsRead.ok ? effectivePolicy(readSessionPolicyEvent(agent.session.snapshotEvents()), settingsRead.settings) : { state: "unprovable" };
+			if (policy.state === "unprovable") {
+				logger.warn("llm-fallbacks: agent \"%s\" subagent model-selection policy is on but unreadable — skipping fallback switch", agent.id);
+				return null;
+			}
+			if (policy.state === "enabled") {
+				const allowed = firstAllowedCandidate(resolvedRoutes(surviving), policy.allowedModels);
+				if (allowed === void 0) {
+					logger.warn("llm-fallbacks: agent \"%s\" fallback switch %s/%s blocked: resolved candidates are all outside the subagent allowlist — no switch", agent.id, target.provider, target.model);
+					blockedAttemptMap.set(agent.id, {
+						at: Date.now(),
+						route: {
+							provider: target.provider,
+							model: target.model
+						},
+						reason
+					});
+					return null;
+				}
+				target = {
+					provider: allowed.provider,
+					model: allowed.model
+				};
+			}
+		}
+		if (target === void 0) return null;
 		if ((source().recovery ?? "timer") === "half-open" && state !== void 0 && state.recovery.tryMarkProbeLogged(selectorKey(target.provider, target.model))) logger.info("llm-fallbacks: agent \"%s\" half-open probe %s/%s (role=%s, reason=%s)", agent.id, target.provider, target.model, role, reason);
 		logger.info("llm-fallbacks: agent \"%s\" fallback switch (降级切换) %s/%s -> %s/%s (role=%s, reason=%s, candidates=%o)", agent.id, current.provider, current.model, target.provider, target.model, role, reason, annotateCandidates(all, surviving, {
 			current,
@@ -2329,21 +2592,54 @@ function apply(ctx, config = defaultFallbacksConfig) {
 		if (config.enabled && hasChains && agent.session?.header?.origin === "subagent" && !dispatchInjected.has(agent.id)) {
 			dispatchInjected.add(agent.id);
 			try {
-				const role = await resolveRoleAtDispatch(agent, config.roles.rules, roleIds, {
-					automatchEnabled: config.roleAutoMatch ?? true,
-					automatch: (agent) => pickRoleByLlm(ctx, config.roles, agent, { warn: logger.warn }),
-					warn: logger.warn
-				});
-				if (role !== "inherit") {
-					const { all, wildcard } = resolveChainViews(config.roles.list, config.rootChain, role, seed.provider, seed.model, logger.warn);
-					const head = firstExactCandidate(all, wildcard);
-					if (head !== void 0 && head.model !== void 0 && !(head.provider === seed.provider && head.model === seed.model)) {
-						const to = {
-							provider: head.provider,
-							model: head.model
-						};
-						logger.info("llm-fallbacks: agent \"%s\" role-inject role=%s model=%s/%s", agent.id, role, head.provider, head.model);
-						return overrideConfig(seed, to);
+				const settingsRead = readGuardedPolicySettings(ctx, agent.id, lastKnownPolicySettings, logger.warn);
+				const policy = settingsRead.ok ? effectivePolicy(readSessionPolicyEvent(agent.session.snapshotEvents()), settingsRead.settings) : { state: "unprovable" };
+				if (policy.state === "unprovable") logger.warn("llm-fallbacks: agent \"%s\" subagent model-selection policy is on but unreadable — skipping role-inject", agent.id);
+				else {
+					const authorized = policy.state === "enabled" ? detectAuthorizedRoute(authorizedRouteView(ctx, agent)) : void 0;
+					if (authorized !== void 0) {
+						chainHeadMap.set(agent.id, {
+							at: Date.now(),
+							route: {
+								provider: authorized.provider,
+								model: authorized.model
+							},
+							source: "authorized"
+						});
+						logger.info("llm-fallbacks: agent \"%s\" authorized child route %s/%s is the chain head — skipping role-inject", agent.id, authorized.provider, authorized.model);
+					} else {
+						const role = await resolveRoleAtDispatch(agent, config.roles.rules, roleIds, {
+							automatchEnabled: config.roleAutoMatch ?? true,
+							automatch: (agent) => pickRoleByLlm(ctx, config.roles, agent, { warn: logger.warn }),
+							warn: logger.warn
+						});
+						if (role !== "inherit") {
+							const { all, wildcard } = resolveChainViews(config.roles.list, config.rootChain, role, seed.provider, seed.model, logger.warn);
+							let to;
+							if (policy.state === "enabled") {
+								const routes = resolvedRoutes(all);
+								to = firstAllowedCandidate(routes, policy.allowedModels);
+								if (to === void 0 && routes.length > 0) logger.warn("llm-fallbacks: agent \"%s\" role-inject candidates are all outside the subagent allowlist — skipping inject (host seed stands)", agent.id);
+							} else {
+								const head = firstExactCandidate(all, wildcard);
+								if (head !== void 0 && head.model !== void 0) to = {
+									provider: head.provider,
+									model: head.model
+								};
+							}
+							if (to !== void 0 && !(to.provider === seed.provider && to.model === seed.model)) {
+								if (policy.state === "enabled") chainHeadMap.set(agent.id, {
+									at: Date.now(),
+									route: {
+										provider: to.provider,
+										model: to.model
+									},
+									source: "injected"
+								});
+								logger.info("llm-fallbacks: agent \"%s\" role-inject role=%s model=%s/%s", agent.id, role, to.provider, to.model);
+								return overrideConfig(seed, to);
+							}
+						}
 					}
 				}
 			} catch (error) {
@@ -2377,6 +2673,9 @@ function apply(ctx, config = defaultFallbacksConfig) {
 		states.delete(agent.id);
 		dispatchInjected.delete(agent.id);
 		slotWinners.delete(agent.id);
+		blockedAttemptMap.delete(agent.id);
+		chainHeadMap.delete(agent.id);
+		lastKnownPolicySettings.delete(agent.id);
 	});
 	ctx.on("session/event", (session, event) => {
 		if (event.type !== "assistant/message") return;
@@ -2392,6 +2691,9 @@ function apply(ctx, config = defaultFallbacksConfig) {
 		states.clear();
 		dispatchInjected.clear();
 		slotWinners.clear();
+		blockedAttemptMap.clear();
+		chainHeadMap.clear();
+		lastKnownPolicySettings.clear();
 	}, "llm-fallbacks: clear per-agent state");
 	const fallbacksCommandController = {
 		getSnapshot(agent) {
@@ -2405,7 +2707,7 @@ function apply(ctx, config = defaultFallbacksConfig) {
 				role,
 				...resolveChainForDiagnostic(config.roles.list, config.rootChain, role, logger.warn),
 				slot: resolveSlotState(config, new Date(), config.tz ?? "Asia/Shanghai"),
-				switches: recentFallbacksSwitches(agent.session.events, 5),
+				switches: recentFallbacksSwitches(agent.session.snapshotEvents(), 5),
 				cooldown: state === void 0 ? [] : recovery === "half-open" ? [...state.cooldown.snapshot(), ...state.recovery.halfOpenEntries().map((entry) => ({
 					key: entry.key,
 					untilEpochMs: entry.untilEpochMs,
@@ -2469,4 +2771,4 @@ function apply(ctx, config = defaultFallbacksConfig) {
 	});
 }
 //#endregion
-export { Config, FallbacksSeedManager, INHERIT_ROLE_ID, ROLE_ID_PATTERN, SelectorError, annotateCandidates, apply, countRetryEvents, createCandidateFilter, defaultFallbacksConfig, detectLegacyKeys, hasWildcardEntry, name, parseSelector, presetRoles, provide, resolveCandidate, resolveChain, resolveChainViews, resolveRole, selectCandidates, stateStore, validateFallbacksConfig };
+export { Config, FallbacksSeedManager, INHERIT_ROLE_ID, ROLE_ID_PATTERN, SelectorError, annotateCandidates, apply, blockedAttempts, chainHeads, countRetryEvents, createCandidateFilter, defaultFallbacksConfig, detectLegacyKeys, hasWildcardEntry, name, parseSelector, presetRoles, provide, resolveCandidate, resolveChain, resolveChainViews, resolveRole, selectCandidates, stateStore, validateFallbacksConfig };

package/dist/override.d.ts

@@ -0,0 +1,39 @@
+/**
+ * RouteChanged effort rule for config overrides (plan dsh-012-subagent-routing
+ * T4; spec D3).
+ *
+ * Pure, host-free module: plain seed config plus a target route in, the
+ * overridden config out. The effort handling mirrors the upstream
+ * `resolveChildAgentOptions` rule (deepseek-harness
+ * `subagent/src/child-agent.ts:117`): a changed provider+model route drops the
+ * seed's route-owned `reasoningEffort` so the selected model resolves its own
+ * default, unless an effort is explicitly named for the override; an
+ * unchanged route keeps the seed effort. Policy-independent by design — the
+ * same rule applies on every override path whether the subagent routing
+ * policy is on or off (spec D3). Never throws.
+ *
+ * @module dsh-llm-fallbacks/override
+ */
+import type { LlmCallConfig } from '@deepseek-ai/dsh-llm';
+/** Reasoning-effort value carried by `LlmCallConfig.reasoningEffort`. */
+export type LlmReasoningEffort = NonNullable<LlmCallConfig['reasoningEffort']>;
+/**
+ * Override a request config with a target route under the upstream
+ * routeChanged effort rule (spec D3):
+ *
+ * - An explicitly named effort always survives — it wins over the seed effort
+ *   on either route (upstream semantics: the request overrides the parent).
+ * - Same provider+model route → the seed `reasoningEffort` is preserved.
+ * - Route changed without an explicit effort → the seed effort is dropped
+ *   (never carry a stale effort into a different provider/model route).
+ *
+ * @param seed - the caller's current request config.
+ * @param to - the effective target route.
+ * @param explicitEffort - an effort explicitly named for this override.
+ * @returns a fresh config routed to `to` with the effort rule applied; never
+ * mutates `seed`.
+ */
+export declare function overrideConfigWithRouteRule(seed: LlmCallConfig, to: {
+    provider: string;
+    model: string;
+}, explicitEffort?: LlmReasoningEffort): LlmCallConfig;

package/dist/route-allowlist.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Route identity and allowlist intersection on resolved candidates (plan
+ * dsh-012-subagent-routing T2; spec D1 ∩ D2).
+ *
+ * Pure, host-free module: plain route data in, results out. Route identity is
+ * the EXACT provider string plus the EXACT model string — no aliasing, no
+ * case-folding, no catalog-id substitution (spec Terms). Intersections run on
+ * RESOLVED candidates (concrete provider+model after the chain candidate
+ * pipeline); this module never resolves chains or expands wildcards — the
+ * caller passes already-resolved candidates in.
+ *
+ * Fail-closed direction: an empty allowlist contains nothing and an empty
+ * intersection yields `undefined` — the caller must skip the
+ * plugin-originated route rather than fall back to an unproven one (spec D1).
+ * Never throws.
+ *
+ * @module dsh-llm-fallbacks/route-allowlist
+ */
+import type { PolicyRoute } from './subagent-policy.ts';
+/** One resolved chain candidate: a selector anchored to a concrete model id. */
+export type ResolvedCandidate = {
+    readonly provider: string;
+    readonly model?: string;
+};
+/**
+ * Normalize resolved chain candidates into detached plain routes. Candidates
+ * without a concrete model id are dropped (they are not routes); every
+ * surviving entry is a fresh object, so the result never aliases the
+ * caller's candidate list.
+ */
+export declare function resolvedRoutes(candidates: readonly ResolvedCandidate[]): PolicyRoute[];
+/**
+ * Whether the route is on the allowlist under exact route identity: both the
+ * provider and the model strings must equal an allowed route exactly.
+ */
+export declare function routeOnAllowlist(route: PolicyRoute, allowedModels: readonly PolicyRoute[]): boolean;
+/**
+ * The first resolved candidate that is on the allowlist, preserving the
+ * candidate order (the chain's first in-allowlist entry wins), or `undefined`
+ * when the intersection is empty — the caller then skips the inject / switch
+ * and the host seed stands (spec D1 ∩ D2).
+ */
+export declare function firstAllowedCandidate(resolved: readonly PolicyRoute[], allowedModels: readonly PolicyRoute[]): PolicyRoute | undefined;