dsh-switchman 1.11.2 → 1.11.3

package/README.md

@@ -154,7 +154,7 @@ All keys live in Settings → dsh-switchman; defaults from `host/config.js`:
 
 ## How it works
 
-- The host half (`index.js` + `host/`) injects the byte-stable system-prompt sections (language / lanes / watermark protocol / teams) plus the live watermark line through the tail runtime-context snapshot (a channel that appends instead of rewriting the prompt head, so the provider prompt cache stays intact), the read-budget plus enforce double gate, and four slash commands (the ctx trio + `/vision`). A saved setting takes effect at the very next prompt assembly — no restart.
+- The host half (`index.js` + `host/`) injects the byte-stable system-prompt sections (language / lanes / watermark protocol / teams / PTC guard) plus the live watermark line through the tail runtime-context snapshot (a channel that appends instead of rewriting the prompt head, so the provider prompt cache stays intact), the read-budget plus enforce double gate, and four slash commands (the ctx trio + `/vision`). A saved setting takes effect at the very next prompt assembly — no restart. In PTC sessions (programmatic tool calls) the PTC guard renders as the final section and restates that every named tool must be invoked inside a `run_code` program (`await tools.name(args)`), making `unknown tool` rejections much less likely when doctrines or skill catalogs name tools directly (a prompt-level mitigation, not a hard guarantee).
 - The client half (`client.js`) renders the settings page, the ⚡ badge and ◇ model marker in the session header, and the live handover indicator; config snapshots are read and written through the Host route family.
 - The "Switchman Dispatch Center" entry in the home sidebar opens that same settings page as a center panel in one click; the original settings entry stays.
 - `cordis.patch.yml` keeps the factory preset plugin list fully intact and only extends the persona suffix; the Agent Teams tools themselves come from the factory bundle and switch on automatically with teams mode.
@@ -162,7 +162,7 @@ All keys live in Settings → dsh-switchman; defaults from `host/config.js`:
 ## Maintenance notes
 
 - After a DSH upgrade, if the factory preset plugin list changed, re-sync `cordis.patch.yml` from the new `presets/*.patch.yml` (keeping the doctrine suffix and the compaction arbitration — `auto: false` on the `compaction-basic` rows), then reinstall.
-- Protocol lines (`[SWITCHMAN:LANG|POOLS|WATERMARK|TEAMS]`) are deliberately English and byte-stable — don't localize them.
+- Protocol lines (`[SWITCHMAN:LANG|POOLS|WATERMARK|TEAMS|PTC]`) are deliberately English and byte-stable — don't localize them.
 - `npm pack --dry-run` should keep the audited 60-file / ~380 kB tarball shape (~1.26 MB unpacked). `docs/` stays out of the package (it is not in `package.json files`), while the 11 `README.*` translations are always shipped by npm.
 - **Zero runtime dependencies — a hard invariant.** Host-plane packages (`@deepseek-ai/schemastery`, cordis, …) are declared as `peerDependencies` only, and the running DSH satisfies them from its own copy. An ordinary `dependencies` entry is physically installed into the profile workspace (`<profile>/node_modules/…`), where it shadows the host's copy for every other profile-resident plugin — this is exactly what crashed the dshmarket plugin market while 1.7.0 carried schemastery as a dependency (two schemastery instances in one process; the market's schemas no longer matched the host's). `scripts/validate.mjs` fails if a `dependencies` entry ever reappears, so installing, updating, or removing dsh-switchman can never touch what dshmarket or any other community bundle resolves at runtime.
 

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/teams.js

@@ -86,6 +86,7 @@ const TEAMS_SECTION_TEXT = [
 	"- 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/index.js

@@ -51,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";
@@ -70,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";
 
@@ -197,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}`);
@@ -214,6 +224,7 @@ function apply(ctx, config) {
 	applyLanguage(ctx, config);
 	applyDispatch(ctx, config);
 	applyTeams(ctx, config);
+	applyPtcGuard(ctx);
 	applyContextWatch(ctx, config);
 	applyContextTrim(ctx, config);
 	applyVision(ctx, config);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dsh-switchman",
-	"version": "1.11.2",
+	"version": "1.11.3",
 	"description": "Autonomous Agent Teams doctrine for the four shipped DeepSeek Harness presets, plus language preferences, dispatch pools with model ranking, and context watermark control.",
 	"license": "MIT",
 	"keywords": [