dsh-switchman 1.11.1 → 1.11.3

package/host/dispatch.js

@@ -15,7 +15,14 @@
  * 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).
+ * deny is the only correction channel `tools/pre-execute` offers). The
+ * same pass covers the field-shape failures production logs show models
+ * repeating (a merged "provider/model" string with the provider field
+ * omitted, a bare model with the provider field omitted, a model still
+ * carrying its "provider/" prefix, and a provider-less
+ * list_subagent_models call) — every such call is rejected by DSH
+ * outright, so each deny carries the exact corrected fields and turns
+ * 2-4 blind retries into one immediate re-dispatch.
  *
  * 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
@@ -284,6 +291,208 @@ function annotationFixOf(args, config) {
 	);
 }
 
+/** Every configured {provider, model} route across all lanes and
+ *  modelRank, in config order. Unlike configuredRoutes (whose folded key
+ *  is first-wins per model segment — right for route MATCHING, where
+ *  duplicates would collapse), this keeps every entry: provider-candidate
+ *  hints must see all providers offering the same model id. */
+function allConfiguredRoutes(config) {
+	const routes = [];
+	const add = (route) => {
+		if (isModelRoute(route)) routes.push(route);
+	};
+	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;
+}
+
+/** Distinct configured providers whose folded model key matches one bare
+ *  model id, in config order — completes a corrective hint for a
+ *  delegation or enumeration call that omitted the provider field. */
+function modelProviderMatches(config, model) {
+	const key = normalizeModelKey("", model);
+	if (key === "") return [];
+	const seen = new Set();
+	const providers = [];
+	for (const route of allConfiguredRoutes(config)) {
+		if (normalizeModelKey("", route.model) !== key || seen.has(route.provider)) continue;
+		seen.add(route.provider);
+		providers.push(route.provider);
+	}
+	return providers;
+}
+
+/** Canonical pool spelling for a folded model-id hit (caller casing
+ *  and annotation tail vary); the trimmed input when no pool route
+ *  folds to it. */
+function canonicalPoolModel(config, providers, model) {
+	const hit = allConfiguredRoutes(config).find(
+		(route) =>
+			providers.includes(route.provider) &&
+			normalizeModelKey("", route.model) === normalizeModelKey("", model),
+	);
+	return hit !== undefined ? hit.model : model;
+}
+
+/** Corrective deny reason for one delegation call whose provider/model
+ *  field SPLIT is malformed, or null to pass through. Covers the field
+ *  failures observed in production session logs (each burned 2-4 blind
+ *  retries before a manual fix):
+ *
+ *  - provider omitted, model a merged "provider/model" string: DSH rejects
+ *    EVERY such call with "`provider` and `model` must be supplied
+ *    together" before any route check, so denying with the split fields is
+ *    a strict improvement even when the split is not a configured route —
+ *    a deliberate exception to the annotated-copy rule that unknown ids
+ *    pass through (that rule protects calls DSH would ACCEPT; these can
+ *    never succeed);
+ *  - provider given, model still carrying that same "provider/" prefix:
+ *    DSH joins provider + "/" + model itself, so the resolved route
+ *    double-encodes the provider and misses the exact-match whitelist;
+ *  - provider omitted, model a bare id: resolved against the pool table —
+ *    exactly one configured provider → the pair; several → the candidate
+ *    list; none → pass through (DSH's own error already says what's wrong);
+ *  - provider given, model naming a DIFFERENT provider's configured route:
+ *    denied with that route's pair; anything else passes untouched. */
+function routeFixOf(args, config) {
+	const model = typeof args?.model === "string" ? args.model.trim() : "";
+	if (model === "") return null;
+	const providerGiven = typeof args?.provider === "string" && args.provider.trim() !== "";
+	const provider = providerGiven ? args.provider.trim() : "";
+
+	// Provider given, model still prefixed: the double-encoded route can
+	// never match the exact whitelist, so the correction is unconditional.
+	if (providerGiven && model.startsWith(`${provider}/`)) {
+		const fixed = model.slice(provider.length + 1).trim();
+		if (fixed === "" || fixed.includes("/")) return null;
+		return (
+			`[SWITCHMAN:POOLS] the model argument already carries the provider prefix — DSH joins provider + "/" + model itself, so this call resolves to the route "${provider}/${model}" and is rejected. ` +
+			`Re-dispatch with provider "${provider}", model "${fixed}", keeping every other argument unchanged.`
+		);
+	}
+
+	const cut = model.lastIndexOf("/");
+
+	// Provider given, model names another provider's configured route.
+	if (providerGiven && cut > 0) {
+		const prefix = model.slice(0, cut).trim();
+		const known =
+			prefix === ""
+				? undefined
+				: allConfiguredRoutes(config).find(
+					(route) =>
+						route.provider.toLowerCase() === prefix.toLowerCase() &&
+						normalizeModelKey("", route.model) === normalizeModelKey("", model.slice(cut + 1).trim()),
+				);
+		// No configured route under that prefix: not a shape we can correct
+		// — pass through for DSH's own rejection, without tripping the
+		// fail-open catch.
+		if (known === undefined) return null;
+		return (
+			`[SWITCHMAN:POOLS] the model argument embeds another provider's route — with provider "${provider}" this resolves to "${provider}/${model}", which no authorized route matches. ` +
+			`Re-dispatch with provider "${known.provider}", model "${known.model}", keeping every other argument unchanged.`
+		);
+	}
+
+	if (providerGiven) return null;
+
+	// Provider omitted, merged "provider/model" string: always rejected by
+	// DSH (both fields are required together), deny with the split fields.
+	if (cut > 0) {
+		// A merged copy of the already-prefixed id ("prov/prov/model") —
+		// the repeated head segment is the giveaway; recommend the inner
+		// pair directly. Other mid-slash shapes stay uncorrectable.
+		const segments = model.split("/");
+		const doubled =
+			segments.length === 3 &&
+			segments[0].trim().toLowerCase() === segments[1].trim().toLowerCase();
+		const providerFix = (doubled ? segments[0] : model.slice(0, cut)).trim();
+		const modelFix = stripTrailingAnnotations((doubled ? segments[2] : model.slice(cut + 1)).trim());
+		// Segments still malformed after the split (a mid-slash provider,
+		// a leading-slash or nested model) cannot be corrected into a call
+		// DSH would accept — pass through.
+		if (
+			providerFix === "" ||
+			modelFix === "" ||
+			providerFix.includes("/") ||
+			modelFix.includes("/")
+		)
+			return null;
+		const matched = allConfiguredRoutes(config).find(
+			(route) =>
+				route.provider.toLowerCase() === providerFix.toLowerCase() &&
+				normalizeModelKey("", route.model) === normalizeModelKey("", modelFix),
+		);
+		// Recommend the pool's canonical spelling on a folded hit so
+		// case-variant or annotated copies resolve on the first retry.
+		const shownProvider = matched !== undefined ? matched.provider : providerFix;
+		const shownModel = matched !== undefined ? matched.model : modelFix;
+		const note =
+			matched === undefined
+				? `If "${shownProvider}/${shownModel}" is not authorized for this session, the re-dispatch error will say so precisely.`
+				: `This is the configured pool route ${shownProvider}/${shownModel}.`;
+		return (
+			`[SWITCHMAN:POOLS] the model argument merges provider and model into one string — subagent calls take SEPARATE provider and model fields, and DSH rejects every call that omits either. ` +
+			`Re-dispatch with provider "${shownProvider}", model "${shownModel}", keeping every other argument unchanged. ${note}`
+		);
+	}
+
+	// A leading "/" (cut === 0) is malformed beyond folding: the pool
+	// matcher would silently strip it and recommend the malformed id back.
+	// Pass through and let DSH's own schema error surface.
+	if (cut === 0) return null;
+
+	// Provider omitted, bare model id: resolve the provider from the pool
+	// table; pass through when the id names no configured provider.
+	const providers = modelProviderMatches(config, model);
+	if (providers.length === 0) return null;
+	const shownModel = canonicalPoolModel(config, providers, model);
+	if (providers.length === 1) {
+		return (
+			`[SWITCHMAN:POOLS] the provider field is missing — subagent calls take SEPARATE provider and model fields, and DSH rejects every call that omits either. ` +
+			`The model id "${model}" is configured under exactly one provider. Re-dispatch with provider "${providers[0]}", model "${shownModel}", keeping every other argument unchanged.`
+		);
+	}
+	return (
+		`[SWITCHMAN:POOLS] the provider field is missing and the model id "${model}" is configured under several providers (${providers.join(", ")}). ` +
+		`Re-dispatch with one of those providers as the provider field, model "${shownModel}", keeping every other argument unchanged.`
+	);
+}
+
+/** Corrective deny reason for a malformed list_subagent_models call, or
+ *  null to pass through. DSH's own schema rejects {} and {model}-only
+ *  calls with a bare "`provider` must be non-empty"; production logs show
+ *  that error costing 2-4 blind probes (empty, empty, provider-only,
+ *  provider+model). One deny carrying the pool table's provider list
+ *  turns that into a single corrected call. provider-given calls always
+ *  pass. */
+function enumerationFixOf(args, config) {
+	const provider = typeof args?.provider === "string" ? args.provider.trim() : "";
+	if (provider !== "") return null;
+	const model = typeof args?.model === "string" ? args.model.trim() : "";
+	if (model === "") {
+		const providers = [...new Set(allConfiguredRoutes(config).map((route) => route.provider))];
+		const list = providers.length > 0 ? ` Providers configured on this session's pools: ${providers.join(", ")}.` : "";
+		return (
+			`[SWITCHMAN:POOLS] list_subagent_models requires a non-empty provider — a call without one is rejected, not a listing of everything. ` +
+			`Call it with {"provider":"<provider>"} to enumerate that provider's selectable models, then add "model" for one route's details.${list}`
+		);
+	}
+	const providers = modelProviderMatches(config, model);
+	if (providers.length === 0) return null;
+	const shownModel = canonicalPoolModel(config, providers, model);
+	if (providers.length === 1) {
+		return (
+			`[SWITCHMAN:POOLS] list_subagent_models requires a non-empty provider. The model id "${model}" is configured under exactly one provider — ` +
+			`call it with provider "${providers[0]}", model "${shownModel}" for that route's details.`
+		);
+	}
+	return (
+		`[SWITCHMAN:POOLS] list_subagent_models requires a non-empty provider. The model id "${model}" is configured under several providers (${providers.join(", ")}) — ` +
+		`call it with one of those providers as the provider field, model "${shownModel}".`
+	);
+}
+
 /** The assembling session's own route, from the DSH agent-loop's assemble
  *  context (`agent.ts` passes `modelSelection` with every turn assembly;
  *  older builds and non-agent assemblies omit it). Null when absent or
@@ -340,9 +549,11 @@ function renderPoolsBlock(state, sessionRoute = null) {
 		`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.`,
 		`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.`,
+		`Decompose into SEPARATE tool fields: 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).`,
+		`The table cell is ONE display string, never a field value: "model":"provider/model" (provider field omitted) is rejected, and model NEVER carries a "provider/" prefix — DSH joins provider + "/" + model itself, so a prefixed model double-encodes the provider and misses the whitelist.`,
 		`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 lane dispatch is the DEFAULT for subagent/workflow: name provider+model+reasoning_effort decomposed from the lane row (validated against this session's DSH-authorized child models — DSH Settings: allow agents to choose subagent models — NOT against this table). Implicit dispatch (omitting all three fields) is a LAST-RESORT fallback, never a shortcut: use it only after an explicit attempt was denied or list_subagent_models confirmed no authorized route, and declare IMPLICIT-DOWNGRADED in your report when you do — the child then uses configured defaults or inherits the parent route, so the lane's model is lost.`,
+		`list_subagent_models verifies authorized routes before dispatching: {"provider":"<provider>"} lists that provider's models, {"provider":"<provider>","model":"<model>"} returns one route's details — {} and {"model"} alone are rejected (provider is required and non-empty).`,
 	);
 	if (anyUnauthorized) {
 		lines.push(
@@ -395,6 +606,13 @@ function applyDispatch(ctx, config) {
 	// named; model-less calls use the system default and pass through.
 	ctx.on("tools/pre-execute", (exec, next) => {
 		try {
+			if (exec?.name === "list_subagent_models") {
+				// Enumeration sanitation: DSH rejects provider-less calls with a
+				// bare "`provider` must be non-empty"; deny once with the pool
+				// table's provider list instead (fail-open wrapper below).
+				const fix = enumerationFixOf(exec.arguments, config);
+				return fix === null ? next() : { kind: "deny", reason: fix };
+			}
 			if (exec?.name !== "subagent" && exec?.name !== "subagent_fork") return next();
 			const args = exec.arguments;
 
@@ -405,7 +623,7 @@ function applyDispatch(ctx, config) {
 			// 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);
+			const fix = annotationFixOf(args, config) ?? routeFixOf(args, config);
 			if (fix !== null) return { kind: "deny", reason: fix };
 
 			// Enforce gate: unchanged semantics, now sharing the factored

package/host/ptc-guard.js

@@ -0,0 +1,114 @@
+/** dsh-switchman PTC direct-call guard layer.
+ *
+ * Symptom (observed 2026-11-12, session-level): in PTC sessions the model
+ * calls a named tool DIRECTLY — e.g. `spawn_teammate` or `skill` after the
+ * teams doctrine or the skill catalog names it — and the harness rejects the
+ * whole call with `unknown tool "x": only \`run_code\` is callable directly`.
+ * The PTC executor's own `PTC_ONLY` section (order 800) states the rule once
+ * near the top, but every later doctrine that names tools directly erodes it.
+ *
+ * Second symptom (same day, session 22ced69f): the model sets `sandbox_permissions`
+ * on a call while the session already runs `danger-full-access`; the escalation
+ * request is rejected outright with `sandbox escalation to "workspace-write" is
+ * not strictly wider than this call's current "danger-full-access" mode` — an
+ * error with no correction hint. The clause below also states the never-set
+ * default and the retry-without-the-field fix.
+ *
+ * Fix: one extra dynamic systemPrompt section (order 10510 — AFTER every
+ * other dsh-switchman section: teams 10250, lang 10300, dispatch 10400,
+ * context-trim 10450, context-watch 10500) that re-states the transport rule
+ * as the LAST word whenever the viewing scope actually resolves to the PTC
+ * executor. Native scopes render an empty string (status quo).
+ *
+ * Detection mirrors the ToolsService's own per-scope resolution: the section
+ * text closure receives the assemble context, whose `scope` is the viewing
+ * Agent/preset scope key; `ctx.tools.selectExecutor(scope)` (TS-private but
+ * present at runtime — verified in the packaged app, `selectExecutor` survives
+ * bundling) resolves the nearest scoped executor or the deployment default.
+ * The executor is then discriminated BEHAVIORALLY via its public `describe()`:
+ * the PTC executor declares `knownNames: ["run_code"]` exactly; the native
+ * executor returns no `knownNames` at all. No class-name sniffing, no config
+ * reads, no false positives for other executor implementations (they simply
+ * get no guard).
+ *
+ * Fail-open everywhere: a missing/renamed private API, a throwing describe(),
+ * or an unavailable executor selection all render "" — the session keeps its
+ * current behavior and only loses the mitigation. Zero new dependencies.
+ *
+ * The clause is English, byte-stable protocol text (same convention as the
+ * lang layer) with a `[SWITCHMAN:PTC]` anchor, `interpolate: false` because
+ * the text contains braces.
+ */
+
+/** Reserved transport-tool name the PTC executor declares as its only direct call. */
+const RUN_CODE_NAME = "run_code";
+
+/** Final-say section position: after context-watch (10500), the last existing section. */
+const PTC_GUARD_ORDER = 10510;
+
+/** True when an executor description declares exactly the reserved run_code transport. */
+function isPtcDescription(description) {
+	if (description === null || typeof description !== "object") return false;
+	const known = description.knownNames;
+	return Array.isArray(known) && known.length === 1 && known[0] === RUN_CODE_NAME;
+}
+
+/** Selected executor for one assemble scope, or null when the private probe
+ *  is unusable (missing service, missing/renamed method, unavailable selection). */
+function selectedExecutor(ctx, scope) {
+	const tools = ctx?.tools;
+	if (tools === null || typeof tools !== "object") return null;
+	if (typeof tools.selectExecutor !== "function") return null;
+	try {
+		const executor = tools.selectExecutor(scope);
+		return executor === null || typeof executor !== "object" ? null : executor;
+	} catch {
+		return null;
+	}
+}
+
+/** True when the scope's selected executor is the PTC executor. `describe([])`
+ *  is safe for every known executor: the PTC implementation lazily creates its
+ *  transport there (the ToolsService calls it on every model call anyway) and
+ *  the native one maps over the empty list. */
+function isPtcScope(ctx, scope) {
+	const executor = selectedExecutor(ctx, scope);
+	if (executor === null || typeof executor.describe !== "function") return false;
+	try {
+		return isPtcDescription(executor.describe([]));
+	} catch {
+		return false;
+	}
+}
+
+/** Byte-stable protocol clause. The SDK call shape `await tools.name(args)` is
+ *  quoted verbatim from the run_code tool's own model-facing description. */
+function renderPtcGuard() {
+	return [
+		`[SWITCHMAN:PTC] This session runs in PTC (programmatic tool call) mode: \`${RUN_CODE_NAME}\` is the ONLY tool callable directly.`,
+		`- Every other tool MUST be invoked as an awaited SDK function inside a ${RUN_CODE_NAME} program: \`await tools.name(args)\` — e.g. \`await tools.skill({ name: "git-commit-message" })\` or \`await tools.spawn_teammate({ ... })\`.`,
+		`- A direct call fails with: unknown tool "x": only \`${RUN_CODE_NAME}\` is callable directly — call \`x\` from inside a \`${RUN_CODE_NAME}\` program instead. Never retry the direct form; wrap the call.`,
+		`- Wherever this prompt says "call the X tool" (skill catalog, doctrines, per-turn reminders), read it as "call X inside a ${RUN_CODE_NAME} program". Batch independent calls as parallel awaits inside ONE program.`,
+		`- Never set \`sandbox_permissions\` on any call, direct or SDK: it is a privilege-escalation request and fails with "not strictly wider than this call's current ... mode" whenever the session already runs at least that access level — retry without the field.`,
+	].join("\n");
+}
+
+/** Mount the PTC guard section. Section registration itself relies on the
+ *  injected systemPrompt service (same as every other layer); the text closure
+ *  is fully defensive so an assembly in an unexpected shape renders "". */
+function applyPtcGuard(ctx) {
+	ctx.systemPrompt.section({
+		name: "switchman:ptc-guard",
+		order: PTC_GUARD_ORDER,
+		interpolate: false,
+		text: (context) => {
+			try {
+				return isPtcScope(ctx, context?.scope) ? renderPtcGuard() : "";
+			} catch {
+				return "";
+			}
+		},
+	});
+}
+
+export { applyPtcGuard, isPtcDescription, isPtcScope, renderPtcGuard, selectedExecutor };

package/host/routes.js

@@ -95,6 +95,12 @@ const NUMBER_FIELDS = [
 	"wmReadBudgetTokens",
 	"wmSubagentForceTokens",
 ];
+/** Watermark numbers with REAL bounds (host/config.js schema): rejected (not
+ *  clamped) on write, defaulted on read — NUMBER_FIELDS only rejects negatives,
+ *  which would let a 0 ratio silently disable subagent tier scaling. */
+const WM_BOUNDED_NUMBER_FIELDS = [
+	{ field: "wmSubagentWindowRatio", min: 0.1, max: 1, def: 0.75 },
+];
 /** Trim numbers carry their own schema bounds (host/config.js), so the
  *  shared NUMBER_FIELDS coercion (which only rejects negatives) is too
  *  loose — these validate against each field's declared min/max. This group
@@ -144,10 +150,13 @@ const INTENT_NUMBER_FIELDS = [
 	{ field: "intentHistoryMaxChars", min: 200, max: 20000, def: 2400 },
 	{ field: "intentContextWindow", min: 1024, max: Number.POSITIVE_INFINITY, def: 200000 },
 ];
-/** Intent route references: unlike pool routes they round-trip the "unset"
- *  {provider:"", model:""} pair, so they validate against the loosened
- *  cleanIntentRoute (both keys must be strings; either may be empty). */
-const INTENT_ROUTE_FIELDS = ["intentClassifierRoute", "intentFallbackRoute", "trimSideModel", "trimFoldFallbackModel"];
+/** Intent route references round-trip the "unset" {provider:"", model:""}
+ *  pair, so they validate against the loosened cleanIntentRoute (both keys
+ *  must be strings; either may be empty); intent routes never carry effort. */
+const INTENT_ROUTE_FIELDS = ["intentClassifierRoute", "intentFallbackRoute"];
+/** Trim side routes additionally round-trip an optional effort pin — the
+ *  settings page's reasoning-effort select — via cleanTrimRoute below. */
+const TRIM_ROUTE_FIELDS = ["trimSideModel", "trimFoldFallbackModel"];
 /** Intent candidate list (route + optional effort/note per entry). */
 const INTENT_CANDIDATE_FIELDS = ["intentCandidates"];
 
@@ -304,6 +313,18 @@ function cleanIntentRoute(entry) {
 	const provider = typeof entry.provider === "string" ? entry.provider.trim() : null;
 	const model = typeof entry.model === "string" ? entry.model.trim() : null;
 	return provider === null || model === null ? null : { provider, model };
+	}
+
+/** Coerce one TRIM side route: like cleanIntentRoute, but a non-empty string
+ *  effort rides along — the trim summarizer pins reasoning effort on its side
+ *  model, and stripping it here made every settings save silently revert the
+ *  settings page's effort select to the default. Intent routes omit effort. */
+function cleanTrimRoute(entry) {
+	const route = cleanIntentRoute(entry);
+	if (route === null) return null;
+	const effort = typeof entry.effort === "string" ? entry.effort.trim() : "";
+	if (effort !== "") route.effort = effort;
+	return route;
 }
 
 /** Coerce one intent candidate: provider/model must be non-empty; effort/note
@@ -349,6 +370,7 @@ export function snapshotOf(config) {
 			? rawOf(config[field]).map(cleanEffortEntry).filter(Boolean)
 			: [];
 	for (const field of INTENT_ROUTE_FIELDS) values[field] = cleanIntentRoute(rawOf(config?.[field])) ?? { provider: "", model: "" };
+	for (const field of TRIM_ROUTE_FIELDS) values[field] = cleanTrimRoute(rawOf(config?.[field])) ?? { provider: "", model: "" };
 	for (const field of INTENT_CANDIDATE_FIELDS)
 		values[field] = mergeIntentCandidates(rawOf(config?.[field]));
 	values.intentClassifierKind = ENUM_FIELDS.intentClassifierKind.includes(rawOf(config?.intentClassifierKind))
@@ -372,6 +394,10 @@ export function snapshotOf(config) {
 		const raw = Number(rawOf(config?.[field]));
 		values[field] = Number.isFinite(raw) ? raw : 0;
 	}
+	for (const { field, def } of WM_BOUNDED_NUMBER_FIELDS) {
+		const raw = Number(rawOf(config?.[field]));
+		values[field] = Number.isFinite(raw) ? raw : def;
+	}
 	values.wmDenyMode = ENUM_FIELDS.wmDenyMode.includes(rawOf(config?.wmDenyMode))
 		? rawOf(config.wmDenyMode)
 		: "cap";
@@ -419,6 +445,11 @@ export function coerceValues(input) {
 		if (route === null) return null;
 		values[field] = route;
 	}
+	for (const field of TRIM_ROUTE_FIELDS) {
+		const route = cleanTrimRoute(input[field]);
+		if (route === null) return null;
+		values[field] = route;
+	}
 	for (const field of INTENT_CANDIDATE_FIELDS) {
 		if (!Array.isArray(input[field])) return null;
 		const candidates = input[field].map(cleanIntentCandidate);
@@ -454,6 +485,11 @@ export function coerceValues(input) {
 		if (!Number.isFinite(raw) || raw < 0) return null;
 		values[field] = raw;
 	}
+	for (const { field, min, max } of WM_BOUNDED_NUMBER_FIELDS) {
+		const raw = Number(input[field]);
+		if (!Number.isFinite(raw) || raw < min || raw > max) return null;
+		values[field] = raw;
+	}
 	if (!ENUM_FIELDS.wmDenyMode.includes(input.wmDenyMode)) return null;
 	values.wmDenyMode = input.wmDenyMode;
 	for (const field of BOOLEAN_FIELDS) {

package/host/teams.js

@@ -82,9 +82,11 @@ const TEAMS_SECTION_TEXT = [
 	"系统提示词前文的默认团队策略写的是「仅当用户明确要求时才创建 teammate」。该默认策略在当前 profile 下不适用：用户安装 dsh-switchman 即预先授权，你应当自主判断、自主触发，无需再询问用户。",
 	"",
 	"## 五、团队触发与协作纪律",
-	"- 需要多成员持久协作、共享任务板、消息往来的用 Agent Teams（满足任一即触发 spawn_teammate：可并行的多个独立子任务；量大且自包含；主上下文水位已高；需要角色分离）；一次性、无需共享状态的单点调查用 subagent。",
+	"- 派发通道优先级（取代前文「一次性、无需共享状态的单点调查用 subagent」的默认分工）：本会话工具目录里有 spawn_teammate/list_agents（Agent Teams 已启用）时，一切子任务委派默认走 Agent Teams——spawn_teammate 组队、team_task_* 落共享任务板、send_message/wait_agent 协作；subagent/subagent_fork 单智能体派发退为后备通道，仅在本条下一条所述的不可用场景使用。",
+	"- teams 不可用即降级，不重试：工具目录没有 spawn_teammate/list_agents（bundle 未生效或本会话不支持），或 spawn_teammate 报 provisioning failed / 创建失败时，直接改用 subagent/subagent_fork 派发并继续工作，不要反复重试 teams 通道。你自身是 teammate（非 Lead）时维持原规则：不 spawn_teammate，需要子委派时用 subagent。workflow 仅在用户明确要求工作流或脚本化大规模编排时使用，默认不主动使用。",
 	"- 写作域隔离：共享任务上写明互不重叠的 write_scopes；用 team_task_* 维护任务板与依赖顺序；Lead 汇总最终 diff、复核关键改动并运行测试；用 wait_agent 等到必需的 teammate 完成，绝不在结果未回前下最终结论。",
 	"- 子智能体消息通道：subagent/workflow 返回的子会话 id 只能经 child_message 桥接送达——send_message 只解析 teammate 名字，对子会话 id 必报 active teammate「…」not found；该报错不代表子会话死亡，先改用 child_message，不要据此重派或判定死亡。",
+	"- run_code 并行隔离：spawn_teammate / send_message 这类会改变团队环境（成员目录、工具表）的调用不要与文件/搜索工具放进同一 run_code 程序里 Promise.all 并行——并发窗口内其它工具绑定可能误报 unknown tool「…」（UNKNOWN_TOOL）；让这类调用单独占一步执行。某工具此前可用却突然报 UNKNOWN_TOOL 时，下一步原样重试即可，不要换工具名或放弃任务。",
 ].join("\n");
 
 // ---- shared volatile-read helpers (mirrors dispatch.js) --------------------

package/host/tool-args-sanitize.js

@@ -0,0 +1,106 @@
+/** Transparent tool-argument sanitation layer (`tools/pre-execute`).
+ *
+ * Production session logs (4 days, 5961 tool calls, 300 failures) show a
+ * recurring failure class where the model emits a composite argument in the
+ * wrong JSON shape and the tool's own validation rejects it — the retry loop
+ * then often repeats the SAME shape (worst observed: 8 identical failures in
+ * a row). Two shapes dominate:
+ *
+ * 1. Stringified JSON composites: `view_range: "[100, 145]"` (a JSON string
+ *    instead of the native array; 24 failures), `input: "{...}"` for
+ *    cordis_inspect_query (3). The deterministic fix is one JSON.parse.
+ * 2. Empty string for an enum-ish field: `read` with `encoding: ""`
+ *    (26 failures) — the tool wants the field absent, not blank.
+ *
+ * This layer coerces those shapes BEFORE the tool implementations validate
+ * (better-edit's requireViewRange / normalizeEncoding, or the native
+ * defineTool INVALID_ARGS check) and before guards/approvals observe the
+ * arguments, so the call succeeds transparently instead of burning a retry.
+ *
+ * Conservative by construction:
+ * - ONLY whitelisted field names are touched (observed-broken plus same-shape
+ *   kin); content-bearing string fields like `command` are never parsed.
+ * - A stringified value is replaced only when JSON.parse yields a value that
+ *   satisfies the field's structural assertion. Anything else keeps the
+ *   original string so the tool's own [TO MODEL] error reaches the model
+ *   unchanged — sanitation must never swallow or rewrite a real error.
+ * - Any internal error fails open (next()), never denies, never throws.
+ */
+
+/** Structural assertions for whitelisted fields (tool-level code validates
+ *  the contents; we only gate the composite SHAPE). */
+const isPairRange = (value) =>
+	Array.isArray(value) && value.length === 2 &&
+	value.every((item) => Number.isInteger(item) && item > 0);
+const isPlainArray = (value) => Array.isArray(value);
+const isPlainObject = (value) =>
+	value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** Field-name whitelist → structural assertion. Field names are narrow enough
+ *  to stand alone (view_range/edits: str_replace_editor; windows: read;
+ *  input: cordis_inspect_query) — no tool-name gate, so future tools reusing
+ *  the same names get the same tolerance. */
+const SHAPE_FIELDS = {
+	view_range: isPairRange,
+	windows: isPlainArray,
+	edits: isPlainArray,
+	input: isPlainObject,
+};
+
+/** Fields where an empty string means "not provided" (tool default applies). */
+const EMPTY_UNSET_FIELDS = ["encoding"];
+
+/** Coerce known broken argument shapes. Returns `{ args, fixes }` when at
+ *  least one coercion applied, `null` when the arguments are clean (or not a
+ *  plain object). Pure: never mutates the input object. */
+export function sanitizeToolArgs(args) {
+	if (args === null || typeof args !== "object" || Array.isArray(args))
+		return null;
+	const out = { ...args };
+	const fixes = [];
+	for (const [field, assert] of Object.entries(SHAPE_FIELDS)) {
+		const value = out[field];
+		if (typeof value !== "string") continue;
+		const trimmed = value.trim();
+		if (!trimmed.startsWith("[") && !trimmed.startsWith("{")) continue;
+		let parsed;
+		try {
+			parsed = JSON.parse(trimmed);
+		} catch {
+			continue;
+		}
+		if (!assert(parsed)) continue;
+		out[field] = parsed;
+		fixes.push(`${field}: stringified JSON -> ${Array.isArray(parsed) ? "array" : "object"}`);
+	}
+	for (const field of EMPTY_UNSET_FIELDS) {
+		if (out[field] === "") {
+			delete out[field];
+			fixes.push(`${field}: "" -> unset`);
+		}
+	}
+	return fixes.length > 0 ? { args: out, fixes } : null;
+}
+
+/** Mount the sanitation layer (one `tools/pre-execute` listener). Runs before
+ *  guards and before every tool implementation's own validation; replaces
+ *  `exec.arguments` wholesale (lossless plain JSON) when a known shape was
+ *  coerced, then always calls next(). */
+export function applyToolArgsSanitize(ctx, config) {
+	const warn = (message) => ctx.logger.warn(`dsh-switchman: ${message}`);
+	ctx.on("tools/pre-execute", (exec, next) => {
+		try {
+			const result = sanitizeToolArgs(exec?.arguments);
+			if (result !== null) {
+				exec.arguments = result.args;
+				ctx.logger.debug(
+					`dsh-switchman: sanitized ${exec?.name ?? "?"} arguments (${result.fixes.join("; ")})`,
+				);
+			}
+			return next();
+		} catch (error) {
+			warn(`tool-args sanitation failed open: ${error?.message ?? error}`);
+			return next();
+		}
+	});
+}

package/index.js

@@ -25,6 +25,12 @@
  * ctx_handover agent tool, and the /ctx-pause, /ctx-resume,
  * /ctx-handover commands.
  *
+ * The tool-argument sanitation layer (host/tool-args-sanitize.js) is a
+ * `tools/pre-execute` waterfall listener that transparently coerces known
+ * broken argument shapes — stringified-JSON composites ("[100, 145]" instead
+ * of [100, 145]) and empty-string enum fields (encoding: "") — before the
+ * tool implementations validate them, eliminating a recurring class of
+ * self-correcting tool-call retries observed in production session logs.
  * Teams mode mounts two more layers: host/teams.js carries the team clauses
  * extracted from the cordis.patch.yml suffix in a `[SWITCHMAN:TEAMS]` section
  * (order 10250, injected only while teamsMode is ON) plus the deferred ON
@@ -45,6 +51,13 @@
  * defensive ctx.get reads (NOT declared in inject): a deployment without the
  * llm service leaves this layer a warn-once no-op — a documented runtime
  * precondition, like sessionQuery/pluginManager above.
+ * The PTC direct-call guard (host/ptc-guard.js) is a final-say prompt section
+ * (order 10510) rendered only when the viewing scope resolves to the PTC tool
+ * executor — detected per assembly via ctx.tools.selectExecutor(context.scope)
+ * plus the executor's describe() knownNames — restating that every named tool
+ * must be called inside a run_code program (`await tools.name(args)`), so
+ * doctrines and skill catalogs that name tools directly can no longer trigger
+ * `unknown tool` rejections in PTC sessions.
  */
 
 import { readdirSync, readFileSync } from "node:fs";
@@ -64,6 +77,8 @@ import { applyDispatch } from "./host/dispatch.js";
 // Agent Teams layer (teams-mode doctrine section + bundle/whitelist
 // orchestration; the clause text extracted from the cordis.patch.yml suffix).
 import { applyTeams } from "./host/teams.js";
+// PTC direct-call guard (final-say transport rule for PTC-executor scopes).
+import { applyPtcGuard } from "./host/ptc-guard.js";
 // Subagent model-visibility layer (post-execute `model:` annotation).
 import { applySubagentModel } from "./host/subagent-model.js";
 
@@ -81,6 +96,9 @@ import { applyIntent } from "./host/intent.js";
 // Client-bridge routes (config snapshot/fenced write + model catalog for the
 // restricted browser half, which has no configForms/remote services).
 import { applyRoutes } from "./host/routes.js";
+// Tool-argument sanitation (transparent coercion of stringified-JSON and
+// empty-string argument shapes before tool validation).
+import { applyToolArgsSanitize } from "./host/tool-args-sanitize.js";
 
 /** Cordis plugin name. */
 const name = "dsh-switchman";
@@ -188,7 +206,8 @@ function loadSkillCandidates(root, warn) {
 /** Register the bundled dsh-switchman skill provider on `ctx.skills` and
  *  mount the language (lang), dispatch (dispatch), teams (teams), watermark
  *  (context-watch), vision (vision), intent routing (intent), subagent model
- *  visibility (subagent-model), and client-bridge (routes) layers. */
+ *  visibility (subagent-model), client-bridge (routes), and the PTC
+ *  direct-call guard (ptc-guard) layers. */
 function apply(ctx, config) {
 	const root = fileURLToPath(new URL("./skills/", import.meta.url));
 	const warn = (message) => ctx.logger.warn(`dsh-switchman: ${message}`);
@@ -205,12 +224,14 @@ function apply(ctx, config) {
 	applyLanguage(ctx, config);
 	applyDispatch(ctx, config);
 	applyTeams(ctx, config);
+	applyPtcGuard(ctx);
 	applyContextWatch(ctx, config);
 	applyContextTrim(ctx, config);
 	applyVision(ctx, config);
 	applyIntent(ctx, config);
 	applySubagentModel(ctx);
 	applyRoutes(ctx, config);
+	applyToolArgsSanitize(ctx, config);
 }
 
 export { apply, inject, name };