github-router 0.3.152 → 0.3.153

package/dist/main.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-import { $ as logStreamError, $t as copilotBaseUrl, At as UPSTREAM_FETCH_TIMEOUT_MS, B as toolbeltEnabled, Bt as cacheCopilotVersion, C as repoFingerprint, Ct as ArtifactClient, D as trustRepo, Dt as DEFAULT_CODEX_MODEL, E as stopReviewStateDir, Et as DEFAULT_CLAUDE_MODEL_FALLBACKS, Ft as withInstallLock, G as searchWeb, Gt as resolveCodexModel, H as vscodeRipgrepPath, Ht as cacheVSCodeVersion, It as setupCopilotToken, J as buildAdvisorStream, Jt as getModels, K as ADVISOR_INTERNAL_TOOL_NAME, Kt as resolveModel, Lt as setupGitHubAgentToken, Mt as generateRandomPort, Nt as pickClaudeDefault, O as resolveSealedGate, Ot as DEFAULT_CODEX_MODEL_FALLBACKS, Pt as getPackageVersion, Q as isControllerClosedError, Qt as GITHUB_API_BASE_URL, R as availableToolCommands, Rt as setupGitHubToken, S as isSubagentContext, St as shouldUseInsecureTls, T as stopGateEnabledForRepo, Tt as toolbeltPathOverride, U as TOOLBELT_TOOLS, Ut as filterBetaHeader, V as toolbeltSkipSet, Vt as cacheModels, W as assetFor, Wt as isNullish, X as isAdvisorRequested, Xt as HTTPError, Y as injectAdvisorTool, Yt as fetchWithTransientRetry, Z as buildOpenAIErrorEvent, Zt as forwardError, _ as stopReviewEnabled, _t as provisionBrowserAssets, a as buildPeerAwarenessSnippet, at as browserToolsEnabled, b as fileLastPromptStore, bt as extractTarGzMember, c as buildSessionBindHookCommand, ct as workerToolsEnabled, d as decideStopHook, dt as getTokenCount, en as copilotHeaders, et as readIteratorWithTimeout, f as fileBlockBudget, ft as createResponses, g as stopGateId, gt as parseJsonOrDiagnose, h as stopGateDisabled, ht as readResponseBodyCapped, i as buildAgentPrompt, it as agentToolsEnabled, jt as UPSTREAM_INACTIVITY_TIMEOUT_MS, k as liveExec, kt as DEFAULT_PORT, l as buildStopHookCommand, lt as countTokens, m as launchBaselineKey, mt as MAX_RESPONSE_BODY_BYTES, n as MCP_GROUPS, nn as state, nt as handleMcpDelete, o as personasFor, ot as fleetToolsEnabled, p as injectStopHookIntoSettingsFile, pt as createChatCompletions, q as ADVISOR_TOOL_INSTRUCTIONS, qt as sleep, r as assertMcpToolSurfaceConsistent, rt as handleMcpPost, s as buildArtifactOpenHookCommand, st as standInToolEnabled, t as GROUP_META, tn as githubHeaders, tt as relayAnthropicStream, u as captureLaunchBaseline, ut as createMessages, v as fileBaselineStore, vt as hasSupportedBrowserInstalled, w as repoRoot, wt as collapsePathKeys, x as fileReviewDebounce, xt as extractZipMember, y as fileFindingsStore, yt as provisionAndIndexColbert, z as buildToolbeltAwareness, zt as tryRefreshAndRetry } from "./peer-mcp-personas-BQVOxB1i.js";
-import { a as removeOwnClaudeConfigMirror, i as isUnderClaudeConfigMirror, l as writeArtifactCredsToMirror, n as ensureClaudeConfigMirror, r as ensurePaths, t as PATHS, u as writeRuntimeFileSecure } from "./paths-D0tJ_tms.js";
-import { c as killManagedTree, d as runCommandCapture, f as runCommandVoid, l as parseBoolEnv, s as killChildProcessTree, u as resolveExecutable } from "./lifecycle-DyEXZu2z.js";
-import { a as sweepRegistry } from "./lifecycle-DGvk4z63.js";
+import { $ as logStreamError, $t as GITHUB_API_BASE_URL, At as DEFAULT_PORT, B as toolbeltEnabled, Bt as tryRefreshAndRetry, C as repoFingerprint, Ct as shouldUseInsecureTls, D as trustRepo, Dt as DEFAULT_CLAUDE_MODEL_FALLBACKS, E as stopReviewStateDir, Et as toolbeltPathOverride, Ft as getPackageVersion, G as searchWeb, Gt as isNullish, H as vscodeRipgrepPath, Ht as cacheModels, It as withInstallLock, J as buildAdvisorStream, Jt as sleep, K as ADVISOR_INTERNAL_TOOL_NAME, Kt as resolveCodexModel, Lt as setupCopilotToken, Mt as UPSTREAM_INACTIVITY_TIMEOUT_MS, Nt as generateRandomPort, O as resolveSealedGate, Ot as DEFAULT_CODEX_MODEL, Pt as pickClaudeDefault, Q as isControllerClosedError, Qt as forwardError, R as availableToolCommands, Rt as setupGitHubAgentToken, S as isSubagentContext, St as extractZipMember, T as stopGateEnabledForRepo, Tt as collapsePathKeys, U as TOOLBELT_TOOLS, Ut as cacheVSCodeVersion, V as toolbeltSkipSet, Vt as cacheCopilotVersion, W as assetFor, Wt as filterBetaHeader, X as isAdvisorRequested, Xt as fetchWithTransientRetry, Y as injectAdvisorTool, Yt as getModels, Z as buildOpenAIErrorEvent, Zt as HTTPError, _ as stopReviewEnabled, _t as parseJsonOrDiagnose, a as buildPeerAwarenessSnippet, at as browseAgentEnabled, b as fileLastPromptStore, bt as provisionAndIndexColbert, c as buildSessionBindHookCommand, ct as standInToolEnabled, d as decideStopHook, dt as createMessages, en as copilotBaseUrl, et as readIteratorWithTimeout, f as fileBlockBudget, ft as getTokenCount, g as stopGateId, gt as readResponseBodyCapped, h as stopGateDisabled, ht as MAX_RESPONSE_BODY_BYTES, i as buildAgentPrompt, it as agentToolsEnabled, jt as UPSTREAM_FETCH_TIMEOUT_MS, k as liveExec, kt as DEFAULT_CODEX_MODEL_FALLBACKS, l as buildStopHookCommand, lt as workerToolsEnabled, m as launchBaselineKey, mt as createChatCompletions, n as MCP_GROUPS, nn as githubHeaders, nt as handleMcpDelete, o as personasFor, ot as browserToolsEnabled, p as injectStopHookIntoSettingsFile, pt as createResponses, q as ADVISOR_TOOL_INSTRUCTIONS, qt as resolveModel, r as assertMcpToolSurfaceConsistent, rn as state, rt as handleMcpPost, s as buildArtifactOpenHookCommand, st as fleetToolsEnabled, t as GROUP_META, tn as copilotHeaders, tt as relayAnthropicStream, u as captureLaunchBaseline, ut as countTokens, v as fileBaselineStore, vt as provisionBrowserAssets, w as repoRoot, wt as ArtifactClient, x as fileReviewDebounce, xt as extractTarGzMember, y as fileFindingsStore, yt as hasSupportedBrowserInstalled, z as buildToolbeltAwareness, zt as setupGitHubToken } from "./peer-mcp-personas-DMM1akDa.js";
+import { a as removeOwnClaudeConfigMirror, i as isUnderClaudeConfigMirror, l as writeArtifactCredsToMirror, n as ensureClaudeConfigMirror, r as ensurePaths, t as PATHS, u as writeRuntimeFileSecure } from "./paths-Bt7sqiVr.js";
+import { c as killManagedTree, d as runCommandCapture, f as runCommandVoid, l as parseBoolEnv, s as killChildProcessTree, u as resolveExecutable } from "./lifecycle-VTQI28wT.js";
+import { a as sweepRegistry } from "./lifecycle-C4k0pEvn.js";
 import { defineCommand, runMain } from "citty";
 import consola from "consola";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
@@ -809,6 +809,223 @@ function launchChild(target, server$1, options = {}) {
 	});
 }
 
+//#endregion
+//#region src/lib/worker-dispatch.ts
+/**
+* Frozen contract for the NON-BLOCKING workers surface.
+*
+* The `workers` MCP tools (`explore`/`implement`/`review`/`plan`/`test`, and
+* `browse` when the browse agent is enabled) BLOCK the caller for up to 30 min
+* (`runWorkerAgent`). The MAIN Claude Code agent must never block on one, so a
+* per-mode `worker-*` DISPATCHER SUBAGENT — which Claude Code runs in the
+* background and reports on via a completion notification — is the only
+* sanctioned way to run a worker. This module is the single source of truth for
+* three things that must never drift:
+*
+*   1. the tool → dispatcher map (`mcp__<workersKey>__<mode>` ↔ `worker-<mode>`),
+*   2. the PreToolUse GUARD decision that denies a raw worker call from the main
+*      agent (or any non-dispatcher subagent) and redirects it to the matching
+*      `worker-*` agent, allowing it only from the dispatcher itself, and
+*   3. the dispatcher subagent bodies (description / system prompt / `tools:`
+*      allowlist).
+*
+* Imported by `codex-mcp-config.ts` (dispatcher `.md` generation + the hook
+* command it bakes into settings.json) AND `internal-worker-guard.ts` (the
+* runtime PreToolUse hook). Keeping the map here means the settings matcher, the
+* redirect target, the dispatcher names, and the `tools:` allowlist are all
+* derived from one place.
+*
+* Discrimination mechanism: a Claude Code PreToolUse payload carries
+* `agent_type` (the invoking subagent's name) ONLY inside a subagent context —
+* absent for the top-level/main agent. So `agent_type === "worker-<mode>"` is
+* the reliable "this call came from the dispatcher, allow it" signal, and its
+* absence (or any other value) means "main agent or an unrelated subagent →
+* deny". This is the SAME field this repo's Stop / prompt-submit hooks already
+* key off (`isSubagentContext` in `orchestration/stop-gate-policy.ts`); the
+* guard here is the inverse (allow-only-dispatcher rather than skip-any-sub).
+*/
+/** The five always-available worker modes (gated by `workerToolsEnabled()`). */
+const CORE_WORKER_MODES = [
+	"explore",
+	"implement",
+	"review",
+	"plan",
+	"test"
+];
+/** The browse worker mode, gated separately by `browseAgentEnabled()`. */
+const BROWSE_WORKER_MODE = "browse";
+/** Every mode the surface can expose — used to build the sweep-regex allowlist
+*  and to validate `--modes`. Order is stable (core first, browse last). */
+const ALL_WORKER_DISPATCH_MODES = [...CORE_WORKER_MODES, BROWSE_WORKER_MODE];
+/** The dispatcher subagent name for a mode, e.g. `implement` → `worker-implement`. */
+function dispatcherAgentName(mode) {
+	return `worker-${mode}`;
+}
+/** Every possible dispatcher subagent name (used by the stale-`.md` sweep). */
+const ALL_DISPATCHER_AGENT_NAMES = ALL_WORKER_DISPATCH_MODES.map(dispatcherAgentName);
+/** The MCP tool name the workers server exposes for a mode under the resolved key. */
+function workerToolName(workersKey, mode) {
+	return `mcp__${workersKey}__${mode}`;
+}
+/** The active dispatch modes for a launch: the five core modes plus `browse`
+*  only when the browse agent is enabled. */
+function activeDispatchModes(opts) {
+	return opts.browse ? [...CORE_WORKER_MODES, BROWSE_WORKER_MODE] : [...CORE_WORKER_MODES];
+}
+function escapeRegex(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* The Claude Code PreToolUse `matcher` (a regex over the tool name) that scopes
+* the guard hook to exactly the active worker tools — nothing else invokes the
+* hook. Anchored + exact-alternation so an unrelated `mcp__<key>__status` (a
+* future non-blocking tool with no dispatcher) is never matched, hence never
+* denied.
+*/
+function guardToolMatcher(workersKey, modes) {
+	const alt = modes.map((m) => escapeRegex(m)).join("|");
+	return `^mcp__${escapeRegex(workersKey)}__(${alt})$`;
+}
+/** Parse the worker mode out of a tool name for the resolved key, or null if it
+*  isn't one of the recognized worker tools. */
+function parseWorkerToolCall(toolName, workersKey, modes) {
+	const prefix = `mcp__${workersKey}__`;
+	if (!toolName.startsWith(prefix)) return null;
+	const rest = toolName.slice(prefix.length);
+	return modes.includes(rest) ? rest : null;
+}
+/** The `permissionDecisionReason` shown to the model on a deny, steering it to
+*  the matching background dispatcher. `mode` is null when the payload was
+*  unparseable (fail-closed generic message). */
+function guardDenyReason(mode) {
+	return `Workers run as background subagents in this session so your turn never blocks. Re-issue this as ${mode ? `Agent(subagent_type: "${dispatcherAgentName(mode)}", prompt: <your worker brief>)` : `the matching background \`worker-*\` agent via the Agent tool`}. It returns immediately and delivers the worker's result as a completion notification — do not call the raw \`mcp__…__\` worker tool from the main thread.`;
+}
+/** The stdout JSON a PreToolUse hook prints to DENY a tool call. */
+function guardDenyOutput(mode) {
+	return JSON.stringify({ hookSpecificOutput: {
+		hookEventName: "PreToolUse",
+		permissionDecision: "deny",
+		permissionDecisionReason: guardDenyReason(mode)
+	} });
+}
+/**
+* Pure PreToolUse guard decision. Given the raw stdin payload, the resolved
+* workers key, and the active modes, decide whether to DENY the tool call.
+*
+* Rules (fail toward protecting the "main never blocks" invariant):
+*   - Payload unparseable / no string `tool_name`: the matcher only fires this
+*     hook for worker tools, so a payload we can't read is still a worker call
+*     → DENY (fail closed, generic redirect).
+*   - `tool_name` is not a recognized worker tool for this key: ALLOW (not a
+*     tool we guard — never deny a non-worker tool).
+*   - `agent_type` equals one of the active dispatcher names: ALLOW (the call
+*     came from the dispatcher subagent that is meant to run the worker).
+*   - Otherwise (main agent: `agent_type` absent; or a non-dispatcher subagent):
+*     DENY with a redirect to the matching `worker-<mode>` agent.
+*/
+function decideWorkerGuard(input) {
+	let payload = null;
+	try {
+		const parsed = JSON.parse(input.stdin);
+		if (parsed && typeof parsed === "object") payload = parsed;
+	} catch {
+		payload = null;
+	}
+	const toolName = typeof payload?.tool_name === "string" ? payload.tool_name : null;
+	if (!toolName) return {
+		output: guardDenyOutput(null),
+		verdict: "deny-malformed"
+	};
+	const mode = parseWorkerToolCall(toolName, input.workersKey, input.modes);
+	if (mode === null) return {
+		output: null,
+		verdict: "allow-non-worker"
+	};
+	const agentType = payload?.agent_type;
+	if (typeof agentType === "string" && agentType === dispatcherAgentName(mode)) return {
+		output: null,
+		verdict: "allow-dispatcher"
+	};
+	return {
+		output: guardDenyOutput(mode),
+		verdict: "deny-main"
+	};
+}
+/** One-line human description shown to the lead when picking a subagent. Uses
+*  the documented "Use proactively" auto-delegation idiom. */
+function dispatcherDescription(mode) {
+	return `${{
+		explore: "Non-blocking `explore` worker: dispatches a read-only autonomous worker (its own context) in the background and delivers its summary as a completion notification.",
+		implement: "Non-blocking `implement` worker: dispatches an autonomous coding worker (read/write/bash, optional git worktree) in the background and delivers its result as a completion notification.",
+		review: "Non-blocking `review` worker: dispatches a read-only reviewer that reads the code itself to verify a change or claim, in the background, and delivers findings as a completion notification.",
+		plan: "Non-blocking `plan` worker: dispatches a read-only planner that returns an ordered implementation plan, in the background, and delivers it as a completion notification.",
+		test: "Non-blocking `test` worker: dispatches an independent test author that writes tests trying to break the implementation, in the background, and delivers pass/fail as a completion notification.",
+		browse: "Non-blocking `browse` worker: dispatches an autonomous browser agent in the background and delivers its result as a completion notification."
+	}[mode]} Use proactively for any ${mode}-mode worker task so a long run never blocks your turn: it returns immediately and notifies you when done.`;
+}
+/** The dispatcher subagent's full system prompt: call the one worker tool once,
+*  relay verbatim, do nothing else. */
+function dispatcherPrompt(mode, workersKey) {
+	const tool = workerToolName(workersKey, mode);
+	return [
+		`# Subagent: ${dispatcherAgentName(mode)}`,
+		"",
+		`You are a thin DISPATCHER for the \`${mode}\` worker. You run in the background so the`,
+		"lead agent's turn is never blocked while the (up-to-30-minute) worker runs.",
+		"",
+		"## Your only job",
+		"",
+		`Call the \`${tool}\` tool EXACTLY ONCE, passing through the fields from the lead's brief:`,
+		"  - `prompt`: the lead's worker brief, copied verbatim",
+		"  - `workspace` (optional): absolute path, if the lead specified one",
+		"  - `model` / `thinking` (optional): only if the lead specified them" + (mode === "implement" || mode === "test" ? "\n  - `worktree` (optional): pass `true` if the lead asked for isolated-worktree execution" : ""),
+		"",
+		"When the tool returns, output its result VERBATIM as your final message. That final",
+		"message is what the lead receives in the completion notification — it IS the result.",
+		"",
+		"## Hard rules",
+		"",
+		"- Call the worker tool exactly once. Do not retry on a normal (non-error) return.",
+		"- Do NOT attempt the task yourself, do NOT read/edit files, do NOT run other tools.",
+		"- Do NOT spawn other agents (you have no Agent tool and must not try to gain one).",
+		"- Do NOT summarize, paraphrase, or add commentary — relay the worker output verbatim.",
+		"- If the worker returns an error, relay that error verbatim (do not mask it)."
+	].join("\n");
+}
+/** The `tools:` frontmatter allowlist for a dispatcher: the workers MCP server
+*  wildcard (`mcp__<workersKey>__*`). Claude Code's `tools:` field supports
+*  MCP patterns only at SERVER granularity (`mcp__<server>__*`), not individual
+*  tool names, so this grants exactly the workers tools and NOTHING else — no
+*  Agent/Task (so it cannot spawn further agents → no recursion), no Read/Bash
+*  (so it cannot do extra work). The dispatcher's prompt narrows it to the one
+*  mode; the guard allows any dispatcher-named caller regardless. */
+function dispatcherTools(_mode, workersKey) {
+	return [`mcp__${workersKey}__*`];
+}
+/**
+* Build the shell command Claude Code runs for the workers `PreToolUse` guard
+* hook — the running github-router via its node/bun binary so it works
+* regardless of PATH. Mirrors `buildPromptSubmitHookCommand`.
+*
+* The resolved `workersKey` and the active `modes` are baked into the command
+* ARGS (not env): `mergeStopHookIntoSettings` dedups hooks by the command
+* string only, so baking the key/modes makes a changed resolution produce a
+* DISTINCT command — no stale-matcher entry can survive from a prior launch.
+*/
+function buildWorkerGuardHookCommand(execPath, scriptPath, workersKey, modes) {
+	const q = (s) => `"${s}"`;
+	const args = `internal-worker-guard --workers-key ${q(workersKey)} --modes ${q(modes.join(","))}`;
+	if (scriptPath && scriptPath !== execPath) return `${q(execPath)} ${q(scriptPath)} ${args}`;
+	return `${q(execPath)} ${args}`;
+}
+/** Parse a `--modes` CSV back into validated modes (drops unknown tokens). */
+function parseModesCsv(csv) {
+	if (!csv) return [...CORE_WORKER_MODES];
+	const known = new Set(ALL_WORKER_DISPATCH_MODES);
+	const out = csv.split(",").map((s) => s.trim()).filter((s) => known.has(s));
+	return out.length > 0 ? out : [...CORE_WORKER_MODES];
+}
+
 //#endregion
 //#region src/lib/codex-mcp-config.ts
 /** The `peers` server is always enabled, so its resolved key always exists;
@@ -816,6 +1033,13 @@ function launchChild(target, server$1, options = {}) {
 function peersKeyOf(groupKeys) {
 	return groupKeys.peers ?? GROUP_META.peers.preferredKey;
 }
+/** The resolved `workers` server key (bare `workers`, or the `gh-router-workers`
+*  fallback on collision). Used to name the dispatcher tools and the guard
+*  matcher. Falls back to the preferred bare key when the group is absent (the
+*  caller only builds worker dispatchers when the group is enabled anyway). */
+function workersKeyOf(groupKeys) {
+	return groupKeys.workers ?? GROUP_META.workers.preferredKey;
+}
 /**
 * Decide which MCP backend serves the codex personas.
 *
@@ -975,6 +1199,14 @@ function buildPeerAgentDefinitions(opts) {
 		codexCli: opts.codexCli,
 		geminiAvailable: opts.geminiAvailable
 	});
+	if (opts.workerToolsAvailable) {
+		const workersKey = workersKeyOf(opts.groupKeys);
+		for (const mode of activeDispatchModes({ browse: opts.browseAvailable === true })) out[dispatcherAgentName(mode)] = {
+			description: dispatcherDescription(mode),
+			prompt: dispatcherPrompt(mode, workersKey),
+			tools: dispatcherTools(mode, workersKey)
+		};
+	}
 	return out;
 }
 /**
@@ -1018,17 +1250,24 @@ function escapeYamlString(s) {
 * component.
 */
 const VALID_AGENT_NAME = /^[a-z][a-z0-9-]*$/;
-/** Build a single subagent .md file body (frontmatter + system prompt). */
+/** Build a single subagent .md file body (frontmatter + system prompt).
+*
+* `tools` (optional) becomes a `tools:` frontmatter allowlist RESTRICTING the
+* subagent to exactly those tools (omission inherits the parent's full toolset,
+* per Claude Code semantics). Used by the `worker-*` dispatchers to pin each to
+* its single `mcp__<workersKey>__<mode>` tool — which physically prevents them
+* from spawning other agents or doing extra work. Names are validated by the
+* caller (`writePeerAgentMdFiles`) / are proxy-generated, so no escaping needed
+* beyond the comma-join Claude Code's frontmatter parser expects. */
 function buildAgentMd(spec) {
-	return [
+	const lines = [
 		"---",
 		`name: ${spec.name}`,
-		`description: ${escapeYamlString(spec.description)}`,
-		"---",
-		"",
-		spec.prompt,
-		""
-	].join("\n");
+		`description: ${escapeYamlString(spec.description)}`
+	];
+	if (spec.tools && spec.tools.length > 0) lines.push(`tools: [${spec.tools.map((t) => JSON.stringify(t)).join(", ")}]`);
+	lines.push("---", "", spec.prompt, "");
+	return lines.join("\n");
 }
 /**
 * Write per-launch subagent .md files into the user's `~/.claude/agents/`
@@ -1059,7 +1298,8 @@ async function writePeerAgentMdFiles(agents, opts) {
 			await writeRuntimeFileSecure(filePath, buildAgentMd({
 				name: name$1,
 				description: def.description,
-				prompt: def.prompt
+				prompt: def.prompt,
+				tools: def.tools
 			}));
 			paths.push(filePath);
 		}
@@ -1251,6 +1491,8 @@ async function writePeerMcpRuntimeFiles(serverUrl, opts) {
 		codexCli: opts.codexCli,
 		geminiAvailable: opts.geminiAvailable,
 		groupKeys: opts.groupKeys,
+		workerToolsAvailable: opts.workerToolsAvailable,
+		browseAvailable: opts.browseAvailable,
 		nonce,
 		codexHome
 	});
@@ -2036,7 +2278,7 @@ async function discoverGateCommands(cwd, opts) {
 	if (files.length === 0) return null;
 	let result;
 	try {
-		const { runWorkerAgent } = await import("./engine-CvY9mR3b.js");
+		const { runWorkerAgent } = await import("./engine-BP5EnZ-n.js");
 		result = await runWorkerAgent({
 			mode: "explore",
 			workspace: root,
@@ -2250,9 +2492,9 @@ Use the request's kind and payload as the contract:
 
 Delegate heavy reading to workers:
 
-- Use mcp__workers__explore for focused source or history gathering.
-- Use mcp__workers__review for compact review of a specific plan, PR summary, or suspicious change.
-- Use mcp__workers__test when a missing executable check is the blocker.
+- Use the worker-explore subagent (Agent tool) for focused source or history gathering.
+- Use the worker-review subagent (Agent tool) for compact review of a specific plan, PR summary, or suspicious change.
+- Use the worker-test subagent (Agent tool) when a missing executable check is the blocker.
 
 Do not read a full diff, full CI log, or full transcript in the lead context. Ask workers for narrow facts and compact excerpts. The ledger is durable memory; context is not.
 
@@ -2385,7 +2627,7 @@ Binding rule:
 
 Ask whether changed behavior has executable coverage.
 
-- If behavior changed and no relevant test exists, use mcp__workers__test to author a focused test through a DIFFERENT lab than the implementer when possible.
+- If behavior changed and no relevant test exists, dispatch the worker-test subagent (Agent tool, subagent_type worker-test) to author a focused test through a DIFFERENT lab than the implementer when possible.
 - Cap missing-test attempts; default to a small number of focused tries.
 - Run the new test and then the relevant existing gate.
 - If creating a large new harness, broad fixture system, or slow integration environment is required, ask the user before proceeding.
@@ -2534,10 +2776,10 @@ Tag every blind spot as executable-checkable or judgment-only.
 
 ## Phase 3 and 4: decompose and plan (run in parallel)
 
-These two are INDEPENDENT: mcp__orchestrate__decompose consumes { ask, context: research brief plus blind-spots }, and mcp__workers__plan consumes the ask, acceptance criteria, research pointer, and blind-spot table. Neither needs the other's output. So issue BOTH calls in a SINGLE parallel batch (same turn) — do not wait for decompose before calling plan.
+These two are INDEPENDENT: mcp__orchestrate__decompose consumes { ask, context: research brief plus blind-spots }, and the worker-plan subagent consumes the ask, acceptance criteria, research pointer, and blind-spot table. Neither needs the other's output. So issue BOTH in a SINGLE parallel batch (same turn) — call mcp__orchestrate__decompose and dispatch the worker-plan subagent together; do not wait for decompose first.
 
 - decompose: mcp__orchestrate__decompose({ ask, context: research brief plus blind-spots }). Treat the output as a proposal, not gospel; reject or revise nodes that do not map to a real blind spot.
-- plan: mcp__workers__plan with the ask, acceptance criteria, research pointer, and blind-spot table. Ask for files, tests, rollback concerns, and minimal safe increments; keep it bounded and suited to the change size.
+- plan: dispatch the worker-plan subagent (Agent tool, subagent_type worker-plan) with the ask, acceptance criteria, research pointer, and blind-spot table. Ask for files, tests, rollback concerns, and minimal safe increments; keep it bounded and suited to the change size.
 
 ## Phase 5: compose a native Workflow
 
@@ -2559,10 +2801,10 @@ Parallelism (the Workflow tool's core optimization rule):
 
 Role to tool mapping:
 
-- research: mcp__workers__explore and mcp__search__code for focused follow-ups.
-- plan: mcp__workers__plan.
-- implement: mcp__workers__implement, with worktree:true for parallel writers.
-- test: mcp__workers__test, authored by a DIFFERENT LAB than the implementer when possible. This is an advisory practice, not enforced provenance.
+- research: worker-explore (Agent subagent) and mcp__search__code for focused follow-ups.
+- plan: worker-plan (Agent subagent).
+- implement: worker-implement (Agent subagent), with worktree:true for parallel writers.
+- test: worker-test (Agent subagent), authored by a DIFFERENT LAB than the implementer when possible. This is an advisory practice, not enforced provenance.
 - review: mcp__peers__codex_reviewer plus mcp__peers__gemini_reviewer. Advisory unless findings are converted into executable checks or code changes.
 - baseline and selector: OPT-IN only because it doubles cost. Choose max(orchestrated, baseline) by EXECUTABLE gate result, not model judgment. If no executable oracle exists, say the selector is advisory.
 - verify: cross-lab checker plus mcp__orchestrate__attest_step with producer not equal to checker lab.
@@ -2672,7 +2914,7 @@ Default caps unless the user explicitly gives a smaller or larger budget:
    - Then use mcp__search__code lexically for exact symbols, filenames, errors, routes, flags, and config keys.
    - Use git blame or history when authorship, regression timing, or intent matters.
    - Use mcp__search__web for upstream APIs, package behavior, protocol docs, or public issues.
-   - Launch parallel mcp__workers__explore workers for heavy gathering, each with a narrow question and expected artifact.
+   - Launch parallel worker-explore background subagents (via the Agent tool, subagent_type worker-explore) for heavy gathering, each with a narrow question and expected artifact. They run non-blocking and report back on completion.
    - Keep worker results summarized; do not paste every detail into the main context.
 
 4. Form a root-cause hypothesis.
@@ -2684,7 +2926,7 @@ Default caps unless the user explicitly gives a smaller or larger budget:
 5. Verify load-bearing claims adversarially.
    - First preference: reproduce the bug, run the failing test, or run the direct check. Tag verified-executable.
    - If executable proof is not available, read the actual source or primary artifact and cite the lines. Tag verified-source.
-   - Ask mcp__workers__review to confirm the source-reading for important claims.
+   - Dispatch the worker-review subagent (via the Agent tool) to confirm the source-reading for important claims.
    - Ask a different-lab refuter through mcp__peers__codex_critic or mcp__peers__gemini_critic to try to refute the hypothesis.
    - Give the refuter the symptom, observed facts, and acceptance criteria, but not your proposed root cause. Avoid anchoring them.
    - If the refuter finds a plausible alternative, add it to the worklist and spend at most one bounded round resolving it.
@@ -2723,6 +2965,67 @@ Return a compact brief, not the whole research dump:
 `
 };
 
+//#endregion
+//#region src/lib/injected-skills/worker-skill.ts
+/**
+* The `/gh-worker` skill: the operating model for the NON-BLOCKING workers
+* surface. Materialized into the per-launch mirror whenever `workerToolsEnabled()`
+* (same gate as the other floor-raising skills). Discoverability + playbook; the
+* load-bearing enforcement is the PreToolUse guard + the `worker-*` dispatcher
+* subagents (see src/lib/worker-dispatch.ts).
+*/
+const WORKER_SKILL = {
+	name: "gh-worker",
+	md: `---
+name: gh-worker
+description: How to run github-router workers without blocking your turn. Workers (explore/implement/review/plan/test) can run up to 30 minutes; dispatch the matching worker-* background subagent so you get a completion notification instead of waiting. Use whenever you would reach for a worker.
+user-invocable: true
+---
+
+# gh-worker: non-blocking workers
+
+Worker tasks (explore, implement, review, plan, test) can run for up to 30
+minutes. In this session they are NON-BLOCKING BY DESIGN: you dispatch a
+background \`worker-*\` subagent, get control back immediately, and receive the
+worker's result as a completion notification when it finishes. Your turn is
+never blocked waiting on a worker, and the worker's tool output never fills your
+context (only its final result comes back).
+
+## How to run a worker
+
+Dispatch the matching dispatcher subagent with the Agent tool:
+
+- worker-explore: read-only investigation / codebase gathering, returns a summary.
+- worker-review: reads the code itself to verify a change or claim; findings with severity + file:line.
+- worker-plan: returns an ordered implementation plan from a task + acceptance criteria.
+- worker-implement: read/write/bash coding worker; pass worktree: true for isolated-worktree execution + a returned diff.
+- worker-test: independent test author that writes tests trying to break the implementation and reports pass/fail.
+
+Put the full worker brief in the subagent's prompt (and an absolute workspace
+path, or model/thinking/worktree, only if you need to override the defaults).
+The dispatcher calls the worker once and relays its result verbatim.
+
+## What to expect
+
+- The dispatch returns immediately; you can keep working or start other workers.
+- When the worker finishes you get a completion notification carrying its result.
+- Up to 8 workers run concurrently (the worker-semaphore cap); further dispatches queue.
+- You do NOT call the raw mcp__...__ worker tools from the main thread: a guard
+  denies that and points you at the matching worker-* subagent. That guard is the
+  guarantee your turn never blocks; dispatching worker-* directly is the normal path.
+
+## Notes
+
+- Large worker output may be summarized by the dispatcher relay; for a big
+  artifact, have the worker write it to a file and return the path.
+- Dispatching the same worker twice runs it twice (no dedup); avoid double-dispatch
+  for side-effecting work like worker-implement.
+- Background subagents + completion notifications are the interactive default. In
+  headless (claude -p) runs the task surface behaves differently; prefer interactive
+  for long worker fan-out.
+`
+};
+
 //#endregion
 //#region src/lib/injected-skills/artifact-review-skill.ts
 const ARTIFACT_REVIEW_SKILL = {
@@ -2814,6 +3117,8 @@ const PEER_MARKER_OPEN = "<!-- gh-router peer-mcp awareness — auto-injected, r
 const PEER_MARKER_CLOSE = "<!-- /gh-router peer-mcp awareness -->";
 const STYLE_MARKER_OPEN = "<!-- gh-router style directive — auto-injected, regenerated per launch -->";
 const STYLE_MARKER_CLOSE = "<!-- /gh-router style directive -->";
+const OPERATING_MARKER_OPEN = "<!-- gh-router operating defaults — auto-injected, regenerated per launch -->";
+const OPERATING_MARKER_CLOSE = "<!-- /gh-router operating defaults -->";
 const TOOLBELT_MARKER_OPEN = "<!-- gh-router toolbelt awareness — auto-injected, regenerated per launch -->";
 const TOOLBELT_MARKER_CLOSE = "<!-- /gh-router toolbelt awareness -->";
 const ARTIFACT_MARKER_OPEN = "<!-- gh-router artifact-panel directive — auto-injected when in an ai-or-die tab -->";
@@ -2829,6 +3134,28 @@ const ARTIFACT_PANEL_DIRECTIVE = "## Review in the artifact panel (HTML by defau
 */
 const STYLE_DIRECTIVE = "Write concisely without losing detail. Use a natural human voice. Avoid em dashes. Do not attribute work to Claude, AI, LLM, or Anthropic anywhere (commits, PRs, issues, code, comments, docs).";
 /**
+* Operating-defaults directive injected at the TOP of the mirrored CLAUDE.md
+* AND into the main agent's system prompt (`--append-system-prompt`), so it is
+* the highest-salience behavioral default. Two defaults, both explicitly
+* overridden by the user's own direction and the domain's standards:
+*
+*   1. Orchestrate (strong default): delegate the heavy / parallel /
+*      context-heavy work to the right subagent / worker / model, keeping the
+*      main context free to reason and collaborate with the user, while still
+*      doing trivial / surgical / last-mile work directly (delegating that
+*      would only add relay-fidelity loss + latency).
+*   2. Excellence lens (HYBRID per the peer review): the reliable control
+*      signal is the PRINCIPLE stated plainly; the well-known names appear only
+*      as a "bar to clear" calibration, NOT as "channel X", with an explicit
+*      no-impersonation / no-theatrics guardrail (cross-lab critics: a named
+*      entity is a dense, high-variance vector that pulls in noise + persona
+*      mannerisms at top salience, so the principle leads and the name calibrates).
+*
+* Self-referentially compliant with the style directive: no em dashes, no
+* Claude / Anthropic attribution.
+*/
+const OPERATING_DEFAULTS_DIRECTIVE = "## Operating defaults (apply when the user has not specified otherwise; the user's explicit direction and the domain's own standards always override)\n\nOrchestrate. Delegate research, implementation, review, and large reads to the right subagent, worker, or model (worker-* agents for background non-blocking runs, Task subagents for parallel work, peer critics for review) so your own context stays free to reason and collaborate with the user. Prefer parallel delegation for independent work. Do trivial, surgical, and last-mile work directly; delegate the rest rather than doing it yourself and filling your own context.\n\nAim high. Default to radical simplicity and relentless focus on the user's real experience (the Jobs and Ive bar for design), whole-systems first-principles thinking that anticipates scale and the long arc (the Gates bar for architecture and tech), and customer obsession that works backwards from the outcome (the Bezos bar for product and business). Question every assumption and prefer what you can derive, reproduce, or test. Adopt the principles, not a persona: no impersonation, name-dropping, or theatrics.";
+/**
 * Skip the helper if the user's `~/.claude/CLAUDE.md` (or, equivalently,
 * the would-be post-write file) has grown past this size.
 * Read-modify-write becomes pathological at very large sizes; CLAUDE.md
@@ -3166,6 +3493,23 @@ async function prependStyleDirectiveToMirroredClaudeMd(directive = STYLE_DIRECTI
 	});
 }
 /**
+* Prepend the operating-defaults directive (orchestrator posture + hybrid
+* excellence lens; `OPERATING_DEFAULTS_DIRECTIVE` above) to the TOP of the
+* mirrored CLAUDE.md so descendant agents (Agent subagents, agent-teams
+* teammates) inherit it. The main agent gets the same text at higher salience
+* via `--append-system-prompt`. Separate marker fence from the style / peer
+* blocks so all coexist; best-effort (warn-and-continue) like its siblings.
+*/
+async function prependOperatingDefaultsToMirroredClaudeMd(directive = OPERATING_DEFAULTS_DIRECTIVE) {
+	await injectMarkerBlock({
+		snippet: directive,
+		markerOpen: OPERATING_MARKER_OPEN,
+		markerClose: OPERATING_MARKER_CLOSE,
+		position: "top",
+		label: "operating-defaults"
+	});
+}
+/**
 * Append the toolbelt awareness one-liner (which CLI tools are on PATH)
 * to the bottom of the mirrored CLAUDE.md so descendant agents (Agent
 * subagents, agent-teams teammates) learn about the provisioned tools.
@@ -3257,6 +3601,7 @@ const INJECTED_SKILLS = [
 	RESEARCH_SKILL,
 	ORCHESTRATE_SKILL,
 	FLOOR_KEEPER_SKILL,
+	WORKER_SKILL,
 	FIRST_MATE_SKILL
 ];
 
@@ -3739,7 +4084,7 @@ function initProxyFromEnv() {
 //#endregion
 //#region package.json
 var name = "github-router";
-var version$1 = "0.3.152";
+var version$1 = "0.3.153";
 
 //#endregion
 //#region src/lib/approval.ts
@@ -5890,6 +6235,7 @@ const claude = defineCommand({
 			await removeOwnClaudeConfigMirror();
 		};
 		let onShutdown = baseShutdown;
+		let peerAwarenessSnippet;
 		if (args["codex-mcp"] !== false) try {
 			const requestedCli = args["codex-cli"] ?? false;
 			const backend = resolveCodexCliBackend({
@@ -5912,7 +6258,9 @@ const claude = defineCommand({
 			const runtime = await writePeerMcpRuntimeFiles(serverUrl, {
 				codexCli: backend === "cli",
 				geminiAvailable,
-				groupKeys
+				groupKeys,
+				workerToolsAvailable: workerToolsEnabled(),
+				browseAvailable: browseAgentEnabled()
 			});
 			state.peerMcpNonce = runtime.nonce;
 			envVars.GH_ROUTER_HOOK_MCP_URL = serverUrl;
@@ -5945,6 +6293,16 @@ const claude = defineCommand({
 				} catch (err) {
 					consola.warn(`Could not register the UserPromptSubmit hook: ${String(err)}`);
 				}
+				if (!injected.ok) consola.warn("Workers non-blocking guard NOT registered: subagent MCP injection fell back to parent-only (--mcp-config), so worker-* dispatchers cannot reach the workers server. Raw (blocking) worker tools remain usable on the main thread this session.");
+				else if (process$1.env.GH_ROUTER_DISABLE_WORKER_GUARD === "1") consola.info("Workers non-blocking guard disabled via GH_ROUTER_DISABLE_WORKER_GUARD=1 — raw mcp__workers__* is callable on the main thread (blocking); the worker-* background agents remain the steered, non-blocking default.");
+				else try {
+					const settingsPath = nodePath.join(PATHS.CLAUDE_CONFIG_DIR, "settings.json");
+					const workersKey = workersKeyOf(groupKeys);
+					const modes = activeDispatchModes({ browse: browseAgentEnabled() });
+					await injectStopHookIntoSettingsFile(settingsPath, buildWorkerGuardHookCommand(process$1.execPath, process$1.argv[1], workersKey, modes), "PreToolUse", 10, guardToolMatcher(workersKey, modes));
+				} catch (err) {
+					consola.warn(`Could not register the workers PreToolUse guard hook: ${String(err)}`);
+				}
 				if (skillsWritten > 0) {
 					const skillNames = skillsToWrite.map((s) => `/${s.name}`).join(", ");
 					process$1.stderr.write(`Injected skills (${skillsWritten}/${skillsToWrite.length}): ${skillNames}.\n`);
@@ -6084,7 +6442,7 @@ const claude = defineCommand({
 				agentToolsAvailable: agentToolsEnabled(),
 				groupKeys
 			});
-			extraArgs.push("--append-system-prompt", peerSnippet);
+			peerAwarenessSnippet = peerSnippet;
 			try {
 				await appendPeerAwarenessToMirroredClaudeMd(peerSnippet);
 			} catch (err) {
@@ -6098,6 +6456,12 @@ const claude = defineCommand({
 		} catch (err) {
 			consola.warn(`Peer MCP wiring failed (claude will launch without it): ${err instanceof Error ? err.message : String(err)}`);
 		}
+		extraArgs.push("--append-system-prompt", peerAwarenessSnippet ? `${OPERATING_DEFAULTS_DIRECTIVE}\n\n${peerAwarenessSnippet}` : OPERATING_DEFAULTS_DIRECTIVE);
+		try {
+			await prependOperatingDefaultsToMirroredClaudeMd();
+		} catch (err) {
+			consola.warn(`Operating-defaults CLAUDE.md prepend failed: ${err instanceof Error ? err.message : String(err)}`);
+		}
 		launchChild({
 			kind: "claude-code",
 			envVars,
@@ -6373,7 +6737,7 @@ async function postJson(url, payload, opts) {
 * no such handle. Hooks always receive piped/redirected stdin, so this never
 * blocks (guarded against an interactive TTY, and any error -> "").
 */
-function readStdin$3() {
+function readStdin$4() {
 	try {
 		if (process.stdin.isTTY) return "";
 		return readFileSync(0, "utf8");
@@ -6404,7 +6768,7 @@ const internalPromptSubmit = defineCommand({
 	},
 	async run() {
 		try {
-			const stdin = readStdin$3();
+			const stdin = readStdin$4();
 			const steerEnabled = parseBoolEnv(process.env.GH_ROUTER_DISABLE_PROMPT_STEER) !== true;
 			const runtime = hookMcpRuntimeFromEnv();
 			let decision;
@@ -6464,7 +6828,7 @@ const internalPromptSubmit = defineCommand({
 * teardown and trips a `uv_async_send` assertion; a synchronous read has no such
 * handle. Hooks always receive piped stdin (guarded against a TTY; any error -> "").
 */
-function readStdin$2() {
+function readStdin$3() {
 	try {
 		if (process.stdin.isTTY) return "";
 		return readFileSync(0, "utf8");
@@ -6554,7 +6918,7 @@ const internalSessionBind = defineCommand({
 		try {
 			const out = typeof args.out === "string" ? args.out.trim() : "";
 			if (!out) return;
-			const record = decodeSessionBind(readStdin$2());
+			const record = decodeSessionBind(readStdin$3());
 			if (record) writeSidecar(out, record);
 		} catch {}
 		process.exitCode = 0;
@@ -6723,7 +7087,7 @@ ${body}
 
 //#endregion
 //#region src/internal-artifact-open.ts
-function readStdin$1() {
+function readStdin$2() {
 	try {
 		if (process.stdin.isTTY) return "";
 		return readFileSync(0, "utf8");
@@ -6817,7 +7181,7 @@ const internalArtifactOpen = defineCommand({
 	},
 	async run() {
 		try {
-			const raw = readStdin$1();
+			const raw = readStdin$2();
 			let payload;
 			try {
 				payload = JSON.parse(raw);
@@ -6845,7 +7209,7 @@ const internalArtifactOpen = defineCommand({
 * no such handle. Hooks always receive piped/redirected stdin, so this never
 * blocks (guarded against an interactive TTY, and any error -> "").
 */
-function readStdin() {
+function readStdin$1() {
 	try {
 		if (process.stdin.isTTY) return "";
 		return readFileSync(0, "utf8");
@@ -6972,7 +7336,7 @@ const internalStopHook = defineCommand({
 		description: "Internal: the structural-gate Stop hook. Reads the Claude Code hook payload on stdin, runs the sealed gate, exits 2 (blocks the stop) on a red gate or gate-weakening diff."
 	},
 	async run() {
-		const stdin = readStdin();
+		const stdin = readStdin$1();
 		const reviewEnabled = stopReviewEnabled() && hookMcpRuntimeFromEnv() !== void 0;
 		let transcriptPath = "";
 		let userPrompt = "";
@@ -7109,6 +7473,56 @@ const internalStopReview = defineCommand({
 	}
 });
 
+//#endregion
+//#region src/internal-worker-guard.ts
+/**
+* Read the hook payload from stdin SYNCHRONOUSLY (`readFileSync(0)`) — same
+* rationale as `internal-prompt-submit`: an async stdin read leaves an in-flight
+* libuv FS request that races Windows process teardown. Hooks always receive
+* piped stdin (guarded against an interactive TTY; any error → "").
+*/
+function readStdin() {
+	try {
+		if (process.stdin.isTTY) return "";
+		return readFileSync(0, "utf8");
+	} catch {
+		return "";
+	}
+}
+const internalWorkerGuard = defineCommand({
+	meta: {
+		name: "internal-worker-guard",
+		description: "Internal: the workers PreToolUse guard. Denies a raw mcp__<workers>__<mode> call from the main agent (redirecting to the worker-<mode> background subagent) and allows it from the dispatcher subagent. Fails closed."
+	},
+	args: {
+		"workers-key": {
+			type: "string",
+			description: "Resolved workers MCP config key (bare `workers` or `gh-router-workers`).",
+			required: true
+		},
+		modes: {
+			type: "string",
+			description: "CSV of active worker modes, e.g. `explore,implement,review,plan,test`.",
+			required: false
+		}
+	},
+	run(ctx) {
+		try {
+			const stdin = readStdin();
+			const workersKey = String(ctx.args["workers-key"] ?? "").trim();
+			if (workersKey.length > 0) {
+				const { output } = decideWorkerGuard({
+					stdin,
+					workersKey,
+					modes: parseModesCsv(typeof ctx.args.modes === "string" ? ctx.args.modes : void 0)
+				});
+				if (output) process.stdout.write(output);
+			}
+		} catch {}
+		process.exitCode = 0;
+	}
+});
+
 //#endregion
 //#region src/models.ts
 const models = defineCommand({
@@ -7394,7 +7808,7 @@ process.on("uncaughtException", (error) => {
 const version = getPackageVersion();
 const argv = process.argv.slice(2);
 const isVersionFlag = argv.includes("--version");
-const isInternalHook = argv[0] === "internal-stop-hook" || argv[0] === "internal-prompt-submit" || argv[0] === "internal-stop-review" || argv[0] === "internal-session-bind" || argv[0] === "internal-artifact-open";
+const isInternalHook = argv[0] === "internal-stop-hook" || argv[0] === "internal-prompt-submit" || argv[0] === "internal-stop-review" || argv[0] === "internal-session-bind" || argv[0] === "internal-artifact-open" || argv[0] === "internal-worker-guard";
 if (!isVersionFlag && !isInternalHook) consola.info(`github-router v${version}`);
 await runMain(defineCommand({
 	meta: {
@@ -7414,7 +7828,8 @@ await runMain(defineCommand({
 		"internal-prompt-submit": internalPromptSubmit,
 		"internal-stop-review": internalStopReview,
 		"internal-session-bind": internalSessionBind,
-		"internal-artifact-open": internalArtifactOpen
+		"internal-artifact-open": internalArtifactOpen,
+		"internal-worker-guard": internalWorkerGuard
 	}
 }));