@webpresso/agent-kit 3.1.30 → 3.2.0

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)

package/dist/esm/hooks/pretool-guard/logger.d.ts

@@ -1,3 +1,4 @@
+import { type GuardOutcome } from "#hooks/shared/guard-outcome";
 export type LogStatus = "PASS" | "BLOCK" | "WARN" | "ERROR";
 export type ToolType = string;
 export interface LogEntry {
@@ -6,6 +7,10 @@ export interface LogEntry {
     tool: ToolType;
     failures?: string[];
     error?: string;
+    /** GUARD_* reason code for the decision (additive; present on BLOCK/WARN). */
+    code?: string;
+    /** Two-axis guard outcome for the decision (additive). */
+    outcome?: GuardOutcome;
 }
 export interface LogConfig {
     logDir: string;
@@ -20,6 +25,8 @@ export interface ParsedLogLine {
     target: string;
     failures?: string[];
     error?: string;
+    code?: string;
+    outcome?: GuardOutcome;
 }
 export declare function createLogConfig(): LogConfig;
 export declare function parseLogLine(line: string): ParsedLogLine | null;

package/dist/esm/hooks/pretool-guard/logger.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
+import { GUARD_EFFECT, GUARD_INTENT } from "#hooks/shared/guard-outcome";
 import { redactText } from "#mcp/tools/_shared/redact.js";
 import { getSurfacePath } from "#paths/state-root.js";
 const DEFAULT_MAX_LINES = 250;
@@ -42,6 +43,8 @@ export function parseLogLine(line) {
             ? parsed.failures.filter((value) => typeof value === "string")
             : undefined,
         error: typeof parsed.error === "string" ? parsed.error : undefined,
+        code: typeof parsed.code === "string" ? parsed.code : undefined,
+        outcome: isGuardOutcome(parsed.outcome) ? parsed.outcome : undefined,
     };
 }
 export function rotateLines(lines, maxLines) {
@@ -100,3 +103,16 @@ function isLogStatus(value) {
 function isToolType(value) {
     return typeof value === "string" && value.length > 0;
 }
+const GUARD_EFFECT_VALUES = new Set(Object.values(GUARD_EFFECT));
+const GUARD_INTENT_VALUES = new Set(Object.values(GUARD_INTENT));
+function isGuardOutcome(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    const effect = record["effect"];
+    const intent = record["intent"];
+    return (typeof effect === "string" &&
+        GUARD_EFFECT_VALUES.has(effect) &&
+        typeof intent === "string" &&
+        GUARD_INTENT_VALUES.has(intent));
+}

package/dist/esm/hooks/pretool-guard/runner.d.ts

@@ -10,6 +10,12 @@ export interface ProcessValidationOptions {
     readonly optimizationRules?: readonly OptimizationRule[];
     readonly recordOptimization?: (record: OptimizationTelemetryRecord) => void;
 }
+/**
+ * Registered GUARD_* codes the runner emits directly (beyond the dev-routing
+ * inventory and the per-validator invariant codes in GUARD_VALIDATOR_CODES).
+ * Consumed by the guard-outcome registry-completeness test.
+ */
+export declare const RUNNER_GUARD_CODES: readonly ["GUARD_PROMPT_INTENT"];
 export declare function runAllValidators(input: ToolInput): AggregateResult;
 export declare function formatOutput(aggregate: AggregateResult, input: ToolInput): void;
 export declare function getToolType(input: ToolInput): string;

package/dist/esm/hooks/pretool-guard/runner.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { getActivePromptRouting, isGuardEnabled } from "#hooks/guard-switch/state";
+import { formatGuardReason, GUARD_EFFECT, GUARD_INTENT, GUARD_VALIDATOR_CODES, outcomeForCode, validatorUnexpectedCode, } from "#hooks/shared/guard-outcome";
 import { routePromptIntent } from "#hooks/prompt-routing";
-import { readStdinJson, suppressStderr, writeHookOutput } from "#hooks/shared/hook-bootstrap";
+import { readStdinJson, suppressDecorativeStderr, writeGuardStderr, writeHookOutput, } from "#hooks/shared/hook-bootstrap";
 import { isSyntheticProcessExit } from "#hooks/shared/synthetic-process-exit.js";
 import { buildDenyEnvelope, buildUpdatedInputEnvelope, cloneToolInputWithCommand, getCommand, getFilePath, isBashInput, parseToolInput, } from "#hooks/shared/types";
 import { logRun } from "./logger.js";
@@ -15,6 +16,22 @@ const YELLOW = "\x1b[33m";
 const DIM = "\x1b[2m";
 const BOLD = "\x1b[1m";
 const NC = "\x1b[0m";
+/** Code the pretool-guard emits when a routed prompt-intent forces a redirect. */
+const PROMPT_INTENT_CODE = "GUARD_PROMPT_INTENT";
+/**
+ * Registered GUARD_* codes the runner emits directly (beyond the dev-routing
+ * inventory and the per-validator invariant codes in GUARD_VALIDATOR_CODES).
+ * Consumed by the guard-outcome registry-completeness test.
+ */
+export const RUNNER_GUARD_CODES = [
+    PROMPT_INTENT_CODE,
+];
+/** Resolve the GUARD_* code for a failing validator, with a per-validator fallback. */
+function codeForValidator(validatorName) {
+    if (!validatorName)
+        return "GUARD_VALIDATION_UNEXPECTED";
+    return GUARD_VALIDATOR_CODES[validatorName] ?? validatorUnexpectedCode(validatorName);
+}
 export function runAllValidators(input) {
     const results = VALIDATORS.map((v) => v(input));
     const failed = results.filter((r) => !r.passed);
@@ -62,20 +79,35 @@ export function getTarget(input) {
 export function logValidationResult(result, target, tool) {
     if (!result.passed) {
         const failed = result.results.filter((r) => !r.passed);
+        const code = codeForValidator(failed[0]?.validator);
         logRun({
             status: "BLOCK",
             target: target.slice(0, 100),
             tool,
             failures: failed.map((f) => f.validator),
+            code,
+            outcome: outcomeForCode(code),
         });
         return;
     }
     const warnings = result.results.filter((r) => r.passed && r.message);
+    if (warnings.length > 0) {
+        // A warn does not reach the wire; it is advisory guidance in logs only.
+        const code = codeForValidator(warnings[0]?.validator);
+        logRun({
+            status: "WARN",
+            target: target.slice(0, 100),
+            tool,
+            failures: warnings.map((w) => w.validator),
+            code,
+            outcome: { effect: GUARD_EFFECT.allow, intent: GUARD_INTENT.advise },
+        });
+        return;
+    }
     logRun({
-        status: warnings.length > 0 ? "WARN" : "PASS",
+        status: "PASS",
         target: target.slice(0, 100),
         tool,
-        failures: warnings.length > 0 ? warnings.map((w) => w.validator) : undefined,
     });
 }
 export function handleParseError(error, inputJson) {
@@ -87,18 +119,20 @@ export function handleParseError(error, inputJson) {
     });
     console.error(`${RED}❌ Pretool Guard: Error parsing input${NC}`);
     console.error(`${RED}   ${error instanceof Error ? error.message : "Unknown error"}${NC}`);
+    // Fail-closed as a CODED deny envelope so malformed/unhandled input still
+    // carries the stable GUARD_PRETOOL_FAILURE code on the wire, not a bare exit 2.
+    const detail = error instanceof Error ? error.message : "unknown error";
+    writeDenyDecision(formatGuardReason("GUARD_PRETOOL_FAILURE", `pretool-guard could not evaluate tool input: ${detail}`));
     process.exit(2);
 }
 function writeDenyDecision(permissionDecisionReason) {
+    // Deliver the coded reason on BOTH host channels: the stdout deny envelope
+    // (Codex reads hookSpecificOutput; Grok reads the dual top-level decision) AND
+    // the REAL stderr via writeGuardStderr (Claude reads stderr as the blocking
+    // feedback on an exit-2 PreToolUse deny — it ignores stdout there). The
+    // decorative diagnostics that go through console.error stay suppressed.
     writeHookOutput(JSON.stringify(buildDenyEnvelope({ reason: permissionDecisionReason })));
-    // Claude/Codex treat exit 2 as deny and read the reason from stderr when present.
-    // suppressStderr may null out fd 2; dual JSON still carries the reason for Grok.
-    try {
-        process.stderr.write(`${permissionDecisionReason}\n`);
-    }
-    catch {
-        // ignore
-    }
+    writeGuardStderr(`${permissionDecisionReason}\n`);
 }
 function writeUpdatedInput(input, command) {
     writeHookOutput(JSON.stringify(buildUpdatedInputEnvelope(input, command)));
@@ -125,12 +159,16 @@ function evaluateRoutingPolicy(input) {
         return {
             snapshot: { promptIntentReason, toolInputAction, commandActions: [] },
             denyReason: promptIntentReason,
+            code: PROMPT_INTENT_CODE,
+            outcome: outcomeForCode(PROMPT_INTENT_CODE),
         };
     }
     if (toolInputAction?.action === "deny" || toolInputAction?.action === "sandbox") {
         return {
             snapshot: { promptIntentReason, toolInputAction, commandActions },
             denyReason: toolInputAction.guidance,
+            code: toolInputAction.code,
+            outcome: outcomeForCode(toolInputAction.code),
         };
     }
     for (const commandAction of commandActions) {
@@ -138,18 +176,24 @@ function evaluateRoutingPolicy(input) {
             return {
                 snapshot: { promptIntentReason, toolInputAction, commandActions },
                 denyReason: commandAction.action.guidance,
+                code: commandAction.action.code,
+                outcome: outcomeForCode(commandAction.action.code),
             };
         }
         if (commandAction.action?.action === "sandbox" && !commandAction.alreadySandboxed) {
             return {
                 snapshot: { promptIntentReason, toolInputAction, commandActions },
                 denyReason: commandAction.action.guidance,
+                code: commandAction.action.code,
+                outcome: outcomeForCode(commandAction.action.code),
             };
         }
     }
     return {
         snapshot: { promptIntentReason, toolInputAction, commandActions },
         denyReason: null,
+        code: null,
+        outcome: null,
     };
 }
 function policySnapshotsMatch(originalRouting, replacementRouting, originalValidation, replacementValidation) {
@@ -182,8 +226,11 @@ export function processValidation(inputJson, options = {}) {
     const input = parseToolInput(inputJson);
     const command = isBashInput(input) ? getCommand(input) : null;
     const originalRouting = evaluateRoutingPolicy(input);
-    if (originalRouting.denyReason !== null) {
-        writeDenyDecision(originalRouting.denyReason);
+    if (originalRouting.denyReason !== null && originalRouting.code !== null) {
+        // formatGuardReason owns the 80-char budget on BOTH deny paths (this routing
+        // path was previously untruncated) and rides the GUARD_* code inside the
+        // host-displayed reason so consumers key on the code, not on wording.
+        writeDenyDecision(formatGuardReason(originalRouting.code, originalRouting.denyReason));
         // Exit 2 so Grok (and other exit-code runners) treat this as an explicit
         // deny; dual JSON still carries Claude/Codex hookSpecificOutput.
         process.exit(2);
@@ -201,8 +248,11 @@ export function processValidation(inputJson, options = {}) {
             .map((r) => r.message)
             .find((message) => typeof message === "string" && message.length > 0);
         const validatorReason = failed.map((r) => r.validator).join(", ");
-        const reason = (messageReason ?? (validatorReason || "pretool-guard validation failed")).slice(0, 80);
-        writeDenyDecision(reason);
+        const rawReason = messageReason ?? (validatorReason || "pretool-guard validation failed");
+        // Code derives from the first failing validator's invariant, with a
+        // per-validator GUARD_<NAME>_UNEXPECTED fallback for unclassified failures.
+        const code = codeForValidator(failed[0]?.validator);
+        writeDenyDecision(formatGuardReason(code, rawReason));
         process.exit(2);
     }
     if (command) {
@@ -235,7 +285,9 @@ export function processValidation(inputJson, options = {}) {
     process.exit(result.exitCode);
 }
 export async function main() {
-    suppressStderr();
+    // Suppress decorative stderr but keep fd 2 open so a deny can deliver its
+    // coded reason to the real stderr (Claude's exit-2 blocking-feedback channel).
+    suppressDecorativeStderr();
     const inputJson = await readStdinJson();
     if (!inputJson.trim()) {
         writeHookOutput("{}\n");

package/dist/esm/hooks/pretool-guard/validators/blueprint.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { getFilePath, isFileEditInput, isFileWriteInput } from "#hooks/shared/types";
 import { validateBlueprint as validateBlueprintShared } from "#hooks/shared/validators/blueprint";
-import { isCanonicalBlueprintDocumentPath, isCanonicalBlueprintReviewLedgerPath, } from "./path-contract.js";
+import { getCanonicalBlueprintDocument, getCanonicalBlueprintReviewLedgerPath, } from "./path-contract.js";
 import { buildRedirectMessage } from "./mcp-redirect.js";
 function normalizeFilePath(filePath, cwd) {
     if (!path.isAbsolute(filePath))
@@ -10,6 +10,23 @@ function normalizeFilePath(filePath, cwd) {
         return filePath.replace(/^\/+/, "");
     return path.relative(cwd, filePath).replace(/\\/g, "/");
 }
+/**
+ * Build a short, deterministic `<state>/<slug>` display identity from the
+ * PARSED match, never from the raw input path. The raw path is a
+ * cwd-relative string that can legitimately climb several parent-directory
+ * segments out of the effective repo root (e.g. into
+ * `.webpresso/worktrees/repos/<hash>/.../_overview.md` when cwd is the
+ * primary checkout but the edited file lives inside a managed blueprint
+ * worktree) — confusing to read and, worse, long enough to consume
+ * the guard's entire wire-message budget (`GUARD_REASON_BUDGET`, 80 Unicode
+ * code points total, see `#hooks/shared/guard-outcome.ts`) before any
+ * actionable "use this MCP tool" guidance is shown. Dropping the root prefix
+ * and document filename (both implied by the "blueprint" category, not
+ * distinguishing information) buys back budget for that guidance.
+ */
+function canonicalDisplayId(state, slug) {
+    return `${state}/${slug}`;
+}
 export function validateBlueprint(input) {
     const filePath = getFilePath(input);
     if (filePath && (isFileWriteInput(input) || isFileEditInput(input))) {
@@ -17,28 +34,31 @@ export function validateBlueprint(input) {
         // Detect a canonical blueprint document from EITHER the cwd-normalized form
         // OR the raw path. Detection is prefix-agnostic (path-contract), so an
         // absolute worktree path is caught even when input.cwd is undefined or does
-        // not reduce the path to a recognized blueprints root.
-        if (isCanonicalBlueprintDocumentPath(normalized) ||
-            isCanonicalBlueprintDocumentPath(filePath)) {
+        // not reduce the path to a recognized blueprints root — including when cwd
+        // points at an unrelated checkout (e.g. the primary checkout) and the file
+        // lives inside a managed worktree.
+        const canonicalDoc = getCanonicalBlueprintDocument(normalized) ?? getCanonicalBlueprintDocument(filePath);
+        if (canonicalDoc) {
             return {
                 validator: "blueprint",
                 passed: false,
                 message: buildRedirectMessage({
                     category: "blueprint",
-                    command: normalized,
-                    fallbackHint: "wp_blueprint_create / wp_blueprint_put / wp_blueprint_transition / wp_blueprint_task_verify",
+                    command: canonicalDisplayId(canonicalDoc.state, canonicalDoc.slug),
+                    fallbackHint: "wp_blueprint_put",
                 }),
             };
         }
-        if (isCanonicalBlueprintReviewLedgerPath(normalized) ||
-            isCanonicalBlueprintReviewLedgerPath(filePath)) {
+        const ledgerDoc = getCanonicalBlueprintReviewLedgerPath(normalized) ??
+            getCanonicalBlueprintReviewLedgerPath(filePath);
+        if (ledgerDoc) {
             return {
                 validator: "blueprint",
                 passed: false,
                 message: buildRedirectMessage({
                     category: "blueprint",
-                    command: normalized,
-                    fallbackHint: "wp_blueprint_review_log (or wp review log --reviewer <id>)",
+                    command: canonicalDisplayId(ledgerDoc.state, ledgerDoc.slug),
+                    fallbackHint: "wp_blueprint_review_log",
                 }),
             };
         }

package/dist/esm/hooks/pretool-guard/validators/forbidden-commands.js

@@ -348,6 +348,7 @@ export function createAuditResult(command, rule, options = {}) {
 }
 const AUDIT_KIND_SET = new Set(MCP_AUDIT_KINDS);
 const WP_AUDIT_RE = /^wp\s+audit\s+([a-z0-9-]+)\b/u;
+const WP_CI_PREFLIGHT_RE = /^wp\s+ci-preflight\b/u;
 const SCRIPT_INVOCATION_RE = /^(?:pnpm run|vp run|npm run|pnpm|npm)\s+([A-Za-z0-9:_-]+)/u;
 const RAW_PM_RE = /^(?:pnpm|npm)\b/u;
 function loadGuardConfig(projectDir) {
@@ -389,6 +390,53 @@ function findWpAuditRedirect(command) {
     }
     return undefined;
 }
+/** `wp ci-preflight` (CLI) → `wp_ci_preflight` MCP tool. 1:1 mapping, not gated on config. */
+function findWpCiPreflightRedirect(command) {
+    for (const variant of getCommandVariants(command)) {
+        if (WP_CI_PREFLIGHT_RE.test(variant)) {
+            return `"${variant}" denied — use the webpresso MCP tool wp_ci_preflight(). Runs the same fail-fast, branch-scoped pre-push gate (format → guardrails → typecheck → lint → test) without shelling out. Returns structured, summary-first results.`;
+        }
+    }
+    return undefined;
+}
+const OPENCODE_RUN_RE = /^opencode\s+run\b/u;
+const CODEX_EXEC_OR_REVIEW_RE = /^codex\s+(?:exec|review)\b/u;
+/**
+ * Raw provider-CLI outside-voice review invocations (`opencode run ...`,
+ * `codex exec ...`, `codex review`) → `wp_review_run`. Generic; not gated on
+ * config, mirroring `findWpAuditRedirect`.
+ *
+ * Deliberately narrow: only the review-launching subcommands are blocked.
+ * `codex login status`, `codex --version`, `opencode models opencode-go`
+ * (listing available models — documented in the `codex` skill), and
+ * `opencode --version` are legitimate, non-review invocations and must stay
+ * unblocked.
+ *
+ * A single tool exists here (not a category with several natural
+ * `wp_<suffix>` matchers), so this deliberately does NOT go through the
+ * generic `CommandRule`/`buildRedirectMessage` category pipeline — that
+ * machinery always derives its "use the webpresso MCP tool" claim from a
+ * category → tool-suffix map, which is correct for lint/test/typecheck
+ * (real per-category MCP tools) but would misname the single review tool.
+ * Mirrors `findWpAuditRedirect`'s unconditional standalone-message shape:
+ * always names `wp_review_run` directly rather than gating on
+ * `resolveMcpReady` (the fallback tier that message implies — the `wp
+ * review run` CLI documented in the `codex` skill — is unconditionally
+ * still available as a manual fallback when MCP genuinely is not ready).
+ */
+function findReviewCliRedirect(command) {
+    for (const variant of getCommandVariants(command)) {
+        if (!OPENCODE_RUN_RE.test(variant) && !CODEX_EXEC_OR_REVIEW_RE.test(variant))
+            continue;
+        return [
+            `"${variant}" denied — use the webpresso MCP tool: wp_review_run(...).`,
+            "It runs the probe + review stages of an outside-voice provider review in one call and returns structured, summary-first results with artifact capture under .webpresso/reviews.",
+            "Provider fallback (e.g. Codex out of API credits) is a `provider` PARAMETER change on that SAME tool call (claude|codex|opencode|grok) — never shell into a different provider's raw CLI.",
+            "Fallback if MCP is genuinely unavailable: the `wp review run` CLI (see the `codex` skill) — never a different provider's raw CLI.",
+        ].join("\n");
+    }
+    return undefined;
+}
 /** Repo-declared `guard.scriptRoutes`: a package script mapped to an audit kind. */
 function findScriptRouteRedirect(command, routes) {
     for (const variant of getCommandVariants(command)) {
@@ -446,6 +494,12 @@ export function validateForbiddenCommands(input) {
     const wpAuditRedirect = findWpAuditRedirect(command);
     if (wpAuditRedirect)
         return guardRedirect(wpAuditRedirect);
+    const wpCiPreflightRedirect = findWpCiPreflightRedirect(command);
+    if (wpCiPreflightRedirect)
+        return guardRedirect(wpCiPreflightRedirect);
+    const reviewCliRedirect = findReviewCliRedirect(command);
+    if (reviewCliRedirect)
+        return guardRedirect(reviewCliRedirect);
     const guard = loadGuardConfig(projectDir);
     if (guard?.scriptRoutes) {
         const redirect = findScriptRouteRedirect(command, guard.scriptRoutes);

package/dist/esm/hooks/pretool-guard/validators/index.d.ts

@@ -12,4 +12,11 @@ import { validateTestQuality } from "./test-quality.js";
 import { validateUxQuality } from "./ux-quality.js";
 import { validateWorktreeDiscipline } from "./worktree-discipline.js";
 export declare const VALIDATORS: (typeof validateBlueprintFirst | typeof validateDocsGovernance | typeof validatePackageImports)[];
+/**
+ * Canonical `validator` name each entry in {@link VALIDATORS} reports on its
+ * `ValidationResult`. Kept in lockstep with the array above; the guard-outcome
+ * registry-completeness test asserts every name has a GUARD_* invariant code
+ * (and vice versa).
+ */
+export declare const VALIDATOR_NAMES: readonly ["forbidden-commands", "dangerous-commands", "blueprint", "blueprint-first", "docs-governance", "plan-frontmatter", "complexity", "package-imports", "file-conventions", "command-file", "test-quality", "ux-quality", "worktree-discipline"];
 export { validateBlueprint, validateBlueprintFirst, validateCommandFile, validateComplexity, validateDangerousCommands, validateDocsGovernance, validateFileConventions, validateForbiddenCommands, validatePackageImports, validatePlanFrontmatter, validateTestQuality, validateUxQuality, validateWorktreeDiscipline, };

package/dist/esm/hooks/pretool-guard/validators/index.js

@@ -26,4 +26,25 @@ export const VALIDATORS = [
     validateUxQuality,
     validateWorktreeDiscipline,
 ];
+/**
+ * Canonical `validator` name each entry in {@link VALIDATORS} reports on its
+ * `ValidationResult`. Kept in lockstep with the array above; the guard-outcome
+ * registry-completeness test asserts every name has a GUARD_* invariant code
+ * (and vice versa).
+ */
+export const VALIDATOR_NAMES = [
+    "forbidden-commands",
+    "dangerous-commands",
+    "blueprint",
+    "blueprint-first",
+    "docs-governance",
+    "plan-frontmatter",
+    "complexity",
+    "package-imports",
+    "file-conventions",
+    "command-file",
+    "test-quality",
+    "ux-quality",
+    "worktree-discipline",
+];
 export { validateBlueprint, validateBlueprintFirst, validateCommandFile, validateComplexity, validateDangerousCommands, validateDocsGovernance, validateFileConventions, validateForbiddenCommands, validatePackageImports, validatePlanFrontmatter, validateTestQuality, validateUxQuality, validateWorktreeDiscipline, };

package/dist/esm/hooks/pretool-guard/validators/path-contract.d.ts

@@ -1,3 +1,4 @@
+import type { BlueprintDocumentPath, BlueprintStatus } from "#utils/document-paths.js";
 export declare const BLUEPRINTS_ROOT = "webpresso/blueprints";
 export declare const TECH_DEBT_ROOT = "webpresso/tech-debt";
 /**
@@ -12,5 +13,23 @@ export declare function getNonCanonicalPlanningPathViolation(filePath: string, b
  */
 export declare function isCanonicalBlueprintOverviewPath(filePath: string, blueprintsRoot?: string): boolean;
 export declare function isCanonicalBlueprintDocumentPath(filePath: string, blueprintsRoot?: string): boolean;
+/**
+ * Same detection as {@link isCanonicalBlueprintDocumentPath}, but returns the
+ * parsed `<state>/<slug>/<doc>` identity instead of a boolean. Callers that
+ * need to DISPLAY the match (e.g. a guard denial message) should build their
+ * text from this clean, root-relative identity rather than from the raw
+ * input path — a raw path can be an arbitrarily long, cwd-relative string
+ * (e.g. several parent-directory segments climbing out of an unrelated
+ * worktree) that is both confusing and liable to consume an entire
+ * wire-message budget before any actionable guidance is shown.
+ */
+export declare function getCanonicalBlueprintDocument(filePath: string, blueprintsRoot?: string): BlueprintDocumentPath | null;
+export interface ReviewLedgerDocumentPath {
+    state: BlueprintStatus;
+    slug: string;
+    doc: "reviews.md" | "review-events.jsonl";
+}
+/** Same detection as {@link isCanonicalBlueprintReviewLedgerPath}, returning the parsed identity. */
+export declare function getCanonicalBlueprintReviewLedgerPath(filePath: string, blueprintsRoot?: string): ReviewLedgerDocumentPath | null;
 export declare function isCanonicalBlueprintReviewLedgerPath(filePath: string, blueprintsRoot?: string): boolean;
 export declare function getBlueprintPathViolation(filePath: string, blueprintsRoot?: string, cwd?: string): string | null;