@webpresso/agent-kit 3.1.30 → 3.3.0

package/dist/esm/hooks/__conformance__/matrix.js

@@ -110,6 +110,96 @@ function denyDecision(obj) {
         return "deny";
     return null;
 }
+/** Extract the host-displayed deny reason from either envelope shape. */
+function denyReasonText(obj) {
+    const hookSpecific = obj?.hookSpecificOutput;
+    if (hookSpecific && typeof hookSpecific === "object") {
+        const reason = hookSpecific.permissionDecisionReason;
+        if (typeof reason === "string")
+            return reason;
+    }
+    // Grok dual envelope carries a top-level reason.
+    if (typeof obj?.reason === "string")
+        return obj.reason;
+    return null;
+}
+const GUARD_CODED_REASON_RE = /^GUARD_[A-Z0-9_]+: /u;
+/**
+ * Every PreToolUse deny reason on a parseable stdout envelope carries a stable
+ * `GUARD_<CODE>: ` prefix within the 80-char permissionDecisionReason budget.
+ * The code is the cross-host contract; the prose is truncated to fit.
+ *
+ * This reads `result.stdout` directly (NOT the decision-path `obj`, which is
+ * null for a Claude exit-2 deny) so the coded reason is asserted on BOTH hosts —
+ * pretool-guard always prints the deny envelope to stdout (dual for claude/grok,
+ * hookSpecificOutput-only for codex) even when Claude reads the exit code for the
+ * decision itself. Non-JSON stdout (the synthetic "stdout is ignored" fixture)
+ * and the empty-stdout exit-code-deny convention carry no reason and are skipped.
+ */
+/** Parse an optional deny reason out of a JSON stdout deny envelope. */
+function stdoutDenyReason(stdout) {
+    const text = stdout.trim();
+    if (text === "")
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return null;
+    return denyReasonText(parsed);
+}
+/** First GUARD_-coded line in a captured stderr blob (Claude's exit-2 channel). */
+function stderrCodedReason(stderr) {
+    if (!stderr)
+        return null;
+    for (const line of stderr.split("\n")) {
+        if (GUARD_CODED_REASON_RE.test(line.trim()))
+            return line.trim();
+    }
+    return null;
+}
+/** Assert a single reason is GUARD_-coded and within the 80-code-point budget. */
+function assertCodedWithinBudget(row, label, reason) {
+    if (!GUARD_CODED_REASON_RE.test(reason)) {
+        throw new Error(`[${row.name}] ${label} must start with a GUARD_ code prefix, got ${JSON.stringify(reason)}`);
+    }
+    const points = [...reason].length;
+    if (points > 80) {
+        throw new Error(`[${row.name}] ${label} exceeds the 80-code-point budget (${points}): ${JSON.stringify(reason)}`);
+    }
+}
+function assertGuardCodedDenyReason(row, result) {
+    // The coded reason must reach the host on the channel it reads: the stdout
+    // deny envelope (Codex/Grok) or stderr (Claude reads stderr on an exit-2
+    // PreToolUse deny). Single-spawn tests capture the host boundary directly;
+    // the batch runner installs a row-scoped intentional-stderr capture so this
+    // same assertion also applies to source/compiled parity.
+    const reason = stdoutDenyReason(result.stdout) ?? stderrCodedReason(result.stderr);
+    if (reason === null) {
+        throw new Error(`[${row.name}] a PreToolUse deny must carry a GUARD_-coded reason on the stdout envelope or stderr; found none`);
+    }
+    assertCodedWithinBudget(row, "deny reason", reason);
+}
+function assertCodexExitTwoBlockingReason(row, result) {
+    if (row.host !== "codex" ||
+        row.event !== "PreToolUse" ||
+        result.exitCode !== 2 ||
+        result.stderr === undefined) {
+        return;
+    }
+    const stderrReason = stderrCodedReason(result.stderr);
+    if (stderrReason === null) {
+        throw new Error(`[${row.name}] Codex exit-2 PreToolUse deny must write a GUARD_-coded blocking reason to stderr`);
+    }
+    const stdoutReason = stdoutDenyReason(result.stdout);
+    if (stdoutReason !== null && stderrReason !== stdoutReason) {
+        throw new Error(`[${row.name}] Codex stdout and stderr deny reasons must match exactly`);
+    }
+}
 /** PermissionRequest golden wire: hookSpecificOutput.decision.behavior allow|deny. */
 function permissionRequestBehavior(obj) {
     const hookSpecific = obj?.hookSpecificOutput;
@@ -121,6 +211,45 @@ function permissionRequestBehavior(obj) {
     const behavior = decision.behavior;
     return typeof behavior === "string" ? behavior : null;
 }
+/** PermissionRequest golden wire message: hookSpecificOutput.decision.message. */
+function permissionRequestMessage(obj) {
+    const hookSpecific = obj?.hookSpecificOutput;
+    if (!hookSpecific || typeof hookSpecific !== "object")
+        return null;
+    const decision = hookSpecific.decision;
+    if (!decision || typeof decision !== "object")
+        return null;
+    const message = decision.message;
+    return typeof message === "string" ? message : null;
+}
+/**
+ * A PermissionRequest allow/deny message on a parseable envelope carries the
+ * same `GUARD_<CODE>: ` prefix within the 80-char budget as PreToolUse denies —
+ * the vocabulary is central, not PreToolUse-only. Skipped when there is no
+ * envelope message (e.g. a pure exit-2 deny with no stdout).
+ */
+function assertGuardCodedPermissionMessage(row, result, expect) {
+    let stdoutMessage = null;
+    const text = result.stdout.trim();
+    if (text !== "") {
+        try {
+            const parsed = JSON.parse(text);
+            if (parsed !== null && typeof parsed === "object") {
+                stdoutMessage = permissionRequestMessage(parsed);
+            }
+        }
+        catch {
+            stdoutMessage = null;
+        }
+    }
+    // A deny exits 2 and also carries the coded message on stderr; an allow exits 0
+    // with the coded message on the stdout envelope.
+    const message = stdoutMessage ?? stderrCodedReason(result.stderr);
+    if (message === null) {
+        throw new Error(`[${row.name}] PermissionRequest ${expect} must carry a GUARD_-coded message on the stdout envelope or stderr; found none`);
+    }
+    assertCodedWithinBudget(row, "PermissionRequest message", message);
+}
 function assertNoCodexUnsupportedFields(row, obj) {
     if (row.host !== "codex" || obj === null)
         return;
@@ -170,6 +299,11 @@ export function assertConformance(row, result) {
                 // exit-code deny convention). A deny envelope printed just before the hook
                 // crashes (exit 1) is not a valid decision.
                 assertExitCode(row, result, true);
+                // Every deny reason is GUARD_-coded and within the 80-char budget on
+                // both Tier-1 hosts (read from stdout, which carries the envelope even
+                // when Claude uses the exit code for the decision).
+                assertGuardCodedDenyReason(row, result);
+                assertCodexExitTwoBlockingReason(row, result);
             }
             else {
                 if (decision === "deny") {
@@ -196,6 +330,8 @@ export function assertConformance(row, result) {
                 if (result.exitCode !== 2) {
                     throw new Error(`[${row.name}] expected PermissionRequest deny via exit 2, got exit ${result.exitCode ?? "null"}`);
                 }
+                // The deny message carries the central GUARD_ code contract too.
+                assertGuardCodedPermissionMessage(row, result, "deny");
                 return;
             }
             if (row.expect === "allow") {
@@ -203,6 +339,7 @@ export function assertConformance(row, result) {
                     throw new Error(`[${row.name}] expected PermissionRequest allow envelope, got behavior=${behavior ?? "none"} (stdout: ${result.stdout.slice(0, 160)})`);
                 }
                 assertExitCode(row, result, false);
+                assertGuardCodedPermissionMessage(row, result, "allow");
                 return;
             }
             // pass-through: host default UI — empty object (or empty stdout), no decision, exit 0.

package/dist/esm/hooks/conformance/batch.js

@@ -85,6 +85,7 @@ export async function runHookConformanceBatch() {
     }
     const raw = await readBatchStdin();
     const { isHookName, runHookCommand } = await import("#cli/commands/hook.js");
+    const { installGuardStderrCapture } = await import("#hooks/shared/hook-bootstrap");
     const payload = parseBatchPayload(raw, isHookName);
     const protocolWrite = process.stdout.write.bind(process.stdout);
     for (const row of payload.rows) {
@@ -92,6 +93,9 @@ export async function runHookConformanceBatch() {
         let stdout = "";
         let stderr = "";
         const restoreEnv = setRowEnvironment(row);
+        const restoreGuardStderrCapture = installGuardStderrCapture((text) => {
+            stderr += text;
+        });
         const originalStdoutWrite = process.stdout.write;
         const originalStderrWrite = process.stderr.write;
         process.stdout.write = (chunk) => {
@@ -112,6 +116,7 @@ export async function runHookConformanceBatch() {
         finally {
             process.stdout.write = originalStdoutWrite;
             process.stderr.write = originalStderrWrite;
+            restoreGuardStderrCapture();
             restoreEnv();
         }
         protocolWrite(`${JSON.stringify({ type: "result", id: row.id, stdout, stderr, exitCode })}\n`);

package/dist/esm/hooks/doctor.d.ts

@@ -118,15 +118,17 @@ export declare function checkCodexConfigKeys(configFilePath?: string, deps?: Hos
 export declare function checkProjectMcpPins(cwd?: string, deps?: HostConfigDoctorDeps): DoctorCheck;
 export interface ClaudeMcpDuplicateRegistrationOptions {
     readonly home?: string;
+    /** Project root used to discover a project-local `.mcp.json` registration. */
+    readonly projectRoot?: string;
     readonly exists?: (path: string) => boolean;
     readonly readFile?: (path: string) => string;
 }
 /**
  * `claude-mcp-duplicate-registration` — advisory. A machine can register the
  * webpresso MCP server twice for the same Claude Code session: a manual
- * `claude mcp add webpresso` entry in `~/.claude.json` (user scope or a
- * project scope) plus the agent-kit marketplace plugin's bundled server
- * (plugin cache under `~/.claude/plugins/`). Both spawn `wp mcp`, so affected
+ * `claude mcp add webpresso` entry in Claude Code's home JSON config (user
+ * scope or a project scope) plus the agent-kit marketplace plugin's bundled
+ * server from the Claude plugin cache. Both spawn `wp mcp`, so affected
  * sessions run two server processes and carry a duplicated wp_* tool list.
  * Degrades to ok on missing/unreadable config — loud only on real duplication.
  */

package/dist/esm/hooks/doctor.js

@@ -658,11 +658,15 @@ function probeDecisionRow(wpCli, row) {
             detached: process.platform !== "win32",
         });
         let stdout = "";
+        let stderr = "";
         const timeoutMs = hookProbeTimeoutMs();
         const settle = createOwnedProbeSettler(child, timeoutMs, () => ({ ok: false, detail: `decision probe timed out after ${timeoutMs}ms` }), resolve);
         child.stdout.on("data", (chunk) => {
             stdout += String(chunk);
         });
+        child.stderr.on("data", (chunk) => {
+            stderr += String(chunk);
+        });
         child.stdin.on?.("error", (err) => {
             settle({ ok: false, detail: `stdin write failed: ${err.message}` });
         });
@@ -674,7 +678,7 @@ function probeDecisionRow(wpCli, row) {
         });
         child.on("close", (code) => {
             try {
-                assertConformance(row, { stdout, exitCode: code });
+                assertConformance(row, { stdout, stderr, exitCode: code });
                 settle({ ok: true });
             }
             catch (error) {
@@ -1256,13 +1260,15 @@ async function checkClaudeHost() {
 }
 async function checkGrokHost(cwd = process.cwd()) {
     const available = await runCommand("grok", ["--version"]);
-    const hooksPath = join(cwd, ".grok", "hooks.json");
+    const hooksPath = join(cwd, ".grok", "hooks", "webpresso.json");
     let hooksPresent = false;
     let hostLabeled = false;
     try {
         const body = readFileSync(hooksPath, "utf8");
         hooksPresent = true;
-        hostLabeled = body.includes("WP_HOOK_HOST=grok");
+        // The generated launcher chain shell-quotes the value (WP_HOOK_HOST='grok');
+        // accept any quoting variant so the doctor recognizes its own output.
+        hostLabeled = /WP_HOOK_HOST=(['"]?)grok\1/u.test(body);
     }
     catch {
         // Missing project hooks is advisory when binary absent; fail when binary present.
@@ -1273,8 +1279,8 @@ async function checkGrokHost(cwd = process.cwd()) {
             ok: true,
             detail: hooksPresent
                 ? hostLabeled
-                    ? "skipped (grok not on PATH); native .grok/hooks.json present with WP_HOOK_HOST=grok"
-                    : "skipped (grok not on PATH); .grok/hooks.json present but missing WP_HOOK_HOST=grok"
+                    ? "skipped (grok not on PATH); native .grok/hooks/webpresso.json present with WP_HOOK_HOST=grok"
+                    : "skipped (grok not on PATH); .grok/hooks/webpresso.json present but missing WP_HOOK_HOST=grok"
                 : "skipped (grok not on PATH)",
         };
     }
@@ -1282,20 +1288,20 @@ async function checkGrokHost(cwd = process.cwd()) {
         return {
             name: "Grok host integration",
             ok: false,
-            detail: "grok on PATH but missing project .grok/hooks.json — run wp setup to scaffold native hooks",
+            detail: "grok on PATH but missing project .grok/hooks/webpresso.json — run wp setup to scaffold native hooks, then run /hooks-trust once in Grok",
         };
     }
     if (!hostLabeled) {
         return {
             name: "Grok host integration",
             ok: false,
-            detail: ".grok/hooks.json present but managed commands lack WP_HOOK_HOST=grok",
+            detail: ".grok/hooks/webpresso.json present but managed commands lack WP_HOOK_HOST=grok",
         };
     }
     return {
         name: "Grok host integration",
         ok: true,
-        detail: "native .grok/hooks.json with WP_HOOK_HOST=grok (PreToolUse fail-open residual applies)",
+        detail: "native .grok/hooks/webpresso.json with WP_HOOK_HOST=grok (trust-gated: run /hooks-trust once; PreToolUse fail-open residual applies)",
     };
 }
 // Markers for the direct hook commands `wp setup` writes into
@@ -1793,9 +1799,9 @@ export function checkProjectMcpPins(cwd = process.cwd(), deps = {}) {
 /**
  * `claude-mcp-duplicate-registration` — advisory. A machine can register the
  * webpresso MCP server twice for the same Claude Code session: a manual
- * `claude mcp add webpresso` entry in `~/.claude.json` (user scope or a
- * project scope) plus the agent-kit marketplace plugin's bundled server
- * (plugin cache under `~/.claude/plugins/`). Both spawn `wp mcp`, so affected
+ * `claude mcp add webpresso` entry in Claude Code's home JSON config (user
+ * scope or a project scope) plus the agent-kit marketplace plugin's bundled
+ * server from the Claude plugin cache. Both spawn `wp mcp`, so affected
  * sessions run two server processes and carry a duplicated wp_* tool list.
  * Degrades to ok on missing/unreadable config — loud only on real duplication.
  */
@@ -1810,17 +1816,17 @@ export function checkClaudeMcpDuplicateRegistration(options = {}) {
     }
     const claudeJsonPath = join(home, ".claude.json");
     if (!exists(claudeJsonPath)) {
-        return { name, ok: true, detail: "skipped (no ~/.claude.json)" };
+        return { name, ok: true, detail: "skipped (no Claude Code home JSON config)" };
     }
     let parsed;
     try {
         parsed = JSON.parse(readFile(claudeJsonPath));
     }
     catch {
-        return { name, ok: true, detail: "skipped (~/.claude.json unreadable)" };
+        return { name, ok: true, detail: "skipped (Claude Code home JSON config unreadable)" };
     }
     if (parsed === null || typeof parsed !== "object") {
-        return { name, ok: true, detail: "skipped (~/.claude.json is not an object)" };
+        return { name, ok: true, detail: "skipped (Claude Code home JSON config is not an object)" };
     }
     const config = parsed;
     const manualSources = [];
@@ -1832,6 +1838,29 @@ export function checkClaudeMcpDuplicateRegistration(options = {}) {
             manualSources.push(`project scope ${projectDir}`);
         }
     }
+    // Also scan project-local `.mcp.json` (and ancestors). Claude Code honors
+    // this file as a third registration surface; the home JSON projects map
+    // does not always mirror it, so a plugin + project-file pair still doubles
+    // the tool list without the home-JSON check ever firing.
+    const projectRoot = options.projectRoot ?? process.cwd();
+    for (const candidate of collectProjectMcpJsonCandidates(projectRoot)) {
+        if (!exists(candidate))
+            continue;
+        try {
+            const projectParsed = JSON.parse(readFile(candidate));
+            if (projectParsed !== null &&
+                typeof projectParsed === "object" &&
+                "mcpServers" in projectParsed &&
+                projectParsed.mcpServers &&
+                "webpresso" in
+                    (projectParsed.mcpServers ?? {})) {
+                manualSources.push(`project file ${candidate}`);
+            }
+        }
+        catch {
+            // Unreadable/malformed .mcp.json is not a duplicate signal — degrade.
+        }
+    }
     if (manualSources.length === 0) {
         return { name, ok: true, detail: "plugin-scoped registration only" };
     }
@@ -1839,12 +1868,25 @@ export function checkClaudeMcpDuplicateRegistration(options = {}) {
         name,
         ok: false,
         advisory: true,
-        detail: `the agent-kit Claude plugin bundles the webpresso MCP server, but ~/.claude.json also ` +
+        detail: `the agent-kit Claude plugin bundles the webpresso MCP server, but Claude Code's home JSON config also ` +
             `registers "webpresso" manually (${manualSources.join(", ")}). Affected sessions run two ` +
             `wp mcp processes with a duplicated wp_* tool list. Remove the manual entry: ` +
             `claude mcp remove webpresso (run inside the project directory for project-scope entries).`,
     };
 }
+/** Walk projectRoot → filesystem root collecting `.mcp.json` paths that may register MCP servers. */
+function collectProjectMcpJsonCandidates(projectRoot) {
+    const candidates = [];
+    let current = projectRoot;
+    for (;;) {
+        candidates.push(join(current, ".mcp.json"));
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return candidates;
+}
 const QUOTED_TOML_STRING = /"((?:[^"\\]|\\.)*)"/gu;
 const DANGLING_SYMLINK_SCAN_DEPTH = 3;
 function collectDanglingWorktreePaths(raw, worktreesRoot, exists, alreadyReported) {
@@ -2049,7 +2091,7 @@ export async function runHooksDoctor(opts = {}) {
         checks.push(checkCodexConfigKeys());
     }
     checks.push(checkProjectMcpPins(opts.cwd));
-    checks.push(checkClaudeMcpDuplicateRegistration());
+    checks.push(checkClaudeMcpDuplicateRegistration({ projectRoot: opts.cwd ?? process.cwd() }));
     checks.push({ advisory: true, ...checkDanglingHostPaths() });
     checks.push({ advisory: true, ...checkRootLauncherContract() });
     checks.push({ advisory: true, ...checkNativePluginRuntime() });
@@ -2142,6 +2184,15 @@ export async function runHooksDoctor(opts = {}) {
                         detail: "claude required but not on PATH",
                     });
             }
+            if (host === "grok") {
+                const available = await runCommand("grok", ["--version"]);
+                if (!available.ok)
+                    checks.push({
+                        name: "Grok host integration",
+                        ok: false,
+                        detail: "grok required but not on PATH",
+                    });
+            }
         }
     }
     checks.push(checkHooksManifest(opts.cwd));

package/dist/esm/hooks/permission-request/index.js

@@ -9,7 +9,8 @@
  * Stdin: uses shared `readStdinJson` so conformance-batch can inject payloads via
  * `WP_CONFORMANCE_STDIN` (same contract as other managed hooks).
  */
-import { readStdinJson, writeHookOutput } from "#hooks/shared/hook-bootstrap";
+import { formatGuardReason } from "#hooks/shared/guard-outcome";
+import { readStdinJson, writeGuardStderr, writeHookOutput } from "#hooks/shared/hook-bootstrap";
 import { buildPermissionRequestEnvelope } from "./envelope.js";
 import { evaluatePermissionRequest } from "./policy.js";
 function isRecord(value) {
@@ -53,9 +54,14 @@ export async function main() {
         return;
     }
     // Claude + Codex share the golden PermissionRequest wire shape
-    // (hookSpecificOutput.hookEventName + decision.behavior).
-    writeHookOutput(JSON.stringify(buildPermissionRequestEnvelope(result.decision, result.reason)));
+    // (hookSpecificOutput.hookEventName + decision.behavior). The wire message
+    // carries the GUARD_* code so allow/deny decisions are keyable across hosts.
+    const codedMessage = formatGuardReason(result.code, result.reason);
+    writeHookOutput(JSON.stringify(buildPermissionRequestEnvelope(result.decision, codedMessage)));
     if (result.decision === "deny") {
+        // A deny exits 2; deliver the coded message to the real stderr too so it is
+        // observable even when a host prefers the exit-code channel.
+        writeGuardStderr(`${codedMessage}\n`);
         // Must use process.exit so runHookCommand's synthetic-exit trap records exit 2.
         process.exit(2);
     }

package/dist/esm/hooks/permission-request/policy.d.ts

@@ -5,6 +5,7 @@
  * authoritative when policy is uncertain. Explicit deny only for high-confidence
  * unsafe escalations; explicit allow only for clearly safe read-only escalations.
  */
+import type { GuardReasonCode } from "#hooks/shared/guard-outcome";
 export type PermissionRequestDecision = "allow" | "deny";
 export type PermissionRequestPolicyInput = {
     readonly toolName?: string;
@@ -15,13 +16,21 @@ export type PermissionRequestPolicyInput = {
 export type PermissionRequestPolicyResult = {
     readonly decision: "allow";
     readonly reason: string;
+    readonly code: GuardReasonCode;
 } | {
     readonly decision: "deny";
     readonly reason: string;
+    readonly code: GuardReasonCode;
 } | {
     readonly decision: undefined;
     readonly reason: string;
+    readonly code: GuardReasonCode;
 };
+/**
+ * Every GUARD_* code the permission-request policy can emit. Consumed by the
+ * guard-outcome registry-completeness test.
+ */
+export declare const PERMISSION_GUARD_CODES: readonly ["GUARD_PERMISSION_ALLOWED", "GUARD_PERMISSION_DENIED", "GUARD_HOST_DEFAULT"];
 /**
  * Decide allow / deny / pass-through for a PermissionRequest payload.
  */

package/dist/esm/hooks/permission-request/policy.js

@@ -5,6 +5,15 @@
  * authoritative when policy is uncertain. Explicit deny only for high-confidence
  * unsafe escalations; explicit allow only for clearly safe read-only escalations.
  */
+/**
+ * Every GUARD_* code the permission-request policy can emit. Consumed by the
+ * guard-outcome registry-completeness test.
+ */
+export const PERMISSION_GUARD_CODES = [
+    "GUARD_PERMISSION_ALLOWED",
+    "GUARD_PERMISSION_DENIED",
+    "GUARD_HOST_DEFAULT",
+];
 const SECRET_PATH_RE = /(?:^|\/)(?:\.env(?:\..+)?|.*\.(?:pem|key|p12|pfx)|id_rsa|id_ed25519|credentials(?:\.json)?|secrets?(?:\.ya?ml)?|\.npmrc|\.netrc)(?:$|\/)/iu;
 const DANGEROUS_BASH_RE = /\b(?:rm\s+-[a-zA-Z]*f|sudo\s+|curl\s+[^\n]*\|\s*(?:ba)?sh|wget\s+[^\n]*\|\s*(?:ba)?sh|mkfs\.|dd\s+if=)/iu;
 function asCommand(input) {
@@ -39,12 +48,14 @@ export function evaluatePermissionRequest(input) {
         return {
             decision: "deny",
             reason: "PermissionRequest denied: secret or credential path escalation",
+            code: "GUARD_PERMISSION_DENIED",
         };
     }
     if (DANGEROUS_BASH_RE.test(command) || DANGEROUS_BASH_RE.test(blob)) {
         return {
             decision: "deny",
             reason: "PermissionRequest denied: dangerous shell escalation",
+            code: "GUARD_PERMISSION_DENIED",
         };
     }
     // Explicit safe read-only escalations (narrow allow).
@@ -54,10 +65,12 @@ export function evaluatePermissionRequest(input) {
         return {
             decision: "allow",
             reason: "PermissionRequest allowed: read-only tool escalation",
+            code: "GUARD_PERMISSION_ALLOWED",
         };
     }
     return {
         decision: undefined,
         reason: "PermissionRequest pass-through: no high-confidence policy match",
+        code: "GUARD_HOST_DEFAULT",
     };
 }

package/dist/esm/hooks/pretool-guard/dev-routing.d.ts

@@ -1,14 +1,23 @@
+import type { GuardReasonCode } from "#hooks/shared/guard-outcome";
 export type GuidanceType = "test" | "lint" | "typecheck" | "qa" | "format" | "e2e" | "worktree";
 export type RouteAction = {
     action: "deny";
     tool: string;
     guidance: string;
+    code: GuardReasonCode;
 } | {
     action: "sandbox";
     guidance: string;
+    code: GuardReasonCode;
 } | {
     action: "passthrough";
 };
+/**
+ * Every GUARD_* code a dev-routing deny/sandbox can emit. The guard-outcome
+ * registry-completeness test asserts this stays a subset of GUARD_REASON_CODES
+ * and that each listed code is reachable from a construction site below.
+ */
+export declare const DEV_ROUTING_GUARD_CODES: readonly ["GUARD_RAW_GIT_MUTATION", "GUARD_MANUAL_PR_WAIT", "GUARD_PR_DISCLOSURE", "GUARD_WRAPPED_WP", "GUARD_SOURCE_ENTRYPOINT", "GUARD_DEV_TOOL_REDIRECT", "GUARD_DATA_HEAVY_SANDBOX", "GUARD_SESSION_MEMORY_REDIRECT"];
 export interface RouteDecision {
     action: RouteAction;
 }

package/dist/esm/hooks/pretool-guard/dev-routing.js

@@ -1,5 +1,20 @@
 import { detectWrappedWpCommand, stripLeadingSecretWrappers, wrappedWpGuidanceForArgs, } from "#cli/wrapped-wp";
 import { isSessionSandboxToolName } from "#hooks/shared/types";
+/**
+ * Every GUARD_* code a dev-routing deny/sandbox can emit. The guard-outcome
+ * registry-completeness test asserts this stays a subset of GUARD_REASON_CODES
+ * and that each listed code is reachable from a construction site below.
+ */
+export const DEV_ROUTING_GUARD_CODES = [
+    "GUARD_RAW_GIT_MUTATION",
+    "GUARD_MANUAL_PR_WAIT",
+    "GUARD_PR_DISCLOSURE",
+    "GUARD_WRAPPED_WP",
+    "GUARD_SOURCE_ENTRYPOINT",
+    "GUARD_DEV_TOOL_REDIRECT",
+    "GUARD_DATA_HEAVY_SANDBOX",
+    "GUARD_SESSION_MEMORY_REDIRECT",
+];
 const RAW_MUTATING_GIT_WORKTREE_RE = /^git\s+worktree\s+(?:add|remove|move|prune)(?:\s|$)/u;
 const MANUAL_PR_WAIT_RE = /^sleep\s+\S+[\s\S]*(?:gh\s+pr\s+(?:view|checks|status)|wp(?:_pr_status|\s+pr\s+status))/u;
 function routeRawMutatingGitWorktree(command) {
@@ -9,6 +24,7 @@ function routeRawMutatingGitWorktree(command) {
         action: "deny",
         tool: "wp_worktree",
         guidance: "Use the `wp_worktree` MCP tool (or `wp worktree` CLI when MCP is unavailable) instead — managed repositories may mutate linked worktrees only through agent-kit so owner bindings and the global registry stay consistent.",
+        code: "GUARD_RAW_GIT_MUTATION",
     };
 }
 function routeManualPrWait(command) {
@@ -18,6 +34,7 @@ function routeManualPrWait(command) {
         action: "deny",
         tool: "wp_pr_wait",
         guidance: "Use wp_pr_wait MCP tool instead — it blocks on PR checks or merge state with bounded final output and avoids manual sleep plus status polling loops",
+        code: "GUARD_MANUAL_PR_WAIT",
     };
 }
 const PR_DESCRIPTION_WRITE_GUIDANCE = "Use wp_pr_upsert MCP tool instead — it validates the repository PR disclosure contract before creating or updating a PR title/body.";
@@ -27,6 +44,7 @@ function prDescriptionWriteDeny() {
         action: "deny",
         tool: "wp_pr_upsert",
         guidance: PR_DESCRIPTION_WRITE_GUIDANCE,
+        code: "GUARD_PR_DISCLOSURE",
     };
 }
 function isGhPrDescriptionFlag(token) {
@@ -214,7 +232,7 @@ const ROUTING_RULES = [
         tool: "wp_gain",
     },
     {
-        prefixes: ["vp run public:readiness", "vp run changeset:status"],
+        prefixes: ["wp run changeset:status"],
         guidanceType: "qa",
         guidance: "Use wp_release_readiness MCP tool instead — release gates are aggregated without publishing, tagging, versioning, or merging",
         tool: "wp_release_readiness",
@@ -851,7 +869,13 @@ function extractStringField(record, keys) {
     return null;
 }
 function sessionSandboxDecision(tool, guidance) {
-    return { action: { action: "sandbox", guidance: `Use ${tool} instead — ${guidance}` } };
+    return {
+        action: {
+            action: "sandbox",
+            guidance: `Use ${tool} instead — ${guidance}`,
+            code: "GUARD_SESSION_MEMORY_REDIRECT",
+        },
+    };
 }
 const MAX_SAFE_GREP_HEAD_LIMIT = 100;
 function numericField(record, keys) {
@@ -952,6 +976,7 @@ export function routeCommand(command, _sessionId) {
                 action: "deny",
                 tool,
                 guidance,
+                code: "GUARD_WRAPPED_WP",
             },
         };
     }
@@ -973,6 +998,7 @@ export function routeCommand(command, _sessionId) {
                 action: "deny",
                 tool: sourceEntrypointRule.tool,
                 guidance: sourceEntrypointRule.guidance,
+                code: "GUARD_SOURCE_ENTRYPOINT",
             },
         };
     }
@@ -981,20 +1007,30 @@ export function routeCommand(command, _sessionId) {
         for (const prefix of rule.prefixes) {
             if (matchesPrefix(trimmed, prefix) || matchesDirectToolCommand(trimmed, rule)) {
                 return {
-                    action: { action: "deny", tool: rule.tool, guidance: rule.guidance },
+                    action: {
+                        action: "deny",
+                        tool: rule.tool,
+                        guidance: rule.guidance,
+                        code: "GUARD_DEV_TOOL_REDIRECT",
+                    },
                 };
             }
         }
         if (matchesPackageManagerDirectToolCommand(trimmed, rule)) {
             return {
-                action: { action: "deny", tool: rule.tool, guidance: rule.guidance },
+                action: {
+                    action: "deny",
+                    tool: rule.tool,
+                    guidance: rule.guidance,
+                    code: "GUARD_DEV_TOOL_REDIRECT",
+                },
             };
         }
     }
     // Sandbox rules (data-heavy commands)
     for (const { prefix, guidance } of SANDBOX_PREFIXES) {
         if (matchesPrefix(trimmed, prefix)) {
-            return { action: { action: "sandbox", guidance } };
+            return { action: { action: "sandbox", guidance, code: "GUARD_DATA_HEAVY_SANDBOX" } };
         }
     }
     // Unknown — null (let callers decide)