@lucascouts/claude-agent-tui 0.1.0

package/dist/live-diff-env.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Story 043 (R2.2) — the LIVE_DIFF entrypoint flag parse. Defaults ON: only the explicit
+ * opt-out values "0"/"false" disable it (unset/empty/any other value → ON). Pure + testable;
+ * index.ts calls this so the truth table is unit-checkable without running the entrypoint.
+ */
+export declare function liveDiffEnabled(env?: Record<string, string | undefined>): boolean;
+//# sourceMappingURL=live-diff-env.d.ts.map

package/dist/live-diff-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-diff-env.d.ts","sourceRoot":"","sources":["../src/live-diff-env.ts"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,OAAO,CAE9F"}

package/dist/live-diff-env.js

@@ -0,0 +1,18 @@
+// Story 043 / Task 2.1 (R2.2) — the LIVE_DIFF entrypoint flag parse. Defaults ON: the live Edit/Write
+// diff (the story-021 structuredPatch diff, hydrated onto the reduced-shape JSONL via the diff-enriched
+// reader — see diff-enriched-reader.ts) is emitted by default on BOTH the live pump and the session/load
+// replay, and only the explicit opt-out values "0"/"false" disable it (unset / empty / any other value
+// → ON). This is the v2 default per the FORK.md 4.2 rationale: with the PTY engine the PostToolUse hook
+// that once produced diffs is GONE, so the reduced shape renders no diff unless we hydrate `toolUseResult`
+// by uuid; defaulting ON restores the story-021 diff for live Edit/Write. OFF → byte-for-byte the pre-043
+// reduced reader (R5.1). Kept a self-contained, PURE module (cf. usage-env.ts) so the truth table is
+// unit-checkable without booting the entrypoint; index.ts calls it and threads the result through
+// runAcp → AgentDeps → the agent. It does NOT go through lib.ts (the frozen upstream export surface).
+/**
+ * Story 043 (R2.2) — the LIVE_DIFF entrypoint flag parse. Defaults ON: only the explicit
+ * opt-out values "0"/"false" disable it (unset/empty/any other value → ON). Pure + testable;
+ * index.ts calls this so the truth table is unit-checkable without running the entrypoint.
+ */
+export function liveDiffEnabled(env = process.env) {
+    return env.LIVE_DIFF !== "0" && env.LIVE_DIFF !== "false";
+}

package/dist/live-subagent-env.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Story 044 (R4.1) — the FORK_LIVE_SUBAGENT_WATCH entrypoint flag parse. Defaults ON: only the
+ * explicit opt-out values "0"/"false" disable it (unset/empty/any other value → ON). Pure + testable;
+ * index.ts calls this so the truth table is unit-checkable without running the entrypoint.
+ */
+export declare function liveSubagentWatchEnabled(env?: Record<string, string | undefined>): boolean;
+//# sourceMappingURL=live-subagent-env.d.ts.map

package/dist/live-subagent-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-subagent-env.d.ts","sourceRoot":"","sources":["../src/live-subagent-env.ts"],"names":[],"mappings":"AAYA;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,OAAO,CAEvG"}

package/dist/live-subagent-env.js

@@ -0,0 +1,19 @@
+// Story 044 / Task 2.1 (R4.1, R4.2) — the FORK_LIVE_SUBAGENT_WATCH entrypoint flag parse. Defaults
+// ON: the live sub-agent watcher (the story-044 Option-B 2nd watcher that POLLs the SDK sidechain
+// readers while a turn is in flight, feeding the story-024 detector's noteActivity() seam and the
+// incremental nested render) is armed by default, and only the explicit opt-out values "0"/"false"
+// disable it (unset / empty / any other value → ON). This closes the story-041 R4.2 live gap: a
+// long-running sub-agent (e.g. a ~7-minute `Agent` Task) writes only subagents/*.jsonl while the
+// MAIN transcript stays silent, so the turn watchdog false-stalls a turn that is actually
+// progressing. OFF → byte-for-byte today's pull-only path: NO 2nd watcher armed (R4.2). Kept a
+// self-contained, PURE module (cf. usage-env.ts / live-diff-env.ts) so the truth table is
+// unit-checkable without booting the entrypoint; index.ts calls it and threads the result through
+// runAcp → AgentDeps → the agent. It does NOT go through lib.ts (the frozen upstream export surface).
+/**
+ * Story 044 (R4.1) — the FORK_LIVE_SUBAGENT_WATCH entrypoint flag parse. Defaults ON: only the
+ * explicit opt-out values "0"/"false" disable it (unset/empty/any other value → ON). Pure + testable;
+ * index.ts calls this so the truth table is unit-checkable without running the entrypoint.
+ */
+export function liveSubagentWatchEnabled(env = process.env) {
+    return env.FORK_LIVE_SUBAGENT_WATCH !== "0" && env.FORK_LIVE_SUBAGENT_WATCH !== "false";
+}

package/dist/permissions/allow-inject.d.ts

@@ -0,0 +1,67 @@
+/** The story-032 PTY input primitive this module needs — structurally satisfied by node-pty's IPty. */
+export interface PtyWriter {
+    write(data: string): void;
+}
+/** The keystrokes the native TUI permission prompt accepts (§9): Yes = `'1\r'`, refusal types `'No'`. */
+export declare const KEYSTROKE_YES = "1\r";
+export declare const KEYSTROKE_NO = "No";
+/** Default time (ms) to wait for the native prompt to clear after a keystroke before warning. */
+export declare const DEFAULT_INJECT_TIMEOUT_MS = 2000;
+/** Default poll interval (ms) between prompt-cleared probes. */
+export declare const DEFAULT_INJECT_POLL_MS = 50;
+/**
+ * Pick the keystroke for a decision (R3.1). `'allow'` → `'1\r'` (Yes / first option); `'deny'` →
+ * `'No'` (refusal). Exposed as a pure function so the choice is unit-testable without a PTY.
+ *
+ * @param decision the gate's enforced decision.
+ * @returns the keystroke string to type into the native prompt.
+ */
+export declare function keystrokeFor(decision: "allow" | "deny"): string;
+/** Injectable timer seam (the same `schedule`/clock discipline as end-of-turn + sendPrompt). */
+export type Schedule = (fn: () => void, ms: number) => void;
+/** The outcome of an allow-path keystroke injection. */
+export type InjectResult = {
+    status: "cleared";
+    keystroke: string;
+} | {
+    status: "suppressed";
+} | {
+    status: "stuck";
+    keystroke: string;
+};
+/** Options for {@link clearNativePrompt}. */
+export interface ClearNativePromptOptions {
+    /** The story-032 PTY input primitive (production: the session's IPty). */
+    pty: PtyWriter;
+    /** The gate's enforced decision (`'allow'` types Yes; `'deny'` types No). */
+    decision: "allow" | "deny";
+    /**
+     * Probe whether the native TUI prompt is CURRENTLY shown. Production wires this to an ANSI-mirror /
+     * TUI-state check; injected so a unit test models "prompt shown → cleared after keystroke" or
+     * "prompt stuck". Called before injecting (to skip the suppressed case) and after (to confirm it
+     * cleared).
+     */
+    isPromptShown: () => boolean;
+    /** Max ms to wait for the prompt to clear before warning (default {@link DEFAULT_INJECT_TIMEOUT_MS}). */
+    timeoutMs?: number;
+    /** Poll interval (ms) between cleared-probes (default {@link DEFAULT_INJECT_POLL_MS}). */
+    pollMs?: number;
+    /** Injectable timer (default setTimeout). */
+    schedule?: Schedule;
+    /** Warning sink for the stuck-prompt case (default no-op; production wires the logger). */
+    onWarn?: (message: string) => void;
+}
+/**
+ * Clear the native TUI prompt for an allow/deny decision when it is NOT suppressed (#52822 mitigation).
+ *
+ * 1. If `isPromptShown()` is already false, the native prompt was suppressed (the 2.1.161 case) — return
+ *    `'suppressed'` WITHOUT typing anything (we never type into a prompt that is not there).
+ * 2. Otherwise type the keystroke (`'1\r'`=Yes for allow, `'No'` for deny) via the PTY writer, then
+ *    poll `isPromptShown()` until it clears or the timeout elapses.
+ * 3. On clear → `'cleared'`. On timeout → surface a stuck-prompt warning and return `'stuck'` (the
+ *    caller must NOT treat this as an approval — R3.2: no silent approve).
+ *
+ * @returns an {@link InjectResult}: `'suppressed'` | `'cleared'` | `'stuck'`.
+ */
+export declare function clearNativePrompt(opts: ClearNativePromptOptions): Promise<InjectResult>;
+//# sourceMappingURL=allow-inject.d.ts.map

package/dist/permissions/allow-inject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allow-inject.d.ts","sourceRoot":"","sources":["../../src/permissions/allow-inject.ts"],"names":[],"mappings":"AAsBA,uGAAuG;AACvG,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,yGAAyG;AACzG,eAAO,MAAM,aAAa,QAAQ,CAAC;AACnC,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,iGAAiG;AACjG,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,gEAAgE;AAChE,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,CAE/D;AAED,gGAAgG;AAChG,MAAM,MAAM,QAAQ,GAAG,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;AAM5D,wDAAwD;AACxD,MAAM,MAAM,YAAY,GACpB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,GACxB;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3C,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC,0EAA0E;IAC1E,GAAG,EAAE,SAAS,CAAC;IACf,6EAA6E;IAC7E,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,aAAa,EAAE,MAAM,OAAO,CAAC;IAC7B,yGAAyG;IACzG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,OAAO,CAAC,YAAY,CAAC,CA4CvF"}

package/dist/permissions/allow-inject.js

@@ -0,0 +1,85 @@
+// Story 033 / Task 3.1 — hybrid ALLOW path: on a non-suppressed native prompt (#52822), inject the
+// keystroke into the PTY via the story-032 input driver; on timeout, WARN — never silently approve
+// (R3.1, R3.2).
+//
+// WHY (IMPLEMENTACAO-FORK-ACP.md §9 / GATE_FINDINGS.md #52822): allow does NOT reliably suppress the
+// native TUI prompt. The Degrau-0 probe saw suppression on claude 2.1.161, but that is VERSION-FRAGILE
+// (it may depend on the absence of an `ask` rule + the user's own permissions.allow rules) and is NOT
+// guaranteed. So after the gate returns `allow`, if the native prompt is STILL shown we clear it by
+// typing the keystroke into the PTY: `'1\r'` = Yes (the first/affirmative option), or `'No'` for a
+// refusal. We NEVER assume suppression, and we NEVER spoof an affirmative keystroke for a tool the user
+// actually denied.
+//
+// FAIL CLOSED (design.md): if the injection does not clear the prompt within a timeout, we surface a
+// stuck-prompt warning and HOLD — we do NOT report success / silently approve. The caller treats a
+// stuck prompt as unresolved, not as an allow.
+//
+// REUSE: the keystroke goes through the story-032 PTY input primitive (`IPty.write` — the same
+// primitive `sendPrompt` and the cancel ladder `interrupt`/`escape` use). We write the raw keystroke
+// directly (NOT via `sendPrompt`, which would append its own delayed `\r` for a normal prompt); the
+// `'1\r'` already carries its Enter. Injected behind a minimal `PtyWriter` seam so this is unit-testable
+// OFFLINE with a fake PTY.
+/** The keystrokes the native TUI permission prompt accepts (§9): Yes = `'1\r'`, refusal types `'No'`. */
+export const KEYSTROKE_YES = "1\r";
+export const KEYSTROKE_NO = "No";
+/** Default time (ms) to wait for the native prompt to clear after a keystroke before warning. */
+export const DEFAULT_INJECT_TIMEOUT_MS = 2000;
+/** Default poll interval (ms) between prompt-cleared probes. */
+export const DEFAULT_INJECT_POLL_MS = 50;
+/**
+ * Pick the keystroke for a decision (R3.1). `'allow'` → `'1\r'` (Yes / first option); `'deny'` →
+ * `'No'` (refusal). Exposed as a pure function so the choice is unit-testable without a PTY.
+ *
+ * @param decision the gate's enforced decision.
+ * @returns the keystroke string to type into the native prompt.
+ */
+export function keystrokeFor(decision) {
+    return decision === "allow" ? KEYSTROKE_YES : KEYSTROKE_NO;
+}
+const defaultSchedule = (fn, ms) => {
+    setTimeout(fn, ms);
+};
+/**
+ * Clear the native TUI prompt for an allow/deny decision when it is NOT suppressed (#52822 mitigation).
+ *
+ * 1. If `isPromptShown()` is already false, the native prompt was suppressed (the 2.1.161 case) — return
+ *    `'suppressed'` WITHOUT typing anything (we never type into a prompt that is not there).
+ * 2. Otherwise type the keystroke (`'1\r'`=Yes for allow, `'No'` for deny) via the PTY writer, then
+ *    poll `isPromptShown()` until it clears or the timeout elapses.
+ * 3. On clear → `'cleared'`. On timeout → surface a stuck-prompt warning and return `'stuck'` (the
+ *    caller must NOT treat this as an approval — R3.2: no silent approve).
+ *
+ * @returns an {@link InjectResult}: `'suppressed'` | `'cleared'` | `'stuck'`.
+ */
+export function clearNativePrompt(opts) {
+    const { pty, decision, isPromptShown, timeoutMs = DEFAULT_INJECT_TIMEOUT_MS, pollMs = DEFAULT_INJECT_POLL_MS, schedule = defaultSchedule, onWarn, } = opts;
+    return new Promise((resolve) => {
+        // (1) Already suppressed → nothing to clear; never type into a non-existent prompt.
+        if (!isPromptShown()) {
+            resolve({ status: "suppressed" });
+            return;
+        }
+        // (2) Type the keystroke for the decision. We NEVER spoof Yes for a denied tool: deny types No.
+        const keystroke = keystrokeFor(decision);
+        pty.write(keystroke);
+        // (3) Poll for the prompt to clear, bounded by timeoutMs. On timeout → stuck warning, HOLD.
+        const deadline = timeoutMs;
+        let elapsed = 0;
+        const poll = () => {
+            if (!isPromptShown()) {
+                resolve({ status: "cleared", keystroke });
+                return;
+            }
+            elapsed += pollMs;
+            if (elapsed >= deadline) {
+                onWarn?.(`[gate §9] STUCK PROMPT: injected "${JSON.stringify(keystroke)}" but the native TUI ` +
+                    `permission prompt did not clear within ${timeoutMs}ms (#52822). NOT approving silently — ` +
+                    `holding for manual resolution.`);
+                resolve({ status: "stuck", keystroke });
+                return;
+            }
+            schedule(poll, pollMs);
+        };
+        schedule(poll, pollMs);
+    });
+}

package/dist/permissions/deny.d.ts

@@ -0,0 +1,60 @@
+/** The §9 hook `permissionDecision` values (the allow path is best-effort — see allow-inject.ts). */
+export type PermissionDecision = "allow" | "deny";
+/** Process exit code that a PreToolUse hook uses to intercept the tool (the exit-2 form, §9). */
+export declare const HOOK_DENY_EXIT_CODE = 2;
+/** The §9 PreToolUse hook-specific output block carried in a decision-body response. */
+export interface HookSpecificOutput {
+    hookEventName: "PreToolUse";
+    permissionDecision: PermissionDecision;
+    /** Human-readable reason surfaced to the TUI/log; never silently empty on a deny. */
+    permissionDecisionReason: string;
+}
+/** The JSON body a PreToolUse http hook returns to claude (the decision-body form). */
+export interface HookResponse {
+    hookSpecificOutput: HookSpecificOutput;
+}
+/** Minimal view of the tool call a deny decision is built for (the hook-payload subset). */
+export interface DenyToolCall {
+    /** The tool name from the hook payload / JSONL `tool_use.name` (e.g. `Bash`, `Edit`). */
+    toolName: string;
+    /** The correlation key — hook `tool_use_id` == JSONL `tool_use.id`. */
+    toolUseId: string;
+}
+/**
+ * Default deny reason when the caller supplies none. Names the tool so the TUI/log is never a blank
+ * "denied" — a silent deny is as confusing as a silent approve.
+ */
+export declare function defaultDenyReason(toolCall: DenyToolCall): string;
+/**
+ * Translate a `deny` outcome into the §9 hook decision body that INTERCEPTS the tool before it runs
+ * (R2.3). The returned object is the JSON the loopback hook server writes back to claude.
+ *
+ * @param toolCall the tool the decision is for (names it in the default reason).
+ * @param reason optional explicit reason; defaults to {@link defaultDenyReason} (never blank).
+ * @returns `{ hookSpecificOutput: { hookEventName:'PreToolUse', permissionDecision:'deny', … } }`.
+ */
+export declare function denyDecision(toolCall: DenyToolCall, reason?: string): HookResponse;
+/**
+ * Translate an `allow` outcome into the §9 hook decision body. NOTE: per #52822 an allow body does
+ * NOT reliably suppress the native TUI prompt — the allow path also drives the keystroke-injection
+ * mitigation (allow-inject.ts). This helper only produces the body half.
+ *
+ * @param toolCall the tool the decision is for.
+ * @param reason optional explicit reason; defaults to a tool-naming allow reason.
+ * @returns `{ hookSpecificOutput: { hookEventName:'PreToolUse', permissionDecision:'allow', … } }`.
+ */
+export declare function allowDecision(toolCall: DenyToolCall, reason?: string): HookResponse;
+/**
+ * Matcher-scoped deny predicate (R2.3 NUANCE): does this deny matcher target the given tool?
+ *
+ * `"*"` matches every tool (the broad shape the Degrau-0 probe fired, which masked per-tool reliability
+ * by denying a precursor tool). A specific matcher (e.g. `"Edit"`, `"Bash"`) matches ONLY that tool, so
+ * #37210 (Edit) / #33106 (MCP) can be isolated and characterized at wire time. Matching is exact and
+ * case-sensitive on the tool name — the same convention the §9 settings matcher uses.
+ *
+ * @param matcher the deny matcher (`"*"` or an exact tool name).
+ * @param toolName the tool from the hook payload.
+ * @returns true iff the matcher scopes the deny to this tool.
+ */
+export declare function denyMatchesTool(matcher: string, toolName: string): boolean;
+//# sourceMappingURL=deny.d.ts.map

package/dist/permissions/deny.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deny.d.ts","sourceRoot":"","sources":["../../src/permissions/deny.ts"],"names":[],"mappings":"AAsBA,qGAAqG;AACrG,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,MAAM,CAAC;AAElD,iGAAiG;AACjG,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,wFAAwF;AACxF,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,YAAY,CAAC;IAC5B,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,qFAAqF;IACrF,wBAAwB,EAAE,MAAM,CAAC;CAClC;AAED,uFAAuF;AACvF,MAAM,WAAW,YAAY;IAC3B,kBAAkB,EAAE,kBAAkB,CAAC;CACxC;AAED,4FAA4F;AAC5F,MAAM,WAAW,YAAY;IAC3B,yFAAyF;IACzF,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAKhE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAQlF;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CASnF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE1E"}

package/dist/permissions/deny.js

@@ -0,0 +1,81 @@
+// Story 033 / Task 2.3 — deny enforcement: map a `deny` decision to a hook response that intercepts
+// BEFORE the tool runs (R2.3), and a matcher-scoped deny so per-tool reliability can be characterized.
+//
+// BINDING Degrau-0 finding (experiments/GATE_FINDINGS.md / IMPLEMENTACAO-FORK-ACP.md §9): a
+// `PreToolUse` `permissionDecision:'deny'` body (or process exit code 2) INTERCEPTS the tool before it
+// executes — `intercepted=true` across Bash/Edit/MCP. DENY is the load-bearing capability of the
+// hybrid gate; ALLOW is best-effort (story 033 allow-inject). This module owns ONLY the deny→response
+// translation and the matcher scope; the loopback server is hook-server.ts and the ACP correlation is
+// request-permission.ts.
+//
+// Two response forms, both honored by claude (§9):
+//   - DECISION BODY: `{ hookSpecificOutput: { hookEventName:'PreToolUse', permissionDecision:'deny',
+//     permissionDecisionReason } }` returned as the http hook's JSON response (preferred — carries a
+//     reason the TUI/log can show);
+//   - EXIT CODE 2: a process-exit form for a command/exec hook. Captured here as a constant + helper so
+//     a caller that drives an exec-style hook can fail closed with the right code.
+//
+// NUANCE (#37210 Edit / #33106 MCP — review #18453): the broad `"*"` matcher denied the PRECURSOR tool
+// claude attempted first (Read before Edit; ToolSearch before the MCP), so per-tool deny reliability
+// was NOT isolated in Degrau 0. A MATCHER-SCOPED deny ({@link denyMatchesTool}) targets the intended
+// tool so its reliability can be characterized at wire time (story 034) instead of re-masking it.
+/** Process exit code that a PreToolUse hook uses to intercept the tool (the exit-2 form, §9). */
+export const HOOK_DENY_EXIT_CODE = 2;
+/**
+ * Default deny reason when the caller supplies none. Names the tool so the TUI/log is never a blank
+ * "denied" — a silent deny is as confusing as a silent approve.
+ */
+export function defaultDenyReason(toolCall) {
+    return (`Denied by the Zed permission gate (tool "${toolCall.toolName}", tool_use ${toolCall.toolUseId}). ` +
+        `The tool was intercepted before it ran.`);
+}
+/**
+ * Translate a `deny` outcome into the §9 hook decision body that INTERCEPTS the tool before it runs
+ * (R2.3). The returned object is the JSON the loopback hook server writes back to claude.
+ *
+ * @param toolCall the tool the decision is for (names it in the default reason).
+ * @param reason optional explicit reason; defaults to {@link defaultDenyReason} (never blank).
+ * @returns `{ hookSpecificOutput: { hookEventName:'PreToolUse', permissionDecision:'deny', … } }`.
+ */
+export function denyDecision(toolCall, reason) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: reason ?? defaultDenyReason(toolCall),
+        },
+    };
+}
+/**
+ * Translate an `allow` outcome into the §9 hook decision body. NOTE: per #52822 an allow body does
+ * NOT reliably suppress the native TUI prompt — the allow path also drives the keystroke-injection
+ * mitigation (allow-inject.ts). This helper only produces the body half.
+ *
+ * @param toolCall the tool the decision is for.
+ * @param reason optional explicit reason; defaults to a tool-naming allow reason.
+ * @returns `{ hookSpecificOutput: { hookEventName:'PreToolUse', permissionDecision:'allow', … } }`.
+ */
+export function allowDecision(toolCall, reason) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "allow",
+            permissionDecisionReason: reason ?? `Allowed by the Zed permission gate (tool "${toolCall.toolName}").`,
+        },
+    };
+}
+/**
+ * Matcher-scoped deny predicate (R2.3 NUANCE): does this deny matcher target the given tool?
+ *
+ * `"*"` matches every tool (the broad shape the Degrau-0 probe fired, which masked per-tool reliability
+ * by denying a precursor tool). A specific matcher (e.g. `"Edit"`, `"Bash"`) matches ONLY that tool, so
+ * #37210 (Edit) / #33106 (MCP) can be isolated and characterized at wire time. Matching is exact and
+ * case-sensitive on the tool name — the same convention the §9 settings matcher uses.
+ *
+ * @param matcher the deny matcher (`"*"` or an exact tool name).
+ * @param toolName the tool from the hook payload.
+ * @returns true iff the matcher scopes the deny to this tool.
+ */
+export function denyMatchesTool(matcher, toolName) {
+    return matcher === "*" || matcher === toolName;
+}

package/dist/permissions/gate-wiring.d.ts

@@ -0,0 +1,112 @@
+import { ToolUseCorrelator, type PermissionClient } from "./request-permission.js";
+import { type PtyWriter, type Schedule } from "./allow-inject.js";
+/**
+ * Substrings that evidence the native TUI permission prompt (the bordered "Do you want to
+ * proceed?" box with numbered options), matched case-sensitively against the ANSI-stripped recent
+ * PTY output. COPIED VERBATIM from the Degrau-0 billed probe (`experiments/e-gate.ts`
+ * `NATIVE_PERMISSION_PROMPT_MARKERS`, claude 2.1.161) — the only empirical characterization of the
+ * prompt's rendering we have. ANY hit ⇒ the native prompt is showing (#52822 reproduced).
+ */
+export declare const NATIVE_PERMISSION_PROMPT_MARKERS: readonly string[];
+/** True iff any native-prompt marker appears in `text` (after ANSI stripping). */
+export declare function textShowsNativePrompt(text: string): boolean;
+/** Default bounded wait for the JSONL `tool_use` correlation to land after a hook fires (ms).
+ *  The hook fires AFTER claude appended the assistant `tool_use` line, but the fs-watch → pump
+ *  re-read is asynchronous — this window absorbs that lag. On expiry the decider proceeds and
+ *  request-permission fails closed (deny) on the still-missing correlation. */
+export declare const DEFAULT_CORRELATION_WAIT_MS = 5000;
+/** Default poll interval for the correlation wait (ms). */
+export declare const DEFAULT_CORRELATION_POLL_MS = 50;
+/** Default window for the native prompt to APPEAR after an allow decision (#52822 sweep, ms).
+ *  If no marker renders within it, allow-suppression held (the 2.1.161 case) — nothing to clear. */
+export declare const DEFAULT_PROMPT_APPEAR_MS = 1500;
+/** Default poll interval for the sweep's appear/clear phases (ms). */
+export declare const DEFAULT_PROMPT_POLL_MS = 100;
+/** Default budget for the keystroke to clear the prompt before the stuck warning (ms). */
+export declare const DEFAULT_INJECT_TIMEOUT_MS = 2000;
+/** Default bounded wait for the hook server to close on teardown (ms) — teardown never hangs on a
+ *  socket held open by an in-flight decider; on expiry it warns and proceeds (the process-level
+ *  close still completes in the background). */
+export declare const DEFAULT_CLOSE_TIMEOUT_MS = 2000;
+/** Filename prefix of the per-session scratch settings file (diagnosable in `ls /tmp`). */
+export declare const SCRATCH_SETTINGS_PREFIX = "fork-acp-gate-settings-";
+/** The minimal PTY surface the gate needs: a raw writer (allow keystroke) and, when available, an
+ *  `onData` tap feeding the native-prompt probe. Structurally satisfied by node-pty's IPty; the
+ *  replay-only noop PTY also satisfies it (but replay-only sessions never get a gate). */
+export interface GatePty extends PtyWriter {
+    onData?(cb: (data: string) => void): {
+        dispose(): void;
+    };
+}
+/** Options for {@link setupSessionGate}. Timing knobs are injectable for offline tests. */
+export interface SessionGateOptions {
+    /** The ACP client surface (`AgentSideConnection` satisfies it: `requestPermission(params)`). */
+    client: PermissionClient;
+    /** Diagnostics sink for every fail-closed / stuck-prompt warning (production: logger.error). */
+    onWarn?: (message: string) => void;
+    /** Injectable timer seam (same discipline as allow-inject/end-of-turn). Default: setTimeout. */
+    schedule?: Schedule;
+    /** Directory for the per-session scratch settings file. Default: `os.tmpdir()`. */
+    settingsDir?: string;
+    /** Hook timeout written into the scratch settings, in SECONDS (claude default 600). */
+    hookTimeoutSeconds?: number;
+    /** Hook-server decider budget (ms) before it fails closed; default per hook-server. */
+    deciderTimeoutMs?: number;
+    /** See {@link DEFAULT_CORRELATION_WAIT_MS}. */
+    correlationWaitMs?: number;
+    /** See {@link DEFAULT_CORRELATION_POLL_MS}. */
+    correlationPollMs?: number;
+    /** See {@link DEFAULT_PROMPT_APPEAR_MS}. */
+    promptAppearMs?: number;
+    /** See {@link DEFAULT_PROMPT_POLL_MS}. */
+    promptPollMs?: number;
+    /** See {@link DEFAULT_INJECT_TIMEOUT_MS}. */
+    injectTimeoutMs?: number;
+    /** See {@link DEFAULT_CLOSE_TIMEOUT_MS}. */
+    closeTimeoutMs?: number;
+    /** Injectable port allocator (default: the story-032 `findFreePort`). */
+    findPort?: () => Promise<number>;
+}
+/** The per-session gate runtime handle `createSession` owns and `teardownSession` disposes. */
+export interface SessionGate {
+    /** The verified-free loopback port the hook server bound (== the port in the scratch hook URL). */
+    port: number;
+    /** Absolute path of the per-session scratch settings file (hand to the spawn as `--settings`). */
+    settingsPath: string;
+    /** The per-session `tool_use.id` correlation map. The live pump REGISTERS every JSONL `tool_use`
+     *  id here (`correlator.register(id)`) so a hook call can be matched before it is approved. */
+    correlator: ToolUseCorrelator;
+    /**
+     * Bind the AUTHORITATIVE ACP session id (known only AFTER the engine spawn on the fresh path)
+     * and an optional `nudge` invoked on every hook arrival to force an immediate pump re-read
+     * (shrinking the JSONL-correlation race). MUST be called before the first tool call can be
+     * approved — an unbound gate fails closed (deny).
+     */
+    bindSession(sessionId: string, nudge?: () => void): void;
+    /** Bind the live PTY: stores the raw writer for the allow keystroke and (when the PTY exposes
+     *  `onData`) attaches the recent-output tap feeding the native-prompt probe. */
+    bindPty(pty: GatePty): void;
+    /** Idempotent teardown: close the hook server (bounded) and restore/delete the scratch settings.
+     *  Safe to call from BOTH `teardownSession` and the PTY `onExit` hook. */
+    teardown(): Promise<void>;
+    /** True once {@link teardown} has run. */
+    readonly isTorndown: boolean;
+}
+/**
+ * Set up the per-session HYBRID gate runtime (story 034 wiring): allocate a verified-free loopback
+ * port, start the fail-closed `PreToolUse` hook server with the REAL story-033 decider chain, and
+ * write the per-session scratch settings file the spawn consumes via `--settings "<file>"`.
+ *
+ * ORDERING CONTRACT (GATE_FINDINGS blocker c): the caller MUST `await setupSessionGate(...)` and
+ * pass {@link SessionGate.settingsPath} to the spawn BEFORE the claude PTY is spawned — claude reads
+ * settings only at startup, so a late write misses the first tool call. After the spawn the caller
+ * binds the authoritative session id ({@link SessionGate.bindSession}) and the live PTY
+ * ({@link SessionGate.bindPty}), and disposes via {@link SessionGate.teardown} on session teardown
+ * AND PTY exit (idempotent).
+ *
+ * On a setup failure (port exhaustion, bind error, settings write error) the promise REJECTS with
+ * everything already cleaned up — the caller fails the session creation LOUDLY rather than spawning
+ * an ungated claude that LOOKS gated (the blocker-b hazard). `FORK_GATE=off` is the escape hatch.
+ */
+export declare function setupSessionGate(opts: SessionGateOptions): Promise<SessionGate>;
+//# sourceMappingURL=gate-wiring.d.ts.map

package/dist/permissions/gate-wiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate-wiring.d.ts","sourceRoot":"","sources":["../../src/permissions/gate-wiring.ts"],"names":[],"mappings":"AAyCA,OAAO,EAEL,iBAAiB,EACjB,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAqB,KAAK,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAErF;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,EAAE,SAAS,MAAM,EAO7D,CAAC;AAQF,kFAAkF;AAClF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAG3D;AAED;;;+EAG+E;AAC/E,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAChD,2DAA2D;AAC3D,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAC9C;oGACoG;AACpG,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C,sEAAsE;AACtE,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAC1C,0FAA0F;AAC1F,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAC9C;;gDAEgD;AAChD,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAI7C,2FAA2F;AAC3F,eAAO,MAAM,uBAAuB,4BAA4B,CAAC;AAEjE;;0FAE0F;AAC1F,MAAM,WAAW,OAAQ,SAAQ,SAAS;IACxC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG;QAAE,OAAO,IAAI,IAAI,CAAA;KAAE,CAAC;CAC1D;AAED,2FAA2F;AAC3F,MAAM,WAAW,kBAAkB;IACjC,gGAAgG;IAChG,MAAM,EAAE,gBAAgB,CAAC;IACzB,gGAAgG;IAChG,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,gGAAgG;IAChG,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,mFAAmF;IACnF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uFAAuF;IACvF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,uFAAuF;IACvF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,+CAA+C;IAC/C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0CAA0C;IAC1C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4CAA4C;IAC5C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CAClC;AAED,+FAA+F;AAC/F,MAAM,WAAW,WAAW;IAC1B,mGAAmG;IACnG,IAAI,EAAE,MAAM,CAAC;IACb,kGAAkG;IAClG,YAAY,EAAE,MAAM,CAAC;IACrB;mGAC+F;IAC/F,UAAU,EAAE,iBAAiB,CAAC;IAC9B;;;;;OAKG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACzD;oFACgF;IAChF,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5B;8EAC0E;IAC1E,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AA2RD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAIrF"}