@vellumai/assistant 0.6.4 → 0.6.6

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,72 +189,35 @@ 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,
+          };
         }
-      }
 
-      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 };
+        if (permResult.wasPrompted) {
+          context.approvedViaPrompt = 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;
 
@@ -360,7 +391,6 @@ export class ToolExecutor {
         decision,
         startTime,
         emitLifecycleEvent,
-        sanitizeToolInput,
       );
       if (secretResult.earlyReturn) {
         return secretResult.result;
@@ -384,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) {
@@ -442,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 };
       }
@@ -470,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/filesystem/write.ts

@@ -1,11 +1,35 @@
+import { join, resolve, sep } from "node:path";
+
+import { enqueuePkbIndexJob } from "../../memory/jobs/embed-pkb-file.js";
+import { PKB_WORKSPACE_SCOPE } from "../../memory/pkb/types.js";
 import { RiskLevel } from "../../permissions/types.js";
 import type { ToolDefinition } from "../../providers/types.js";
+import { getLogger } from "../../util/logger.js";
+import { getWorkspaceDir } from "../../util/platform.js";
 import { registerTool } from "../registry.js";
 import { FileSystemOps } from "../shared/filesystem/file-ops-service.js";
 import { formatWriteSummary } from "../shared/filesystem/format-diff.js";
 import { sandboxPolicy } from "../shared/filesystem/path-policy.js";
 import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 
+const logger = getLogger("file-write");
+
+/**
+ * Returns `true` iff `absPath` is an absolute path that resolves strictly
+ * inside `pkbRoot`. Matches the containment semantics used elsewhere in the
+ * daemon (e.g. `pkb-context-tracker`): a root-with-separator prefix check,
+ * guarding against `<root>siblingDir` false positives.
+ */
+function isInsidePkbRoot(absPath: string, pkbRoot: string): boolean {
+  const normalizedRoot = resolve(pkbRoot);
+  const normalized = resolve(absPath);
+  if (normalized === normalizedRoot) return false;
+  const rootWithSep = normalizedRoot.endsWith(sep)
+    ? normalizedRoot
+    : normalizedRoot + sep;
+  return normalized.startsWith(rootWithSep);
+}
+
 class FileWriteTool implements Tool {
   name = "file_write";
   description =
@@ -86,6 +110,34 @@ class FileWriteTool implements Tool {
     }
 
     const { filePath, oldContent, newContent, isNewFile } = result.value;
+
+    // If the write landed inside the workspace PKB root, enqueue a
+    // fire-and-forget re-index job so Qdrant stays in sync with on-disk
+    // content. Failures here must never surface to the caller — a file
+    // was written successfully and that is the user-facing contract.
+    try {
+      const pkbRoot = join(getWorkspaceDir(), "pkb");
+      // Gate on `.md` to match `scanPkbFiles`, which only walks markdown.
+      // Indexing `pkb/*.json` (or any other extension) here would produce
+      // chunks the reconciler can't see, leading to orphaned vectors and
+      // pointless embedding work.
+      if (filePath.toLowerCase().endsWith(".md") && isInsidePkbRoot(filePath, pkbRoot)) {
+        enqueuePkbIndexJob({
+          pkbRoot,
+          absPath: filePath,
+          memoryScopeId: PKB_WORKSPACE_SCOPE,
+        });
+      }
+    } catch (err) {
+      logger.warn(
+        {
+          filePath,
+          error: err instanceof Error ? err.message : String(err),
+        },
+        "Failed to enqueue PKB re-index job after file_write",
+      );
+    }
+
     return {
       content: `Successfully wrote to ${filePath} ${formatWriteSummary(
         oldContent,

package/src/tools/host-terminal/host-shell.ts

@@ -31,6 +31,18 @@ import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 
 const log = getLogger("host-shell-tool");
 
+const HOST_BASH_PROXY_ENV_KEYS = [
+  // Preserve per-instance routing so nested `assistant` CLI commands invoked
+  // over host_bash proxy target the same daemon/socket as the origin turn.
+  "BASE_DATA_DIR",
+  "VELLUM_WORKSPACE_DIR",
+  // Keep legacy/diagnostic workspace + environment context aligned.
+  "VELLUM_DATA_DIR",
+  "VELLUM_ENVIRONMENT",
+  // Preserve local control-plane routing when nested commands call APIs.
+  "INTERNAL_GATEWAY_BASE_URL",
+] as const;
+
 function buildHostShellEnv(): Record<string, string> {
   const env = buildSanitizedEnv();
   // Ensure ~/.local/bin and ~/.bun/bin are in PATH so `vellum` and `bun` are
@@ -46,6 +58,29 @@ function buildHostShellEnv(): Record<string, string> {
   return env;
 }
 
+function buildHostBashProxyEnv(
+  hostLockdownActive: boolean,
+  conversationId: string,
+): Record<string, string> {
+  const env: Record<string, string> = {};
+
+  for (const key of HOST_BASH_PROXY_ENV_KEYS) {
+    const value = process.env[key];
+    if (value != null && value.length > 0) {
+      env[key] = value;
+    }
+  }
+
+  if (hostLockdownActive) {
+    env.VELLUM_UNTRUSTED_SHELL = "1";
+  }
+
+  // Keep nested `assistant` CLI calls in host_bash aligned with the
+  // originating conversation so browser IPC can resolve live proxy context.
+  env.__CONVERSATION_ID = conversationId;
+  return env;
+}
+
 class HostShellTool implements Tool {
   name = "host_bash";
   description =
@@ -150,11 +185,13 @@ class HostShellTool implements Tool {
         1,
         Math.min(rawSec, shellMaxTimeoutSec),
       );
-      // Propagate VELLUM_UNTRUSTED_SHELL to the proxied client so CLI
-      // commands self-deny raw-secret flows even when executed remotely.
-      const proxyEnv: Record<string, string> | undefined = hostLockdownActive
-        ? { VELLUM_UNTRUSTED_SHELL: "1" }
-        : undefined;
+      // Forward instance-routing env vars so nested `assistant` CLI commands
+      // executed on a proxied host machine can still resolve the correct
+      // daemon IPC socket and workspace, plus lockdown marker when required.
+      const proxyEnv = buildHostBashProxyEnv(
+        hostLockdownActive,
+        context.conversationId,
+      );
       return context.hostBashProxy.request(
         {
           command,
@@ -199,6 +236,9 @@ class HostShellTool implements Tool {
       if (hostLockdownActive) {
         hostEnv.VELLUM_UNTRUSTED_SHELL = "1";
       }
+      // Match `bash` tool behavior so nested assistant CLI calls can bind to
+      // the active conversation when running through host_bash.
+      hostEnv.__CONVERSATION_ID = context.conversationId;
 
       const child = spawn("bash", ["-c", "--", command], {
         cwd: workingDir,

package/src/tools/memory/register.test.ts

@@ -0,0 +1,185 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  mock,
+  test,
+} from "bun:test";
+
+import { PKB_WORKSPACE_SCOPE } from "../../memory/pkb/types.js";
+import type { ToolContext } from "../types.js";
+
+let tmpWorkspace: string;
+let previousWorkspaceEnv: string | undefined;
+
+// Track calls to enqueuePkbIndexJob so we can assert remember wires writes
+// through to the re-index queue. Declared at module scope so the mock.module
+// factory (hoisted) can close over it.
+const enqueueCalls: Array<{
+  pkbRoot: string;
+  absPath: string;
+  memoryScopeId: string;
+}> = [];
+let enqueueShouldThrow = false;
+
+mock.module("../../memory/jobs/embed-pkb-file.js", () => ({
+  enqueuePkbIndexJob: (input: {
+    pkbRoot: string;
+    absPath: string;
+    memoryScopeId: string;
+  }) => {
+    enqueueCalls.push(input);
+    if (enqueueShouldThrow) {
+      throw new Error("simulated enqueue failure");
+    }
+    return "job-mock-id";
+  },
+}));
+
+beforeAll(() => {
+  tmpWorkspace = mkdtempSync(join(tmpdir(), "remember-tool-test-"));
+  previousWorkspaceEnv = process.env.VELLUM_WORKSPACE_DIR;
+  process.env.VELLUM_WORKSPACE_DIR = tmpWorkspace;
+});
+
+afterAll(() => {
+  if (previousWorkspaceEnv === undefined) {
+    delete process.env.VELLUM_WORKSPACE_DIR;
+  } else {
+    process.env.VELLUM_WORKSPACE_DIR = previousWorkspaceEnv;
+  }
+  rmSync(tmpWorkspace, { recursive: true, force: true });
+});
+
+// Import after the env var is set so getWorkspaceDir() resolves to the tmpdir.
+const { rememberTool } = await import("./register.js");
+
+function makeContext(overrides: Partial<ToolContext> = {}): ToolContext {
+  return {
+    workingDir: tmpWorkspace,
+    conversationId: "test-conversation",
+    trustClass: "guardian",
+    ...overrides,
+  };
+}
+
+describe("rememberTool.execute — finish_turn", () => {
+  test("omits yieldToUser when finish_turn is not provided", async () => {
+    const result = await rememberTool.execute(
+      { content: "no finish_turn provided" },
+      makeContext(),
+    );
+    expect(result.isError).toBe(false);
+    expect(result.yieldToUser).toBeUndefined();
+  });
+
+  test("omits yieldToUser when finish_turn is false", async () => {
+    const result = await rememberTool.execute(
+      { content: "finish_turn=false", finish_turn: false },
+      makeContext(),
+    );
+    expect(result.isError).toBe(false);
+    expect(result.yieldToUser).toBeUndefined();
+  });
+
+  test("sets yieldToUser=true when finish_turn is true", async () => {
+    const result = await rememberTool.execute(
+      { content: "finish_turn=true", finish_turn: true },
+      makeContext(),
+    );
+    expect(result.isError).toBe(false);
+    expect(result.yieldToUser).toBe(true);
+  });
+
+  test("sets yieldToUser=true even when the write fails (empty content)", async () => {
+    const result = await rememberTool.execute(
+      { content: "", finish_turn: true },
+      makeContext(),
+    );
+    expect(result.isError).toBe(true);
+    expect(result.yieldToUser).toBe(true);
+  });
+});
+
+describe("rememberTool.execute — PKB re-index enqueue", () => {
+  beforeEach(() => {
+    enqueueCalls.length = 0;
+    enqueueShouldThrow = false;
+  });
+
+  test("enqueues re-index jobs for both buffer and daily archive paths", async () => {
+    const result = await rememberTool.execute(
+      { content: "index me please" },
+      // Passes a non-default per-conversation scopeId to prove the PKB
+      // enqueue ignores it and pins to PKB_WORKSPACE_SCOPE instead.
+      makeContext({ memoryScopeId: "scope-enqueue" }),
+    );
+    expect(result.isError).toBe(false);
+
+    const pkbRoot = join(tmpWorkspace, "pkb");
+    const bufferPath = join(pkbRoot, "buffer.md");
+
+    // Archive path is dated; derive from today's date the same way
+    // handleRemember does.
+    const now = new Date();
+    const yyyy = now.getFullYear();
+    const mm = String(now.getMonth() + 1).padStart(2, "0");
+    const dd = String(now.getDate()).padStart(2, "0");
+    const archivePath = join(pkbRoot, "archive", `${yyyy}-${mm}-${dd}.md`);
+
+    expect(enqueueCalls).toHaveLength(2);
+    expect(enqueueCalls[0]).toEqual({
+      pkbRoot,
+      absPath: bufferPath,
+      memoryScopeId: PKB_WORKSPACE_SCOPE,
+    });
+    expect(enqueueCalls[1]).toEqual({
+      pkbRoot,
+      absPath: archivePath,
+      memoryScopeId: PKB_WORKSPACE_SCOPE,
+    });
+  });
+
+  test("does not enqueue when content is empty (write was skipped)", async () => {
+    const result = await rememberTool.execute(
+      { content: "   " },
+      makeContext({ memoryScopeId: "scope-empty" }),
+    );
+    expect(result.isError).toBe(true);
+    expect(enqueueCalls).toHaveLength(0);
+  });
+
+  test("thrown enqueue does not surface; remember still writes files", async () => {
+    enqueueShouldThrow = true;
+
+    const result = await rememberTool.execute(
+      { content: "enqueue will throw" },
+      makeContext({ memoryScopeId: "scope-throw" }),
+    );
+
+    // Remember call succeeded despite enqueue throwing for each write.
+    expect(result.isError).toBe(false);
+
+    // Both writes attempted their enqueue.
+    expect(enqueueCalls).toHaveLength(2);
+
+    // Files were written correctly.
+    const pkbRoot = join(tmpWorkspace, "pkb");
+    const bufferPath = join(pkbRoot, "buffer.md");
+    const bufferContents = readFileSync(bufferPath, "utf-8");
+    expect(bufferContents).toContain("enqueue will throw");
+
+    const now = new Date();
+    const yyyy = now.getFullYear();
+    const mm = String(now.getMonth() + 1).padStart(2, "0");
+    const dd = String(now.getDate()).padStart(2, "0");
+    const archivePath = join(pkbRoot, "archive", `${yyyy}-${mm}-${dd}.md`);
+    const archiveContents = readFileSync(archivePath, "utf-8");
+    expect(archiveContents).toContain("enqueue will throw");
+  });
+});

package/src/tools/memory/register.ts

@@ -29,14 +29,16 @@ class RememberTool implements Tool {
     input: Record<string, unknown>,
     context: ToolContext,
   ): Promise<ToolExecutionResult> {
+    const typedInput = input as unknown as RememberInput;
     const result = handleRemember(
-      input as unknown as RememberInput,
+      typedInput,
       context.conversationId,
       context.memoryScopeId ?? "default",
     );
     return {
       content: result.message,
       isError: !result.success,
+      ...(typedInput.finish_turn === true ? { yieldToUser: true } : {}),
     };
   }
 }

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;
             }