@squadrant-ai/auto-gate 0.1.0

package/dist/adapters/opencode/sse.js

@@ -0,0 +1,29 @@
+/** Pure. Unknown / heartbeat / non-JSON frames return null (the caller ignores
+ *  them). Live-verified shape (opencode 1.15.13): permission.asked properties =
+ *  { id:"per_…", sessionID:"ses_…", permission:"bash", patterns:[cmd] }. */
+export function parseSseFrame(raw) {
+    const line = raw.startsWith("data:") ? raw.slice(5).trim() : raw.trim();
+    if (!line || line === "[DONE]")
+        return null;
+    let j;
+    try {
+        j = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    const p = j.properties ?? {};
+    if (j.type === "permission.asked" && typeof p.id === "string" && typeof p.sessionID === "string") {
+        return { kind: "permission.asked", id: p.id, sessionID: p.sessionID,
+            permission: typeof p.permission === "string" ? p.permission : "a tool",
+            patterns: Array.isArray(p.patterns) ? p.patterns.map(String) : [] };
+    }
+    if (j.type === "permission.replied" && typeof p.id === "string")
+        return { kind: "permission.replied", id: p.id };
+    const part = p.part;
+    if ((j.type === "message.part.updated" || j.type === "message.updated") &&
+        p.role === "user" && part?.type === "text" && typeof part.text === "string" && typeof p.sessionID === "string") {
+        return { kind: "user-text", sessionID: p.sessionID, text: part.text };
+    }
+    return null;
+}

package/dist/adapters/opencode/watch.d.ts

@@ -0,0 +1,43 @@
+import type { GateOutcome, GateRequest } from "../../core/types.js";
+export interface WatcherDeps {
+    host: string;
+    port: number;
+    acquire(): {
+        ok: boolean;
+        release?(): void;
+    };
+    subscribe(url: string, onFrame: (line: string) => void | Promise<void>): Promise<() => void>;
+    decide(req: GateRequest): Promise<GateOutcome>;
+    answer(a: {
+        sessionID: string;
+        permissionID: string;
+        response: "once" | "reject";
+    }): Promise<void>;
+    log?: (m: string) => void;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    bootDeadlineMs?: number;
+}
+export interface Watcher {
+    /** Resolves once the watcher has settled into its steady state (or given up). */
+    start(): Promise<"yielded" | "unrecoverable" | "running">;
+    /** Ask the watcher to release its lock and tear down its subscription. */
+    stop(): void;
+    /** Resolves when the watcher has stopped (by `stop()` or a terminal outcome). */
+    stopped: Promise<void>;
+}
+/** The ONE client allowed to answer permissions for this server (§15 #7). The
+ *  loser yields permanently — it never loops, never fights the owner. */
+export declare function createWatcher(d: WatcherDeps): Watcher;
+/** Real SSE subscription over fetch — used only by the CLI, never in tests (the
+ *  watcher takes `subscribe` as a dep so every behaviour is unit-tested with a
+ *  fake). Resolves to a teardown that aborts the request. */
+export declare function subscribeSse(url: string, onFrame: (line: string) => void | Promise<void>): Promise<() => void>;
+/** Real answer POST over fetch — CLI only, as above. */
+export declare function answerPermission(o: {
+    host: string;
+    port: number;
+    sessionID: string;
+    permissionID: string;
+    response: "once" | "reject";
+}): Promise<void>;

package/dist/adapters/opencode/watch.js

@@ -0,0 +1,138 @@
+import { parseSseFrame } from "./sse.js";
+import { reconstructIntent } from "./intent.js";
+import { answerFor } from "./answer.js";
+const BACKOFF_BASE_MS = 500;
+const BACKOFF_CAP_MS = 30_000;
+/** The ONE client allowed to answer permissions for this server (§15 #7). The
+ *  loser yields permanently — it never loops, never fights the owner. */
+export function createWatcher(d) {
+    const now = d.now ?? Date.now;
+    const sleep = d.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const deadline = d.bootDeadlineMs ?? 120_000;
+    let release;
+    let unsubscribe;
+    let resolveStopped = () => { };
+    const stopped = new Promise((r) => { resolveStopped = r; });
+    let finished = false;
+    function finish() {
+        if (finished)
+            return;
+        finished = true;
+        try {
+            unsubscribe?.();
+        }
+        catch { /* already gone */ }
+        try {
+            release?.();
+        }
+        catch { /* already gone */ }
+        resolveStopped();
+    }
+    async function onFrame(line, history) {
+        const ev = parseSseFrame(line);
+        if (!ev)
+            return;
+        history.push(ev);
+        if (history.length > 200)
+            history.shift();
+        if (ev.kind !== "permission.asked")
+            return;
+        const intent = reconstructIntent(ev.sessionID, history);
+        const req = {
+            agent: "opencode",
+            toolName: ev.permission,
+            toolPayload: ev.patterns.join(" "),
+            // D3: `permission.asked` carries NO cwd, so we cannot derive scope here.
+            // Keep "" rather than add an endpoint/dep; opencode `scope_escape` fidelity
+            // is therefore LOWER than claude's (documented in the PR body).
+            cwd: "",
+            ...(intent.text ? { userIntent: intent.text } : {}),
+            intentSupport: intent.support,
+            sessionKind: "standalone",
+            raw: { sessionID: ev.sessionID, permID: ev.id },
+        };
+        const outcome = await d.decide(req);
+        const response = answerFor(outcome);
+        if (response)
+            await d.answer({ sessionID: ev.sessionID, permissionID: ev.id, response });
+        else
+            d.log?.(`auto-gate opencode: leaving ${ev.id} pending (${outcome.decision}) — needs a human`);
+    }
+    return {
+        stopped,
+        async start() {
+            const lock = d.acquire();
+            if (!lock.ok) {
+                d.log?.(`auto-gate opencode: another client owns ${d.host}:${d.port} — observing only (§15#7)`);
+                finish();
+                return "yielded";
+            }
+            release = lock.release;
+            const history = [];
+            const started = now();
+            let backoff = BACKOFF_BASE_MS;
+            for (;;) {
+                try {
+                    unsubscribe = await d.subscribe(`http://${d.host}:${d.port}/event`, (line) => onFrame(line, history));
+                    return "running";
+                }
+                catch (e) {
+                    if (now() - started >= deadline) {
+                        d.log?.(`auto-gate opencode: unrecoverable after ${deadline}ms — ${e.message}`);
+                        finish();
+                        return "unrecoverable";
+                    }
+                    d.log?.(`auto-gate opencode: subscribe failed (${e.message}); retry in ${backoff}ms`);
+                    await sleep(backoff);
+                    backoff = Math.min(backoff * 2, BACKOFF_CAP_MS);
+                }
+            }
+        },
+        stop() { finish(); },
+    };
+}
+/** Real SSE subscription over fetch — used only by the CLI, never in tests (the
+ *  watcher takes `subscribe` as a dep so every behaviour is unit-tested with a
+ *  fake). Resolves to a teardown that aborts the request. */
+export async function subscribeSse(url, onFrame) {
+    const ctrl = new AbortController();
+    const res = await fetch(url, { headers: { accept: "text/event-stream" }, signal: ctrl.signal });
+    if (!res.ok || !res.body)
+        throw new Error(`SSE connect failed: ${res.status}`);
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    void (async () => {
+        try {
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                buf += decoder.decode(value, { stream: true });
+                let idx;
+                while ((idx = buf.indexOf("\n\n")) >= 0) {
+                    const chunk = buf.slice(0, idx);
+                    buf = buf.slice(idx + 2);
+                    for (const line of chunk.split("\n")) {
+                        const t = line.trim();
+                        if (t.startsWith("data:"))
+                            await onFrame(t);
+                    }
+                }
+            }
+        }
+        catch { /* stream aborted/closed */ }
+    })();
+    return () => ctrl.abort();
+}
+/** Real answer POST over fetch — CLI only, as above. */
+export async function answerPermission(o) {
+    const url = `http://${o.host}:${o.port}/session/${o.sessionID}/permissions/${o.permissionID}`;
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ response: o.response }),
+    });
+    if (!res.ok)
+        throw new Error(`permission answer failed: ${res.status}`);
+}

package/dist/classifiers/battery.d.ts

@@ -0,0 +1,26 @@
+import type { GateRequest } from "../core/types.js";
+import { redact } from "../core/redact.js";
+export interface ChoiceQuestion {
+    type: "choice";
+    instructions: string;
+    criteria: Record<string, string>;
+}
+export interface NoulQuestion {
+    type: "noul";
+    instructions: string;
+    criteria?: {
+        true: string;
+        false: string;
+    };
+}
+export interface ScoreQuestion {
+    type: "score";
+    instructions: string;
+    criteria: string[];
+}
+export type Question = ChoiceQuestion | NoulQuestion | ScoreQuestion;
+/** One request, all questions parallel (§6.3). intent_match is omitted when the
+ *  adapter declares intent permanently unavailable (§6.2.1). */
+export declare function buildQuestions(req: GateRequest): Record<string, Question>;
+/** Kept beside the battery so both redact identically. Exported for reuse. */
+export { redact };

package/dist/classifiers/battery.js

@@ -0,0 +1,27 @@
+import { redact } from "../core/redact.js";
+const DECISION = {
+    type: "choice",
+    instructions: "Decide whether the agent may run this action, given the user's stated intent.",
+    criteria: {
+        allow: "Safe, ordinary software-development work in service of the user's stated intent; reversible; touches no secrets; no system/home-config writes.",
+        deny: "Destructive, irreversible, credential-exfiltrating, or system-damaging; or clearly outside the user's stated intent.",
+        ask: "Genuinely ambiguous, or the state does not contain enough to decide.",
+    },
+};
+/** One request, all questions parallel (§6.3). intent_match is omitted when the
+ *  adapter declares intent permanently unavailable (§6.2.1). */
+export function buildQuestions(req) {
+    const q = {
+        decision: DECISION,
+        destructive: { type: "noul", instructions: "Would this action be destructive, irreversible, or hard to undo?" },
+        secrets: { type: "noul", instructions: "Does this action read, write, or transmit credentials, keys, or secrets?" },
+        scope_escape: { type: "noul", instructions: "Does this action touch paths outside the working directory (system paths, other repositories, home configuration)?" },
+        severity: { type: "score", instructions: "How much harm if this runs?", criteria: ["none", "mild", "serious", "severe"] },
+    };
+    if (req.intentSupport !== "unsupported") {
+        q.intent_match = { type: "noul", instructions: "Is this action plausibly in service of the user's stated intent?" };
+    }
+    return q;
+}
+/** Kept beside the battery so both redact identically. Exported for reuse. */
+export { redact };

package/dist/classifiers/classify.d.ts

@@ -0,0 +1,15 @@
+import type { GateAssessment, GateRequest } from "../core/types.js";
+export interface Classifier {
+    id: string;
+    model?: string;
+    classify(req: GateRequest): Promise<GateAssessment>;
+}
+export interface ClassifyConfig {
+    kind: "jev" | "generative";
+    primary: Classifier;
+    fallback?: Classifier;
+}
+/** Jev first (unless kind==='generative'), then the fallback, else ask (§4, §8).
+ *  The fallback is a safety net: §7 only honours its verdict when
+ *  fallbackAcceptsVerdict is true, so reaching it never weakens the gate. */
+export declare function classify(req: GateRequest, cfg: ClassifyConfig): Promise<GateAssessment>;

package/dist/classifiers/classify.js

@@ -0,0 +1,25 @@
+async function safe(c, req) {
+    try {
+        const a = await c.classify(req);
+        if (!a || typeof a.verdict !== "string")
+            throw new Error("malformed assessment");
+        return a;
+    }
+    catch {
+        return { verdict: "ask", classifier: `${c.id}-error`, tier: 2 };
+    }
+}
+/** Jev first (unless kind==='generative'), then the fallback, else ask (§4, §8).
+ *  The fallback is a safety net: §7 only honours its verdict when
+ *  fallbackAcceptsVerdict is true, so reaching it never weakens the gate. */
+export async function classify(req, cfg) {
+    const first = cfg.kind === "jev" ? cfg.primary : cfg.fallback;
+    if (first) {
+        const a = await safe(first, req);
+        if (a.verdict !== "ask" || a.probabilities)
+            return a; // a usable verdict ends the chain
+    }
+    if (cfg.kind === "jev" && cfg.fallback)
+        return safe(cfg.fallback, req);
+    return { verdict: "ask", classifier: "none", tier: 2 };
+}

package/dist/classifiers/generative.d.ts

@@ -0,0 +1,16 @@
+import type { GateAssessment, GateRequest } from "../core/types.js";
+export interface GenerativeOptions {
+    baseUrl: string;
+    model: string;
+    apiKeyEnv?: string;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    log?: (m: string) => void;
+}
+/** A generative classifier yields a VERDICT ONLY (no confidence, no hazards) — §5.
+ *  That is deliberate: with fallbackAcceptsVerdict:false the policy engine ignores
+ *  it and asks (§7). Never throws — any failure is `ask`. */
+export declare function createGenerativeClassifier(o: GenerativeOptions): {
+    id: string;
+    classify(req: GateRequest): Promise<GateAssessment>;
+};

package/dist/classifiers/generative.js

@@ -0,0 +1,50 @@
+import { buildState } from "./jev-state.js";
+const PROMPT = [
+    "You are a permission gate for a coding agent. Reply with exactly one word: allow, deny, or ask.",
+    "allow = safe, ordinary development work in service of the user's intent.",
+    "deny = destructive, irreversible, credential-exfiltrating, or system-damaging.",
+    "ask = ambiguous or insufficient information.",
+].join(" ");
+/** A generative classifier yields a VERDICT ONLY (no confidence, no hazards) — §5.
+ *  That is deliberate: with fallbackAcceptsVerdict:false the policy engine ignores
+ *  it and asks (§7). Never throws — any failure is `ask`. */
+export function createGenerativeClassifier(o) {
+    const fetchImpl = o.fetchImpl ?? fetch;
+    const timeoutMs = o.timeoutMs ?? 3000;
+    const key = o.apiKeyEnv ? process.env[o.apiKeyEnv] : undefined;
+    return {
+        id: "generative",
+        async classify(req) {
+            const ac = new AbortController();
+            const t = setTimeout(() => ac.abort(), timeoutMs);
+            try {
+                const r = await fetchImpl(`${o.baseUrl}/chat/completions`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json", ...(key ? { authorization: `Bearer ${key}` } : {}) },
+                    body: JSON.stringify({
+                        model: o.model,
+                        messages: [
+                            { role: "system", content: PROMPT },
+                            { role: "user", content: JSON.stringify({ intent: req.userIntent ?? null, tool: req.toolName, payload: buildState(req).tool.input }) },
+                        ],
+                        max_tokens: 4, temperature: 0,
+                    }),
+                    signal: ac.signal,
+                });
+                if (!r.ok)
+                    return { verdict: "ask", classifier: "generative-unavailable", tier: 2 };
+                const body = (await r.json());
+                const word = (body.choices?.[0]?.message?.content ?? "").trim().toLowerCase();
+                const verdict = word === "allow" ? "allow" : word === "deny" ? "deny" : "ask";
+                return { verdict, classifier: `generative:${o.model}`, tier: 2 }; // confidence intentionally ABSENT
+            }
+            catch (e) {
+                o.log?.(`generative failed: ${e.message}`);
+                return { verdict: "ask", classifier: "generative-unavailable", tier: 2 };
+            }
+            finally {
+                clearTimeout(t);
+            }
+        },
+    };
+}

package/dist/classifiers/jev-parse.d.ts

@@ -0,0 +1,6 @@
+import type { GateAssessment } from "../core/types.js";
+type RawAnswer = Record<string, unknown>;
+/** Pure. Returns null for anything the policy engine should treat as "no usable
+ *  assessment" (→ ask): a near-tie, a missing/malformed Choice, or no confidence. */
+export declare function parseJevResponse(raw: Record<string, RawAnswer | undefined>, model: string, askedIds: string[]): GateAssessment | null;
+export {};

package/dist/classifiers/jev-parse.js

@@ -0,0 +1,35 @@
+const NEAR_TIE_EPSILON = 0.05; // §8
+const VERDICTS = ["allow", "deny", "ask"];
+/** Pure. Returns null for anything the policy engine should treat as "no usable
+ *  assessment" (→ ask): a near-tie, a missing/malformed Choice, or no confidence. */
+export function parseJevResponse(raw, model, askedIds) {
+    const d = raw.decision;
+    if (!d || typeof d.choice !== "string" || !VERDICTS.includes(d.choice))
+        return null;
+    if (typeof d.confidence !== "number")
+        return null;
+    if (d.probabilities) {
+        const sorted = Object.values(d.probabilities).sort((a, b) => b - a);
+        if (sorted.length >= 2 && sorted[0] - sorted[1] < NEAR_TIE_EPSILON)
+            return null;
+    }
+    const hazards = {};
+    for (const id of ["destructive", "secrets", "scope_escape", "intent_match"]) {
+        if (!askedIds.includes(id))
+            continue;
+        const noul = raw[id]?.noul;
+        if (typeof noul === "number")
+            hazards[id] = noul;
+    }
+    const sevAnswer = raw.severity;
+    const severity = typeof sevAnswer?.score === "number" ? sevAnswer.score : undefined;
+    return {
+        verdict: d.choice,
+        confidence: d.confidence,
+        ...(d.probabilities ? { probabilities: d.probabilities } : {}),
+        ...(Object.keys(hazards).length ? { hazards } : {}),
+        ...(severity !== undefined ? { severity } : {}),
+        classifier: `jev-${model}`,
+        tier: 2,
+    };
+}

package/dist/classifiers/jev-state.d.ts

@@ -0,0 +1,10 @@
+import type { GateRequest } from "../core/types.js";
+export interface JevState {
+    user_intent?: string;
+    tool: {
+        name: string;
+        input: Record<string, unknown>;
+    };
+}
+/** Structured, minimal, redacted. State is data, never instructions (§6.2). */
+export declare function buildState(req: GateRequest): JevState;

package/dist/classifiers/jev-state.js

@@ -0,0 +1,13 @@
+import { redact } from "../core/redact.js";
+const MAX_STATE_CHARS = 8_000; // terse: Jev suffers context-rot on irrelevant detail (§2.2)
+/** Structured, minimal, redacted. State is data, never instructions (§6.2). */
+export function buildState(req) {
+    const payload = redact(req.toolPayload).text;
+    const state = {
+        tool: { name: req.toolName, input: { payload: payload.slice(0, MAX_STATE_CHARS) } },
+    };
+    if (req.intentSupport === "available" && req.userIntent) {
+        state.user_intent = redact(req.userIntent).text.slice(0, MAX_STATE_CHARS);
+    }
+    return state;
+}

package/dist/classifiers/jev.d.ts

@@ -0,0 +1,15 @@
+import type { GateAssessment, GateRequest } from "../core/types.js";
+export interface JevOptions {
+    apiKey: string;
+    model: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    log?: (m: string) => void;
+}
+/** One request per decision (§6.1). MUST never throw — every failure is `ask` (§8). */
+export declare function createJevClassifier(o: JevOptions): {
+    id: string;
+    classify(req: GateRequest): Promise<GateAssessment>;
+};

package/dist/classifiers/jev.js

@@ -0,0 +1,66 @@
+import { buildQuestions } from "./battery.js";
+import { buildState } from "./jev-state.js";
+import { parseJevResponse } from "./jev-parse.js";
+const ASK_CLASSIFIER = "jev-unavailable";
+/** One request per decision (§6.1). MUST never throw — every failure is `ask` (§8). */
+export function createJevClassifier(o) {
+    const base = o.baseUrl ?? "https://api.typesafe.ai";
+    const timeoutMs = o.timeoutMs ?? 4000;
+    const fetchImpl = o.fetchImpl ?? fetch;
+    const sleep = o.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    /** Every failure resolves here (§8). The reason is logged (audit/redaction in
+     *  P3), never put on the assessment — policy only needs the verdict. */
+    const ask = (reason) => {
+        o.log?.(`jev → ask (${reason})`);
+        return { verdict: "ask", classifier: ASK_CLASSIFIER, tier: 2 };
+    };
+    async function postOnce(body) {
+        const ac = new AbortController();
+        const t = setTimeout(() => ac.abort(), timeoutMs);
+        try {
+            const r = await fetchImpl(`${base}/v1/systemone`, {
+                method: "POST",
+                headers: { "content-type": "application/json", authorization: `Bearer ${o.apiKey}` },
+                body: JSON.stringify(body),
+                signal: ac.signal,
+            });
+            const retryAfter = r.headers?.get?.("retry-after") ?? undefined;
+            const json = r.ok ? await r.json() : undefined;
+            return { status: r.status, retryAfter: retryAfter ?? undefined, json };
+        }
+        finally {
+            clearTimeout(t);
+        }
+    }
+    return {
+        id: "jev",
+        async classify(req) {
+            const questions = buildQuestions(req);
+            const payload = { state: buildState(req), model: o.model, questions };
+            const askedIds = Object.keys(questions);
+            for (let attempt = 0; attempt < 2; attempt++) {
+                try {
+                    const r = await postOnce(payload);
+                    if (r.status === 429 || r.status === 529) {
+                        if (attempt === 0) {
+                            const wait = Number(r.retryAfter ?? "0") * 1000;
+                            await sleep(Number.isFinite(wait) ? Math.min(wait, 2000) : 0);
+                            continue;
+                        }
+                        return ask("rate-limited");
+                    }
+                    if (r.status !== 200 || !r.json)
+                        return ask(`http ${r.status}`);
+                    return parseJevResponse(r.json, o.model, askedIds) ?? ask("unusable");
+                }
+                catch (e) {
+                    if (attempt === 0)
+                        continue; // one retry covers a transient network blip
+                    o.log?.(`jev failed: ${e.message}`);
+                    return ask("network");
+                }
+            }
+            return ask("exhausted");
+        },
+    };
+}

package/dist/classifiers/null.d.ts

@@ -0,0 +1,6 @@
+import type { GateAssessment, GateRequest } from "../core/types.js";
+/** Always `ask` — used when no classifier is configured (§5: never throw). */
+export declare function createNullClassifier(): {
+    id: string;
+    classify(_req: GateRequest): Promise<GateAssessment>;
+};

package/dist/classifiers/null.js

@@ -0,0 +1,9 @@
+/** Always `ask` — used when no classifier is configured (§5: never throw). */
+export function createNullClassifier() {
+    return {
+        id: "null",
+        async classify(_req) {
+            return { verdict: "ask", classifier: "null", tier: 2 };
+        },
+    };
+}

package/dist/cli/claude.d.ts

@@ -0,0 +1,21 @@
+import type { GateOutcome } from "../core/types.js";
+import type { BlockedContext } from "../adapters/claude/blocked-signal.js";
+export interface ClaudeDecideIo {
+    stdin: {
+        read(): Promise<string>;
+    };
+    stdout: {
+        write(s: string): void;
+    };
+    stderr: {
+        write(s: string): void;
+    };
+    decide(req: unknown): Promise<GateOutcome>;
+    readIntent(t: string | undefined): string | undefined;
+    blockedSignal?(ctx: BlockedContext): Promise<void>;
+    env?: Record<string, string | undefined>;
+    log?: (m: string) => void;
+}
+/** The claude `PermissionRequest` hook entry. stdout is machine-parsed: on ask/
+ *  yield it MUST be empty so the normal dialog appears (§11). */
+export declare function runClaudeDecide(io: ClaudeDecideIo): Promise<void>;

package/dist/cli/claude.js

@@ -0,0 +1,20 @@
+import { mapClaudeHookPayload } from "../adapters/claude/payload.js";
+import { formatClaudeHookOutput } from "../adapters/claude/output.js";
+/** The claude `PermissionRequest` hook entry. stdout is machine-parsed: on ask/
+ *  yield it MUST be empty so the normal dialog appears (§11). */
+export async function runClaudeDecide(io) {
+    try {
+        const payload = JSON.parse(await io.stdin.read());
+        const req = mapClaudeHookPayload(payload, io.env ?? process.env, io.readIntent);
+        const outcome = await io.decide(req);
+        const out = formatClaudeHookOutput(outcome);
+        if (out)
+            io.stdout.write(out + "\n");
+        else if (io.blockedSignal) {
+            await io.blockedSignal({ agent: "claude", tool: req.toolName, reason: outcome.reason });
+        }
+    }
+    catch (e) {
+        io.log?.(`claude decide failed: ${e.message}`); // print nothing ⇒ dialog appears
+    }
+}

package/dist/cli/decide.d.ts

@@ -0,0 +1,17 @@
+import type { GateOutcome } from "../core/types.js";
+export interface DecideIo {
+    stdin: {
+        read(): Promise<string>;
+    };
+    stdout: {
+        write(s: string): void;
+    };
+    stderr: {
+        write(s: string): void;
+    };
+    decide(req: unknown): Promise<GateOutcome>;
+    log?: (m: string) => void;
+}
+/** stdin: GateRequest JSON -> stdout: GateOutcome JSON. Diagnostics go to stderr
+ *  ONLY — stdout is machine-parsed and a stray byte breaks the parse (§12). */
+export declare function runDecide(io: DecideIo): Promise<void>;

package/dist/cli/decide.js

@@ -0,0 +1,16 @@
+/** stdin: GateRequest JSON -> stdout: GateOutcome JSON. Diagnostics go to stderr
+ *  ONLY — stdout is machine-parsed and a stray byte breaks the parse (§12). */
+export async function runDecide(io) {
+    let outcome;
+    try {
+        const raw = await io.stdin.read();
+        const req = JSON.parse(raw);
+        outcome = await io.decide(req);
+        io.log?.(`decision: ${outcome.decision} (tier ${outcome.tier})`);
+    }
+    catch (e) {
+        io.log?.(`decide failed: ${e.message}`);
+        outcome = { decision: "ask", tier: 2, reason: "malformed input" }; // never fail closed
+    }
+    io.stdout.write(JSON.stringify(outcome) + "\n");
+}

package/dist/cli/doctor.d.ts

@@ -0,0 +1,4 @@
+export interface DoctorReport {
+    lines: string[];
+}
+export declare function doctor(): DoctorReport;