fix(exec): surface headless gate denials on stderr via onHeadlessDeny

Author: TheGreatAxios

src/exec/runner.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, spyOn, test } from "bun:test";
+import type { ToolCall } from "@intx/types/runtime";
 import type { AgentTool } from "@intx/agent";
 import { submitOutputDefinition } from "../agent/director.js";
 import { DIRECTOR_REGISTRY } from "../agent/directors/registry.js";
@@ -19,7 +20,7 @@ import {
 } from "../auth/codex/session.js";
 import type { Config } from "../config/index.js";
 import { CREDENTIAL_FAILURE_USER_MESSAGE } from "../inference-error-message.js";
-import type { PermissionRequest } from "../permission/types.js";
+import { createPermissionGate } from "../permission/gate.js";
 import {
   clearActiveRun,
   getActiveRun,
@@ -45,7 +46,6 @@ import {
   createExecToolPromoter,
   execUserFailureMessage,
   isExecOverlayToolAllowed,
-  promptPermission,
   refreshSelectedProviderCredential,
   resolveExecDirectorOverlay,
   resolveExecDirectorOverlayForPackage,
@@ -844,13 +844,22 @@ describe("exec permission prompt gating (CL-9002)", () => {
     ).toBe(false);
   });
 
-  test("headless permission seam fails closed with an explicit stderr denial", async () => {
-    const request: PermissionRequest = {
-      tool: "run_shell",
-      action: "Run shell",
-      subject: "rm -rf /tmp/work",
-      scopes: [],
-    };
+  // Exec-identical headless gate wiring: interactive:false with the prompt seam
+  // armed to throw, so a test passes only when decide() denies on the real
+  // production path (the old direct-seam test never went through decide()).
+  const headlessGate = (onDeny: (reason: string) => void) =>
+    createPermissionGate({
+      approvals: [],
+      requestApproval: async () => {
+        throw new Error("headless run must never reach the prompt seam");
+      },
+      interactive: false,
+      onHeadlessDeny: onDeny,
+      skipPermissions: false,
+      reactorGated: true,
+    });
+
+  const captureStdio = () => {
     const errWrites: string[] = [];
     const outWrites: string[] = [];
     const stderrSpy = spyOn(process.stderr, "write").mockImplementation(((
@@ -865,16 +874,89 @@ describe("exec permission prompt gating (CL-9002)", () => {
       outWrites.push(String(chunk));
       return true;
     }) as typeof process.stdout.write);
+    return {
+      errWrites,
+      outWrites,
+      restore: () => {
+        stderrSpy.mockRestore();
+        stdoutSpy.mockRestore();
+      },
+    };
+  };
+
+  test("headless gate deny names the action and remedy on stderr, stdout clean", async () => {
+    const stdio = captureStdio();
     try {
-      const outcome = await promptPermission(request, false);
-      expect(outcome).toEqual({ allow: false });
+      // Same shape as runner.ts: the denial surfaces on stderr, never stdout.
+      const gate = headlessGate((reason) => {
+        process.stderr.write(`Permission denied: ${reason}\n`);
+      });
+      const authorized = await gate.authorizeCall({
+        id: "h1",
+        name: "web_fetch",
+        arguments: { url: "https://example.com/docs", format: "markdown" },
+      } as ToolCall);
+      expect(authorized.effect).toBe("deny");
+      const evaluated = await gate.evaluate({
+        id: "h2",
+        name: "web_fetch",
+        arguments: { url: "https://example.com/other", format: "markdown" },
+      } as ToolCall);
+      expect(evaluated.allowed).toBe(false);
     } finally {
-      stderrSpy.mockRestore();
-      stdoutSpy.mockRestore();
+      stdio.restore();
     }
-    const denial = errWrites.join("");
-    expect(denial).toContain("Run shell");
+    const denial = stdio.errWrites.join("");
+    expect(denial).toContain("Permission denied:");
+    expect(denial).toContain("requires operator approval");
     expect(denial).toContain("--dangerously-skip-permissions");
-    expect(outWrites).toEqual([]);
+    expect(stdio.outWrites).toEqual([]);
+  });
+
+  test("secret-path headless deny names the action without bypass coaching", async () => {
+    const stdio = captureStdio();
+    try {
+      const gate = headlessGate((reason) => {
+        process.stderr.write(`Permission denied: ${reason}\n`);
+      });
+      const verdict = await gate.evaluate({
+        id: "s1",
+        name: "run_shell",
+        arguments: { command: "cat .env" },
+      } as ToolCall);
+      expect(verdict.allowed).toBe(false);
+    } finally {
+      stdio.restore();
+    }
+    const denial = stdio.errWrites.join("");
+    expect(denial).toContain("sensitive path");
+    expect(denial).not.toContain("--dangerously-skip-permissions");
+    expect(stdio.outWrites).toEqual([]);
+  });
+
+  test("piped stdout with a stdin TTY keeps the ask advertised and round-trips", async () => {
+    expect(resolveExecInteractive({ stdinTTY: true, stdoutTTY: false })).toBe(
+      true,
+    );
+    const seen: string[] = [];
+    const gate = createPermissionGate({
+      approvals: [],
+      requestApproval: async (request) => {
+        seen.push(request.subject);
+        return { allow: true };
+      },
+      interactive: true,
+      skipPermissions: false,
+      reactorGated: true,
+    });
+    const call = {
+      id: "i1",
+      name: "web_fetch",
+      arguments: { url: "https://example.com/docs", format: "markdown" },
+    } as ToolCall;
+    const authorized = await gate.authorizeCall(call);
+    expect(authorized.effect).toBe("ask");
+    expect(await gate.evaluate(call)).toEqual({ allowed: true });
+    expect(seen).toEqual(["https://example.com/docs"]);
   });
 });

src/exec/runner.ts

@@ -688,7 +688,7 @@ export async function runExec(config: Config): Promise<ExecResult> {
       model: config.model,
       telemetry: liveTelemetry,
       requestApproval: (request: PermissionRequest): Promise<ApprovalOutcome> =>
-        promptPermission(request, interactive),
+        promptPermission(request),
       getActiveProviderModel: () => `${config.providerName}:${config.model}`,
       onPersistNotice: (text) => {
         stderr.write(`${text}\n`);
@@ -697,6 +697,14 @@ export async function runExec(config: Config): Promise<ExecResult> {
         stderr.write(`${text}\n`);
       },
       interactive,
+      // Headless operator surface: the gate denies without an operator before
+      // ever reaching requestApproval, so the explicit denial lives here —
+      // naming the action and the remedy on stderr (never stdout: piped stdout
+      // may feed JSON consumers). The reason already omits the bypass remedy
+      // on sensitive-path denials; emit it verbatim.
+      onHeadlessDeny: (reason) => {
+        stderr.write(`Permission denied: ${reason}\n`);
+      },
       skipPermissions: config.dangerouslySkipPermissions,
       auto: config.auto,
       // Main session: gating rides the reactor's approval-suspend seam. In
@@ -1415,7 +1423,9 @@ export async function runExec(config: Config): Promise<ExecResult> {
  * stdin and write stderr, so a piped stdout must not disable them: stdin TTY
  * alone means an operator can answer. Fully headless (stdin not a TTY) fails
  * closed — denials name the action and the remedy on stderr instead of
- * prompting. stdoutTTY rides along so the call site stays explicit that a
+ * prompting (gate onHeadlessDeny wiring above, not the prompt seam: the gate
+ * denies headless asks before requestApproval is ever reached). stdoutTTY
+ * rides along so the call site stays explicit that a
  * piped stdout is a supported prompting configuration, not an oversight.
  */
 export function resolveExecInteractive(stdio: {
@@ -1450,22 +1460,9 @@ async function promptOperator(
   }
 }
 
-export async function promptPermission(
+async function promptPermission(
   request: PermissionRequest,
-  interactive: boolean,
 ): Promise<ApprovalOutcome> {
-  if (!interactive) {
-    // Fail closed and say so on stderr (never stdout: piped stdout may feed
-    // JSON consumers — see printResumeHint). A headless ask has no operator
-    // to answer, so the denial names the action and the bypass instead of
-    // vanishing into a generic block. Same sentence as the gate's
-    // non-interactive deny reasons (src/permission/gate.ts) by intent; the
-    // gate stays canonical for model-facing text, this seam for the operator.
-    stderr.write(
-      `Permission denied: ${request.action} requires operator approval, which is unavailable in a non-interactive run. Re-run with --dangerously-skip-permissions to bypass, or narrow the action.\n`,
-    );
-    return { allow: false };
-  }
   // Same freeze-while-deciding contract as the TUI gate: the tool wall-clock
   // budget must not run down while the operator reads the prompt.
   const budget = getToolApprovalBudget();

src/permission/gate.ts

@@ -395,6 +395,13 @@ export interface PermissionGateOptions {
   // No operator is attached (headless). An unresolved "ask" becomes a denial
   // unless skipPermissions is set.
   interactive: boolean;
+  // Headless operator surface: fired with the deny reason when decide() denies
+  // because no operator is attached (the !interactive exits above). Exec wires
+  // it to stderr so the denial names the action and the remedy; gates without
+  // an operator surface omit it and stay silent by construction. The reason
+  // already carries the secret-path distinction (no bypass remedy on
+  // sensitive-path denials), so callers emit it verbatim.
+  onHeadlessDeny?: ((reason: string) => void) | undefined;
   // The --dangerously-skip-permissions escape hatch: auto-allow anything the
   // authorization layer did not already deny.
   skipPermissions: boolean;
@@ -1023,6 +1030,7 @@ export function createPermissionGate(
             ? `${request.action} references a sensitive path and requires operator approval, which is unavailable in a non-interactive run.`
             : `${request.action} requires operator approval, which is unavailable in a non-interactive run. Re-run with --dangerously-skip-permissions to bypass, or narrow the action.`;
           denialMemory.record(stableId, reason);
+          options.onHeadlessDeny?.(reason);
           return { kind: "deny", reason };
         }
 
@@ -1067,6 +1075,7 @@ export function createPermissionGate(
         recordAutoDecision(request.tool, "non-interactive", "deny");
         const reason = `${request.action} requires operator approval, which is unavailable in a non-interactive run. Re-run with --dangerously-skip-permissions to bypass, or narrow the action.`;
         denialMemory.record(stableId, reason);
+        options.onHeadlessDeny?.(reason);
         return { kind: "deny", reason };
       }
 

src/session/assemble-runtime.ts

@@ -265,6 +265,12 @@ export interface SessionGateArgs {
    */
   onPendingProjectGrants?: ((text: string) => void) | undefined;
   interactive: boolean;
+  /**
+   * Headless operator surface (see PermissionGateOptions.onHeadlessDeny):
+   * fired with the deny reason when the gate denies for want of an operator.
+   * Exec writes it to stderr; the TUI omits it.
+   */
+  onHeadlessDeny?: ((reason: string) => void) | undefined;
   skipPermissions: boolean;
   auto?: boolean | undefined;
   /** Route this gate's decisions through the reactor authz seam (main session). */
@@ -308,6 +314,7 @@ export async function assembleSessionGate(
     ),
     approvalLog: createApprovalLog(sessionDir(args.cwd, args.sessionId)),
     interactive: args.interactive,
+    onHeadlessDeny: args.onHeadlessDeny,
     skipPermissions: args.skipPermissions,
     auto: args.auto,
     reactorGated: args.reactorGated,