productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/gongNango.js

@@ -0,0 +1,308 @@
+// Gong through Nango (gong-discovery-connector-v0, local worker mode).
+//
+// Nango is the credential broker only (Granola packet D-007, carried by this
+// packet's D-003/D-010): productfoo asks Nango for the company's Gong credential and
+// then talks to Gong's REST API directly, so transcript bytes never transit
+// Nango. Everything here is content-free on every surface productfoo owns: credentials
+// are held in process memory for one command, the Nango connection id is never
+// printed (an opaque `connection_ref` stands in for it), and errors carry a
+// typed code plus a bounded message that never embeds a provider response.
+//
+// Gong API shapes below are beliefs owned by the packet's feasibility task
+// (T-001) and pinned by fixtures in test/discoveryGongRuntime.test.ts; the
+// live dogfood run (T-009) is what promotes them from belief to verified.
+import { createHash } from "node:crypto";
+import { refuseSourceWrite } from "./sourceIngress.js";
+export class GongRuntimeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "GongRuntimeError";
+    }
+}
+// Versioned policy fields (Granola packet R-005): hard ceilings the worker
+// enforces and reports, so a later change is explicit rather than silent.
+export const GONG_POLICY = {
+    policy_version: "gong-local-worker-0.1",
+    max_response_bytes: 8 * 1024 * 1024,
+    fetch_timeout_ms: 90_000,
+    max_model_input_tokens: 100_000,
+    max_list_pages: 5,
+    min_request_interval_ms: 350,
+};
+const GONG_TRANSCRIPT_SCOPE = "api:calls:read:transcript";
+const DEFAULT_NANGO_HOST = "https://api.nango.dev";
+const DEFAULT_GONG_BASE = "https://api.gong.io";
+function nangoConfigured(env) {
+    return Boolean(env.NANGO_SECRET_KEY?.trim() && env.FOO_GONG_NANGO_CONNECTION?.trim());
+}
+function directConfigured(env) {
+    return Boolean(env.FOO_GONG_ACCESS_KEY?.trim() && env.FOO_GONG_ACCESS_KEY_SECRET?.trim());
+}
+export function gongConnectionConfigured(env) {
+    return nangoConfigured(env) || directConfigured(env);
+}
+export function gongCredentialBroker(env) {
+    if (nangoConfigured(env))
+        return "nango";
+    if (directConfigured(env))
+        return "direct";
+    return null;
+}
+function opaqueConnectionRef(integration, connectionId) {
+    return `gong:${createHash("sha256").update(`${integration}\n${connectionId}`).digest("hex").slice(0, 16)}`;
+}
+async function fetchWithTimeout(fetchImpl, url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetchImpl(url, { ...init, signal: controller.signal });
+    }
+    catch (error) {
+        if (controller.signal.aborted)
+            throw new GongRuntimeError("provider_timeout", "the provider did not answer within the fetch ceiling");
+        throw new GongRuntimeError("network", `network failure reaching ${new URL(url).hostname}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+// Reads a response body while counting toward the byte ceiling, so an
+// oversized transcript is dropped before it is ever materialized in full.
+async function readBounded(response, maxBytes) {
+    const declared = Number(response.headers.get("content-length") ?? "0");
+    if (Number.isFinite(declared) && declared > maxBytes)
+        throw new GongRuntimeError("transcript_too_large", "the provider response exceeds the byte ceiling");
+    if (!response.body) {
+        const buffer = await response.arrayBuffer();
+        if (buffer.byteLength > maxBytes)
+            throw new GongRuntimeError("transcript_too_large", "the provider response exceeds the byte ceiling");
+        return new TextDecoder().decode(buffer);
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel().catch(() => undefined);
+            chunks.length = 0;
+            throw new GongRuntimeError("transcript_too_large", "the provider response exceeds the byte ceiling");
+        }
+        chunks.push(value);
+    }
+    return new TextDecoder().decode(Buffer.concat(chunks));
+}
+function parseJson(text, label) {
+    try {
+        const parsed = JSON.parse(text);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new Error("not an object");
+        return parsed;
+    }
+    catch {
+        throw new GongRuntimeError("provider_failure", `${label} returned a response productfoo could not read`);
+    }
+}
+/**
+ * Resolve the company's Gong credential. Nango is the primary broker: it holds
+ * the credential, refreshes it, and is where an administrator revokes it. When
+ * Nango is not configured, an administrator-issued access key and secret set
+ * directly in this runtime's environment (FOO_GONG_ACCESS_KEY /
+ * FOO_GONG_ACCESS_KEY_SECRET) is accepted as the direct fallback — the same
+ * company credential, minus the central refresh and revoke story. Either way
+ * productfoo receives it for one command and never persists or prints it.
+ */
+export async function resolveGongConnection(input) {
+    const broker = gongCredentialBroker(input.env);
+    if (broker === null) {
+        throw new GongRuntimeError("not_connected", "Gong is not connected: set NANGO_SECRET_KEY and FOO_GONG_NANGO_CONNECTION for the company connection through Nango, or FOO_GONG_ACCESS_KEY and FOO_GONG_ACCESS_KEY_SECRET for a direct administrator-issued access key");
+    }
+    if (broker === "direct") {
+        const username = input.env.FOO_GONG_ACCESS_KEY.trim();
+        const password = input.env.FOO_GONG_ACCESS_KEY_SECRET.trim();
+        return {
+            connection_ref: `gong:direct:${createHash("sha256").update(username).digest("hex").slice(0, 16)}`,
+            broker: "direct",
+            credential: { type: "basic", username, password },
+            credential_type: "basic",
+            transcript_scope: "granted",
+        };
+    }
+    const secret = input.env.NANGO_SECRET_KEY.trim();
+    const connectionId = input.env.FOO_GONG_NANGO_CONNECTION.trim();
+    const integration = input.env.FOO_GONG_NANGO_INTEGRATION?.trim() || "gong";
+    const host = (input.env.NANGO_HOST?.trim() || DEFAULT_NANGO_HOST).replace(/\/+$/, "");
+    const url = `${host}/connection/${encodeURIComponent(connectionId)}?provider_config_key=${encodeURIComponent(integration)}`;
+    const response = await fetchWithTimeout(input.fetchImpl, url, { method: "GET", headers: { authorization: `Bearer ${secret}`, accept: "application/json" } }, GONG_POLICY.fetch_timeout_ms);
+    if (response.status === 401 || response.status === 403)
+        throw new GongRuntimeError("not_connected", "Nango refused the secret key; reconnect Gong");
+    if (response.status === 404)
+        throw new GongRuntimeError("not_connected", "Nango has no Gong connection with that reference; connect Gong first");
+    if (!response.ok)
+        throw new GongRuntimeError("provider_failure", `Nango answered ${response.status} while resolving the connection`);
+    const body = parseJson(await readBounded(response, 256 * 1024), "Nango");
+    const credentials = (body.credentials ?? {});
+    const type = String(credentials.type ?? "").toUpperCase();
+    const ref = opaqueConnectionRef(integration, connectionId);
+    if (type === "BASIC") {
+        const username = String(credentials.username ?? "");
+        const password = String(credentials.password ?? "");
+        if (!username || !password)
+            throw new GongRuntimeError("not_connected", "the Nango connection carries no usable Gong access key");
+        return { connection_ref: ref, broker: "nango", credential: { type: "basic", username, password }, credential_type: "basic", transcript_scope: "granted" };
+    }
+    if (type === "OAUTH2") {
+        const token = String(credentials.access_token ?? "");
+        if (!token)
+            throw new GongRuntimeError("auth_expired", "the Nango connection carries no usable Gong access token; refresh or reconnect");
+        const raw = (credentials.raw ?? {});
+        const scopeValue = typeof raw.scope === "string" ? raw.scope : typeof credentials.scope === "string" ? credentials.scope : "";
+        const scopes = scopeValue.split(/[\s,]+/).filter(Boolean);
+        const transcriptScope = scopes.length === 0 ? "unknown" : scopes.includes(GONG_TRANSCRIPT_SCOPE) ? "granted" : "missing";
+        return { connection_ref: ref, broker: "nango", credential: { type: "oauth2", access_token: token }, credential_type: "oauth2", transcript_scope: transcriptScope };
+    }
+    throw new GongRuntimeError("not_connected", "the Nango connection uses a credential type productfoo does not support for Gong");
+}
+const READ_ONLY_POSTS = new Set(["/v2/calls/extensive", "/v2/calls/transcript"]);
+/**
+ * Minimal read-only Gong REST client. Only documented read operations are
+ * reachable; any other method or path routes through the single write-refusal
+ * choke point (R-009) so the refusal is testable rather than scattered.
+ */
+export class GongClient {
+    credential;
+    options;
+    requests = { list: 0, extensive: 0, transcript: 0 };
+    lastRequestAt = 0;
+    baseUrl;
+    sleep;
+    now;
+    fetchTimeoutMs;
+    constructor(credential, options) {
+        this.credential = credential;
+        this.options = options;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_GONG_BASE).replace(/\/+$/, "");
+        this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+        this.now = options.now ?? (() => Date.now());
+        this.fetchTimeoutMs = options.fetchTimeoutMs ?? GONG_POLICY.fetch_timeout_ms;
+    }
+    authorization() {
+        if (this.credential.type === "basic")
+            return `Basic ${Buffer.from(`${this.credential.username}:${this.credential.password}`).toString("base64")}`;
+        return `Bearer ${this.credential.access_token}`;
+    }
+    async request(method, pathname, body, maxBytes = GONG_POLICY.max_response_bytes) {
+        const readOnly = method === "GET" || (method === "POST" && READ_ONLY_POSTS.has(pathname.split("?")[0]));
+        if (!readOnly)
+            refuseSourceWrite(`gong ${method} ${pathname}`);
+        const wait = this.lastRequestAt + GONG_POLICY.min_request_interval_ms - this.now();
+        if (wait > 0)
+            await this.sleep(wait);
+        this.lastRequestAt = this.now();
+        const response = await fetchWithTimeout(this.options.fetchImpl, `${this.baseUrl}${pathname}`, {
+            method,
+            headers: { authorization: this.authorization(), accept: "application/json", ...(body !== undefined ? { "content-type": "application/json" } : {}) },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        }, this.fetchTimeoutMs);
+        if (response.status === 401)
+            throw new GongRuntimeError("auth_expired", "Gong rejected the credential; refresh or reconnect");
+        if (response.status === 403)
+            throw new GongRuntimeError("access_denied", "Gong denied this read; the credential lacks the required permission");
+        if (response.status === 429)
+            throw new GongRuntimeError("budget_exhausted", "Gong rate limit reached; no retry was attempted");
+        if (response.status === 404)
+            throw new GongRuntimeError("provider_failure", "Gong reported the requested record does not exist");
+        if (!response.ok)
+            throw new GongRuntimeError("provider_failure", `Gong answered ${response.status}`);
+        return parseJson(await readBounded(response, maxBytes), "Gong");
+    }
+    /** Bounded metadata listing: one time window, a page ceiling, no content. */
+    async listCalls(window) {
+        const calls = [];
+        let cursor;
+        let pages = 0;
+        for (;;) {
+            if (pages >= GONG_POLICY.max_list_pages)
+                return { calls, pages, truncated: true };
+            const params = new URLSearchParams({ fromDateTime: window.from, toDateTime: window.to });
+            if (window.workspaceId)
+                params.set("workspaceId", window.workspaceId);
+            if (cursor)
+                params.set("cursor", cursor);
+            this.requests.list += 1;
+            const body = await this.request("GET", `/v2/calls?${params.toString()}`, undefined, 4 * 1024 * 1024);
+            pages += 1;
+            for (const entry of Array.isArray(body.calls) ? body.calls : []) {
+                if (!entry || typeof entry.id !== "string")
+                    continue;
+                calls.push({
+                    id: entry.id,
+                    title: typeof entry.title === "string" ? entry.title : undefined,
+                    url: typeof entry.url === "string" ? entry.url : undefined,
+                    scheduled: typeof entry.scheduled === "string" ? entry.scheduled : undefined,
+                    started: typeof entry.started === "string" ? entry.started : undefined,
+                    duration: typeof entry.duration === "number" ? entry.duration : undefined,
+                    workspaceId: typeof entry.workspaceId === "string" ? entry.workspaceId : undefined,
+                });
+            }
+            const records = (body.records ?? {});
+            cursor = typeof records.cursor === "string" && records.cursor ? records.cursor : undefined;
+            if (!cursor)
+                return { calls, pages, truncated: false };
+        }
+    }
+    /** Party metadata for the given calls (names, titles, affiliation, speaker ids) — no content fields are requested. */
+    async parties(callIds) {
+        const out = new Map();
+        for (let index = 0; index < callIds.length; index += 100) {
+            const batch = callIds.slice(index, index + 100);
+            this.requests.extensive += 1;
+            const body = await this.request("POST", "/v2/calls/extensive", {
+                filter: { callIds: batch },
+                contentSelector: { exposedFields: { parties: true } },
+            }, 4 * 1024 * 1024);
+            for (const call of Array.isArray(body.calls) ? body.calls : []) {
+                const meta = (call.metaData ?? {});
+                const id = typeof meta.id === "string" ? meta.id : undefined;
+                if (!id)
+                    continue;
+                const parties = Array.isArray(call.parties) ? call.parties : [];
+                out.set(id, parties.map((party) => ({
+                    name: typeof party.name === "string" ? party.name : undefined,
+                    emailAddress: typeof party.emailAddress === "string" ? party.emailAddress : undefined,
+                    title: typeof party.title === "string" ? party.title : undefined,
+                    affiliation: typeof party.affiliation === "string" ? party.affiliation : undefined,
+                    speakerId: typeof party.speakerId === "string" ? party.speakerId : undefined,
+                })));
+            }
+        }
+        return out;
+    }
+    /**
+     * Exactly one call's transcript (R-007). Gong's transcript operation is
+     * batch-capable; this method refuses to ask for more than one identifier and
+     * a fixture observes that no request ever carries more.
+     */
+    async transcript(callId) {
+        if (!callId || /\s/.test(callId))
+            throw new GongRuntimeError("provider_failure", "a single well-formed call identifier is required");
+        this.requests.transcript += 1;
+        const body = await this.request("POST", "/v2/calls/transcript", { filter: { callIds: [callId] } });
+        const transcripts = Array.isArray(body.callTranscripts) ? body.callTranscripts : [];
+        const own = transcripts.find((entry) => entry.callId === callId);
+        if (!own || !Array.isArray(own.transcript))
+            throw new GongRuntimeError("access_denied", "Gong returned no transcript for the selected call");
+        return own.transcript.map((monologue) => ({
+            speakerId: typeof monologue.speakerId === "string" ? monologue.speakerId : undefined,
+            topic: typeof monologue.topic === "string" ? monologue.topic : undefined,
+            sentences: (Array.isArray(monologue.sentences) ? monologue.sentences : [])
+                .filter((sentence) => typeof sentence.text === "string")
+                .map((sentence) => ({ start: typeof sentence.start === "number" ? sentence.start : undefined, end: typeof sentence.end === "number" ? sentence.end : undefined, text: sentence.text })),
+        }));
+    }
+}

package/dist-public/src/grammarGate.d.ts

@@ -0,0 +1,13 @@
+import { type GrammarFinding } from "./specSections.js";
+export type StagedSpec = {
+    file: string;
+    text: string;
+};
+export declare function decideGrammarGate(staged: StagedSpec[]): Array<{
+    file: string;
+    finding: GrammarFinding;
+}>;
+export declare function runGrammarGate(root: string): {
+    output: string;
+    exitCode: number;
+};

package/dist-public/src/grammarGate.js

@@ -0,0 +1,72 @@
+// packet-grammar-v1 R-005: the commit-time grammar gate, a B2 spec-identity
+// extension. Blocks a STAGED spec.md whose anchors are duplicated or
+// malformed; everything else the lint can say (missing IDs, unparsed
+// candidates) stays advisory in `asp validate` and never gates.
+//
+// Fail direction copies the redact gate's split (guard-redaction.sh): any
+// plumbing failure — git missing, blob unreadable, a bug in the linter —
+// exits 0 with a note, because a broken gate must not brick every commit
+// (V-006); the detection decision itself is fail-closed. It lints staged
+// blobs (`git show :<path>`), never the working tree, so half-staged edits
+// are judged only on what is actually being committed.
+//
+// One channel, said plainly: a pre-commit terminal has no separate agent/user
+// surface, so the denial carries both halves — one calm line of what
+// happened, then the exact fix and the override.
+import { gitRun, gitRunBuffer } from "./gitRun.js";
+import { lintAnchors } from "./specSections.js";
+const BLOCKING = new Set(["grammar.duplicate_id", "grammar.malformed_id"]);
+// Pure decision, side-effect-free: which staged specs carry blocking findings.
+export function decideGrammarGate(staged) {
+    const blocked = [];
+    for (const s of staged) {
+        for (const finding of lintAnchors(s.text)) {
+            if (BLOCKING.has(finding.code))
+                blocked.push({ file: s.file, finding });
+        }
+    }
+    return blocked;
+}
+const SPEC_PATH_RE = /^specs\/[^/]+\/spec\.md$/;
+export function runGrammarGate(root) {
+    try {
+        if (process.env.FOO_ALLOW_GRAMMAR === "1") {
+            return { output: "foo grammar gate — OVERRIDE: FOO_ALLOW_GRAMMAR=1, staged spec.md anchors not checked.\n", exitCode: 0 };
+        }
+        const listed = gitRun(["diff", "--cached", "--name-only", "--diff-filter=ACM", "-z"], { cwd: root });
+        if (!listed.ok) {
+            return { output: "foo grammar gate — skipped: git unavailable, cannot read staged content (fail-open).\n", exitCode: 0 };
+        }
+        const names = listed.stdout.split("\0").filter((n) => SPEC_PATH_RE.test(n));
+        if (names.length === 0)
+            return { output: "", exitCode: 0 };
+        const staged = [];
+        for (const file of names) {
+            const blob = gitRunBuffer(["show", `:${file}`], { cwd: root, maxBuffer: 16 * 1024 * 1024 });
+            if (!blob.ok)
+                continue; // unreadable staged blob — fail-open, skip
+            staged.push({ file, text: blob.stdout.toString("utf8") });
+        }
+        const blocked = decideGrammarGate(staged);
+        if (blocked.length === 0) {
+            return { output: `foo grammar gate — ok: ${staged.length} staged spec.md file(s) well-anchored.\n`, exitCode: 0 };
+        }
+        const byPacket = new Set(blocked.map((b) => b.file.split("/").slice(0, 2).join("/")));
+        const lines = [
+            "foo grammar gate — BLOCKED: a staged spec has ambiguous anchors (B2 spec identity).",
+            "",
+            ...blocked.map((b) => `  ${b.file}:${b.finding.line}  ${b.finding.code} — ${b.finding.detail}`),
+            "",
+            "Canonical form: `### R-001 Title` headings, `- V-001 — text` bullets.",
+            ...[...byPacket].map((p) => `Fix (one paste): foo asp migrate ${p}   — or edit the line named above.`),
+            'Override (deliberate): FOO_ALLOW_GRAMMAR=1 git commit ...',
+            "",
+        ];
+        return { output: lines.join("\n"), exitCode: 1 };
+    }
+    catch (error) {
+        // A bug in the linter must not brick every spec commit (R-005, V-006).
+        const msg = error instanceof Error ? error.message : String(error);
+        return { output: `foo grammar gate — skipped: internal error (fail-open): ${msg}\n`, exitCode: 0 };
+    }
+}

package/dist-public/src/harnessGates.d.ts

@@ -0,0 +1,65 @@
+export type HarnessGateFormat = "claude" | "cursor" | "codex" | "opencode" | "grok";
+/** What the gate can actually intercept in a given harness. Reported honestly, never rounded up. */
+export interface GateCoverage {
+    /** Can we refuse a subagent fan-out? */
+    readonly fanOut: boolean;
+    /** Can we refuse a direct web read? (The behavioural trip needs this.) */
+    readonly webRead: boolean;
+    /** Does a foo crash DENY the user's tool call instead of allowing it? */
+    readonly failsClosed: boolean;
+    /** Does the harness refuse to run a hook it has not been told to trust? */
+    readonly needsTrust: boolean;
+    readonly note?: string;
+}
+export interface HarnessGate {
+    readonly format: HarnessGateFormat;
+    readonly label: string;
+    /** Where the gate config belongs, relative to the repo. */
+    readonly configPath: string;
+    readonly coverage: GateCoverage;
+    /** The config productfoo would write. */
+    render(shim: string): string;
+}
+/**
+ * A denial has TWO audiences, and they are not the same reader.
+ *
+ * The `agent` text is an instruction: the command to run instead, the escape hatch, the
+ * reason the gate fired. It is productfoo's machinery, and the agent is the only one who can act
+ * on any of it. The `user` text is one calm line telling the human what just took over —
+ * because a denial is not a failure, it is foo doing its job, and it should not read like
+ * a crash in their transcript.
+ *
+ * foo used to send one string to both. Every deny therefore printed skill paths, `bin/foo`
+ * invocations and env-var overrides into the user's terminal in red, on a product whose
+ * first rule is that the user never sees the machinery. Cursor's own API had been saying so
+ * the whole time — it asks for `user_message` and `agent_message` separately, and foo handed
+ * it the same string twice.
+ */
+export interface DenialText {
+    /** One line, for the human. No paths, no commands, no env vars, no foo vocabulary. */
+    readonly user: string;
+    /** The instruction, for the agent. Machinery belongs here and only here. */
+    readonly agent: string;
+}
+/**
+ * Render a denial in the shape a given harness understands.
+ *
+ * Returns the stdout to print and the exit code to use. Getting either wrong is a silent
+ * allow — the harness shrugs at output it cannot parse and runs the tool anyway.
+ *
+ * Some harnesses have a second channel for the agent. Where there is
+ * no split, the agent's text is what goes out, because a deny the agent cannot act on just
+ * blocks the work with no route forward — a worse failure than a leaky message. Those gaps
+ * are named below rather than quietly rounded up: productfoo does not report a thing as clean in a
+ * harness where it isn't.
+ */
+export declare function renderDenial(format: HarnessGateFormat, text: DenialText): {
+    stdout: string;
+    exit: number;
+};
+/** An allow. Silence is the safe answer everywhere: no harness treats empty stdout as a deny. */
+export declare const ALLOW: {
+    readonly stdout: "";
+    readonly exit: 0;
+};
+export declare const HARNESS_GATES: readonly HarnessGate[];

package/dist-public/src/harnessGates.js

@@ -0,0 +1,168 @@
+// Supported harness gate adapters share one policy with explicit wire formats.
+// Claude Code and Codex use the same denial schema; Cursor has separate user
+// and agent fields. OpenCode denies by throwing and must fail open on internal
+// errors. Grok Bot coverage remains provisional. Preserve each host's actual
+// coverage rather than claiming every hook can intercept every tool.
+/**
+ * Render a denial in the shape a given harness understands.
+ *
+ * Returns the stdout to print and the exit code to use. Getting either wrong is a silent
+ * allow — the harness shrugs at output it cannot parse and runs the tool anyway.
+ *
+ * Some harnesses have a second channel for the agent. Where there is
+ * no split, the agent's text is what goes out, because a deny the agent cannot act on just
+ * blocks the work with no route forward — a worse failure than a leaky message. Those gaps
+ * are named below rather than quietly rounded up: productfoo does not report a thing as clean in a
+ * harness where it isn't.
+ */
+export function renderDenial(format, text) {
+    switch (format) {
+        case "claude":
+        case "codex":
+            // Codex deliberately mirrors Claude's schema. One shape, two harnesses.
+            // permissionDecisionReason is shown to the USER; additionalContext reaches the MODEL
+            // only, and never renders in the transcript. That is the whole split.
+            return {
+                stdout: JSON.stringify({
+                    hookSpecificOutput: {
+                        hookEventName: "PreToolUse",
+                        permissionDecision: "deny",
+                        permissionDecisionReason: text.user,
+                        additionalContext: text.agent,
+                    },
+                }),
+                exit: 0,
+            };
+        case "cursor":
+            // Two audiences, two fields — as Cursor intended.
+            return {
+                stdout: JSON.stringify({ permission: "deny", user_message: text.user, agent_message: text.agent }),
+                exit: 0,
+            };
+        case "opencode":
+            // OpenCode has no JSON deny channel — the plugin throws. The shim prints the reason
+            // and exits 1; the generated plugin turns that into a throw.
+            return { stdout: text.agent, exit: 1 };
+        case "grok":
+            // Grok Bot wire format provisional — conservatively fail open with no message until verified.
+            // No second channel for now.
+            return { stdout: JSON.stringify({ permission: "deny", reason: text.agent }), exit: 0 };
+    }
+}
+/** An allow. Silence is the safe answer everywhere: no harness treats empty stdout as a deny. */
+export const ALLOW = { stdout: "", exit: 0 };
+export const HARNESS_GATES = [
+    {
+        format: "claude",
+        label: "Claude Code",
+        configPath: ".claude/settings.json",
+        coverage: { fanOut: true, webRead: true, failsClosed: false, needsTrust: false },
+        render: () => "", // already wired by productfoo's existing settings.json
+    },
+    {
+        format: "cursor",
+        label: "Cursor",
+        configPath: ".cursor/hooks.json",
+        coverage: {
+            fanOut: true,
+            webRead: false,
+            failsClosed: false,
+            needsTrust: false,
+            note: "Cursor has no web-search tool to match, so the Nth-read trip cannot fire here — only the fan-out gate does. Reported, not rounded up.",
+        },
+        render: (shim) => `${JSON.stringify({
+            version: 1,
+            hooks: {
+                // Scoped to Task, NOT the unmatched default: Cursor's preToolUse fires for
+                // EVERY tool, and there is no documented default timeout. An unscoped foo hook
+                // would spawn a subprocess on every keystroke-adjacent action the agent takes.
+                subagentStart: [{ command: shim, timeout: 10, failClosed: false }],
+                preToolUse: [{ command: shim, matcher: "Task", timeout: 10, failClosed: false }],
+            },
+        }, null, 2)}\n`,
+    },
+    {
+        format: "codex",
+        label: "Codex",
+        configPath: ".codex/hooks.json",
+        coverage: {
+            fanOut: true,
+            webRead: false,
+            failsClosed: false,
+            needsTrust: true,
+            note: "Codex will NOT run a hook it has not been told to trust, and productfoo cannot self-trust. This is the correct design and productfoo should copy it, not route around it.",
+        },
+        render: (shim) => `${JSON.stringify({
+            description: "foo research gate (B5) — routes web research through `foo research`",
+            hooks: {
+                PreToolUse: [
+                    { matcher: "^(spawn_agent|Agent)$", hooks: [{ type: "command", command: shim, timeout: 10 }] },
+                ],
+            },
+        }, null, 2)}\n`,
+    },
+    {
+        format: "opencode",
+        label: "OpenCode",
+        configPath: ".opencode/plugins/foo-research-gate.ts",
+        coverage: {
+            fanOut: true,
+            webRead: true,
+            failsClosed: true,
+            needsTrust: false,
+            note: "FAIL-CLOSED with NO timeout: an unhandled throw in productfoo's plugin kills every tool call, forever, with no escape. The plugin below swallows every error except a deliberate deny.",
+        },
+        render: (shim) => `// foo research gate (B5). Generated by \`foo agent setup --gate\`. Safe to delete.
+//
+// OpenCode's only deny channel is a throw, it is fail-closed, and it has NO timeout wrapper.
+// So a BUG in foo here is indistinguishable from a foo POLICY to the user: every tool call
+// dies with a stack trace and nothing saves them. Hence the shape below — the try/catch
+// swallows everything except the one throw we mean.
+import { execFileSync } from "node:child_process";
+import type { Plugin } from "@opencode-ai/plugin";
+
+export const FooResearchGate: Plugin = async () => ({
+  "tool.execute.before": async (input: { tool: string }, output: { args: unknown }) => {
+    let denial: string | null = null;
+    try {
+      // execFileSync takes a PATH and an ARGV — it does not split a command string. Passing
+      // "script.sh opencode" as one argument looks for a file with a space in its name, throws
+      // ENOENT, and the catch below fails open: the gate would silently never enforce, while
+      // reporting success. A silent allow is the worst failure this module has, so: argv.
+      execFileSync(${JSON.stringify(shim)}, ["opencode"], {
+        input: JSON.stringify({ tool_name: input.tool, tool_input: output.args }),
+        encoding: "utf8",
+        timeout: 10_000,
+      });
+    } catch (err) {
+      // Exit 1 with a reason IS the deny. Anything else — foo missing, node missing, a bug
+      // in the gate — must fail OPEN, because a gate that blocks every tool call the moment
+      // it breaks is a gate the user rips out, and here they cannot even see why.
+      const e = err as { status?: number; stdout?: string };
+      if (e.status === 1 && e.stdout) denial = String(e.stdout);
+    }
+    if (denial) throw new Error(denial);
+  },
+});
+`,
+    },
+    {
+        format: "grok",
+        label: "Grok Bot",
+        configPath: ".grok/hooks.json",
+        coverage: {
+            fanOut: false,
+            webRead: false,
+            failsClosed: false,
+            needsTrust: false,
+            note: "Grok Bot gate coverage unverified — wire format and hook surface are provisional pending x.ai platform docs. Conservatively reported as no coverage until confirmed.",
+        },
+        render: (shim) => `${JSON.stringify({
+            version: 1,
+            description: "foo research gate (B5) — routes web research through `foo research`",
+            hooks: {
+                preToolUse: [{ command: shim, timeout: 10 }],
+            },
+        }, null, 2)}\n`,
+    },
+];

package/dist-public/src/humanSurfaceEval.d.ts

@@ -0,0 +1,19 @@
+export type HumanSurfaceRule = "HS-001" | "HS-002" | "HS-003" | "HS-004";
+export type HumanSurfaceFinding = {
+    rule: HumanSurfaceRule;
+    line: number;
+    phrase: string;
+    rewrite: string;
+};
+export type HumanSurfaceEvalResult = {
+    ok: boolean;
+    findings: HumanSurfaceFinding[];
+    error?: "empty-input";
+};
+export declare function evaluateHumanSurface(text: string): HumanSurfaceEvalResult;
+export declare function renderHumanSurfaceEval(result: HumanSurfaceEvalResult): string;
+export declare class HumanSurfaceLeakError extends Error {
+    readonly result: HumanSurfaceEvalResult;
+    constructor(result: HumanSurfaceEvalResult);
+}
+export declare function guardHumanSurface(text: string): string;