@webpresso/agent-kit 3.1.30 → 3.2.0

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/shared/guard-outcome.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Typed guard-outcome vocabulary for the pretool-guard and permission-request
+ * hook surfaces.
+ *
+ * Two orthogonal axes describe every guard decision:
+ *
+ * - `GUARD_EFFECT`  — what actually reaches the host on the wire.
+ * - `GUARD_INTENT`  — why the guard produced that effect.
+ *
+ * They are deliberately separate because the earlier flat Proceed/Deny/Guide
+ * draft was not mutually exclusive ("Guide" still emits a deny; a host
+ * pass-through is not "Proceed"). The two-axis model is exhaustive and honest
+ * about what the host receives versus what the policy meant.
+ *
+ * Every guard denial carries a stable `GUARD_<CODE>` that survives the
+ * host-displayed wire reason (see {@link formatGuardReason}). Consumers and
+ * audits key on the code, not on fragile English wording, and the code is
+ * identical across every Tier-1 host.
+ *
+ * Precedent for the as-const vocabulary shape: `HOOK_STATUS`
+ * (src/hooks/shared/vocabulary.ts).
+ */
+export declare const GUARD_EFFECT: {
+    /** A deny envelope reaches the host (exit 2 / permissionDecision:"deny"). */
+    readonly block: "block";
+    /** The host is told to proceed (permission allow), or nothing is denied. */
+    readonly allow: "allow";
+    /** No wire change; the host's own UI/policy stays authoritative. */
+    readonly defer: "defer";
+};
+export type GuardEffect = (typeof GUARD_EFFECT)[keyof typeof GUARD_EFFECT];
+export declare const GUARD_INTENT: {
+    /** Block-and-hold: the caller must comply; no automatic reroute. */
+    readonly enforce: "enforce";
+    /** Actively reroute the caller onto a sanctioned sandbox/MCP lane. */
+    readonly redirect: "redirect";
+    /** Non-blocking guidance surfaced in logs only. */
+    readonly advise: "advise";
+    /** Defer to the host default (pass-through); guard expresses no opinion. */
+    readonly hostDefault: "hostDefault";
+};
+export type GuardIntent = (typeof GUARD_INTENT)[keyof typeof GUARD_INTENT];
+export type GuardOutcome = {
+    readonly effect: GuardEffect;
+    readonly intent: GuardIntent;
+};
+/**
+ * Closed set of guard reason codes, one per stable policy invariant (a single
+ * validator enforcing multiple invariants may map to multiple codes). Each code
+ * matches `/^GUARD_[A-Z0-9_]+$/u` and carries its {@link GuardOutcome}.
+ *
+ * Per-validator `GUARD_<NAME>_UNEXPECTED` fallback codes are NOT listed here;
+ * they are a deterministically-derived open family (see
+ * {@link validatorUnexpectedCode}) so that adding a validator never leaves a
+ * failure unclassified.
+ */
+export declare const GUARD_REASON_CODES: {
+    readonly GUARD_RAW_GIT_MUTATION: GuardOutcome;
+    readonly GUARD_MANUAL_PR_WAIT: GuardOutcome;
+    readonly GUARD_PR_DISCLOSURE: GuardOutcome;
+    readonly GUARD_WRAPPED_WP: GuardOutcome;
+    readonly GUARD_SOURCE_ENTRYPOINT: GuardOutcome;
+    readonly GUARD_DEV_TOOL_REDIRECT: GuardOutcome;
+    readonly GUARD_DATA_HEAVY_SANDBOX: GuardOutcome;
+    readonly GUARD_SESSION_MEMORY_REDIRECT: GuardOutcome;
+    readonly GUARD_PROMPT_INTENT: GuardOutcome;
+    readonly GUARD_PRETOOL_FAILURE: GuardOutcome;
+    readonly GUARD_FORBIDDEN_COMMAND: GuardOutcome;
+    readonly GUARD_DANGEROUS_COMMAND: GuardOutcome;
+    readonly GUARD_BLUEPRINT_INVALID: GuardOutcome;
+    readonly GUARD_BLUEPRINT_FIRST: GuardOutcome;
+    readonly GUARD_DOCS_GOVERNANCE: GuardOutcome;
+    readonly GUARD_PLAN_FRONTMATTER: GuardOutcome;
+    readonly GUARD_COMPLEXITY: GuardOutcome;
+    readonly GUARD_PACKAGE_IMPORTS: GuardOutcome;
+    readonly GUARD_FILE_CONVENTIONS: GuardOutcome;
+    readonly GUARD_COMMAND_FILE: GuardOutcome;
+    readonly GUARD_TEST_QUALITY: GuardOutcome;
+    readonly GUARD_UX_QUALITY: GuardOutcome;
+    readonly GUARD_WORKTREE_DISCIPLINE: GuardOutcome;
+    readonly GUARD_PERMISSION_ALLOWED: GuardOutcome;
+    readonly GUARD_PERMISSION_DENIED: GuardOutcome;
+    readonly GUARD_HOST_DEFAULT: GuardOutcome;
+};
+export type GuardReasonCode = keyof typeof GUARD_REASON_CODES;
+/** Deterministically-derived per-validator fallback code family. */
+export type GuardUnexpectedCode = `GUARD_${string}_UNEXPECTED`;
+/** Any accepted guard reason token: a registered code or an UNEXPECTED fallback. */
+export type GuardReasonToken = GuardReasonCode | GuardUnexpectedCode;
+/**
+ * Map a pretool-guard validator name to its canonical invariant code. Runner
+ * derivation falls back to {@link validatorUnexpectedCode} when a validator is
+ * not listed here, so a newly-added validator still produces a classified,
+ * pattern-valid code.
+ */
+export declare const GUARD_VALIDATOR_CODES: Readonly<Record<string, GuardReasonCode>>;
+/**
+ * Deterministic, length-bounded per-validator fallback code, e.g. `test-quality`
+ * -> `GUARD_TEST_QUALITY_UNEXPECTED`. Always {@link GUARD_INTENT.enforce}. The
+ * name segment is capped so even a pathologically long validator name yields a
+ * token well under the wire budget.
+ */
+export declare function validatorUnexpectedCode(validatorName: string): GuardUnexpectedCode;
+/**
+ * Narrow to a registered guard reason code. This is SOUND: it returns true
+ * only for actual keys of the closed {@link GUARD_REASON_CODES} set. A
+ * per-validator `GUARD_<NAME>_UNEXPECTED` fallback is NOT a registered code —
+ * use {@link isGuardReasonToken} for the broader accepted family.
+ */
+export declare function isGuardReasonCode(value: string): value is GuardReasonCode;
+/**
+ * Narrow to any accepted guard reason token: a registered code or a well-formed
+ * `GUARD_<NAME>_UNEXPECTED` fallback. A fallback token is only accepted when it
+ * fits the wire budget as a prefix (token + ": " <= GUARD_REASON_BUDGET), so an
+ * accepted token can never force formatGuardReason to truncate its own prefix —
+ * consistent with the length-bounded {@link validatorUnexpectedCode}.
+ */
+export declare function isGuardReasonToken(value: string): value is GuardReasonToken;
+/** Resolve the outcome for a token; UNEXPECTED fallbacks are always block+enforce. */
+export declare function outcomeForCode(code: string): GuardOutcome;
+/** Total wire budget (in Unicode code points) for a host-displayed deny reason. */
+export declare const GUARD_REASON_BUDGET = 80;
+/** Truncate to at most `max` Unicode code points (never splits a surrogate pair). */
+export declare function truncateCodePoints(value: string, max: number): string;
+/**
+ * Truncate a wire reason to the {@link GUARD_REASON_BUDGET} in Unicode code
+ * points (never splitting a surrogate pair). Truncates from the end, so a
+ * leading `GUARD_<CODE>: ` prefix always survives. Shared by buildDenyEnvelope
+ * so the defensive budget matches formatGuardReason exactly.
+ */
+export declare function truncateReasonToBudget(reason: string): string;
+/**
+ * Produce the host-displayed wire reason `"<CODE>: <message>"`.
+ *
+ * The code prefix is reserved FIRST, then the message is sanitized (whitespace
+ * collapsed) and truncated by Unicode code points so the total never exceeds
+ * {@link GUARD_REASON_BUDGET} and no emoji/surrogate pair is split. The code
+ * therefore always survives the host budget — that survival is the entire
+ * cross-host stdout integration.
+ *
+ * `code` is a typed {@link GuardReasonToken}, so an over-budget prefix is not a
+ * reachable input (all registered codes and validator fallbacks are far under
+ * 80). If one somehow occurs, the prefix is preserved and the message dropped
+ * rather than corrupting the code.
+ *
+ * A message that already begins with the same `CODE: ` prefix is not
+ * double-prefixed (idempotent for re-formatted reasons).
+ */
+export declare function formatGuardReason(code: GuardReasonToken, message: string): string;

package/dist/esm/hooks/shared/guard-outcome.js

@@ -0,0 +1,215 @@
+/**
+ * Typed guard-outcome vocabulary for the pretool-guard and permission-request
+ * hook surfaces.
+ *
+ * Two orthogonal axes describe every guard decision:
+ *
+ * - `GUARD_EFFECT`  — what actually reaches the host on the wire.
+ * - `GUARD_INTENT`  — why the guard produced that effect.
+ *
+ * They are deliberately separate because the earlier flat Proceed/Deny/Guide
+ * draft was not mutually exclusive ("Guide" still emits a deny; a host
+ * pass-through is not "Proceed"). The two-axis model is exhaustive and honest
+ * about what the host receives versus what the policy meant.
+ *
+ * Every guard denial carries a stable `GUARD_<CODE>` that survives the
+ * host-displayed wire reason (see {@link formatGuardReason}). Consumers and
+ * audits key on the code, not on fragile English wording, and the code is
+ * identical across every Tier-1 host.
+ *
+ * Precedent for the as-const vocabulary shape: `HOOK_STATUS`
+ * (src/hooks/shared/vocabulary.ts).
+ */
+export const GUARD_EFFECT = {
+    /** A deny envelope reaches the host (exit 2 / permissionDecision:"deny"). */
+    block: "block",
+    /** The host is told to proceed (permission allow), or nothing is denied. */
+    allow: "allow",
+    /** No wire change; the host's own UI/policy stays authoritative. */
+    defer: "defer",
+};
+export const GUARD_INTENT = {
+    /** Block-and-hold: the caller must comply; no automatic reroute. */
+    enforce: "enforce",
+    /** Actively reroute the caller onto a sanctioned sandbox/MCP lane. */
+    redirect: "redirect",
+    /** Non-blocking guidance surfaced in logs only. */
+    advise: "advise",
+    /** Defer to the host default (pass-through); guard expresses no opinion. */
+    hostDefault: "hostDefault",
+};
+const BLOCK_ENFORCE = { effect: GUARD_EFFECT.block, intent: GUARD_INTENT.enforce };
+const BLOCK_REDIRECT = { effect: GUARD_EFFECT.block, intent: GUARD_INTENT.redirect };
+const ALLOW_ENFORCE = { effect: GUARD_EFFECT.allow, intent: GUARD_INTENT.enforce };
+const DEFER_HOST = { effect: GUARD_EFFECT.defer, intent: GUARD_INTENT.hostDefault };
+/**
+ * Closed set of guard reason codes, one per stable policy invariant (a single
+ * validator enforcing multiple invariants may map to multiple codes). Each code
+ * matches `/^GUARD_[A-Z0-9_]+$/u` and carries its {@link GuardOutcome}.
+ *
+ * Per-validator `GUARD_<NAME>_UNEXPECTED` fallback codes are NOT listed here;
+ * they are a deterministically-derived open family (see
+ * {@link validatorUnexpectedCode}) so that adding a validator never leaves a
+ * failure unclassified.
+ */
+export const GUARD_REASON_CODES = {
+    // --- pretool-guard dev-routing (block + redirect: each names a wp_* lane) --
+    GUARD_RAW_GIT_MUTATION: BLOCK_REDIRECT,
+    GUARD_MANUAL_PR_WAIT: BLOCK_REDIRECT,
+    GUARD_PR_DISCLOSURE: BLOCK_REDIRECT,
+    GUARD_WRAPPED_WP: BLOCK_REDIRECT,
+    GUARD_SOURCE_ENTRYPOINT: BLOCK_REDIRECT,
+    GUARD_DEV_TOOL_REDIRECT: BLOCK_REDIRECT,
+    GUARD_DATA_HEAVY_SANDBOX: BLOCK_REDIRECT,
+    GUARD_SESSION_MEMORY_REDIRECT: BLOCK_REDIRECT,
+    // --- pretool-guard prompt routing (block + enforce: no tool redirect) ------
+    GUARD_PROMPT_INTENT: BLOCK_ENFORCE,
+    // --- pretool-guard fail-closed error path (block + enforce) ----------------
+    GUARD_PRETOOL_FAILURE: BLOCK_ENFORCE,
+    // --- pretool-guard validators (block + enforce) ---------------------------
+    GUARD_FORBIDDEN_COMMAND: BLOCK_ENFORCE,
+    GUARD_DANGEROUS_COMMAND: BLOCK_ENFORCE,
+    GUARD_BLUEPRINT_INVALID: BLOCK_ENFORCE,
+    GUARD_BLUEPRINT_FIRST: BLOCK_ENFORCE,
+    GUARD_DOCS_GOVERNANCE: BLOCK_ENFORCE,
+    GUARD_PLAN_FRONTMATTER: BLOCK_ENFORCE,
+    GUARD_COMPLEXITY: BLOCK_ENFORCE,
+    GUARD_PACKAGE_IMPORTS: BLOCK_ENFORCE,
+    GUARD_FILE_CONVENTIONS: BLOCK_ENFORCE,
+    GUARD_COMMAND_FILE: BLOCK_ENFORCE,
+    GUARD_TEST_QUALITY: BLOCK_ENFORCE,
+    GUARD_UX_QUALITY: BLOCK_ENFORCE,
+    GUARD_WORKTREE_DISCIPLINE: BLOCK_ENFORCE,
+    // --- permission-request (host-boundary decisions) -------------------------
+    GUARD_PERMISSION_ALLOWED: ALLOW_ENFORCE,
+    GUARD_PERMISSION_DENIED: BLOCK_ENFORCE,
+    GUARD_HOST_DEFAULT: DEFER_HOST,
+};
+/**
+ * Map a pretool-guard validator name to its canonical invariant code. Runner
+ * derivation falls back to {@link validatorUnexpectedCode} when a validator is
+ * not listed here, so a newly-added validator still produces a classified,
+ * pattern-valid code.
+ */
+export const GUARD_VALIDATOR_CODES = {
+    "forbidden-commands": "GUARD_FORBIDDEN_COMMAND",
+    "dangerous-commands": "GUARD_DANGEROUS_COMMAND",
+    blueprint: "GUARD_BLUEPRINT_INVALID",
+    "blueprint-first": "GUARD_BLUEPRINT_FIRST",
+    "docs-governance": "GUARD_DOCS_GOVERNANCE",
+    "plan-frontmatter": "GUARD_PLAN_FRONTMATTER",
+    complexity: "GUARD_COMPLEXITY",
+    "package-imports": "GUARD_PACKAGE_IMPORTS",
+    "file-conventions": "GUARD_FILE_CONVENTIONS",
+    "command-file": "GUARD_COMMAND_FILE",
+    "test-quality": "GUARD_TEST_QUALITY",
+    "ux-quality": "GUARD_UX_QUALITY",
+    "worktree-discipline": "GUARD_WORKTREE_DISCIPLINE",
+};
+const GUARD_CODE_RE = /^GUARD_[A-Z0-9_]+$/u;
+const GUARD_UNEXPECTED_RE = /^GUARD_[A-Z0-9_]+_UNEXPECTED$/u;
+/**
+ * Max code-point length of the derived validator-name segment in an UNEXPECTED
+ * fallback. Bounds the whole token to `GUARD_` (6) + 48 + `_UNEXPECTED` (11) =
+ * 65 code points, comfortably under {@link GUARD_REASON_BUDGET}, so the fallback
+ * path can never blow the 80-code-point wire budget.
+ */
+const UNEXPECTED_NAME_MAX = 48;
+/**
+ * Deterministic, length-bounded per-validator fallback code, e.g. `test-quality`
+ * -> `GUARD_TEST_QUALITY_UNEXPECTED`. Always {@link GUARD_INTENT.enforce}. The
+ * name segment is capped so even a pathologically long validator name yields a
+ * token well under the wire budget.
+ */
+export function validatorUnexpectedCode(validatorName) {
+    const screaming = validatorName
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/gu, "_")
+        .replace(/^_+|_+$/gu, "")
+        .slice(0, UNEXPECTED_NAME_MAX)
+        .replace(/_+$/gu, "");
+    return `GUARD_${screaming || "UNKNOWN"}_UNEXPECTED`;
+}
+/**
+ * Narrow to a registered guard reason code. This is SOUND: it returns true
+ * only for actual keys of the closed {@link GUARD_REASON_CODES} set. A
+ * per-validator `GUARD_<NAME>_UNEXPECTED` fallback is NOT a registered code —
+ * use {@link isGuardReasonToken} for the broader accepted family.
+ */
+export function isGuardReasonCode(value) {
+    return Object.prototype.hasOwnProperty.call(GUARD_REASON_CODES, value);
+}
+/**
+ * Narrow to any accepted guard reason token: a registered code or a well-formed
+ * `GUARD_<NAME>_UNEXPECTED` fallback. A fallback token is only accepted when it
+ * fits the wire budget as a prefix (token + ": " <= GUARD_REASON_BUDGET), so an
+ * accepted token can never force formatGuardReason to truncate its own prefix —
+ * consistent with the length-bounded {@link validatorUnexpectedCode}.
+ */
+export function isGuardReasonToken(value) {
+    if (isGuardReasonCode(value))
+        return true;
+    if (!(GUARD_UNEXPECTED_RE.test(value) && GUARD_CODE_RE.test(value)))
+        return false;
+    // Count Unicode code points to match formatGuardReason's budget exactly
+    // (the regex already constrains tokens to ASCII, so this is belt-and-suspenders).
+    return [...value].length + ": ".length <= GUARD_REASON_BUDGET;
+}
+/** Resolve the outcome for a token; UNEXPECTED fallbacks are always block+enforce. */
+export function outcomeForCode(code) {
+    if (isGuardReasonCode(code)) {
+        return GUARD_REASON_CODES[code];
+    }
+    return BLOCK_ENFORCE;
+}
+/** Total wire budget (in Unicode code points) for a host-displayed deny reason. */
+export const GUARD_REASON_BUDGET = 80;
+/** Truncate to at most `max` Unicode code points (never splits a surrogate pair). */
+export function truncateCodePoints(value, max) {
+    if (max <= 0)
+        return "";
+    const points = Array.from(value);
+    return points.length <= max ? value : points.slice(0, max).join("");
+}
+/**
+ * Truncate a wire reason to the {@link GUARD_REASON_BUDGET} in Unicode code
+ * points (never splitting a surrogate pair). Truncates from the end, so a
+ * leading `GUARD_<CODE>: ` prefix always survives. Shared by buildDenyEnvelope
+ * so the defensive budget matches formatGuardReason exactly.
+ */
+export function truncateReasonToBudget(reason) {
+    return truncateCodePoints(reason, GUARD_REASON_BUDGET);
+}
+/**
+ * Produce the host-displayed wire reason `"<CODE>: <message>"`.
+ *
+ * The code prefix is reserved FIRST, then the message is sanitized (whitespace
+ * collapsed) and truncated by Unicode code points so the total never exceeds
+ * {@link GUARD_REASON_BUDGET} and no emoji/surrogate pair is split. The code
+ * therefore always survives the host budget — that survival is the entire
+ * cross-host stdout integration.
+ *
+ * `code` is a typed {@link GuardReasonToken}, so an over-budget prefix is not a
+ * reachable input (all registered codes and validator fallbacks are far under
+ * 80). If one somehow occurs, the prefix is preserved and the message dropped
+ * rather than corrupting the code.
+ *
+ * A message that already begins with the same `CODE: ` prefix is not
+ * double-prefixed (idempotent for re-formatted reasons).
+ */
+export function formatGuardReason(code, message) {
+    const prefix = `${code}: `;
+    const collapsed = message.replace(/\s+/gu, " ").trim();
+    const withoutDuplicatePrefix = collapsed.startsWith(prefix)
+        ? collapsed.slice(prefix.length)
+        : collapsed;
+    const prefixPoints = Array.from(prefix).length;
+    const room = GUARD_REASON_BUDGET - prefixPoints;
+    if (room <= 0) {
+        // Unreachable for real tokens (all registered codes and bounded UNEXPECTED
+        // fallbacks are far under budget). If a caller ever hands in an oversized
+        // token, the 80-code-point budget still wins: truncate code-point-safe.
+        return truncateCodePoints(prefix, GUARD_REASON_BUDGET);
+    }
+    return `${prefix}${truncateCodePoints(withoutDuplicatePrefix, room)}`;
+}

package/dist/esm/hooks/shared/hook-bootstrap.d.ts

@@ -8,6 +8,32 @@ export declare function writeHookOutput(output: string): void;
  * Cross-platform: no-ops on Windows (fd redirect not portable there).
  */
 export declare function suppressStderr(): void;
+/**
+ * Capture intentional guard feedback at an in-process execution boundary.
+ *
+ * Production launchers leave this unset and write to the real fd 2. The
+ * conformance batch installs a row-scoped capture so direct fd delivery stays
+ * attributable to the row that emitted it.
+ */
+export declare function installGuardStderrCapture(capture: (text: string) => void): () => void;
+/**
+ * Suppress only DECORATIVE JS stderr (console.error / process.stderr.write
+ * diagnostics) while keeping the real fd 2 open. Unlike {@link suppressStderr}
+ * (which closes fd 2 to also block native stderr), this preserves the host's
+ * stderr channel so a PreToolUse deny can deliver its coded reason there —
+ * Claude reads STDERR, not stdout, as the blocking feedback on an exit-2 deny.
+ *
+ * Use this instead of {@link suppressStderr} on the pretool-guard path, which
+ * must both hide noise AND surface the coded deny reason on stderr.
+ */
+export declare function suppressDecorativeStderr(): void;
+/**
+ * Write intentional guard feedback (a coded deny reason) to the REAL stderr —
+ * the channel Claude reads on an exit-2 PreToolUse deny. When decorative stderr
+ * is suppressed (fd 2 still open), write directly to fd 2 to bypass the swallow;
+ * otherwise use the normal `process.stderr`. Never throws.
+ */
+export declare function writeGuardStderr(text: string): void;
 /**
  * Read all stdin bytes and return as UTF-8 string.
  */

package/dist/esm/hooks/shared/hook-bootstrap.js

@@ -1,4 +1,4 @@
-import { closeSync, openSync } from "node:fs";
+import { closeSync, openSync, writeSync } from "node:fs";
 import { rememberHookStdin } from "#hooks/logs/store.js";
 export function writeHookOutput(output) {
     process.stdout.write(output);
@@ -22,6 +22,69 @@ export function suppressStderr() {
         // If stderr is already closed or /dev/null unavailable, ignore silently
     }
 }
+/**
+ * True once {@link suppressDecorativeStderr} has swallowed decorative JS stderr
+ * while keeping the real fd 2 open, so {@link writeGuardStderr} delivers the
+ * coded reason to the real stderr via a direct fd write.
+ */
+let decorativeStderrSuppressed = false;
+let guardStderrCapture = null;
+/**
+ * Capture intentional guard feedback at an in-process execution boundary.
+ *
+ * Production launchers leave this unset and write to the real fd 2. The
+ * conformance batch installs a row-scoped capture so direct fd delivery stays
+ * attributable to the row that emitted it.
+ */
+export function installGuardStderrCapture(capture) {
+    const previous = guardStderrCapture;
+    guardStderrCapture = capture;
+    return () => {
+        if (guardStderrCapture === capture)
+            guardStderrCapture = previous;
+    };
+}
+/**
+ * Suppress only DECORATIVE JS stderr (console.error / process.stderr.write
+ * diagnostics) while keeping the real fd 2 open. Unlike {@link suppressStderr}
+ * (which closes fd 2 to also block native stderr), this preserves the host's
+ * stderr channel so a PreToolUse deny can deliver its coded reason there —
+ * Claude reads STDERR, not stdout, as the blocking feedback on an exit-2 deny.
+ *
+ * Use this instead of {@link suppressStderr} on the pretool-guard path, which
+ * must both hide noise AND surface the coded deny reason on stderr.
+ */
+export function suppressDecorativeStderr() {
+    if (process.platform === "win32")
+        return;
+    if (decorativeStderrSuppressed)
+        return;
+    const swallow = (() => true);
+    process.stderr.write = swallow;
+    decorativeStderrSuppressed = true;
+}
+/**
+ * Write intentional guard feedback (a coded deny reason) to the REAL stderr —
+ * the channel Claude reads on an exit-2 PreToolUse deny. When decorative stderr
+ * is suppressed (fd 2 still open), write directly to fd 2 to bypass the swallow;
+ * otherwise use the normal `process.stderr`. Never throws.
+ */
+export function writeGuardStderr(text) {
+    try {
+        if (guardStderrCapture) {
+            guardStderrCapture(text);
+            return;
+        }
+        if (decorativeStderrSuppressed) {
+            writeSync(2, text);
+            return;
+        }
+        process.stderr.write(text);
+    }
+    catch {
+        // Never block the hook on feedback delivery.
+    }
+}
 /**
  * Read all stdin bytes and return as UTF-8 string.
  */

package/dist/esm/hooks/shared/types.d.ts

@@ -63,8 +63,9 @@ export type ClaudeCodexDenyEnvelope = {
     readonly hookSpecificOutput: ClaudeDenyHookSpecificOutput;
 };
 /**
- * Dual shape for Grok freeload/native: Grok honors decision:"deny" (+ exit 2);
- * Claude still reads hookSpecificOutput.
+ * Dual shape for native/unlabeled Grok: Grok honors decision:"deny" (+ exit 2).
+ * Claude Code / Codex reject a top-level `decision` other than approve|block,
+ * so they never receive this shape — they read hookSpecificOutput instead.
  */
 export type GrokDualDenyEnvelope = {
     readonly decision: "deny";
@@ -75,9 +76,11 @@ export type DenyEnvelope = ClaudeCodexDenyEnvelope | GrokDualDenyEnvelope;
 /**
  * Build a policy deny envelope.
  *
- * - `codex`: Claude-compatible hookSpecificOutput only (golden schema).
- * - `grok` / default (incl. freeload with host labeled claude): dual Grok
- *   decision:"deny" + Claude hookSpecificOutput. Callers must also exit 2.
+ * - `claude` / `codex`: hookSpecificOutput only, because Claude Code and Codex
+ *   strict-validate the hook-output root and reject any top-level `decision`
+ *   other than approve|block. Deny is still delivered via the caller's exit 2.
+ * - `grok` / default / unknown: dual Grok decision:"deny" + hookSpecificOutput
+ *   (Grok reads the top-level decision). Callers must also exit 2.
  */
 export declare function buildDenyEnvelope(options: {
     readonly reason: string;

package/dist/esm/hooks/shared/types.js

@@ -1,3 +1,4 @@
+import { truncateReasonToBudget } from "#hooks/shared/guard-outcome";
 /**
  * Prefer snake_case when both styles are present (Claude/Codex contract).
  * Accept Grok camelCase envelopes so freeload and native Grok hooks parse.
@@ -148,25 +149,39 @@ function resolveDenyHost(env = process.env) {
 /**
  * Build a policy deny envelope.
  *
- * - `codex`: Claude-compatible hookSpecificOutput only (golden schema).
- * - `grok` / default (incl. freeload with host labeled claude): dual Grok
- *   decision:"deny" + Claude hookSpecificOutput. Callers must also exit 2.
+ * - `claude` / `codex`: hookSpecificOutput only, because Claude Code and Codex
+ *   strict-validate the hook-output root and reject any top-level `decision`
+ *   other than approve|block. Deny is still delivered via the caller's exit 2.
+ * - `grok` / default / unknown: dual Grok decision:"deny" + hookSpecificOutput
+ *   (Grok reads the top-level decision). Callers must also exit 2.
  */
 export function buildDenyEnvelope(options, env = process.env) {
+    // Defensive budget: the permissionDecisionReason contract is <=80 chars. A
+    // reason from formatGuardReason is already within budget (idempotent here);
+    // a raw over-budget reason from any future caller is truncated by Unicode
+    // code points (never splitting a surrogate pair, matching formatGuardReason),
+    // from the end, so a leading GUARD_ code prefix always survives.
+    const reason = truncateReasonToBudget(options.reason);
     const hookSpecificOutput = {
         hookEventName: "PreToolUse",
         permissionDecision: "deny",
-        permissionDecisionReason: options.reason,
+        permissionDecisionReason: reason,
     };
+    // Claude Code and Codex strict-validate the PreToolUse hook-output root and
+    // REJECT any top-level `decision` other than approve|block (Claude Code
+    // surfaces "Hook JSON output validation failed"). A real Claude host is
+    // labeled WP_HOOK_HOST=claude, so it MUST get the schema-valid
+    // hookSpecificOutput shape — not the dual envelope. The runner's exit-2
+    // delivers the deny regardless of stdout shape.
     const host = resolveDenyHost(env);
-    if (host === "codex") {
+    if (host === "codex" || host === "claude") {
         return { hookSpecificOutput };
     }
-    // Grok native, freeload (often WP_HOOK_HOST=claude), and unknown hosts:
-    // dual-emit so Grok JSON deny works; Claude ignores extra top-level keys.
+    // Native Grok (WP_HOOK_HOST=grok) and unknown/unlabeled hosts (treated as a
+    // Grok freeload fallback): dual-emit so Grok's JSON deny works. Callers exit 2.
     return {
         decision: "deny",
-        reason: options.reason,
+        reason,
         hookSpecificOutput,
     };
 }

package/dist/esm/hooks/stop/qa-changed-files.d.ts

@@ -21,6 +21,17 @@ export declare function getChangedFiles(projectDir: string): string[];
 export declare function filterQaFiles(files: string[]): string[];
 export declare function getTypecheckFiles(files: string[]): string[];
 export declare function findTestFiles(sourceFile: string, projectDir: string): string[];
+/**
+ * Every test path the cross-cutting map can yield.
+ *
+ * Exported so a guard test can assert these still exist on disk. Without that
+ * guard a rename would keep the unit tests green — they only compare strings —
+ * while the caller's existence filter silently dropped the path, reinstating
+ * the very under-selection this map exists to prevent.
+ */
+export declare function crossCuttingTestDependentPaths(): string[];
+/** Non-colocated tests a changed file is known to affect. */
+export declare function findCrossCuttingTestFiles(sourceFile: string): string[];
 export declare function discoverTestFiles(changedFiles: string[], projectDir: string): string[];
 export declare function buildTypecheckCommand(files: string[]): string | null;
 export declare function buildTestCommand(files: string[]): string | null;