improvement(copilot): refuse approval-gated tools on the in-band lane

Copilot's approval gate is scaffolding today: COPILOT_TOOL_PERMISSIONS_ENABLED is off
by default, so nothing is gated on any lane. It is built only on the dispatch lane,
which holds a call against a streaming context and a decision row and then declines
to dispatch anything the mothership marks in-band. Those calls run via
POST /api/copilot/tools/execute, which has no context and no waiter, so turning the
flag on would gate the foreground and leave background lanes ungated — a gate that
looks enforced but is not.

Add toolRequiresApprovalLane next to toolCallNeedsApproval so the covered tool set is
defined once, and refuse a gated tool at the in-band route before it runs. Refuse
rather than block: a background lane must never hang on a prompt with no row behind
it. The check deliberately ignores the stored auto-allow list — an auto-allowed tool
sent to the checkpoint lane is admitted there without prompting anyone, so reading it
here would only add a database read to reach the same place.

Inert while the flag is off, which is the state this ships in; a test pins that.
Also record on the flag itself that the gate is a property of the lane, since that is
what the next person reads before enabling it.

Author: waleedlatif1

apps/sim/app/api/copilot/tools/execute/route.test.ts

@@ -1,13 +1,20 @@
 /**
  * @vitest-environment node
  */
-import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { resetEnvFlagsMock, setEnvFlags } from '@sim/testing/mocks/env-flags.mock'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { ResolvedSecretTraceRegistry } from '@/executor/utils/resolved-secret-trace-registry'
 
-const { mockCheckInternalApiKey, mockPrepareEnvironmentContext, mockHandler } = vi.hoisted(() => ({
+const {
+  mockCheckInternalApiKey,
+  mockPrepareEnvironmentContext,
+  mockHandler,
+  mockToolRequiresApproval,
+} = vi.hoisted(() => ({
   mockCheckInternalApiKey: vi.fn(),
   mockPrepareEnvironmentContext: vi.fn(),
   mockHandler: vi.fn(),
+  mockToolRequiresApproval: vi.fn().mockReturnValue(false),
 }))
 
 vi.mock('@/lib/copilot/request/http', () => ({
@@ -20,6 +27,7 @@ vi.mock('@/lib/copilot/environment-context', () => ({
 
 vi.mock('@/lib/copilot/tool-executor', () => ({
   ensureHandlersRegistered: vi.fn(),
+  toolRequiresApproval: mockToolRequiresApproval,
 }))
 
 vi.mock('@/lib/copilot/tool-executor/executor', () => ({
@@ -67,6 +75,7 @@ describe('POST /api/copilot/tools/execute (in-band)', () => {
   beforeEach(() => {
     vi.clearAllMocks()
     mockCheckInternalApiKey.mockReturnValue({ success: true })
+    mockToolRequiresApproval.mockReturnValue(false)
     // A fresh, complete registry per test: the module-level turn cache is keyed
     // by messageId, so each test uses a distinct messageId to avoid cross-test
     // cache hits.
@@ -161,6 +170,68 @@ describe('POST /api/copilot/tools/execute (in-band)', () => {
     })
   })
 
+  describe('approval-gated tools', () => {
+    afterEach(resetEnvFlagsMock)
+
+    /**
+     * This lane cannot hold an approval prompt: the dispatch handler owns the gate and
+     * declines to dispatch in-band calls, so a gated tool arriving here has no waiter behind
+     * it. Refuse before running anything rather than execute on consent nobody gave.
+     */
+    it('refuses an approval-gated tool without executing it when permissions are enabled', async () => {
+      setEnvFlags({ isCopilotToolPermissionsEnabled: true })
+      mockToolRequiresApproval.mockReturnValue(true)
+      mockHandler.mockResolvedValue({ success: true, output: { ran: true } })
+
+      const res = await POST(
+        makeRequest({
+          ...BASE_BODY,
+          toolName: 'run_function',
+          params: { code: 'return 1' },
+          messageId: 'msg-gated',
+        }) as never
+      )
+      const body = await res.json()
+
+      expect(mockHandler).not.toHaveBeenCalled()
+      expect(body.success).toBe(false)
+      expect(body.output).toEqual({ resultWithheld: true, effect: 'not_attempted' })
+      expect(body.error).toContain('requires user approval')
+      expect(body.error).toContain('checkpoint lane')
+    })
+
+    it('still runs a tool the catalog does not gate when permissions are enabled', async () => {
+      setEnvFlags({ isCopilotToolPermissionsEnabled: true })
+      mockHandler.mockResolvedValue({ success: true, output: { content: 'hello' } })
+
+      const res = await POST(makeRequest({ ...BASE_BODY, messageId: 'msg-ungated' }) as never)
+
+      expect(mockHandler).toHaveBeenCalledTimes(1)
+      await expect(res.json()).resolves.toEqual({ success: true, output: { content: 'hello' } })
+    })
+
+    /**
+     * The guard is inert while the feature is off, which is the state this ships in — enabling
+     * the flag is what makes it bite, so it cannot change in-band behavior today.
+     */
+    it('runs an approval-gated tool unchanged while permissions are disabled', async () => {
+      mockToolRequiresApproval.mockReturnValue(true)
+      mockHandler.mockResolvedValue({ success: true, output: { ran: true } })
+
+      const res = await POST(
+        makeRequest({
+          ...BASE_BODY,
+          toolName: 'run_function',
+          params: { code: 'return 1' },
+          messageId: 'msg-gated-flag-off',
+        }) as never
+      )
+
+      expect(mockHandler).toHaveBeenCalledTimes(1)
+      await expect(res.json()).resolves.toEqual({ success: true, output: { ran: true } })
+    })
+  })
+
   it('passes a failed generate_api_key call through with its error', async () => {
     mockHandler.mockResolvedValue({ success: false, error: 'name is required' })
     const res = await POST(

apps/sim/app/api/copilot/tools/execute/route.ts

@@ -10,6 +10,7 @@ import { TraceAttr } from '@/lib/copilot/generated/trace-attributes-v1'
 import { TraceSpan } from '@/lib/copilot/generated/trace-spans-v1'
 import { checkInternalApiKey } from '@/lib/copilot/request/http'
 import { withIncomingGoSpan } from '@/lib/copilot/request/otel'
+import { toolRequiresApprovalLane } from '@/lib/copilot/request/tools/permission'
 import {
   describeWithholdingCause,
   inspectToolResultForCopilot,
@@ -126,6 +127,29 @@ export const POST = withRouteHandler((request: NextRequest) =>
         [TraceAttr.UserId]: userId,
       })
 
+      /**
+       * Cheap admission, before any work: this lane cannot hold an approval prompt. The
+       * dispatch handler gates `requiresApproval` tools against a streaming context and a
+       * decision row, then deliberately declines to dispatch anything the mothership marks
+       * in-band — so a gated tool arriving here has no waiter behind it and would run on
+       * consent nobody gave. Refuse instead, and let the mothership take the checkpoint lane
+       * where the gate lives. Inert while copilot tool permissions are disabled, which keeps
+       * enabling the flag from silently leaving background lanes ungated.
+       */
+      if (toolRequiresApprovalLane(toolName)) {
+        logger.warn('Refusing an approval-gated tool on the in-band lane', {
+          toolName,
+          toolCallId,
+          userId,
+        })
+        rootSpan.setAttributes({ [TraceAttr.ToolOutcome]: MothershipStreamV1ToolOutcome.error })
+        return NextResponse.json({
+          success: false,
+          error: `${toolName} was not run: it requires user approval, and this lane cannot hold an approval prompt. Dispatch it on the checkpoint lane instead.`,
+          output: { resultWithheld: true, effect: TOOL_EFFECT_PHASE.notAttempted },
+        })
+      }
+
       let toolRegistry: ResolvedSecretTraceRegistry
       let turnRegistry: ResolvedSecretTraceRegistry
       try {

apps/sim/lib/copilot/request/tools/permission.test.ts

@@ -2,7 +2,8 @@
  * @vitest-environment node
  */
 
-import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { resetEnvFlagsMock, setEnvFlags } from '@sim/testing/mocks/env-flags.mock'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { TraceCollector } from '@/lib/copilot/request/trace'
 
 const { toolRequiresApproval, waitForToolPermissionDecision } = vi.hoisted(() => ({
@@ -28,6 +29,7 @@ import { createStreamingContext } from '@/lib/copilot/request/context/request-co
 import {
   runGatedToolExecution,
   toolCallNeedsApproval,
+  toolRequiresApprovalLane,
 } from '@/lib/copilot/request/tools/permission'
 import type { StreamEvent, ToolCallState } from '@/lib/copilot/request/types'
 
@@ -73,6 +75,38 @@ function gate(
   )
 }
 
+describe('toolRequiresApprovalLane', () => {
+  // vi.clearAllMocks() clears calls but not implementations, so a mockReturnValue
+  // set here would otherwise outlive this block and silently flip the suites below.
+  afterEach(() => {
+    resetEnvFlagsMock()
+    toolRequiresApproval.mockReturnValue(true)
+  })
+
+  /**
+   * Asked by lanes that cannot hold a prompt, so it answers from the catalog and the
+   * feature flag alone — there is no streaming context to consult, and the stored
+   * auto-allow list is deliberately not read (an auto-allowed tool is admitted on the
+   * checkpoint lane without prompting anyone).
+   */
+  it('is false while the feature is off, whatever the catalog says', () => {
+    toolRequiresApproval.mockReturnValue(true)
+    expect(toolRequiresApprovalLane('run_function')).toBe(false)
+  })
+
+  it('is true for a catalog-gated tool once the feature is on', () => {
+    setEnvFlags({ isCopilotToolPermissionsEnabled: true })
+    toolRequiresApproval.mockReturnValue(true)
+    expect(toolRequiresApprovalLane('run_function')).toBe(true)
+  })
+
+  it('is false for an ungated tool once the feature is on', () => {
+    setEnvFlags({ isCopilotToolPermissionsEnabled: true })
+    toolRequiresApproval.mockReturnValue(false)
+    expect(toolRequiresApprovalLane('read')).toBe(false)
+  })
+})
+
 describe('toolCallNeedsApproval', () => {
   const runCall = { operation: 'run', args: { command: 'ls' } }
 

apps/sim/lib/copilot/request/tools/permission.ts

@@ -27,6 +27,7 @@ import type {
   ToolCallState,
 } from '@/lib/copilot/request/types'
 import { getToolEntry, toolRequiresApproval } from '@/lib/copilot/tool-executor'
+import { isCopilotToolPermissionsEnabled } from '@/lib/core/config/env-flags'
 
 const logger = createLogger('CopilotToolPermissionGate')
 
@@ -51,6 +52,26 @@ const PERMISSION_WAIT_TIMEOUT_MS = ORCHESTRATION_TIMEOUT_MS
 
 export const TOOL_AWAITING_APPROVAL_STATUS = MothershipStreamV1ToolStatus.awaiting_approval
 
+/**
+ * Whether a tool may only run on a lane that is able to hold an approval prompt.
+ *
+ * `toolCallNeedsApproval` answers for the dispatch lane, where a streaming
+ * context exists to gate against. The in-band route has neither a context nor a
+ * waiter — the mothership executes those calls itself — so it asks this instead,
+ * before running anything, and refuses rather than blocks: a background lane
+ * must never hang on a prompt with no row behind it.
+ *
+ * Deliberately blind to the stored auto-allow list. Consulting it here would add
+ * a database read to every in-band call to reach the same place by a longer
+ * route: an auto-allowed tool sent to the checkpoint lane is admitted there
+ * without prompting anyone. Refusing unconditionally keeps this fail-closed and
+ * leaves the one implementation of "has the user allowed this" on the lane that
+ * already owns it.
+ */
+export function toolRequiresApprovalLane(toolName: string): boolean {
+  return isCopilotToolPermissionsEnabled && toolRequiresApproval(toolName)
+}
+
 /**
  * Whether this call must be held for an explicit user decision.
  *

apps/sim/lib/core/config/env-flags.ts

@@ -92,6 +92,14 @@ export const isStatusNoticePreviewEnabled = isTruthy(getEnv('NEXT_PUBLIC_STATUS_
  * used tools, so it is an opt-in change in how the product feels, not just a
  * safety toggle. With it off nothing is stamped, gated, or persisted, and an
  * approval stamp arriving from Go is cleared on the way to the client.
+ *
+ * The gate is a property of the lane, not only of the tool. Sim can hold a call
+ * for a decision on the dispatch lane, where a streaming context and a decision
+ * row exist. It cannot on the in-band route (`POST /api/copilot/tools/execute`),
+ * which the mothership drives for background lanes, so that route refuses a
+ * `requiresApproval` tool outright rather than running it ungated — see
+ * `toolRequiresApprovalLane`. Any new execution lane has to answer the same
+ * question before this flag is turned on.
  */
 export const isCopilotToolPermissionsEnabled = isTruthy(env.COPILOT_TOOL_PERMISSIONS_ENABLED)