@vellumai/assistant 0.6.5 → 0.6.6

package/src/tools/browser/cdp-client/__tests__/factory.test.ts

@@ -1058,22 +1058,43 @@ describe("desktop-auto cdp-inspect (macOS)", () => {
     expect(candidates[2].kind).toBe("local");
   });
 
-  test("macOS turn with proxy unavailable skips desktop-auto cdp-inspect (extension intent)", () => {
+  test("macOS turn with registry-routed proxy unavailable skips desktop-auto cdp-inspect (extension intent)", () => {
     const fakeProxy = makeUnavailableProxy();
     const ctx = makeContext({
       conversationId: "macos-proxy-unavailable-no-inspect",
       hostBrowserProxy: fakeProxy,
       transportInterface: "macos",
+      hostBrowserRegistryRouted: true,
     });
 
     const candidates = buildCandidateList(ctx);
 
     // Should only include local -- cdp-inspect is suppressed because extension
-    // transport is expected (proxy exists) but temporarily unavailable.
+    // transport is expected (registry-routed proxy) but temporarily unavailable.
     expect(candidates.length).toBe(1);
     expect(candidates[0].kind).toBe("local");
   });
 
+  test("macOS turn with SSE-backed proxy unavailable still includes desktop-auto cdp-inspect", () => {
+    const fakeProxy = makeUnavailableProxy();
+    const ctx = makeContext({
+      conversationId: "macos-sse-proxy-unavailable-inspect-allowed",
+      hostBrowserProxy: fakeProxy,
+      transportInterface: "macos",
+      // hostBrowserRegistryRouted is NOT set -- SSE-backed proxy
+    });
+
+    const candidates = buildCandidateList(ctx);
+
+    // SSE-backed proxy that is unavailable (non-interactive turn) should NOT
+    // suppress cdp-inspect -- the SSE proxy was never expected to service
+    // browser requests, so cdp-inspect remains available as a fallback.
+    expect(candidates.length).toBe(2);
+    expect(candidates[0].kind).toBe("cdp-inspect");
+    expect(candidates[0].reason).toContain("desktopAuto");
+    expect(candidates[1].kind).toBe("local");
+  });
+
   test("macOS turn with no proxy still includes desktop-auto cdp-inspect", () => {
     const ctx = makeContext({
       conversationId: "macos-no-proxy-inspect-allowed",
@@ -1242,17 +1263,19 @@ describe("desktop-auto cdp-inspect (macOS)", () => {
     expect(candidates[0].kind).toBe("local");
   });
 
-  test("macOS turn with proxy unavailable routes to local without trying cdp-inspect", async () => {
+  test("macOS turn with registry-routed proxy unavailable routes to local without trying cdp-inspect", async () => {
     const fakeProxy = makeUnavailableProxy();
     const ctx = makeContext({
       conversationId: "macos-proxy-unavail-route",
       hostBrowserProxy: fakeProxy,
       transportInterface: "macos",
+      hostBrowserRegistryRouted: true,
     });
 
     const client = getCdpClient(ctx);
 
     // Should go straight to local -- no cdp-inspect candidate inserted
+    // because the registry-routed extension was expected but is unavailable.
     expect(client.kind).toBe("local");
     const result = await client.send<{ ok: boolean; via: string }>(
       "Page.navigate",
@@ -1264,6 +1287,29 @@ describe("desktop-auto cdp-inspect (macOS)", () => {
     client.dispose();
   });
 
+  test("macOS turn with SSE-backed proxy unavailable falls through to cdp-inspect", async () => {
+    const fakeProxy = makeUnavailableProxy();
+    const ctx = makeContext({
+      conversationId: "macos-sse-proxy-unavail-inspect",
+      hostBrowserProxy: fakeProxy,
+      transportInterface: "macos",
+      // hostBrowserRegistryRouted is NOT set -- SSE-backed proxy
+    });
+
+    const client = getCdpClient(ctx);
+
+    // SSE-backed proxy unavailable (non-interactive turn) should NOT
+    // suppress cdp-inspect -- it falls through to desktop-auto cdp-inspect.
+    expect(client.kind).toBe("cdp-inspect");
+    const result = await client.send<{ ok: boolean; via: string }>(
+      "Page.navigate",
+    );
+    expect(result).toEqual({ ok: true, via: "cdp-inspect" });
+    expect(createExtensionCdpClientMock).not.toHaveBeenCalled();
+    expect(createCdpInspectClientMock).toHaveBeenCalledTimes(1);
+    client.dispose();
+  });
+
   test("explicit config cdp-inspect failure does NOT record desktop-auto cooldown", async () => {
     cdpInspectEnabled = true;
 
@@ -1991,3 +2037,100 @@ describe("no-fallback guarantees", () => {
     expect(fallbackLogs.length).toBe(0);
   });
 });
+
+// ── macOS host-browser proxy backend selection ─────────────────────────
+//
+// Verify that macOS turns can use the host browser proxy without requiring
+// extension registry connectivity. When a HostBrowserProxy is provisioned
+// via the SSE sender path (no extension), the factory should select
+// extension as the top candidate (because hostBrowserProxy is available).
+// When both proxy and fallback backends exist, selection is deterministic:
+// extension > cdp-inspect > local.
+
+describe("macOS host-browser proxy without extension registry", () => {
+  beforeEach(() => {
+    createExtensionCdpClientMock.mockClear();
+    createLocalCdpClientMock.mockClear();
+    createCdpInspectClientMock.mockClear();
+    lastExtensionClient = undefined;
+    lastLocalClient = undefined;
+    lastCdpInspectClient = undefined;
+    cdpInspectEnabled = false;
+    desktopAutoConfig = { enabled: true, cooldownMs: 30_000 };
+    _resetDesktopAutoCooldown();
+    logWarnCalls.length = 0;
+    logDebugCalls.length = 0;
+  });
+
+  test("macOS turn with SSE-provisioned hostBrowserProxy selects extension backend", async () => {
+    // Simulates macOS provisioning a HostBrowserProxy via SSE (no extension
+    // registry connection). The proxy is available so extension is selected.
+    const fakeProxy = makeAvailableProxy();
+    const ctx = makeContext({
+      conversationId: "macos-sse-proxy",
+      hostBrowserProxy: fakeProxy,
+      transportInterface: "macos",
+    });
+
+    const client = getCdpClient(ctx);
+
+    expect(client.kind).toBe("extension");
+    const result = await client.send<{ ok: boolean; via: string }>(
+      "Page.navigate",
+      { url: "https://example.com" },
+    );
+    expect(result).toEqual({ ok: true, via: "extension" });
+    expect(createExtensionCdpClientMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("macOS turn with both proxy and cdp-inspect produces deterministic 3-candidate chain", () => {
+    const fakeProxy = makeAvailableProxy();
+    const ctx = makeContext({
+      conversationId: "macos-deterministic",
+      hostBrowserProxy: fakeProxy,
+      transportInterface: "macos",
+    });
+
+    const candidates = buildCandidateList(ctx);
+
+    // Deterministic order: extension > cdp-inspect (desktop-auto) > local
+    expect(candidates.length).toBe(3);
+    expect(candidates[0].kind).toBe("extension");
+    expect(candidates[1].kind).toBe("cdp-inspect");
+    expect(candidates[2].kind).toBe("local");
+  });
+
+  test("macOS turn without proxy falls through to cdp-inspect then local", () => {
+    const ctx = makeContext({
+      conversationId: "macos-no-proxy-fallback",
+      transportInterface: "macos",
+    });
+
+    const candidates = buildCandidateList(ctx);
+
+    // No proxy => skip extension, desktop-auto cdp-inspect + local
+    expect(candidates.length).toBe(2);
+    expect(candidates[0].kind).toBe("cdp-inspect");
+    expect(candidates[1].kind).toBe("local");
+  });
+
+  test("non-macOS interface with proxy still selects extension (unchanged behavior)", async () => {
+    // Verify non-macOS interfaces are unaffected by the macOS host-browser
+    // enablement — proxy presence drives extension selection regardless of
+    // interface.
+    const fakeProxy = makeAvailableProxy();
+    const ctx = makeContext({
+      conversationId: "non-macos-proxy",
+      hostBrowserProxy: fakeProxy,
+      transportInterface: "cli",
+    });
+
+    const client = getCdpClient(ctx);
+
+    expect(client.kind).toBe("extension");
+    const result = await client.send<{ ok: boolean; via: string }>(
+      "Page.navigate",
+    );
+    expect(result).toEqual({ ok: true, via: "extension" });
+  });
+});

package/src/tools/browser/cdp-client/extension-cdp-client.ts

@@ -1,10 +1,30 @@
 import type { HostBrowserProxy } from "../../../daemon/host-browser-proxy.js";
 import { getLogger } from "../../../util/logger.js";
+import type { CdpErrorCode } from "./errors.js";
 import { CdpError } from "./errors.js";
 import type { CdpClientKind, ScopedCdpClient } from "./types.js";
 
 const log = getLogger("extension-cdp-client");
 
+/**
+ * Transport-level error codes that the host_browser dispatcher may
+ * embed in a structured `{ code, message }` error envelope. When the
+ * `code` field of a parsed error object matches one of these values,
+ * the error is classified as `transport_error` so the factory's
+ * failover logic can try the next backend candidate.
+ *
+ * Codes that are NOT in this set are treated as CDP command-level
+ * failures (`cdp_error`) and propagate without failover.
+ */
+const TRANSPORT_ERROR_CODES = new Set([
+  "transport_error",
+  "unreachable",
+  "timeout",
+  "non_loopback",
+  "cdp_session_not_found",
+  "cancelled",
+]);
+
 /**
  * CdpClient backed by HostBrowserProxy. Each `send` becomes a
  * host_browser_request / host_browser_result round-trip over the
@@ -102,11 +122,21 @@ export class ExtensionCdpClient implements ScopedCdpClient {
           typeof (parsedError as { message: unknown }).message === "string" &&
           (parsedError as { message: string }).message) ||
         `CDP error for ${method}`;
+
+      // Detect structured transport error envelopes from the
+      // host_browser dispatcher. When the parsed error object
+      // carries a `code` field that matches a known transport-level
+      // code, classify the error as `transport_error` so the
+      // factory can trigger failover to the next backend candidate.
+      // All other structured errors remain `cdp_error` since they
+      // represent command-level CDP failures that would not benefit
+      // from switching transports.
+      const errorCode = classifyHostBrowserError(parsedError);
       log.debug(
-        { method, params, parsedError },
-        "ExtensionCdpClient: CDP error",
+        { method, params, parsedError, classifiedAs: errorCode },
+        "ExtensionCdpClient: host_browser_result error",
       );
-      throw new CdpError("cdp_error", msg, {
+      throw new CdpError(errorCode, msg, {
         cdpMethod: method,
         cdpParams: params,
         underlying: parsedError,
@@ -139,6 +169,27 @@ export class ExtensionCdpClient implements ScopedCdpClient {
   }
 }
 
+/**
+ * Classify a parsed host_browser_result error envelope as either a
+ * transport-level error (`transport_error`) or a command-level CDP
+ * failure (`cdp_error`).
+ *
+ * Structured envelopes from the host_browser dispatcher carry a
+ * `code` string field (e.g. `"transport_error"`, `"unreachable"`,
+ * `"timeout"`, `"non_loopback"`, `"cdp_session_not_found"`,
+ * `"cancelled"`). When the code matches a known
+ * transport-level value, the error is eligible for factory failover.
+ * All other codes (or missing codes) are treated as CDP command
+ * errors that should propagate without failover.
+ */
+function classifyHostBrowserError(parsed: unknown): CdpErrorCode {
+  if (typeof parsed !== "object" || parsed === null) return "cdp_error";
+  if (!("code" in parsed)) return "cdp_error";
+  const code = (parsed as { code: unknown }).code;
+  if (typeof code !== "string") return "cdp_error";
+  return TRANSPORT_ERROR_CODES.has(code) ? "transport_error" : "cdp_error";
+}
+
 export function createExtensionCdpClient(
   proxy: HostBrowserProxy,
   conversationId: string,

package/src/tools/browser/cdp-client/factory.ts

@@ -349,15 +349,26 @@ export function buildCandidateList(context: ToolContext): BackendCandidate[] {
     cdpInspectConfig.desktopAuto.enabled
   ) {
     // macOS desktop-auto: include cdp-inspect as a candidate unless:
-    // (a) the hostBrowserProxy exists but is temporarily unavailable
-    //     (extension transport expected but transiently disconnected --
-    //     inserting cdp-inspect here would cause a silent takeover), or
+    // (a) the hostBrowserProxy is registry-routed (extension-backed) and
+    //     temporarily unavailable — the extension transport was explicitly
+    //     expected and the disconnection is transient, so inserting
+    //     cdp-inspect would cause a silent takeover. Only applies when
+    //     `hostBrowserRegistryRouted` is true (set when
+    //     `hostBrowserSenderOverride` was wired at turn-start).
+    //     SSE-backed proxies (macOS without an extension connection) that
+    //     report unavailable (e.g. non-interactive turns where
+    //     clientConnected=false) should NOT suppress cdp-inspect — the
+    //     SSE proxy was never expected to service browser requests.
     // (b) the cooldown from a recent failure is still active.
     //
     // When no hostBrowserProxy is present at all (extension not
     // provisioned for this conversation), cdp-inspect remains available
     // as a fallback per the desktop-auto contract.
-    if (hostBrowserProxy && !hostBrowserProxy.isAvailable()) {
+    if (
+      hostBrowserProxy &&
+      !hostBrowserProxy.isAvailable() &&
+      context.hostBrowserRegistryRouted
+    ) {
       log.debug(
         { conversationId },
         "CDP factory: desktop-auto cdp-inspect skipped (extension transport expected but temporarily unavailable)",

package/src/tools/executor.ts

@@ -1,11 +1,18 @@
 import { readFileSync } from "node:fs";
 
+import { parseChannelId } from "../channels/types.js";
 import { getConfig } from "../config/loader.js";
 import { bridgeCesApproval } from "../credential-execution/approval-bridge.js";
 import { isCesShellLockdownEnabled } from "../credential-execution/feature-gates.js";
-import { getHookManager } from "../hooks/manager.js";
 import { PermissionPrompter } from "../permissions/prompter.js";
 import { RiskLevel } from "../permissions/types.js";
+import { runPipeline } from "../plugins/pipeline.js";
+import { getMiddlewaresFor } from "../plugins/registry.js";
+import type {
+  ToolExecuteArgs,
+  ToolExecuteResult,
+  TurnContext,
+} from "../plugins/types.js";
 import { isUntrustedTrustClass } from "../runtime/actor-trust-resolver.js";
 import { redactSensitiveFields } from "../security/redaction.js";
 import { TokenExpiredError } from "../security/token-manager.js";
@@ -46,6 +53,59 @@ export class ToolExecutor {
     name: string,
     input: Record<string, unknown>,
     context: ToolContext,
+    /**
+     * Optional per-turn context threaded in by the agent loop. Production
+     * sites propagate the orchestrator-built `TurnContext` (real
+     * `conversationId`, trust cascade, attached `contextWindowManager`) so
+     * middleware registered on the `toolExecute` pipeline sees the same
+     * context every other pipeline slot uses. When omitted (CLI/test
+     * invocations that call `ToolExecutor.execute` directly), the executor
+     * synthesizes a fallback context from the {@link ToolContext}, which
+     * keeps pre-threading behavior intact for legacy callers.
+     */
+    turnContext?: TurnContext,
+  ): Promise<ToolExecutionResult> {
+    // Prefer the orchestrator-supplied `turnContext` so the pipeline sees
+    // the real conversation identity, per-turn trust, and context-window
+    // manager. When absent (CLI / test invocations that bypass the agent
+    // loop), synthesize a minimal context from the `ToolContext` — the
+    // same fallback the executor has used since the pipeline was added.
+    const turnCtx: TurnContext = turnContext ?? {
+      requestId: context.requestId ?? "",
+      conversationId: context.conversationId,
+      turnIndex: 0,
+      trust: {
+        sourceChannel: parseChannelId(context.executionChannel) ?? "vellum",
+        trustClass: context.trustClass,
+      },
+    };
+
+    const middlewares = getMiddlewaresFor("toolExecute");
+    const pipelineArgs: ToolExecuteArgs = { name, input, context };
+
+    // No pipeline-level timeout: `executeInternal` already wraps the real
+    // tool invocation in `executeWithTimeout`, which is the sole enforcer
+    // of the per-tool budget. Propagating `perToolTimeoutMs` to
+    // `runPipeline` made the pipeline race everything upstream of the
+    // tool call — permission checks, approval waits, middleware — against
+    // the same budget, so a slow human clicking "allow" produced a
+    // `PluginTimeoutError` thrown past `executeInternal`'s catch block,
+    // breaking the `execute()` never-throws contract. Letting the pipeline
+    // run untimed keeps the contract intact; runaway middleware is a
+    // plugin-health concern handled by per-plugin timeouts, not here.
+    return runPipeline<ToolExecuteArgs, ToolExecuteResult>(
+      "toolExecute",
+      middlewares,
+      (args) => this.executeInternal(args.name, args.input, args.context),
+      pipelineArgs,
+      turnCtx,
+    );
+  }
+
+  private async executeInternal(
+    name: string,
+    input: Record<string, unknown>,
+    context: ToolContext,
   ): Promise<ToolExecutionResult> {
     const startTime = Date.now();
     let decision = "allow";
@@ -112,6 +172,14 @@ export class ToolExecutor {
       // Exception: requireFreshApproval tools always go through the
       // permission check even when a grant was consumed - the grant does
       // not substitute for an interactive human review.
+      let permRiskMeta:
+        | {
+            riskLevel: string;
+            riskReason: string;
+            riskScopeOptions: Array<{ pattern: string; label: string }>;
+            isContainerized?: boolean;
+          }
+        | undefined;
       if (!gateResult.grantConsumed || context.requireFreshApproval) {
         // Check permissions via the extracted PermissionChecker
         const permResult = await this.permissionChecker.checkPermission(
@@ -121,16 +189,23 @@ export class ToolExecutor {
           context,
           executionTarget,
           (event) => emitLifecycleEvent(context, event),
-          sanitizeToolInput,
           startTime,
           computePreviewDiff,
         );
 
         riskLevel = permResult.riskLevel;
         decision = permResult.decision;
+        permRiskMeta = permResult.riskMeta;
 
         if (!permResult.allowed) {
-          return { content: permResult.content, isError: true };
+          return {
+            content: permResult.content,
+            isError: true,
+            riskLevel: permRiskMeta?.riskLevel,
+            riskReason: permRiskMeta?.riskReason,
+            riskScopeOptions: permRiskMeta?.riskScopeOptions,
+            isContainerized: permRiskMeta?.isContainerized,
+          };
         }
 
         if (permResult.wasPrompted) {
@@ -138,59 +213,11 @@ export class ToolExecutor {
         }
       }
 
-      const hookResult = await getHookManager().trigger("pre-tool-execute", {
-        toolName: name,
-        input: sanitizeToolInput(name, input),
-        riskLevel,
-        decision,
-        workingDir: context.workingDir,
-        conversationId: context.conversationId,
-      });
-
-      if (hookResult.blocked) {
-        const msg = `Tool execution blocked by hook "${hookResult.blockedBy}"`;
-        const durationMs = Date.now() - startTime;
-        emitLifecycleEvent(context, {
-          type: "error",
-          toolName: name,
-          executionTarget,
-          input,
-          workingDir: context.workingDir,
-          conversationId: context.conversationId,
-          requestId: context.requestId,
-          riskLevel,
-          decision: "blocked",
-          durationMs,
-          errorMessage: msg,
-          isExpected: true,
-          errorCategory: "tool_failure",
-        });
-        return { content: msg, isError: true };
-      }
-
-      // Execute the tool - proxy tools delegate to an external resolver
+      // Execute the tool - proxy tools delegate to an external resolver.
+      // Use the shared per-tool timeout helper so the pipeline runner and
+      // the inner execute-with-timeout wrapper agree on the same budget.
       let execResult: ToolExecutionResult;
-      let toolTimeoutMs: number;
-      if (name === "bash" || name === "host_bash") {
-        // Shell tools manage their own timeouts (SIGKILL on expiry).
-        // Compute the same effective timeout so the executor wrapper
-        // doesn't prematurely kill them with the generic toolExecutionTimeoutSec.
-        const { shellDefaultTimeoutSec, shellMaxTimeoutSec } =
-          getConfig().timeouts;
-        const requestedSec =
-          typeof input.timeout_seconds === "number"
-            ? input.timeout_seconds
-            : shellDefaultTimeoutSec;
-        const shellTimeoutSec = Math.max(
-          1,
-          Math.min(requestedSec, shellMaxTimeoutSec),
-        );
-        // Buffer so the shell's own timeout fires first and handles cleanup
-        toolTimeoutMs = (shellTimeoutSec + 5) * 1000;
-      } else {
-        const rawTimeoutSec = getConfig().timeouts.toolExecutionTimeoutSec;
-        toolTimeoutMs = safeTimeoutMs(rawTimeoutSec);
-      }
+      const toolTimeoutMs = computePerToolTimeoutMs(name, input);
 
       const execContext = context;
 
@@ -364,7 +391,6 @@ export class ToolExecutor {
         decision,
         startTime,
         emitLifecycleEvent,
-        sanitizeToolInput,
       );
       if (secretResult.earlyReturn) {
         return secretResult.result;
@@ -388,14 +414,18 @@ export class ToolExecutor {
         result: safeResult,
       });
 
-      void getHookManager().trigger("post-tool-execute", {
-        toolName: name,
-        input: sanitizeToolInput(name, input),
-        riskLevel,
-        isError: execResult.isError,
-        durationMs,
-        conversationId: context.conversationId,
-      });
+      // Merge risk metadata from the classifier assessment cache onto the
+      // tool result so downstream consumers (AgentEvent → handleToolResult →
+      // ToolResult SSE message) can forward it to the client.
+      if (permRiskMeta) {
+        execResult = {
+          ...execResult,
+          riskLevel: permRiskMeta.riskLevel,
+          riskReason: permRiskMeta.riskReason,
+          riskScopeOptions: permRiskMeta.riskScopeOptions,
+          isContainerized: permRiskMeta.isContainerized,
+        };
+      }
 
       return execResult;
     } catch (err) {
@@ -446,15 +476,6 @@ export class ToolExecutor {
         errorStack: err instanceof Error ? err.stack : undefined,
       });
 
-      void getHookManager().trigger("post-tool-execute", {
-        toolName: name,
-        input: sanitizeToolInput(name, input),
-        riskLevel,
-        isError: true,
-        durationMs,
-        conversationId: context.conversationId,
-      });
-
       if (isExpected) {
         return { content: msg, isError: true };
       }
@@ -474,7 +495,38 @@ export { isSideEffectTool } from "./side-effects.js";
 export { PermissionChecker } from "./permission-checker.js";
 
 /**
- * Sanitize tool inputs before they are emitted in lifecycle events and hooks.
+ * Compute the effective per-tool execution timeout in milliseconds.
+ *
+ * Shell tools (`bash`, `host_bash`) manage their own timeouts with SIGKILL
+ * on expiry. We add a 5s buffer so the shell's own deadline fires first and
+ * handles cleanup before the executor wrapper trips. Non-shell tools use
+ * the generic `toolExecutionTimeoutSec` configuration value.
+ *
+ * Consumed by `executeInternal` via `executeWithTimeout`, which is the
+ * sole enforcer of the per-tool budget.
+ */
+function computePerToolTimeoutMs(
+  name: string,
+  input: Record<string, unknown>,
+): number {
+  if (name === "bash" || name === "host_bash") {
+    const { shellDefaultTimeoutSec, shellMaxTimeoutSec } = getConfig().timeouts;
+    const requestedSec =
+      typeof input.timeout_seconds === "number"
+        ? input.timeout_seconds
+        : shellDefaultTimeoutSec;
+    const shellTimeoutSec = Math.max(
+      1,
+      Math.min(requestedSec, shellMaxTimeoutSec),
+    );
+    return (shellTimeoutSec + 5) * 1000;
+  }
+  const rawTimeoutSec = getConfig().timeouts.toolExecutionTimeoutSec;
+  return safeTimeoutMs(rawTimeoutSec);
+}
+
+/**
+ * Sanitize tool inputs before they are emitted in lifecycle events.
  * Applies recursive field-level redaction for known-sensitive keys.
  */
 function sanitizeToolInput(

package/src/tools/network/script-proxy/session-manager.ts

@@ -81,6 +81,36 @@ const ALLOWED_HOST_PATTERNS: readonly string[] = (() => {
   return defaults;
 })();
 
+/**
+ * Non-sensitive HTTP request headers that are safe to surface in the
+ * `network_request` approval prompt. Strict allowlist to keep Authorization,
+ * Cookie, X-Api-Key, and other custom credential-bearing headers off-screen.
+ */
+const APPROVAL_HEADER_ALLOWLIST: readonly string[] = [
+  "content-type",
+  "content-length",
+  "user-agent",
+  "accept",
+];
+
+/**
+ * Project an incoming header map onto {@link APPROVAL_HEADER_ALLOWLIST},
+ * collapsing multi-value arrays to a comma-joined string. Returns undefined
+ * when no headers are available (e.g. HTTPS CONNECT path).
+ */
+function filterApprovalHeaders(
+  raw: Record<string, string | string[] | undefined> | undefined,
+): Record<string, string> | undefined {
+  if (!raw) return undefined;
+  const out: Record<string, string> = {};
+  for (const key of APPROVAL_HEADER_ALLOWLIST) {
+    const value = raw[key];
+    if (value === undefined) continue;
+    out[key] = Array.isArray(value) ? value.join(", ") : value;
+  }
+  return out;
+}
+
 /**
  * Returns `true` when `hostname` matches any entry in
  * {@link ALLOWED_HOST_PATTERNS}.
@@ -292,12 +322,16 @@ function buildSessionStartHooks(): SessionStartHooks {
         return allKnownCache;
       }
 
-      // Build the policy callback for HTTP/CONNECT request gating
+      // Build the policy callback for HTTP/CONNECT request gating.
+      // `method` / `reqHeaders` are populated for plain-HTTP proxied requests
+      // and undefined for HTTPS CONNECT tunnels (TLS not yet terminated).
       const policyCallback: PolicyCallback = async (
         hostname: string,
         port: number | null,
         reqPath: string,
         scheme: "http" | "https",
+        method?: string,
+        reqHeaders?: Record<string, string | string[] | undefined>,
       ) => {
         if (isAllowedHost(hostname)) {
           log.debug({ hostname }, "Allowing always-permitted host");
@@ -356,6 +390,8 @@ function buildSessionStartHooks(): SessionStartHooks {
               const approved = await managed.approvalCallback({
                 decision,
                 sessionId: managed.session.id,
+                method,
+                requestHeaders: filterApprovalHeaders(reqHeaders),
               });
               return approved ? {} : null;
             }