@squadrant-ai/auto-gate 0.1.0

package/README.md

@@ -0,0 +1,2 @@
+# auto-gate
+Provider-agnostic, cross-agent auto permission gate (Jev-backed). Design: squadrant #828.

package/dist/adapters/claude/blocked-signal.d.ts

@@ -0,0 +1,16 @@
+export interface BlockedContext {
+    agent: string;
+    tool: string;
+    reason: string;
+    project?: string;
+    gateId?: string;
+}
+export interface BlockedSignalDeps {
+    command: string | null;
+    exec?: (cmd: string, env: Record<string, string>) => Promise<unknown>;
+    log?: (m: string) => void;
+}
+/** The standalone analogue of squadrant's #560 `task.blocked` signal (§3 bridge
+ *  interface 3). Best-effort: an unset or failing command NEVER throws — the
+ *  agent's own dialog is still the fallback. */
+export declare function createBlockedSignal(deps: BlockedSignalDeps): (ctx: BlockedContext) => Promise<void>;

package/dist/adapters/claude/blocked-signal.js

@@ -0,0 +1,21 @@
+/** The standalone analogue of squadrant's #560 `task.blocked` signal (§3 bridge
+ *  interface 3). Best-effort: an unset or failing command NEVER throws — the
+ *  agent's own dialog is still the fallback. */
+export function createBlockedSignal(deps) {
+    const exec = deps.exec ?? (async () => ({}));
+    return async (ctx) => {
+        if (!deps.command)
+            return;
+        try {
+            await exec(deps.command, {
+                AUTO_GATE_TOOL: ctx.tool,
+                AUTO_GATE_REASON: ctx.reason,
+                ...(ctx.project ? { AUTO_GATE_PROJECT: ctx.project } : {}),
+                ...(ctx.gateId ? { AUTO_GATE_GATE_ID: ctx.gateId } : {}),
+            });
+        }
+        catch (e) {
+            deps.log?.(`blocked-signal failed: ${e.message}`);
+        }
+    };
+}

package/dist/adapters/claude/install.d.ts

@@ -0,0 +1,12 @@
+export interface InstallResult {
+    installed: boolean;
+    deferredTo?: "squadrant";
+    reason?: string;
+}
+/** Idempotent, non-clobbering. DEFERS when squadrant owns the event (§15 #5). */
+export declare function installClaude(o?: {
+    settingsPath?: string;
+}): InstallResult;
+export declare function uninstallClaude(o?: {
+    settingsPath?: string;
+}): InstallResult;

package/dist/adapters/claude/install.js

@@ -0,0 +1,52 @@
+import { copyFileSync, existsSync, readFileSync, renameSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { addOurHandler, removeOurHandler, foreignOwnerOf } from "./settings.js";
+function settingsPathOf(o) {
+    return o.settingsPath ?? join(homedir(), ".claude", "settings.json");
+}
+function readSettings(p) {
+    if (!existsSync(p))
+        return { missing: true };
+    try {
+        const parsed = JSON.parse(readFileSync(p, "utf8"));
+        return parsed && typeof parsed === "object" ? { json: parsed } : { malformed: true };
+    }
+    catch {
+        return { malformed: true };
+    }
+}
+function writeWithBackup(p, json) {
+    mkdirSync(dirname(p), { recursive: true });
+    if (existsSync(p))
+        copyFileSync(p, `${p}.backup`);
+    const tmp = `${p}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(json, null, 2) + "\n");
+    renameSync(tmp, p);
+}
+/** Idempotent, non-clobbering. DEFERS when squadrant owns the event (§15 #5). */
+export function installClaude(o = {}) {
+    const p = settingsPathOf(o);
+    const { json, malformed } = readSettings(p);
+    if (malformed)
+        return { installed: false, reason: "malformed settings file — refusing to blind-reset" };
+    const base = json ?? {};
+    const owner = foreignOwnerOf(base);
+    if (owner)
+        return { installed: false, deferredTo: owner };
+    const next = addOurHandler(base, "claude permission-request");
+    if (JSON.stringify(next) === JSON.stringify(base))
+        return { installed: true }; // already ours
+    writeWithBackup(p, next);
+    return { installed: true };
+}
+export function uninstallClaude(o = {}) {
+    const p = settingsPathOf(o);
+    const { json, malformed } = readSettings(p);
+    if (malformed || !json)
+        return { installed: false, reason: "nothing to uninstall" };
+    const next = removeOurHandler(json);
+    if (JSON.stringify(next) !== JSON.stringify(json))
+        writeWithBackup(p, next);
+    return { installed: true };
+}

package/dist/adapters/claude/output.d.ts

@@ -0,0 +1,5 @@
+import type { GateOutcome } from "../../core/types.js";
+/** `ask`/`yield` return undefined ⇒ the caller prints NOTHING so the normal
+ *  permission dialog appears (§11). NOTE: this is `hookSpecificOutput.decision.
+ *  behavior`, NOT `permissionDecision` (that shape is PreToolUse-only). */
+export declare function formatClaudeHookOutput(outcome: GateOutcome): string | undefined;

package/dist/adapters/claude/output.js

@@ -0,0 +1,16 @@
+/** `ask`/`yield` return undefined ⇒ the caller prints NOTHING so the normal
+ *  permission dialog appears (§11). NOTE: this is `hookSpecificOutput.decision.
+ *  behavior`, NOT `permissionDecision` (that shape is PreToolUse-only). */
+export function formatClaudeHookOutput(outcome) {
+    if (outcome.decision !== "allow" && outcome.decision !== "deny")
+        return undefined;
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "PermissionRequest",
+            decision: {
+                behavior: outcome.decision,
+                ...(outcome.decision === "deny" ? { message: outcome.reason } : {}),
+            },
+        },
+    });
+}

package/dist/adapters/claude/payload.d.ts

@@ -0,0 +1,14 @@
+import type { GateRequest } from "../../core/types.js";
+export interface ClaudeHookPayload {
+    hook_event_name?: string;
+    session_id?: string;
+    transcript_path?: string;
+    cwd?: string;
+    tool_name?: string;
+    tool_input?: Record<string, unknown>;
+    permission_mode?: string;
+}
+/** Only the bare executable field (spec §6.2). Never the whole tool_input. */
+export declare function extractToolPayload(toolName: string, input?: Record<string, unknown>): string;
+/** Pure. `readIntent` is injected so this stays free of fs/transcript knowledge. */
+export declare function mapClaudeHookPayload(p: ClaudeHookPayload, env: Record<string, string | undefined>, readIntent: (transcriptPath: string | undefined) => string | undefined): GateRequest;

package/dist/adapters/claude/payload.js

@@ -0,0 +1,36 @@
+/** Only the bare executable field (spec §6.2). Never the whole tool_input. */
+export function extractToolPayload(toolName, input = {}) {
+    switch (toolName) {
+        case "Bash": return String(input.command ?? "");
+        case "Write": return `${input.file_path ?? ""}\n${input.content ?? ""}`;
+        case "Edit":
+        case "MultiEdit": return `${input.file_path ?? ""}\n${input.old_string ?? ""}\n${input.new_string ?? ""}`;
+        case "NotebookEdit": return `${input.notebook_path ?? ""}\n${input.new_source ?? ""}`;
+        default: return JSON.stringify(input);
+    }
+}
+function sessionKindFromEnv(env) {
+    if (env.SQUADRANT_CREW_TASK_ID)
+        return "crew";
+    if (env.SQUADRANT_SIDE_SESSION === "1")
+        return "side";
+    if (env.SQUADRANT_ROLE === "captain")
+        return "captain";
+    return "standalone";
+}
+/** Pure. `readIntent` is injected so this stays free of fs/transcript knowledge. */
+export function mapClaudeHookPayload(p, env, readIntent) {
+    const intent = readIntent(p.transcript_path);
+    const intentSupport = intent ? "available" : "pending";
+    return {
+        agent: "claude",
+        toolName: p.tool_name ?? "Unknown",
+        toolPayload: extractToolPayload(p.tool_name ?? "Unknown", p.tool_input),
+        cwd: p.cwd ?? process.cwd(),
+        ...(intent ? { userIntent: intent } : {}),
+        intentSupport,
+        ...(p.permission_mode ? { permissionMode: p.permission_mode } : {}),
+        sessionKind: sessionKindFromEnv(env),
+        raw: { session_id: p.session_id },
+    };
+}

package/dist/adapters/claude/settings.d.ts

@@ -0,0 +1,14 @@
+export declare const OUR_MARKER = " # auto-gate-managed";
+export declare const OUR_COMMAND = "auto-gate decide --agent claude # auto-gate-managed";
+type Json = Record<string, unknown>;
+/** True when a command string is ours — matched by the marker OR by the parsed
+ *  argv basename `auto-gate`, so `npx @squadrant/auto-gate …` / `node <path> …`
+ *  forms are still recognized (§15 #5). */
+export declare function isOurCommand(command: string): boolean;
+/** Idempotent, non-clobbering: appends our handler to the PermissionRequest list. */
+export declare function addOurHandler(settings: Json, _sub: string): Json;
+/** Removes ONLY our handlers; drops entries left empty. Never touches a user's. */
+export declare function removeOurHandler(settings: Json): Json;
+/** "squadrant" when squadrant owns the PermissionRequest event, else null (§15 #5). */
+export declare function foreignOwnerOf(settings: Json): "squadrant" | null;
+export {};

package/dist/adapters/claude/settings.js

@@ -0,0 +1,48 @@
+export const OUR_MARKER = " # auto-gate-managed";
+export const OUR_COMMAND = `auto-gate decide --agent claude${OUR_MARKER}`;
+/** squadrant's managed PermissionRequest command (exact string, #782). */
+const SQUADRANT_COMMAND = "squadrant gate claude permission-request";
+/** True when a command string is ours — matched by the marker OR by the parsed
+ *  argv basename `auto-gate`, so `npx @squadrant/auto-gate …` / `node <path> …`
+ *  forms are still recognized (§15 #5). */
+export function isOurCommand(command) {
+    if (command.includes(OUR_MARKER.trim()))
+        return true;
+    const first = command.trim().split(/\s+/)[0] ?? "";
+    return /(^|[/\\])auto-gate$/.test(first);
+}
+function entries(settings) {
+    const hooks = (settings.hooks ?? {});
+    const list = hooks.PermissionRequest;
+    return Array.isArray(list) ? list : [];
+}
+function setEntries(settings, list) {
+    const hooks = { ...(settings.hooks ?? {}) };
+    hooks.PermissionRequest = list;
+    return { ...settings, hooks };
+}
+/** Idempotent, non-clobbering: appends our handler to the PermissionRequest list. */
+export function addOurHandler(settings, _sub) {
+    const list = entries(settings);
+    const already = list.some((e) => Array.isArray(e.hooks) && e.hooks.some((h) => isOurCommand(String(h.command ?? ""))));
+    if (already)
+        return settings;
+    return setEntries(settings, [...list, { hooks: [{ type: "command", command: OUR_COMMAND }] }]);
+}
+/** Removes ONLY our handlers; drops entries left empty. Never touches a user's. */
+export function removeOurHandler(settings) {
+    const next = [];
+    for (const entry of entries(settings)) {
+        const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
+        const kept = hooks.filter((h) => !isOurCommand(String(h.command ?? "")));
+        if (kept.length > 0)
+            next.push({ ...entry, hooks: kept });
+    }
+    return setEntries(settings, next);
+}
+/** "squadrant" when squadrant owns the PermissionRequest event, else null (§15 #5). */
+export function foreignOwnerOf(settings) {
+    const owns = entries(settings).some((e) => Array.isArray(e.hooks) &&
+        e.hooks.some((h) => String(h.command ?? "") === SQUADRANT_COMMAND));
+    return owns ? "squadrant" : null;
+}

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

@@ -0,0 +1,24 @@
+import type { GateOutcome } from "../../core/types.js";
+/** §11: the opencode answer vocabulary. `ask`/`yield` have NO answer — the native
+ *  prompt stays pending (which is correct only when a human is watching). */
+export declare function answerFor(o: GateOutcome): "once" | "reject" | undefined;
+/** Attendance is an EXPLICIT marker (§15 #4), never TTY sniffing — the watcher's
+ *  TTY is not the crew's TTY. */
+export declare function shouldLeavePending(o: {
+    attended: boolean;
+}): boolean;
+export interface AskOpts {
+    attended: boolean;
+    onAsk?: (ctx: {
+        tool: string;
+        reason: string;
+    }) => Promise<void>;
+    timeoutMs: number;
+    tool: string;
+    reason: string;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+/** Unattended `ask`: fire the notification hook, then DENY on timeout so the crew
+ *  never hangs. The deny is audited+notified by the caller, never silent (§15 #4). */
+export declare function handleAsk(o: AskOpts): Promise<"reject" | undefined>;

package/dist/adapters/opencode/answer.js

@@ -0,0 +1,25 @@
+/** §11: the opencode answer vocabulary. `ask`/`yield` have NO answer — the native
+ *  prompt stays pending (which is correct only when a human is watching). */
+export function answerFor(o) {
+    if (o.decision === "allow")
+        return "once";
+    if (o.decision === "deny")
+        return "reject";
+    return undefined;
+}
+/** Attendance is an EXPLICIT marker (§15 #4), never TTY sniffing — the watcher's
+ *  TTY is not the crew's TTY. */
+export function shouldLeavePending(o) { return o.attended; }
+/** Unattended `ask`: fire the notification hook, then DENY on timeout so the crew
+ *  never hangs. The deny is audited+notified by the caller, never silent (§15 #4). */
+export async function handleAsk(o) {
+    if (o.attended)
+        return undefined;
+    try {
+        await o.onAsk?.({ tool: o.tool, reason: o.reason });
+    }
+    catch { /* best-effort */ }
+    const sleep = o.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    await sleep(o.timeoutMs);
+    return "reject";
+}

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

@@ -0,0 +1,5 @@
+type Json = Record<string, unknown>;
+export declare function mergePermissionBlock(cfg: Json, tools: string[]): Json;
+/** Removes only the `ask` values we set; a user's own value is preserved. */
+export declare function unmergePermissionBlock(cfg: Json): Json;
+export {};

package/dist/adapters/opencode/install.js

@@ -0,0 +1,30 @@
+/** The canonical scope → the native opencode permission keys it maps onto. The
+ *  alias table is §12's (set-valued): `edit` covers write/patch too. */
+const CANONICAL_TO_NATIVE = {
+    Bash: ["bash"], Write: ["edit"], Edit: ["edit"], MultiEdit: ["edit"], NotebookEdit: ["edit"],
+};
+function nativeKeys(tools) {
+    const keys = new Set();
+    for (const t of tools)
+        for (const k of CANONICAL_TO_NATIVE[t] ?? [])
+            keys.add(k);
+    return [...keys].sort();
+}
+export function mergePermissionBlock(cfg, tools) {
+    const permission = { ...(cfg.permission ?? {}) };
+    for (const k of nativeKeys(tools)) {
+        if (permission[k] === "ask")
+            continue; // already ours ⇒ idempotent
+        if (permission[k] === undefined)
+            permission[k] = "ask";
+    }
+    return { ...cfg, permission };
+}
+/** Removes only the `ask` values we set; a user's own value is preserved. */
+export function unmergePermissionBlock(cfg) {
+    const permission = { ...(cfg.permission ?? {}) };
+    for (const k of ["bash", "edit"])
+        if (permission[k] === "ask")
+            delete permission[k];
+    return { ...cfg, permission };
+}

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

@@ -0,0 +1,10 @@
+import type { SseEvent } from "./sse.js";
+import type { IntentSupport } from "../../core/types.js";
+export interface ReconstructedIntent {
+    text?: string;
+    support: IntentSupport;
+}
+/** §15 #3: reconstruct the last HUMAN message from the frame sequence. When none
+ *  has been seen yet the support is `pending` — the policy engine then asks, so
+ *  an unknown intent can never produce a silent auto-allow. */
+export declare function reconstructIntent(sessionID: string, frames: SseEvent[]): ReconstructedIntent;

package/dist/adapters/opencode/intent.js

@@ -0,0 +1,11 @@
+/** §15 #3: reconstruct the last HUMAN message from the frame sequence. When none
+ *  has been seen yet the support is `pending` — the policy engine then asks, so
+ *  an unknown intent can never produce a silent auto-allow. */
+export function reconstructIntent(sessionID, frames) {
+    let text;
+    for (const f of frames) {
+        if (f.kind === "user-text" && f.sessionID === sessionID)
+            text = f.text;
+    }
+    return text ? { text, support: "available" } : { support: "pending" };
+}

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

@@ -0,0 +1,18 @@
+/** Mirrors the #830 telegram poll-lock shape so there is one lock idiom in the codebase. */
+export declare function lockPathFor(host: string, port: number, dir?: string): string;
+export interface AcquireOpts {
+    host: string;
+    port: number;
+    dir?: string;
+    pid?: number;
+    now?: () => number;
+}
+export interface AcquireResult {
+    ok: boolean;
+    release?(): void;
+}
+/** Atomic O_EXCL acquire. A dead owner's lock is reclaimed at most once. The
+ *  loser YIELDS PERMANENTLY (never loops) — see §15 #7 contention policy. */
+export declare function acquireLock(o: AcquireOpts): AcquireResult;
+/** Exposed for the watcher: is the lock present and live? */
+export declare function lockHeldByOther(o: AcquireOpts): boolean;

package/dist/adapters/opencode/lock.js

@@ -0,0 +1,72 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, statSync, unlinkSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const STALE_MS = 2 * 60_000;
+/** Mirrors the #830 telegram poll-lock shape so there is one lock idiom in the codebase. */
+export function lockPathFor(host, port, dir = tmpdir()) {
+    const hash = createHash("sha256").update(`${host}:${port}`).digest("hex").slice(0, 16);
+    return join(dir, `auto-gate-opencode-${hash}.lock`);
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    }
+}
+/** Atomic O_EXCL acquire. A dead owner's lock is reclaimed at most once. The
+ *  loser YIELDS PERMANENTLY (never loops) — see §15 #7 contention policy. */
+export function acquireLock(o) {
+    const dir = o.dir ?? tmpdir();
+    const pid = o.pid ?? process.pid;
+    const file = lockPathFor(o.host, o.port, dir);
+    mkdirSync(dir, { recursive: true });
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            writeFileSync(file, String(pid), { flag: "wx" });
+            return { ok: true, release: () => { try {
+                    unlinkSync(file);
+                }
+                catch { /* already gone */ } } };
+        }
+        catch (e) {
+            if (e.code !== "EEXIST")
+                return { ok: false };
+            let owner;
+            let ageMs = Infinity;
+            try {
+                owner = Number.parseInt(readFileSync(file, "utf8").trim(), 10);
+                ageMs = Date.now() - statSync(file).mtimeMs;
+            }
+            catch { /* absent */ }
+            const held = owner !== undefined && Number.isFinite(owner) ? pidAlive(owner) : ageMs < STALE_MS;
+            if (attempt === 0 && !held) {
+                try {
+                    unlinkSync(file);
+                }
+                catch { /* raced */ }
+                continue;
+            }
+            return { ok: false };
+        }
+    }
+    return { ok: false };
+}
+/** Exposed for the watcher: is the lock present and live? */
+export function lockHeldByOther(o) {
+    const file = lockPathFor(o.host, o.port, o.dir ?? tmpdir());
+    if (!existsSync(file))
+        return false;
+    try {
+        const pid = Number.parseInt(readFileSync(file, "utf8").trim(), 10);
+        if (Number.isFinite(pid))
+            return pidAlive(pid) && pid !== (o.pid ?? process.pid);
+        return Date.now() - statSync(file).mtimeMs < STALE_MS;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,17 @@
+export declare const ENV_PORT = "AUTO_GATE_OPENCODE_PORT";
+export interface PortInput {
+    flag?: number;
+    env?: Record<string, string | undefined>;
+}
+export type PortResult = {
+    port: number;
+    source: "flag" | "env";
+} | {
+    error: string;
+};
+/** Precedence: explicit --port > AUTO_GATE_OPENCODE_PORT > error. There is NO
+ *  default — a fixed default would collide across concurrent crews (§15 #1). */
+export declare function resolvePort(i: PortInput): PortResult;
+/** Bind :0, read the assigned port, release. The window is tiny and the wrapper
+ *  passes the same N to opencode, so the race is a no-op in practice. */
+export declare function allocatePort(): Promise<number>;

package/dist/adapters/opencode/port.js

@@ -0,0 +1,29 @@
+import { createServer } from "node:net";
+export const ENV_PORT = "AUTO_GATE_OPENCODE_PORT";
+function valid(n) { return Number.isInteger(n) && n > 0 && n < 65536; }
+/** Precedence: explicit --port > AUTO_GATE_OPENCODE_PORT > error. There is NO
+ *  default — a fixed default would collide across concurrent crews (§15 #1). */
+export function resolvePort(i) {
+    const env = i.env ?? process.env;
+    if (i.flag !== undefined)
+        return valid(i.flag) ? { port: i.flag, source: "flag" } : { error: `invalid --port ${i.flag}` };
+    const raw = env[ENV_PORT];
+    if (raw !== undefined) {
+        const n = Number(raw);
+        return valid(n) ? { port: n, source: "env" } : { error: `invalid ${ENV_PORT} '${raw}'` };
+    }
+    return { error: `no port: pass --port N or set ${ENV_PORT}` };
+}
+/** Bind :0, read the assigned port, release. The window is tiny and the wrapper
+ *  passes the same N to opencode, so the race is a no-op in practice. */
+export function allocatePort() {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.on("error", reject);
+        srv.listen(0, "127.0.0.1", () => {
+            const addr = srv.address();
+            const port = typeof addr === "object" && addr ? addr.port : 0;
+            srv.close(() => (port ? resolve(port) : reject(new Error("could not allocate a port"))));
+        });
+    });
+}

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

@@ -0,0 +1,40 @@
+export interface RunPlan {
+    opencodeArgs: string[];
+    env: Record<string, string>;
+    watcherArgs: string[];
+}
+export interface RunInput {
+    args: string[];
+    allocate?: () => Promise<number>;
+}
+/** The wrapper OWNS both the port and the watcher's lifetime (§15 #1/#2): it picks
+ *  the port, passes it to opencode, exports it so nothing has to discover it, and
+ *  runs opencode + the watcher as one supervised unit. */
+export declare function buildRunPlan(i: RunInput): Promise<RunPlan>;
+export interface SpawnedProc {
+    pid?: number;
+    on(event: "exit", cb: (code: number | null) => void): void;
+    on(event: "error", cb: (err: Error) => void): void;
+    kill(signal?: NodeJS.Signals): boolean;
+}
+export interface SpawnOptions {
+    stdio: "inherit";
+    detached?: boolean;
+    env?: NodeJS.ProcessEnv;
+}
+export type SpawnFn = (cmd: string, args: string[], opts: SpawnOptions) => SpawnedProc;
+export interface SupervisorDeps {
+    spawn?: SpawnFn;
+    killPid?: (pid: number, signal?: NodeJS.Signals) => void;
+    log?: (m: string) => void;
+}
+/** Documented supervision contract, asserted by the test so it cannot silently
+ *  drift: watcher death ⇒ kill opencode, exit with the watcher's code (unattended
+ *  must not hang); opencode exit ⇒ SIGTERM the watcher (§15 #2). */
+export declare const runPolicy: "watcher-death-kills-opencode";
+/** Runs opencode and the watcher as one supervised unit and resolves with the
+ *  exit code the wrapper should propagate. `spawn`/`killPid` are injectable so the
+ *  process-group supervision is testable without a live opencode. opencode is
+ *  spawned detached so it leads its own process group — node cannot join an
+ *  existing pgid, so `process.kill(-pid)` targets opencode's group. */
+export declare function supervise(plan: RunPlan, deps?: SupervisorDeps): Promise<number>;

package/dist/adapters/opencode/run.js

@@ -0,0 +1,69 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import { allocatePort as defaultAllocate } from "./port.js";
+/** The wrapper OWNS both the port and the watcher's lifetime (§15 #1/#2): it picks
+ *  the port, passes it to opencode, exports it so nothing has to discover it, and
+ *  runs opencode + the watcher as one supervised unit. */
+export async function buildRunPlan(i) {
+    if (i.args.includes("--port"))
+        throw new Error("args already specifies --port — the wrapper owns the port (§15#1)");
+    const port = await (i.allocate ?? defaultAllocate)();
+    return {
+        opencodeArgs: ["--port", String(port), ...i.args],
+        // D5: the watcher builds `sessionKind: "standalone"`, so without a positive
+        // marker `decideRequest` YIELDS every permission. Export AUTO_GATE_SESSION=1
+        // so `isGateSession(env)` is true in the watcher child (inherited via spawn).
+        env: { AUTO_GATE_OPENCODE_PORT: String(port), AUTO_GATE_SESSION: "1" },
+        watcherArgs: ["opencode", "watch", "--port", String(port)],
+    };
+}
+/** Documented supervision contract, asserted by the test so it cannot silently
+ *  drift: watcher death ⇒ kill opencode, exit with the watcher's code (unattended
+ *  must not hang); opencode exit ⇒ SIGTERM the watcher (§15 #2). */
+export const runPolicy = "watcher-death-kills-opencode";
+buildRunPlan.__policy = runPolicy;
+/** Runs opencode and the watcher as one supervised unit and resolves with the
+ *  exit code the wrapper should propagate. `spawn`/`killPid` are injectable so the
+ *  process-group supervision is testable without a live opencode. opencode is
+ *  spawned detached so it leads its own process group — node cannot join an
+ *  existing pgid, so `process.kill(-pid)` targets opencode's group. */
+export function supervise(plan, deps = {}) {
+    const spawn = deps.spawn ?? ((cmd, args, opts) => nodeSpawn(cmd, args, opts));
+    const killPid = deps.killPid ?? ((pid, signal) => { process.kill(pid, signal); });
+    const log = deps.log;
+    const env = { ...process.env, ...plan.env };
+    const opencode = spawn("opencode", plan.opencodeArgs, { stdio: "inherit", detached: true, env });
+    const watcher = spawn(plan.watcherArgs[0], plan.watcherArgs.slice(1), { stdio: "inherit", env });
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (code) => { if (settled)
+            return; settled = true; resolve(code); };
+        const killOpencodeGroup = () => {
+            if (opencode.pid === undefined)
+                return;
+            try {
+                killPid(-opencode.pid, "SIGTERM");
+            }
+            catch (e) {
+                log?.(`auto-gate opencode: group kill failed — ${e.message}`);
+            }
+        };
+        watcher.on("exit", (code) => {
+            log?.("auto-gate opencode: watcher exited — killing the opencode group (§15#2)");
+            killOpencodeGroup();
+            settle(code ?? 1);
+        });
+        watcher.on("error", (err) => {
+            log?.(`auto-gate opencode: watcher error — ${err.message}; killing the opencode group (§15#2)`);
+            killOpencodeGroup();
+            settle(1);
+        });
+        opencode.on("exit", (code) => {
+            log?.("auto-gate opencode: opencode exited — signalling the watcher (§15#2)");
+            try {
+                watcher.kill("SIGTERM");
+            }
+            catch { /* already gone */ }
+            settle(code ?? 0);
+        });
+    });
+}

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

@@ -0,0 +1,18 @@
+export type SseEvent = {
+    kind: "permission.asked";
+    id: string;
+    sessionID: string;
+    permission: string;
+    patterns: string[];
+} | {
+    kind: "permission.replied";
+    id: string;
+} | {
+    kind: "user-text";
+    sessionID: string;
+    text: string;
+};
+/** 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 declare function parseSseFrame(raw: string): SseEvent | null;