@lucascouts/claude-agent-tui 0.1.0

package/dist/permissions/gate-wiring.js

@@ -0,0 +1,350 @@
+// Story 034 (§9 / R3.3) — runtime wiring of the HYBRID permission gate into the real session path.
+//
+// Stories 032/033 delivered the gate as STANDALONE, offline-tested seams: the verified-free loopback
+// port (gate/port.ts), the non-destructive `--settings` hook writer (gate/settings-writer.ts), the
+// fail-closed `PreToolUse` http hook server (hook-server.ts), the `tool_use.id` correlation + ACP
+// `session/request_permission` bridge (request-permission.ts), and the #52822 allow keystroke
+// mitigation (allow-inject.ts). THIS module is the missing glue: one {@link SessionGate} PER SESSION
+// that composes those REAL units (no re-implementation) so `createSession` can:
+//
+//   1. allocate a free loopback port (`findFreePort`) and start the hook server on it;
+//   2. write the per-session SCRATCH settings file carrying the hook (`injectHook`) — NEVER the
+//      user's `~/.claude/settings*.json` and NEVER the project `settings.local.json`; the scratch
+//      lives in `os.tmpdir()` and is handed to the spawn as `--settings "<file>"` (GATE_FINDINGS
+//      blocker c: settings MUST be on disk BEFORE the spawn — claude reads them only at startup);
+//   3. decide each `PreToolUse` via the REAL story-033 decider chain: correlate by `tool_use.id`
+//      against the JSONL (fed by the pump through {@link SessionGate.correlator}) → raise ACP
+//      `session/request_permission` in Zed → enforce (`deny` body intercepts BEFORE the tool runs);
+//   4. on `allow`, run the #52822 sweep: if the native TUI prompt still renders, inject the `'1\r'`
+//      keystroke RAW into the PTY (allow-inject — deliberately NOT `sendPrompt`, whose leading
+//      Ctrl+U clear byte must never touch a pending native dialog); on a stuck prompt WARN and hold;
+//   5. tear everything down (close the server, `restore` the scratch) on `teardownSession` AND on
+//      PTY exit — idempotently, leaking no port, server, or scratch file.
+//
+// FAIL CLOSED (PERMISSIONS.md §6): every uncertain path in the chain below already resolves to deny
+// (malformed payload / no decider / decider timeout → hook-server; missing/duplicate id, ACP
+// transport error, cancelled outcome → request-permission). This module adds two more: a missing
+// session binding (no ACP sessionId to prompt with) denies, and a correlation that never appears
+// within the bounded wait lets request-permission deny. Nothing here ever approves silently.
+//
+// OFFLINE: this module spawns NO claude and bills nothing; the http server binds 127.0.0.1 only.
+import * as os from "node:os";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { findFreePort } from "../gate/port.js";
+import { injectHook, restore } from "../gate/settings-writer.js";
+import { startHookServer, } from "./hook-server.js";
+import { requestPermission, ToolUseCorrelator, } from "./request-permission.js";
+import { clearNativePrompt } 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 const NATIVE_PERMISSION_PROMPT_MARKERS = [
+    "Do you want to proceed",
+    "Do you want to allow",
+    "Yes, and don't ask again",
+    "Yes, allow",
+    "1. Yes",
+    "No, and tell Claude",
+];
+/** Strip CSI / common ANSI escape sequences so prompt markers match the plain text (e-gate probe). */
+function stripAnsiText(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, "");
+}
+/** True iff any native-prompt marker appears in `text` (after ANSI stripping). */
+export function textShowsNativePrompt(text) {
+    const stripped = stripAnsiText(text);
+    return NATIVE_PERMISSION_PROMPT_MARKERS.some((m) => stripped.includes(m));
+}
+/** 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 const DEFAULT_CORRELATION_WAIT_MS = 5000;
+/** Default poll interval for the correlation wait (ms). */
+export 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 const DEFAULT_PROMPT_APPEAR_MS = 1500;
+/** Default poll interval for the sweep's appear/clear phases (ms). */
+export const DEFAULT_PROMPT_POLL_MS = 100;
+/** Default budget for the keystroke to clear the prompt before the stuck warning (ms). */
+export 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 const DEFAULT_CLOSE_TIMEOUT_MS = 2000;
+/** Cap on the retained rolling tail of recent PTY output (chars) for the prompt probe. */
+const OUTPUT_TAIL_CAP = 16384;
+/** Filename prefix of the per-session scratch settings file (diagnosable in `ls /tmp`). */
+export const SCRATCH_SETTINGS_PREFIX = "fork-acp-gate-settings-";
+const defaultSchedule = (fn, ms) => {
+    setTimeout(fn, ms);
+};
+/** Internal mutable state of one session's gate. */
+class SessionGateImpl {
+    constructor(opts) {
+        this.opts = opts;
+        this.port = 0;
+        this.settingsPath = "";
+        this.correlator = new ToolUseCorrelator();
+        /** Rolling tail of recent PTY output + absolute count of chars ever appended (probe offsets). */
+        this.outputTail = "";
+        this.totalOutput = 0;
+        this.torndown = false;
+    }
+    get isTorndown() {
+        return this.torndown;
+    }
+    warn(message) {
+        this.opts.onWarn?.(message);
+    }
+    get schedule() {
+        return this.opts.schedule ?? defaultSchedule;
+    }
+    /** Start the hook server, then write the scratch settings (server first, so the URL the settings
+     *  point at is live before claude can ever read them; settings BEFORE the spawn is the caller's
+     *  ordering contract — blocker c). */
+    async start() {
+        const findPort = this.opts.findPort ?? findFreePort;
+        this.port = await findPort();
+        this.server = await startHookServer({
+            port: this.port,
+            deciderTimeoutMs: this.opts.deciderTimeoutMs,
+            onWarn: (m) => this.warn(m),
+            onToolCall: (call) => this.decide(call),
+        });
+        const dir = this.opts.settingsDir ?? os.tmpdir();
+        this.settingsPath = path.join(dir, `${SCRATCH_SETTINGS_PREFIX}${randomUUID()}.json`);
+        try {
+            this.backup = await injectHook({
+                settingsPath: this.settingsPath,
+                port: this.port,
+                timeout: this.opts.hookTimeoutSeconds,
+            });
+        }
+        catch (err) {
+            // The settings write failed AFTER the server bound — close it before surfacing, so a failed
+            // gate setup leaks nothing (the caller aborts createSession; FORK_GATE=off is the escape hatch).
+            await this.closeServerBounded();
+            throw err;
+        }
+    }
+    bindSession(sessionId, nudge) {
+        this.sessionId = sessionId;
+        this.nudge = nudge;
+    }
+    bindPty(pty) {
+        this.pty = pty;
+        if (typeof pty.onData === "function") {
+            this.outputTap = pty.onData((data) => {
+                this.totalOutput += data.length;
+                this.outputTail = (this.outputTail + data).slice(-OUTPUT_TAIL_CAP);
+            });
+        }
+    }
+    /** Bytes received after the absolute output offset `mark` (clipped to the retained tail). */
+    outputSince(mark) {
+        const available = Math.min(this.outputTail.length, Math.max(0, this.totalOutput - mark));
+        return available === 0 ? "" : this.outputTail.slice(-available);
+    }
+    /**
+     * The REAL decider chain (the hook→ACP connection): nudge the pump → bounded-wait for the JSONL
+     * `tool_use.id` correlation → raise ACP `session/request_permission` (story 033, fail-closed) →
+     * on `allow`, arm the #52822 native-prompt sweep. Every deny path is request-permission's own.
+     */
+    async decide(call) {
+        if (this.torndown)
+            return "deny"; // a hook racing teardown is never approved
+        // Kick the pump so the freshest JSONL (carrying this call's `tool_use` line) is re-read NOW.
+        try {
+            this.nudge?.();
+        }
+        catch {
+            // a nudge failure only widens the correlation wait below; never approves/denies by itself
+        }
+        const sessionId = this.sessionId ?? call.sessionId;
+        if (!sessionId) {
+            this.warn(`[gate §9] FAIL CLOSED: PreToolUse for tool_use ${call.toolUseId} arrived before the gate ` +
+                `was bound to an ACP session — denying (cannot raise session/request_permission).`);
+            return "deny";
+        }
+        await this.waitForCorrelation(call.toolUseId);
+        const decision = await requestPermission({
+            client: this.opts.client,
+            sessionId,
+            toolCall: {
+                toolUseId: call.toolUseId,
+                toolName: call.toolName,
+                toolInput: call.toolInput,
+            },
+            correlator: this.correlator,
+            onWarn: (m) => this.warn(m),
+        });
+        if (decision === "allow") {
+            // Return the allow body FIRST (claude is blocked on this response); sweep out of band.
+            this.armAllowSweep(call);
+        }
+        return decision;
+    }
+    /** Bounded poll until the pump has registered `toolUseId` as a clean single JSONL match. On
+     *  expiry, resolve anyway — `requestPermission` then fails closed on the missing correlation. */
+    waitForCorrelation(toolUseId) {
+        const waitMs = this.opts.correlationWaitMs ?? DEFAULT_CORRELATION_WAIT_MS;
+        const pollMs = this.opts.correlationPollMs ?? DEFAULT_CORRELATION_POLL_MS;
+        if (this.correlator.isCleanMatch(toolUseId))
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            let elapsed = 0;
+            const poll = () => {
+                if (this.torndown || this.correlator.isCleanMatch(toolUseId)) {
+                    resolve();
+                    return;
+                }
+                elapsed += pollMs;
+                if (elapsed >= waitMs) {
+                    this.warn(`[gate §9] correlation wait expired (${waitMs}ms) for tool_use ${toolUseId} — the JSONL ` +
+                        `tool_use line never reached the pump; the decision will fail closed (deny).`);
+                    resolve();
+                    return;
+                }
+                this.schedule(poll, pollMs);
+            };
+            this.schedule(poll, pollMs);
+        });
+    }
+    /**
+     * #52822 sweep (allow path, best-effort by design): wait a bounded window for the native TUI
+     * prompt to APPEAR in the post-decision PTY output; if it never renders, allow-suppression held
+     * (the 2.1.161 case) and nothing is typed. If it renders, clear it via the story-033
+     * `clearNativePrompt` — the `'1\r'` keystroke goes RAW through `pty.write` (never `sendPrompt`,
+     * whose leading Ctrl+U clear byte must not touch a pending dialog). On a stuck prompt it WARNS
+     * and holds — never a silent approve (R3.2).
+     *
+     * Post-keystroke probe semantics (honest limits): the prompt counts as CLEARED only when NEW
+     * output arrives after the keystroke and carries no prompt marker (the TUI re-rendered past the
+     * dialog). Zero new output ⇒ still shown ⇒ the stuck warning fires at the timeout. A re-rendered
+     * marker ⇒ still shown. This is a byte-stream heuristic over the Degrau-0 markers — the live
+     * fidelity check is story 034's acceptance run.
+     */
+    armAllowSweep(call) {
+        const pty = this.pty;
+        if (!pty) {
+            this.warn(`[gate §9] allow for tool_use ${call.toolUseId}: no PTY bound — cannot run the #52822 ` +
+                `keystroke sweep; if the native prompt appears it needs a manual keystroke.`);
+            return;
+        }
+        const appearMs = this.opts.promptAppearMs ?? DEFAULT_PROMPT_APPEAR_MS;
+        const pollMs = this.opts.promptPollMs ?? DEFAULT_PROMPT_POLL_MS;
+        const appearMark = this.totalOutput; // only output AFTER the allow decision is scanned
+        let elapsed = 0;
+        const pollAppear = () => {
+            if (this.torndown)
+                return;
+            if (textShowsNativePrompt(this.outputSince(appearMark))) {
+                void this.runClear(call, pty);
+                return;
+            }
+            elapsed += pollMs;
+            if (elapsed >= appearMs)
+                return; // suppressed (the 2.1.161 case) — nothing to clear
+            this.schedule(pollAppear, pollMs);
+        };
+        this.schedule(pollAppear, pollMs);
+    }
+    /** Drive the story-033 keystroke injection against the live output probe (see armAllowSweep). */
+    async runClear(call, pty) {
+        let keystrokeMark = null;
+        const isPromptShown = () => {
+            if (keystrokeMark === null) {
+                // First probe (pre-keystroke): the appear-poll already proved the prompt is up. Mark the
+                // output offset so the post-keystroke probes scan only the TUI's REACTION to the keystroke.
+                keystrokeMark = this.totalOutput;
+                return true;
+            }
+            if (this.totalOutput === keystrokeMark)
+                return true; // TUI has not reacted yet — still shown
+            return textShowsNativePrompt(this.outputSince(keystrokeMark));
+        };
+        const result = await clearNativePrompt({
+            pty,
+            decision: "allow",
+            isPromptShown,
+            timeoutMs: this.opts.injectTimeoutMs ?? DEFAULT_INJECT_TIMEOUT_MS,
+            pollMs: this.opts.promptPollMs ?? DEFAULT_PROMPT_POLL_MS,
+            schedule: this.schedule,
+            onWarn: (m) => this.warn(m),
+        });
+        if (result.status === "stuck") {
+            // clearNativePrompt already warned; name the tool here for the session log's correlation.
+            this.warn(`[gate §9] STUCK PROMPT for tool_use ${call.toolUseId} (tool "${call.toolName}") — the ` +
+                `allow keystroke did not clear the native prompt; holding (no silent approve).`);
+        }
+    }
+    /** Close the hook server with a bounded wait so teardown never hangs on an in-flight request. */
+    async closeServerBounded() {
+        const server = this.server;
+        this.server = undefined;
+        if (!server)
+            return;
+        const closeTimeoutMs = this.opts.closeTimeoutMs ?? DEFAULT_CLOSE_TIMEOUT_MS;
+        let timedOut = false;
+        await Promise.race([
+            server.close(),
+            new Promise((resolve) => this.schedule(() => {
+                timedOut = true;
+                resolve();
+            }, closeTimeoutMs)),
+        ]);
+        if (timedOut) {
+            this.warn(`[gate §9] hook server on 127.0.0.1:${this.port} did not close within ${closeTimeoutMs}ms ` +
+                `(an in-flight decider may be holding a request open); teardown proceeds — the close ` +
+                `completes in the background.`);
+        }
+    }
+    async teardown() {
+        if (this.torndown)
+            return;
+        this.torndown = true;
+        this.outputTap?.dispose();
+        this.outputTap = undefined;
+        await this.closeServerBounded();
+        const backup = this.backup;
+        this.backup = undefined;
+        if (backup) {
+            try {
+                await restore(backup); // scratch was created by injectHook (existed:false) → deleted here
+            }
+            catch (err) {
+                this.warn(`[gate §9] scratch settings restore failed for ${backup.settingsPath} ` +
+                    `(${err instanceof Error ? err.message : String(err)}) — the file may need manual removal.`);
+            }
+        }
+    }
+}
+/**
+ * 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 async function setupSessionGate(opts) {
+    const gate = new SessionGateImpl(opts);
+    await gate.start();
+    return gate;
+}

package/dist/permissions/hook-server.d.ts

@@ -0,0 +1,72 @@
+import { type Server } from "node:http";
+/** The §9 `PreToolUse` http payload shape (GATE_FINDINGS keystone 1.3). All fields optional on parse
+ *  so a malformed body fails closed rather than throwing — a missing tool_use_id is itself a deny. */
+export interface PreToolUsePayload {
+    session_id?: string;
+    transcript_path?: string;
+    cwd?: string;
+    permission_mode?: string;
+    hook_event_name?: string;
+    tool_name?: string;
+    tool_input?: unknown;
+    tool_use_id?: string;
+}
+/** The normalized tool call forwarded to the decider (camelCase, the shape request-permission uses). */
+export interface ForwardedToolCall {
+    toolName: string;
+    toolInput: unknown;
+    toolUseId: string;
+    sessionId?: string;
+    permissionMode?: string;
+}
+/** The decider the server forwards each tool call to; returns the enforced `'allow'`/`'deny'`. */
+export type ToolCallDecider = (call: ForwardedToolCall) => Promise<"allow" | "deny"> | "allow" | "deny";
+/** The running hook server handle. */
+export interface HookServer {
+    /** The loopback port the server bound (feeds the story-032 hook URL). */
+    port: number;
+    /** Register/replace the decider invoked per PreToolUse call. */
+    onToolCall(decider: ToolCallDecider): void;
+    /** Idempotently close the server. */
+    close(): Promise<void>;
+}
+/** Options for {@link startHookServer}. */
+export interface StartHookServerOptions {
+    /** The verified-free loopback port (story-032 `findFreePort`). */
+    port: number;
+    /** Initial decider (may also be set later via {@link HookServer.onToolCall}). */
+    onToolCall?: ToolCallDecider;
+    /**
+     * Max ms to await the decider before failing closed (deny). DISTINCT from the 5583 ms turn watchdog
+     * (story 024) and the claude hook timeout (story 032, 600 s) — this is the server's own
+     * never-hang-the-request budget. Defaults to a conservative value.
+     */
+    deciderTimeoutMs?: number;
+    /** Injectable http-server factory (defaults to `node:http`'s `createServer`); for tests. */
+    createHttpServer?: () => Server;
+    /** Optional diagnostics sink for fail-closed events (defaults to no-op). */
+    onWarn?: (message: string) => void;
+}
+/** Default decider timeout (ms) — long enough for an async Zed decision relay, short of a hang. */
+export declare const DEFAULT_DECIDER_TIMEOUT_MS = 600000;
+/**
+ * Parse a PreToolUse payload from raw JSON, normalizing to {@link ForwardedToolCall}. Returns null when
+ * the body is unparseable OR lacks a `tool_use_id`/`tool_name` — the caller fails closed on null (a
+ * call we cannot identify is denied, never approved).
+ */
+export declare function parsePayload(raw: string): ForwardedToolCall | null;
+/**
+ * Bind a loopback `PreToolUse` http hook server on `port` and forward each tool call to the decider,
+ * FAILING CLOSED on every error path (R2.1, R2.4).
+ *
+ * The server binds {@link LOOPBACK_HOST} (127.0.0.1) ONLY — never `0.0.0.0` — matching the blocker-b
+ * constraint that the transport is loopback TCP. Each request body is parsed by {@link parsePayload};
+ * a malformed/identity-less payload, a decider timeout, or a decider throw all write a
+ * `permissionDecision:'deny'` body so the tool never runs ungated. A clean `'allow'` writes the allow
+ * body (the keystroke mitigation for #52822 is a separate allow-inject.ts concern).
+ *
+ * @returns a {@link HookServer} once the socket is bound (rejects on a bind error — the spawn path then
+ *   fails fast rather than spawning claude with an ungated hook URL).
+ */
+export declare function startHookServer(opts: StartHookServerOptions): Promise<HookServer>;
+//# sourceMappingURL=hook-server.d.ts.map

package/dist/permissions/hook-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-server.d.ts","sourceRoot":"","sources":["../../src/permissions/hook-server.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAsC,KAAK,MAAM,EAAuB,MAAM,WAAW,CAAC;AAIjG;sGACsG;AACtG,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wGAAwG;AACxG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,kGAAkG;AAClG,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,GAAG,OAAO,GAAG,MAAM,CAAC;AAExG,sCAAsC;AACtC,MAAM,WAAW,UAAU;IACzB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IAC3C,qCAAqC;IACrC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4FAA4F;IAC5F,gBAAgB,CAAC,EAAE,MAAM,MAAM,CAAC;IAChC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED,mGAAmG;AACnG,eAAO,MAAM,0BAA0B,SAAU,CAAC;AAsBlD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAyBlE;AAiCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC,CAkFjF"}

package/dist/permissions/hook-server.js

@@ -0,0 +1,179 @@
+// Story 033 / Task 2.1 — loopback PreToolUse http hook server that forwards tool calls over IPC and
+// FAILS CLOSED on any transport/timeout error (R2.1, R2.4).
+//
+// BINDING Degrau-0 constraint (experiments/GATE_FINDINGS.md blocker b): the `PreToolUse` type:http
+// hook is TCP-LOOPBACK ONLY — a unix-socket URL form is silently ignored AND the tool runs ungated. So
+// this server MUST bind `127.0.0.1` (loopback) on the story-032 `findFreePort` port, and MUST fail
+// closed (respond `permissionDecision:'deny'`) on a malformed payload, a missing decision, or a decider
+// timeout — never leave a tool ungated by returning nothing or throwing out of the request handler.
+//
+// WIRING (IMPLEMENTACAO-FORK-ACP.md §9): claude POSTs the `PreToolUse` payload to
+// `http://127.0.0.1:<port>/__fork-acp-gate__` (the story-032 hook URL) BEFORE the tool runs; the server
+// parses `{session_id, transcript_path, cwd, permission_mode, hook_event_name, tool_name, tool_input,
+// tool_use_id}`, forwards `{toolName, toolInput, toolUseId, …}` to the injected `onToolCall` decider
+// (which correlates by tool_use.id + raises ACP session/request_permission — request-permission.ts),
+// and writes the decision body back. The decider is INJECTED so the server is unit-testable OFFLINE.
+//
+// The hook is injected into the TUI via `--settings <scratchFile>` (story 032 injectHook), never the
+// user's real config — that wiring is the engine-integration concern; this module is the standalone
+// server seam.
+import { createServer } from "node:http";
+import { LOOPBACK_HOST } from "../gate/port.js";
+import { allowDecision, denyDecision } from "./deny.js";
+/** Default decider timeout (ms) — long enough for an async Zed decision relay, short of a hang. */
+export const DEFAULT_DECIDER_TIMEOUT_MS = 600_000;
+/** Read a request body fully into a UTF-8 string (bounded by Node's own socket limits). */
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let body = "";
+        req.setEncoding("utf8");
+        req.on("data", (chunk) => {
+            body += chunk;
+        });
+        req.on("end", () => resolve(body));
+        req.on("error", reject);
+    });
+}
+/** Write a decision body as the http JSON response (always 200 — the body carries the decision). */
+function writeDecision(res, decision) {
+    const json = JSON.stringify(decision);
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(json);
+}
+/**
+ * Parse a PreToolUse payload from raw JSON, normalizing to {@link ForwardedToolCall}. Returns null when
+ * the body is unparseable OR lacks a `tool_use_id`/`tool_name` — the caller fails closed on null (a
+ * call we cannot identify is denied, never approved).
+ */
+export function parsePayload(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== "object") {
+        return null;
+    }
+    const toolUseId = parsed.tool_use_id;
+    const toolName = parsed.tool_name;
+    if (typeof toolUseId !== "string" || toolUseId.length === 0) {
+        return null;
+    }
+    if (typeof toolName !== "string" || toolName.length === 0) {
+        return null;
+    }
+    return {
+        toolName,
+        toolInput: parsed.tool_input,
+        toolUseId,
+        sessionId: typeof parsed.session_id === "string" ? parsed.session_id : undefined,
+        permissionMode: typeof parsed.permission_mode === "string" ? parsed.permission_mode : undefined,
+    };
+}
+/** Run the decider with a timeout; on timeout or throw, resolve `'deny'` (fail closed). */
+async function decideWithTimeout(decider, call, timeoutMs, onWarn) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            onWarn?.(`[gate §9] FAIL CLOSED: decider timed out after ${timeoutMs}ms for tool_use ` +
+                `${call.toolUseId} (tool "${call.toolName}") — denying.`);
+            resolve("deny");
+        }, timeoutMs);
+    });
+    try {
+        const decided = await Promise.race([Promise.resolve(decider(call)), timeout]);
+        return decided;
+    }
+    catch (err) {
+        onWarn?.(`[gate §9] FAIL CLOSED: decider threw for tool_use ${call.toolUseId} ` +
+            `(${err instanceof Error ? err.message : String(err)}) — denying.`);
+        return "deny";
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Bind a loopback `PreToolUse` http hook server on `port` and forward each tool call to the decider,
+ * FAILING CLOSED on every error path (R2.1, R2.4).
+ *
+ * The server binds {@link LOOPBACK_HOST} (127.0.0.1) ONLY — never `0.0.0.0` — matching the blocker-b
+ * constraint that the transport is loopback TCP. Each request body is parsed by {@link parsePayload};
+ * a malformed/identity-less payload, a decider timeout, or a decider throw all write a
+ * `permissionDecision:'deny'` body so the tool never runs ungated. A clean `'allow'` writes the allow
+ * body (the keystroke mitigation for #52822 is a separate allow-inject.ts concern).
+ *
+ * @returns a {@link HookServer} once the socket is bound (rejects on a bind error — the spawn path then
+ *   fails fast rather than spawning claude with an ungated hook URL).
+ */
+export function startHookServer(opts) {
+    const { port, deciderTimeoutMs = DEFAULT_DECIDER_TIMEOUT_MS, createHttpServer = createServer, onWarn, } = opts;
+    let decider = opts.onToolCall;
+    const server = createHttpServer();
+    server.on("request", (req, res) => {
+        void (async () => {
+            // The tool name is unknown until the body parses; default the fail-closed deny target.
+            let call = null;
+            try {
+                const raw = await readBody(req);
+                call = parsePayload(raw);
+                if (call === null) {
+                    onWarn?.(`[gate §9] FAIL CLOSED: unparseable or identity-less PreToolUse payload — denying.`);
+                    // No tool identity: still respond deny so claude intercepts rather than running ungated.
+                    writeDecision(res, denyDecision({ toolName: "(unknown)", toolUseId: "(unknown)" }));
+                    return;
+                }
+                if (decider === undefined) {
+                    onWarn?.(`[gate §9] FAIL CLOSED: no decider registered for tool_use ${call.toolUseId} — denying.`);
+                    writeDecision(res, denyDecision(call));
+                    return;
+                }
+                const decision = await decideWithTimeout(decider, call, deciderTimeoutMs, onWarn);
+                writeDecision(res, decision === "allow" ? allowDecision(call) : denyDecision(call));
+            }
+            catch (err) {
+                // Any unexpected handler error (body read failure, write failure) → fail closed.
+                onWarn?.(`[gate §9] FAIL CLOSED: hook request handler error ` +
+                    `(${err instanceof Error ? err.message : String(err)}) — denying.`);
+                try {
+                    writeDecision(res, denyDecision(call ?? { toolName: "(unknown)", toolUseId: "(unknown)" }));
+                }
+                catch {
+                    // The response may already be partially sent; nothing else to do but not crash the server.
+                }
+            }
+        })();
+    });
+    return new Promise((resolve, reject) => {
+        const onError = (err) => {
+            server.removeListener("listening", onListening);
+            reject(err);
+        };
+        const onListening = () => {
+            server.removeListener("error", onError);
+            resolve({
+                port,
+                onToolCall(next) {
+                    decider = next;
+                },
+                close() {
+                    return new Promise((res) => {
+                        try {
+                            server.close(() => res());
+                        }
+                        catch {
+                            res();
+                        }
+                    });
+                },
+            });
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        // LOOPBACK ONLY (blocker b) — bind 127.0.0.1, never 0.0.0.0.
+        server.listen(port, LOOPBACK_HOST);
+    });
+}

package/dist/permissions/permission-mode.d.ts

@@ -0,0 +1,67 @@
+import { type GuardHooks, type WatchedMessage } from "../billing/entrypoint-guard.js";
+/** The two auto-approve permission modes the alternative supports (§9). */
+export type AltPermissionMode = "acceptEdits" | "bypassPermissions";
+/**
+ * Build the `--permission-mode <mode>` spawn flag fragment for the alternative (R4.1). Returns the two
+ * argv tokens; the spawn path appends them to the interactive `claude` argv. NOTE: this flag changes
+ * only how the TUI PROMPTS — it does NOT add `-p`/`stream-json` and therefore does NOT change billing.
+ *
+ * @param mode `acceptEdits` (the safe default) or `bypassPermissions`.
+ * @returns the argv tokens `['--permission-mode', mode]`.
+ * @throws {Error} on an unrecognized mode (never silently fall through to a non-gating flag).
+ */
+export declare function permissionModeFlag(mode: AltPermissionMode): [string, string];
+/**
+ * The DENY-ONLY policy for the alternative: the set of dangerous tools (or matchers) the hook denies
+ * while everything else auto-approves in the TUI. Kept as a caller-supplied list so the dangerous set
+ * is an explicit, reviewable decision (not a hidden default). The matcher uses the same exact/`"*"`
+ * convention as the §9 settings matcher.
+ */
+export interface DenyOnlyPolicy {
+    /** Tool names (or `"*"`) the hook DENIES; everything not listed auto-approves. */
+    denyMatchers: string[];
+}
+/**
+ * Decide whether the deny-only hook should DENY this tool (R4.1). Returns true iff the tool matches a
+ * deny matcher (exact name or `"*"`); otherwise the tool is allowed to auto-approve in the TUI.
+ *
+ * @param policy the deny-only policy (the dangerous-tool matchers).
+ * @param toolName the tool from the hook payload.
+ * @returns true → the hook denies this tool; false → auto-approve.
+ */
+export declare function denyOnlyShouldDeny(policy: DenyOnlyPolicy, toolName: string): boolean;
+/**
+ * Re-assert the story-022 billing guard-rail (§10) for one observed message under the alternative mode
+ * (R4.2). This is the SAME guard-rail the read-only pump runs — re-asserted here so enabling
+ * auto-approve does NOT weaken billing. Delegates to {@link guardEvent} (it never re-derives the class
+ * and never mutates/spoofs `entrypoint`): on a `sdk-*`/`print` (or unknown) label it alerts + stops the
+ * session via the injected hooks; on `cli` it is a silent no-op.
+ *
+ * @param event one watched message event (the story-015 watcher shape).
+ * @param hooks the alert/stop sink (wired to the engine-lifecycle stop in production).
+ * @returns the guard decision (`allow`/`abort`/`skip`) so the caller can branch.
+ */
+export declare function reassertBillingGuard(event: WatchedMessage, hooks: GuardHooks): import("../billing/entrypoint-guard.js").GuardDecision;
+/** Result of {@link assertEntrypointCli}: the session may proceed, or it must abort (credit-class). */
+export type EntrypointAssertion = {
+    ok: true;
+    entrypoint: string;
+} | {
+    ok: false;
+    entrypoint: string;
+    reason: string;
+};
+/**
+ * Convenience post-spawn assertion (R4.2): given the FIRST observed billing message's entrypoint
+ * self-label, decide whether the alternative-mode session may proceed. ABORTS (`ok:false`) on anything
+ * that is not the subscription `cli` label, naming the observed entrypoint in the reason — never
+ * proceeds on a `sdk-*`/`print` label and never spoofs the value toward `cli`.
+ *
+ * This is a thin, pure wrapper over {@link guardEvent} for the spawn path that wants a boolean rather
+ * than the hook side-effects; the side-effecting {@link reassertBillingGuard} is used by the live pump.
+ *
+ * @param event the first observed `assistant`/`user` event under the alternative mode.
+ * @returns `{ ok:true, entrypoint }` for `cli`; `{ ok:false, entrypoint, reason }` otherwise.
+ */
+export declare function assertEntrypointCli(event: WatchedMessage): EntrypointAssertion;
+//# sourceMappingURL=permission-mode.d.ts.map