@te-river/opencode-team-mode 1.5.1 → 1.5.2

package/dist/approval-gate.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Unified approval gate — Layer 2 (timeout auto-reject) + Layer 3 (SDK
+ * fallback) of the R6 + R2 approval flow.
+ *
+ * The host only shows its official confirmation dialog for command patterns
+ * declared `ask` in an agent's permission config (Layer 1, envprotect.ts).
+ * When a dialog opens it SUSPENDS the tool call and waits for a human; on the
+ * OpenCode DESKTOP that human is present, but a request can also be left
+ * unanswered.  This module owns ONE timer that watches the host permission
+ * events and closes abandoned requests on the safe side.
+ *
+ * REAL host contract (1.18.29, probed live via SSE + the plugin event hook —
+ * see gate-test report-p5):
+ *   permission.asked   → properties = { id, sessionID, permission: "bash",
+ *                        patterns: [<concrete command segment>, …], metadata:
+ *                        { command }, always: [<host's "always" generalization
+ *                        proposal>], tool: { messageID, callID } } — the props
+ *                        carry NO `type` field, and the tool name sits in
+ *                        `permission`.  A props matching one of OUR injected
+ *                        bash ask sets means the dialog is ours: audit "ask",
+ *                        arm the timeout, and — for the R6 env face — mark
+ *                        the session deferrable (canDefer, see below).
+ *   permission.replied → properties = { sessionID, requestID, reply } on the
+ *                        wire, but the plugin-side observer has also seen it
+ *                        with ONLY { sessionID }.  The gate therefore cancels
+ *                        EVERY pending timer of that session on a reply: an
+ *                        already-approved command left on a live timer would
+ *                        get a second reject after the timeout, the SDK call
+ *                        would hit a dead id (4xx) and flip the gate
+ *                        permanently degraded.
+ *
+ * Older/typed spellings (`permission.updated`, `pattern`, `permissionID`,
+ * `response`) keep being accepted — the shipped SDK d.ts still names the
+ * events that way, and some builds omit the reply id entirely (a short
+ * ghost-suppression window per session then absorbs late/duplicate `asked`
+ * replays instead of re-arming a ghost timer).
+ *
+ * Hard rules (HUMAN-approved):
+ *   - the plugin NEVER self-allows: `reply` is fixed to "reject".  The only
+ *     way a gated command runs is a human approving the dialog;
+ *   - on `TM_ENV_PROTECT=off` the gate is not armed (index.ts decides);
+ *   - deferral is SESSION-SCOPED (canDefer): only sessions registered as
+ *     carrying our injected ask set may have env reads passed through —
+ *     registration comes from an exec-role user prompt (the live-proven
+ *     `message.updated` UserMessage{role,agent,sessionID} signal, plus the
+ *     documented `chat.message` hook) or from an R6-env-classified asked
+ *     event.  Stock build/plan sessions never register, so the global R6
+ *     hook keeps hard-throwing there — closing the R6 bypass the global
+ *     `isArmed()` deferral allowed;
+ *   - if the SDK reply FAILS (network/host — including the v1
+ *     `throwOnError:false` envelope resolving with `{ error }`), we cannot
+ *     close the dialog, so the gate flips itself permanently "degraded" —
+ *     the R6 hook stops deferring env reads and hard-throws them again
+ *     (fail-closed), and the event is audited "degraded".
+ *
+ * SDK surface (probed live on 1.18.x): the plugin's `input.client` is the v1
+ * `OpencodeClient`, which has NO `permission` namespace and NO list/create
+ * endpoint; the reply path is the top-level
+ * `postSessionIdPermissionsPermissionId({ path: { id: sessionID,
+ * permissionID }, body: { response } })`.  `client.permission.reply` /
+ * `client.permission.list` are still tried first so a richer host build is
+ * supported, but on v1 they are simply absent and the poll fallback is a
+ * no-op (events are the sole pending signal there).
+ */
+import type { PermissionEvent } from "./types.js";
+/** Default timeout, in minutes, before an unanswered dialog is auto-rejected. */
+export declare const DEFAULT_ASK_TIMEOUT_MIN = 10;
+/**
+ * Hard floor (minutes) for the auto-reject timeout.  Measured live on the
+ * OpenCode Desktop: a `permission.replied` (human answered "once") reaches
+ * the plugin through the host event bus ~120s LATE — a 1-minute timer
+ * therefore fires BEFORE the cancel arrives and auto-rejects the just-
+ * approved request on a dead id (4xx → permanent degraded, the D4
+ * double-reject race).  3 min = observed ~120s lag + margin; in-range
+ * values below the floor clamp UP to it (a longer timeout is always the
+ * safe direction — the dialog just stays open a bit longer).
+ */
+export declare const MIN_ASK_TIMEOUT_MIN = 3;
+/** The verdict vocabulary recorded in the audit trail (privacy: no command
+ *  text, path, variable name or value is ever logged). */
+export type ApprovalVerdict = "ask" | "allowed-once" | "allowed-always" | "rejected" | "timeout-rejected" | "degraded";
+/**
+ * Resolve `TM_ASK_TIMEOUT_MIN`.  Unset / blank / non-numeric / <1 / >1440
+ * (24h) fall back to the 10-minute default — a mistyped value can never
+ * disable the timeout or make it absurdly long.  Valid values below the
+ * 3-minute bus-lag floor clamp UP to it (1→3, 2→3; see
+ * `MIN_ASK_TIMEOUT_MIN` for the measured ~120s replied-event lag).
+ */
+export declare function resolveAskTimeoutMs(env?: Record<string, string | undefined>): number;
+type TimerHandle = unknown;
+export interface GateTimers {
+    setTimeoutFn: (cb: () => void, ms: number) => TimerHandle;
+    clearTimeoutFn: (handle: TimerHandle) => void;
+}
+export interface ApprovalGateDeps {
+    client: unknown;
+    timeoutMs: number;
+    /** Injectable timers (default: real global timers) for deterministic tests. */
+    timers?: GateTimers;
+    /** Injectable clock (default: Date.now) for deterministic window tests. */
+    now?: () => number;
+}
+export interface ApprovalGate {
+    /** Handle one host event (permission.asked/updated / permission.replied). */
+    handleEvent(event: PermissionEvent): void;
+    /** Start the poll fallback (no-op on v1 where no list endpoint exists). */
+    start(): void;
+    /** Stop the poll + every pending timer. */
+    dispose(): void;
+    /** Global gate health: armed, not degraded, and the client can reply. */
+    isArmed(): boolean;
+    /**
+     * The R6 hook's deferral query: TRUE only when this exact session is
+     * registered as carrying our injected ask set AND the gate is healthy.
+     * Replaces the old global `isArmed()` deferral (which let stock build/plan
+     * sessions pass env reads silently with no dialog in front of them).
+     */
+    canDefer(sessionID?: string): boolean;
+    /** True once a session registered (exec-role prompt seen on
+     *  message.updated / chat.message by index.ts, or an R6-env-classified
+     *  asked event).  Introspection for tests/diagnostics. */
+    hasLiveAsk(sessionID?: string): boolean;
+    /** Mark a session as carrying the injected ask set (index.ts calls this
+     *  when a user prompt routes to an agent we injected the escalated bash
+     *  ask object into — proven live: `message.updated` UserMessage carries
+     *  { sessionID, role:"user", agent } and fires BEFORE the session's first
+     *  tool call, while permission.asked fires AFTER tool.execute.before). */
+    registerExecSession(sessionID?: string): void;
+    /** True after the user picked "always" on an env-related ask in this session
+     *  — subsequent env reads pass silently (the approval event itself is audited). */
+    isEnvApproved(sessionID?: string): boolean;
+    /** Number of pending requests currently being timed (tests / introspection). */
+    pendingSize(): number;
+}
+/** True when the client exposes a permission-reply path at all.  index.ts
+ *  arms the gate ONLY for such a client — fail-closed otherwise (no armed
+ *  auto-reject ⇒ the R6 hook keeps hard-throwing every env read). */
+export declare function hasPermissionReplyCapability(client: unknown): boolean;
+/**
+ * Create the approval gate.  It is intentionally pure about timing +
+ * replying + session registration; the caller (index.ts) decides whether to
+ * arm it (mode != off AND the client is reply-capable), feeds events in, and
+ * wires `canDefer(sessionID)` into the R6 hook.
+ */
+export declare function createApprovalGate(deps: ApprovalGateDeps): ApprovalGate;
+export {};
+//# sourceMappingURL=approval-gate.d.ts.map

package/dist/approval-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-gate.d.ts","sourceRoot":"","sources":["../src/approval-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAGjD,iFAAiF;AACjF,eAAO,MAAM,uBAAuB,KAAK,CAAA;AAEzC;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAiBpC;0DAC0D;AAC1D,MAAM,MAAM,eAAe,GACvB,KAAK,GACL,cAAc,GACd,gBAAgB,GAChB,UAAU,GACV,kBAAkB,GAClB,UAAU,CAAA;AAEd;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,MAAM,CAQjG;AAED,KAAK,WAAW,GAAG,OAAO,CAAA;AAE1B,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,WAAW,CAAA;IACzD,cAAc,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAA;CAC9C;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAA;IACzC,2EAA2E;IAC3E,KAAK,IAAI,IAAI,CAAA;IACb,2CAA2C;IAC3C,OAAO,IAAI,IAAI,CAAA;IACf,yEAAyE;IACzE,OAAO,IAAI,OAAO,CAAA;IAClB;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACrC;;8DAE0D;IAC1D,UAAU,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IACvC;;;;8EAI0E;IAC1E,mBAAmB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7C;uFACmF;IACnF,aAAa,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;IAC1C,gFAAgF;IAChF,WAAW,IAAI,MAAM,CAAA;CACtB;AA6GD;;qEAEqE;AACrE,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAErE;AAgBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CA6OvE"}

package/dist/approval-gate.js

@@ -0,0 +1,471 @@
+/**
+ * Unified approval gate — Layer 2 (timeout auto-reject) + Layer 3 (SDK
+ * fallback) of the R6 + R2 approval flow.
+ *
+ * The host only shows its official confirmation dialog for command patterns
+ * declared `ask` in an agent's permission config (Layer 1, envprotect.ts).
+ * When a dialog opens it SUSPENDS the tool call and waits for a human; on the
+ * OpenCode DESKTOP that human is present, but a request can also be left
+ * unanswered.  This module owns ONE timer that watches the host permission
+ * events and closes abandoned requests on the safe side.
+ *
+ * REAL host contract (1.18.29, probed live via SSE + the plugin event hook —
+ * see gate-test report-p5):
+ *   permission.asked   → properties = { id, sessionID, permission: "bash",
+ *                        patterns: [<concrete command segment>, …], metadata:
+ *                        { command }, always: [<host's "always" generalization
+ *                        proposal>], tool: { messageID, callID } } — the props
+ *                        carry NO `type` field, and the tool name sits in
+ *                        `permission`.  A props matching one of OUR injected
+ *                        bash ask sets means the dialog is ours: audit "ask",
+ *                        arm the timeout, and — for the R6 env face — mark
+ *                        the session deferrable (canDefer, see below).
+ *   permission.replied → properties = { sessionID, requestID, reply } on the
+ *                        wire, but the plugin-side observer has also seen it
+ *                        with ONLY { sessionID }.  The gate therefore cancels
+ *                        EVERY pending timer of that session on a reply: an
+ *                        already-approved command left on a live timer would
+ *                        get a second reject after the timeout, the SDK call
+ *                        would hit a dead id (4xx) and flip the gate
+ *                        permanently degraded.
+ *
+ * Older/typed spellings (`permission.updated`, `pattern`, `permissionID`,
+ * `response`) keep being accepted — the shipped SDK d.ts still names the
+ * events that way, and some builds omit the reply id entirely (a short
+ * ghost-suppression window per session then absorbs late/duplicate `asked`
+ * replays instead of re-arming a ghost timer).
+ *
+ * Hard rules (HUMAN-approved):
+ *   - the plugin NEVER self-allows: `reply` is fixed to "reject".  The only
+ *     way a gated command runs is a human approving the dialog;
+ *   - on `TM_ENV_PROTECT=off` the gate is not armed (index.ts decides);
+ *   - deferral is SESSION-SCOPED (canDefer): only sessions registered as
+ *     carrying our injected ask set may have env reads passed through —
+ *     registration comes from an exec-role user prompt (the live-proven
+ *     `message.updated` UserMessage{role,agent,sessionID} signal, plus the
+ *     documented `chat.message` hook) or from an R6-env-classified asked
+ *     event.  Stock build/plan sessions never register, so the global R6
+ *     hook keeps hard-throwing there — closing the R6 bypass the global
+ *     `isArmed()` deferral allowed;
+ *   - if the SDK reply FAILS (network/host — including the v1
+ *     `throwOnError:false` envelope resolving with `{ error }`), we cannot
+ *     close the dialog, so the gate flips itself permanently "degraded" —
+ *     the R6 hook stops deferring env reads and hard-throws them again
+ *     (fail-closed), and the event is audited "degraded".
+ *
+ * SDK surface (probed live on 1.18.x): the plugin's `input.client` is the v1
+ * `OpencodeClient`, which has NO `permission` namespace and NO list/create
+ * endpoint; the reply path is the top-level
+ * `postSessionIdPermissionsPermissionId({ path: { id: sessionID,
+ * permissionID }, body: { response } })`.  `client.permission.reply` /
+ * `client.permission.list` are still tried first so a richer host build is
+ * supported, but on v1 they are simply absent and the poll fallback is a
+ * no-op (events are the sole pending signal there).
+ */
+import { ENV_PROTECT_SERVICE, categorizePermission } from "./envprotect.js";
+/** Default timeout, in minutes, before an unanswered dialog is auto-rejected. */
+export const DEFAULT_ASK_TIMEOUT_MIN = 10;
+/**
+ * Hard floor (minutes) for the auto-reject timeout.  Measured live on the
+ * OpenCode Desktop: a `permission.replied` (human answered "once") reaches
+ * the plugin through the host event bus ~120s LATE — a 1-minute timer
+ * therefore fires BEFORE the cancel arrives and auto-rejects the just-
+ * approved request on a dead id (4xx → permanent degraded, the D4
+ * double-reject race).  3 min = observed ~120s lag + margin; in-range
+ * values below the floor clamp UP to it (a longer timeout is always the
+ * safe direction — the dialog just stays open a bit longer).
+ */
+export const MIN_ASK_TIMEOUT_MIN = 3;
+/** Poll cadence (ms) that re-scans pending permissions in case an event was
+ *  missed — only meaningful when the client exposes a list capability. */
+const POLL_INTERVAL_MS = 60 * 1000;
+/** Suppression window (ms) for late/duplicate `permission.asked` replays
+ *  after a `permission.replied` that carried NO permission id.  Ghost timers
+ *  are the degraded-flip poison (dead id → 4xx → permanent degraded); the
+ *  window only sacrifices the timeout for brand-new asks of the same session
+ *  for this short period, never a self-allow. */
+const GHOST_ASK_WINDOW_MS = 60 * 1000;
+/** Cap on the closed-permission-id tombstone set (ids are unique, so the
+ *  set is purely an anti-ghost cache — pruning oldest is sufficient). */
+const MAX_TOMBSTONES = 500;
+/**
+ * Resolve `TM_ASK_TIMEOUT_MIN`.  Unset / blank / non-numeric / <1 / >1440
+ * (24h) fall back to the 10-minute default — a mistyped value can never
+ * disable the timeout or make it absurdly long.  Valid values below the
+ * 3-minute bus-lag floor clamp UP to it (1→3, 2→3; see
+ * `MIN_ASK_TIMEOUT_MIN` for the measured ~120s replied-event lag).
+ */
+export function resolveAskTimeoutMs(env = process.env) {
+    const raw = env.TM_ASK_TIMEOUT_MIN;
+    if (typeof raw !== "string" || raw.trim() === "")
+        return DEFAULT_ASK_TIMEOUT_MIN * 60 * 1000;
+    const n = Number(raw.trim());
+    if (!Number.isFinite(n))
+        return DEFAULT_ASK_TIMEOUT_MIN * 60 * 1000;
+    const min = Math.trunc(n);
+    if (min < 1 || min > 1440)
+        return DEFAULT_ASK_TIMEOUT_MIN * 60 * 1000;
+    return Math.max(min, MIN_ASK_TIMEOUT_MIN) * 60 * 1000;
+}
+/** Best-effort structured audit; a failing log endpoint never breaks the gate. */
+function auditAsk(client, tool, category, verdict) {
+    try {
+        // `app.log({...})` is a METHOD call on `app` — casting the fetched
+        // function and invoking it plain (`(app.log as Fn)({...})`) drops the
+        // SDK `this` exactly like the historic R6 audit bug did, silently
+        // killing every gate audit line (pinned by the this-bound §7 mocks).
+        const app = client?.app;
+        if (!app || typeof app.log !== "function")
+            return;
+        void app.log({
+            body: {
+                level: "warn",
+                service: ENV_PROTECT_SERVICE,
+                message: `${ENV_PROTECT_SERVICE} :: ${tool} :: ${category} :: ${verdict}`,
+            },
+        });
+    }
+    catch {
+        /* audit is best-effort */
+    }
+}
+/**
+ * v1 SDK default is `throwOnError:false` (types/sdk.gen contract): an HTTP
+ * failure — e.g. a 4xx on an already-closed permission id — RESOLVES with an
+ * `{ error }` envelope instead of rejecting.  Unwrapping it into a throw is
+ * what makes the Layer-3 degraded flip actually fire on the real host.
+ */
+function unwrapSdkEnvelope(res) {
+    if (res && typeof res === "object" && "error" in res) {
+        const err = res.error;
+        if (err)
+            throw err;
+    }
+    return res;
+}
+/**
+ * Non-privacy diagnostic appended to a `degraded` audit verdict: the error
+ * CLASS name and host status code only — never message text, request params
+ * or paths (privacy red line).  Handles both thrown Errors and v1 envelope
+ * bodies (`{ error: { name, status | status_code } }`); the name passes an
+ * identifier whitelist so hostile/echoed text can never ride into the log.
+ */
+function errorDiagnostic(err) {
+    const e = err;
+    const name = typeof e?.name === "string" && /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/.test(e.name)
+        ? e.name
+        : "Error";
+    const rawStatus = [e?.status, e?.statusCode, e?.status_code].find((v) => typeof v === "number" && Number.isFinite(v));
+    return ` err=${name}${rawStatus !== undefined ? ` status=${rawStatus}` : ""}`;
+}
+/**
+ * Build the reject closure.  CRITICAL: every SDK endpoint is invoked as a
+ * METHOD (`perm.reply({...})` / `c.post...({...})` — property-access call
+ * sites keep the receiver binding).  Fetching the function first
+ * (`const post = c.post...` then `await post({...})`) drops the SDK `this`,
+ * so EVERY outbound reply died synchronously on the real host — the timer
+ * fired at ask+timeout yet the dialog stayed open and the gate flipped
+ * `degraded` (same regression class as the historic app.log audit bug; the
+ * §7 test mocks now require the binding so it can never come back).
+ */
+function replyCapableFn(client) {
+    const c = client;
+    if (!c)
+        return null;
+    const perm = c.permission;
+    if (perm && typeof perm.reply === "function") {
+        return async (sid, pid) => {
+            // richest host first (permission.reply), reject-only, both param shapes
+            return unwrapSdkEnvelope(
+            // `!` + property-access call site: binding survives, compiler stays happy
+            await perm.reply({ path: { sessionID: sid, id: pid }, body: { response: "reject" } }));
+        };
+    }
+    if (typeof c.postSessionIdPermissionsPermissionId === "function") {
+        return async (sid, pid) => unwrapSdkEnvelope(await c.postSessionIdPermissionsPermissionId({
+            path: { id: sid, permissionID: pid },
+            body: { response: "reject" },
+        }));
+    }
+    return null;
+}
+function listCapableFn(client) {
+    const c = client;
+    const perm = c?.permission;
+    if (perm && typeof perm.list === "function") {
+        // method call on `perm` — `this` must survive (see replyCapableFn note)
+        return async () => await perm.list({});
+    }
+    return null;
+}
+/** True when the client exposes a permission-reply path at all.  index.ts
+ *  arms the gate ONLY for such a client — fail-closed otherwise (no armed
+ *  auto-reject ⇒ the R6 hook keeps hard-throwing every env read). */
+export function hasPermissionReplyCapability(client) {
+    return replyCapableFn(client) !== null;
+}
+/** First string-ish value among the host's several id/response spellings. */
+function str(...values) {
+    for (const v of values) {
+        if (typeof v === "string" && v.trim() !== "")
+            return v.trim();
+    }
+    return undefined;
+}
+/**
+ * Create the approval gate.  It is intentionally pure about timing +
+ * replying + session registration; the caller (index.ts) decides whether to
+ * arm it (mode != off AND the client is reply-capable), feeds events in, and
+ * wires `canDefer(sessionID)` into the R6 hook.
+ */
+export function createApprovalGate(deps) {
+    const { client, timeoutMs } = deps;
+    const timers = deps.timers ?? {
+        // unref() so a pending timeout never, on its own, keeps the host process
+        // alive (same philosophy as the blackboard sweeper's unref'd interval)
+        setTimeoutFn: (cb, ms) => {
+            const t = setTimeout(cb, ms);
+            if (typeof t?.unref === "function")
+                t.unref();
+            return t;
+        },
+        clearTimeoutFn: (h) => clearTimeout(h),
+    };
+    const nowMs = deps.now ?? (() => Date.now());
+    const reply = replyCapableFn(client);
+    const list = listCapableFn(client);
+    const pending = new Map();
+    /** Sessions known to carry our injected ask set (deferral whitelist). */
+    const liveAsk = new Set();
+    /** Permission ids already closed (replied / timed out): a late or
+     *  duplicated `asked` replay for one must never re-arm a ghost timer. */
+    const closedIds = new Set();
+    /** Sessions whose reply carried NO permission id → suppress fresh asks of
+     *  that session briefly (map sid → expiry ms). */
+    const repliedNoId = new Map();
+    /** Sessions blanket-approved for env reads ("always" on an env ask). */
+    const envApprovedSessions = new Set();
+    let armed = true;
+    let degraded = false;
+    let pollHandle = null;
+    function remove(id) {
+        const rec = pending.get(id);
+        if (rec) {
+            timers.clearTimeoutFn(rec.timer);
+            pending.delete(id);
+        }
+        return rec;
+    }
+    function tombstone(id) {
+        closedIds.add(id);
+        if (closedIds.size > MAX_TOMBSTONES) {
+            const oldest = closedIds.values().next().value;
+            if (oldest !== undefined)
+                closedIds.delete(oldest);
+        }
+    }
+    /** True while sid is inside the no-id-reply ghost window. */
+    function ghostSuppressed(sid) {
+        const expiry = repliedNoId.get(sid);
+        if (expiry === undefined)
+            return false;
+        if (expiry <= nowMs()) {
+            repliedNoId.delete(sid);
+            return false;
+        }
+        return true;
+    }
+    async function fireReject(id, cat) {
+        const rec = pending.get(id);
+        if (!rec)
+            return;
+        pending.delete(id);
+        tombstone(id);
+        let ok = false;
+        let errDiag = "";
+        try {
+            if (reply) {
+                // unwrapSdkEnvelope inside `reply` turns the v1 {error} envelope into
+                // a throw; a rejecting transport lands in the same catch.
+                await reply(rec.sid, id);
+                ok = true;
+            }
+        }
+        catch (err) {
+            ok = false;
+            errDiag = errorDiagnostic(err);
+        }
+        if (!ok) {
+            // Layer 3 fallback: we could not close the dialog ⇒ stop trusting the
+            // popup path; the hook reverts to hard-throwing env reads.
+            degraded = true;
+        }
+        // degraded carries the non-privacy error class/status tail (see
+        // errorDiagnostic) so a live-host failure is diagnosable from the log
+        auditAsk(client, "bash", cat, (ok ? "timeout-rejected" : "degraded") + errDiag);
+    }
+    function arm(id, sid, cat) {
+        if (pending.has(id))
+            return;
+        const timer = timers.setTimeoutFn(() => void fireReject(id, cat), timeoutMs);
+        pending.set(id, { sid, cat, timer });
+    }
+    /** Single registration funnel for both event and poll discovery. */
+    function registerAsk(id, sid, cat) {
+        if (!id || !sid)
+            return;
+        if (closedIds.has(id))
+            return; // ghost replay of a closed request
+        if (ghostSuppressed(sid))
+            return; // replied-without-id; assume a replay
+        if (pending.has(id))
+            return;
+        // The R6 ENV face is the deferral proof: only sessions whose dialogs
+        // actually carry our injected env-ask patterns (or an exec-role
+        // chat.message, see registerExecSession) may defer env reads.  Danger
+        // faces never register — stock hosts that ask on `rm` by default must
+        // not gain env deferral.
+        if (cat === "env")
+            liveAsk.add(sid);
+        auditAsk(client, "bash", cat, "ask");
+        arm(id, sid, cat);
+    }
+    async function pollOnce() {
+        if (!list || !armed)
+            return;
+        try {
+            const res = await list();
+            const data = Array.isArray(res) ? res : res?.data;
+            if (Array.isArray(data)) {
+                for (const item of data) {
+                    const props = item?.properties ?? item;
+                    const cat = categorizePermission(props);
+                    if (!cat)
+                        continue;
+                    const p = props;
+                    registerAsk(str(p.id, p.permissionID, p.requestID), str(p.sessionID), cat);
+                }
+            }
+        }
+        catch {
+            /* poll is best-effort */
+        }
+    }
+    function schedulePoll() {
+        pollHandle = timers.setTimeoutFn(() => {
+            void pollOnce().finally(() => {
+                // dispose() during an in-flight poll must not re-arm a zombie chain
+                if (armed)
+                    schedulePoll();
+            });
+        }, POLL_INTERVAL_MS);
+    }
+    function onAsked(props) {
+        if (degraded)
+            return; // auto-reject is broken — do not open new timers
+        const cat = categorizePermission(props);
+        if (!cat)
+            return; // not one of our injected bash asks → leave it to the human
+        registerAsk(str(props.id, props.permissionID, props.requestID), str(props.sessionID), cat);
+    }
+    function onReplied(props) {
+        const sid = str(props.sessionID);
+        const id = str(props.requestID, props.permissionID, props.id);
+        const resp = str(props.reply, props.response);
+        if (id)
+            tombstone(id);
+        // Real 1.18.29 replied props identify the request via `requestID` — and
+        // the plugin-side observer has seen builds carrying ONLY { sessionID }.
+        // Cancel EVERY pending timer of the session either way: an approved
+        // command left timed would fire a reject on a dead id (4xx) and flip the
+        // gate permanently degraded.
+        const affected = [];
+        if (id) {
+            const rec = remove(id);
+            if (rec)
+                affected.push(rec);
+        }
+        for (const [pid, rec] of [...pending]) {
+            if (sid && rec.sid === sid) {
+                pending.delete(pid);
+                timers.clearTimeoutFn(rec.timer);
+                tombstone(pid);
+                affected.push(rec);
+            }
+        }
+        if (!id && sid)
+            repliedNoId.set(sid, nowMs() + GHOST_ASK_WINDOW_MS);
+        for (const rec of affected) {
+            if (!resp)
+                continue; // outcome unknown: cancel silently, never invent a verdict
+            const lower = resp.toLowerCase();
+            const verdict = lower === "reject" ? "rejected"
+                : lower === "always" ? "allowed-always"
+                    : lower === "once" ? "allowed-once"
+                        : "degraded"; // out-of-vocabulary word: record it honestly, not as "rejected"
+            auditAsk(client, "bash", rec.cat, verdict);
+            // "always" on an env-related ask → blanket-approve all env reads for
+            // this session (the host's pattern generalization is too broad, so we
+            // interpret "always" as a session-scoped env approval).
+            if (verdict === "allowed-always" && sid && /^(bash-)?env/.test(rec.cat)) {
+                envApprovedSessions.add(sid);
+            }
+        }
+    }
+    /** Global gate health: armed, not degraded, and the client can reply. */
+    function healthy() {
+        return armed && !degraded && reply !== null;
+    }
+    return {
+        handleEvent(event) {
+            if (!armed)
+                return; // disposed
+            const type = String(event?.type ?? "");
+            const props = event?.properties;
+            if (!props)
+                return;
+            // live host 1.18.29 emits `permission.asked`; the shipped d.ts spells
+            // the same signal `permission.updated` — accept both open spellings
+            if (type === "permission.asked" || type === "permission.updated")
+                onAsked(props);
+            else if (type === "permission.replied")
+                onReplied(props);
+        },
+        start() {
+            // v1 has no list endpoint (`list` is null) — events are the only
+            // pending signal there, so start() is a deliberate no-op on v1.
+            if (!list || !armed)
+                return;
+            schedulePoll();
+        },
+        dispose() {
+            armed = false;
+            if (pollHandle != null)
+                timers.clearTimeoutFn(pollHandle);
+            pollHandle = null;
+            for (const id of [...pending.keys()])
+                remove(id);
+        },
+        isArmed() {
+            return healthy();
+        },
+        canDefer(sessionID) {
+            // bound-method-safe (no `this`): destructure-able by the R6 hook
+            return healthy() && !!sessionID && liveAsk.has(sessionID);
+        },
+        hasLiveAsk(sessionID) {
+            return sessionID ? liveAsk.has(sessionID) : false;
+        },
+        registerExecSession(sessionID) {
+            if (sessionID)
+                liveAsk.add(sessionID);
+        },
+        isEnvApproved(sessionID) {
+            return !!sessionID && envApprovedSessions.has(sessionID);
+        },
+        pendingSize() {
+            return pending.size;
+        },
+    };
+}
+//# sourceMappingURL=approval-gate.js.map

package/dist/approval-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-gate.js","sourceRoot":"","sources":["../src/approval-gate.ts"],"names":[],"mappings":"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"}

package/dist/commands.js

@@ -85,7 +85,7 @@ If no specific scope is given, identify the most recently modified source files
 };
 /* ------------------------------------------------------------------ */
 const teamResearch = {
-    description: "Research a topic — libraries, APIs, best practices, or documentation.",
+    description: "Research a topic — grounded in the local repository (code, configs, installed packages, shipped docs).",
     agent: "researcher",
     template: `Research the following topic and provide actionable findings.
 
@@ -96,9 +96,9 @@ $ARGUMENTS
 1. **Summary** — Key findings in 2-3 sentences.
 2. **Details** — Structured findings with sources.
 3. **Recommendation** — What the team should do, with trade-offs.
-4. **Sources** — Links or file paths consulted.
+4. **Sources** — Local file paths consulted (file:line).
 
-Cite your sources.  Do not fabricate URLs or API details.`,
+Cite your sources with file:line paths.  Do not fabricate APIs or citations.`,
 };
 /* ------------------------------------------------------------------ */
 const teamRun = {