@webpresso/agent-kit 3.1.28 → 3.2.0

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

@@ -25,13 +25,15 @@ const VALIDATOR_NAME = "worktree-discipline";
  *  effective cwd elsewhere (e.g. CI)        → ALLOW (rule scoped to local ~/repos primaries)
  * ```
  *
- * The "effective cwd" is the tool's ambient `input.cwd`, lowered only by a
- * success-gated cwd chain that directly governs the forbidden git op, e.g.
- * `cd <worktree> && git commit` or `(cd <worktree> && git commit)`, then by
- * EVERY `git -C <dir>` flag on the matched invocation (git applies them
- * cumulatively). Unsupported cwd-changing control flow, option-bearing `cd`,
- * `cd -`, or unresolvable `cd`/`-C` targets fail closed because they could hide
- * a primary-checkout mutation. Prefer `git -C <worktree> ...` or running the
+ * The "effective cwd" is the tool's ambient `input.cwd`, lowered by a
+ * success-gated `&&` chain that governs the forbidden git op, e.g.
+ * `cd <worktree> && git commit`, `cd <worktree> && ./bin/wp … && git commit`,
+ * or `(cd <worktree> && git commit)`, then by EVERY `git -C <dir>` flag on the
+ * matched invocation (git applies them cumulatively). Intermediate non-cwd
+ * commands after a proven `cd` leave the chain cwd unchanged. Unsupported
+ * control flow (`;` / `|` / braces), option-bearing `cd`, `cd -`, or
+ * unresolvable `cd`/`-C` targets fail closed because they could hide a
+ * primary-checkout mutation. Prefer `git -C <worktree> ...` or running the
  * command with the tool cwd already set to the worktree.
  *
  * Known best-effort limits (acceptable for an agent guard with a documented
@@ -634,12 +636,13 @@ const DIR_TOKEN = String.raw `(?:"[^"]+"|'[^']+'|[^\s;&|(){}]+)`;
 const QUOTED_ARG = String.raw `(?:"[^"]+"|'[^']+'|\S+)`;
 const CD_TARGET = String.raw `(?:--\s+)?(${DIR_TOKEN}|-)`;
 const CD_LEADER = String.raw `(?:[A-Za-z_]\w*=\S*\s+)*(?:command\s+|builtin\s+)?(?:cd|pushd)\s+`;
-// A success-gated cwd chain that directly governs the forbidden git op. We only
-// trust cwd changes in this shape; `;`, `||`, skipped/failed `cd`, quoted spoof
-// text, and other unsupported shell control flow fail closed instead.
+// Pure cd/pushd segment that updates the success-gated cwd (optional leading env /
+// command|builtin wrapper). Trailing whitespace is allowed; nothing else.
+const PURE_CD_SEGMENT = new RegExp(String.raw `^\s*${CD_LEADER}${CD_TARGET}\s*$`, "u");
+// Legacy pure trailing-cd chain (also used for subshell-local `(cd X && git …)`).
 const CD_CHAIN = new RegExp(String.raw `(?:^|[;&|(){}]\s*)?((?:\s*${CD_LEADER}${CD_TARGET}\s*&&)+)\s*$`, "u");
 const CD_IN_CHAIN = new RegExp(String.raw `(?:^|&&)\s*${CD_LEADER}${CD_TARGET}\s*(?=&&)`, "gu");
-const CWD_WORD = new RegExp(String.raw `(?:^|[;{}()&|]\s*|\s+)(?:[A-Za-z_]\w*=\S*\s+)*(?:command\s+|builtin\s+)?(?:cd|pushd)\b`, "gu");
+const CWD_WORD = new RegExp(String.raw `(?:^|[;{}()&|]\s*|\s+)(?:[A-Za-z_]\w*=\S*\s+)*(?:command\s+|builtin\s+)?(?:cd|pushd|popd)\b`, "gu");
 const DASH_C = new RegExp(String.raw `-C\s+(${DIR_TOKEN})`, "gu");
 function isInsideSingleOrDoubleQuotes(command, index) {
     let quote = null;
@@ -667,6 +670,27 @@ function hasUnquotedCwdCommand(command) {
     }
     return false;
 }
+/** True when unquoted `;` `|` `{` `}` appear (breaks a pure `&&` agent chain). */
+function hasUnquotedUnsafeAndChainControl(command) {
+    for (let i = 0; i < command.length; i += 1) {
+        const ch = command[i];
+        if (ch !== ";" && ch !== "|" && ch !== "{" && ch !== "}" && ch !== "\n")
+            continue;
+        if (!isInsideSingleOrDoubleQuotes(command, i))
+            return true;
+    }
+    return false;
+}
+function hasUnquotedParen(command) {
+    for (let i = 0; i < command.length; i += 1) {
+        const ch = command[i];
+        if (ch !== "(" && ch !== ")")
+            continue;
+        if (!isInsideSingleOrDoubleQuotes(command, i))
+            return true;
+    }
+    return false;
+}
 /** Apply one dir token to `cwd`, or signal ambiguity if it cannot be statically resolved. */
 function applyDir(token, cwd) {
     if (!token)
@@ -683,11 +707,85 @@ function isTrustedCwdChainStart(commandPrefix, chainStart) {
     const before = commandPrefix.slice(0, chainStart).trimEnd();
     return before.endsWith("&&") || before.endsWith("(") || before.endsWith("{");
 }
-function applySuccessGatedCwdChain(commandPrefix, baseCwd) {
+/**
+ * Split a pure `&&` command prefix into segments. Returns null when the prefix
+ * uses `;` / `|` / braces / newlines we refuse to model.
+ */
+function splitSuccessGatedAndSegments(commandPrefix) {
+    if (!commandPrefix.trim())
+        return [];
+    if (hasUnquotedUnsafeAndChainControl(commandPrefix))
+        return null;
+    const segments = [];
+    let current = "";
+    let quote = null;
+    let escaped = false;
+    for (let i = 0; i < commandPrefix.length; i += 1) {
+        const ch = commandPrefix[i] ?? "";
+        if (escaped) {
+            current += ch;
+            escaped = false;
+            continue;
+        }
+        if (quote !== "'" && ch === "\\") {
+            escaped = true;
+            current += ch;
+            continue;
+        }
+        if ((ch === '"' || ch === "'") && (quote === null || quote === ch)) {
+            quote = quote === ch ? null : ch;
+            current += ch;
+            continue;
+        }
+        if (!quote && ch === "&" && commandPrefix[i + 1] === "&") {
+            if (current.trim())
+                segments.push(current);
+            current = "";
+            i += 1;
+            continue;
+        }
+        current += ch;
+    }
+    if (quote || escaped)
+        return null;
+    if (current.trim())
+        segments.push(current);
+    return segments;
+}
+/**
+ * Walk pure `&&` segments: resolvable cd/pushd updates cwd; other segments must
+ * not smuggle unquoted cwd changes. Enables
+ * `cd <managed-worktree> && ./bin/wp … && git commit`.
+ */
+function applyAndSegmentCwdChain(commandPrefix, baseCwd) {
+    const segments = splitSuccessGatedAndSegments(commandPrefix);
+    if (segments === null)
+        return { ambiguous: true };
+    if (segments.length === 0)
+        return { ambiguous: false, cwd: baseCwd };
+    let cwd = baseCwd;
+    for (const segment of segments) {
+        const pureCd = PURE_CD_SEGMENT.exec(segment);
+        if (pureCd) {
+            const next = applyDir(pureCd[1], cwd);
+            if (next === "ambiguous")
+                return { ambiguous: true };
+            cwd = next.cwd;
+            continue;
+        }
+        if (hasUnquotedCwdCommand(segment))
+            return { ambiguous: true };
+    }
+    return { ambiguous: false, cwd };
+}
+/**
+ * Legacy trailing pure-cd chain (and subshell-local `(cd X && git …)` forms).
+ * Kept for paren-scoped ops; intermediate non-cd commands are handled by
+ * {@link applyAndSegmentCwdChain} when no unquoted parens are present.
+ */
+function applyLegacyTrailingCdChain(commandPrefix, baseCwd) {
     const chain = CD_CHAIN.exec(commandPrefix);
     const chainStart = chain?.index ?? commandPrefix.length;
-    // If there is any other unquoted cwd-changing syntax before this simple chain,
-    // we cannot prove the chain governs the op. Fail closed.
     if (hasUnquotedCwdCommand(commandPrefix.slice(0, chainStart)))
         return { ambiguous: true };
     if (!chain)
@@ -703,6 +801,20 @@ function applySuccessGatedCwdChain(commandPrefix, baseCwd) {
     }
     return { ambiguous: false, cwd };
 }
+/**
+ * Success-gated cwd chain for a forbidden git op's command prefix.
+ *
+ * Prefer the `&&`-segment walk when the prefix has no unquoted parentheses so
+ * agents can run tools between a managed `cd` and a mutation. When parentheses
+ * appear (subshell-local ops), fall back to the legacy trailing-cd chain so
+ * non-persistent `(cd …) && git …` stays fail-closed.
+ */
+function applySuccessGatedCwdChain(commandPrefix, baseCwd) {
+    if (!hasUnquotedParen(commandPrefix)) {
+        return applyAndSegmentCwdChain(commandPrefix, baseCwd);
+    }
+    return applyLegacyTrailingCdChain(commandPrefix, baseCwd);
+}
 /**
  * The directory the git op actually runs in: `baseCwd` lowered by the
  * success-gated cwd chain that directly governs this op, then through EVERY

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.
  */