@webpresso/agent-kit 3.1.30 → 3.3.0

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;

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

@@ -107,7 +107,17 @@ function findCanonicalBlueprintDocument(normalized, roots) {
     }
     return null;
 }
-function getCanonicalBlueprintDocument(filePath, blueprintsRoot) {
+/**
+ * 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 function getCanonicalBlueprintDocument(filePath, blueprintsRoot) {
     const normalized = normalizePlanningPath(filePath);
     const roots = blueprintsRoot ? [blueprintsRoot] : CANONICAL_BLUEPRINTS_ROOTS;
     return findCanonicalBlueprintDocument(normalized, roots);
@@ -115,12 +125,14 @@ function getCanonicalBlueprintDocument(filePath, blueprintsRoot) {
 function parseReviewLedgerRelativePath(tail) {
     const parts = tail.split("/").filter((segment) => segment.length > 0);
     if (parts.length < 3)
-        return false;
+        return null;
     const [state, slug, ...rest] = parts;
     if (!isBlueprintStatus(state) || !slug)
-        return false;
+        return null;
     const doc = rest.join("/");
-    return doc === "reviews.md" || doc === "review-events.jsonl";
+    if (doc !== "reviews.md" && doc !== "review-events.jsonl")
+        return null;
+    return { state, slug, doc };
 }
 /**
  * Prefix-agnostic detection of a blueprint's review-ledger AUTHORITY files:
@@ -140,17 +152,22 @@ function findCanonicalBlueprintReviewLedgerPath(normalized, roots) {
             if (!matchesHere)
                 continue;
             const tail = segments.slice(start + rootSegments.length).join("/");
-            if (parseReviewLedgerRelativePath(tail))
-                return true;
+            const parsed = parseReviewLedgerRelativePath(tail);
+            if (parsed)
+                return parsed;
         }
     }
-    return false;
+    return null;
 }
-export function isCanonicalBlueprintReviewLedgerPath(filePath, blueprintsRoot) {
+/** Same detection as {@link isCanonicalBlueprintReviewLedgerPath}, returning the parsed identity. */
+export function getCanonicalBlueprintReviewLedgerPath(filePath, blueprintsRoot) {
     const normalized = normalizePlanningPath(filePath);
     const roots = blueprintsRoot ? [blueprintsRoot] : CANONICAL_BLUEPRINTS_ROOTS;
     return findCanonicalBlueprintReviewLedgerPath(normalized, roots);
 }
+export function isCanonicalBlueprintReviewLedgerPath(filePath, blueprintsRoot) {
+    return getCanonicalBlueprintReviewLedgerPath(filePath, blueprintsRoot) !== null;
+}
 export function getBlueprintPathViolation(filePath, blueprintsRoot, cwd = process.cwd()) {
     const normalized = normalizePlanningPath(filePath);
     if (!isBlueprintPath(normalized, blueprintsRoot))

package/dist/esm/hooks/pretool-guard/validators/worktree-discipline.js

@@ -95,7 +95,12 @@ export function validateWorktreeDiscipline(input) {
     return { validator: VALIDATOR_NAME, passed: true };
 }
 function normalizedToolName(input) {
-    return (input.tool_name ?? "").toLowerCase().replaceAll(/[^a-z]/gu, "");
+    // tool_name is typed string but malformed host envelopes can deliver non-strings;
+    // never call string methods without a typeof guard (same class as isBashInput).
+    const raw = input.tool_name;
+    if (typeof raw !== "string")
+        return "";
+    return raw.toLowerCase().replaceAll(/[^a-z]/gu, "");
 }
 function applyPatchTargets(input) {
     if (!normalizedToolName(input).endsWith("applypatch"))