improvement(copilot): move the approval-lane predicate beside the tool router

Importing the dispatch gate module for a one-line predicate pulled the permission
persistence layer in with it, whose module body opens a pub/sub channel — two Redis
clients and a channel subscription — in every process that loads the in-band route.

Move toolRequiresApprovalLane to tool-executor/router.ts, which imports only the
catalog. The route already imported @/lib/copilot/tool-executor for
ensureHandlersRegistered, so the guard now costs no new import edge at all. The
dispatch gate keeps a pointer to it.

Its flag-and-catalog behavior is covered in the router tests against the real flag and
the real catalog; the route tests keep to what the route does with the answer.

Author: waleedlatif1

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

@@ -1,20 +1,19 @@
 /**
  * @vitest-environment node
  */
-import { resetEnvFlagsMock, setEnvFlags } from '@sim/testing/mocks/env-flags.mock'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { ResolvedSecretTraceRegistry } from '@/executor/utils/resolved-secret-trace-registry'
 
 const {
   mockCheckInternalApiKey,
   mockPrepareEnvironmentContext,
   mockHandler,
-  mockToolRequiresApproval,
+  mockToolRequiresApprovalLane,
 } = vi.hoisted(() => ({
   mockCheckInternalApiKey: vi.fn(),
   mockPrepareEnvironmentContext: vi.fn(),
   mockHandler: vi.fn(),
-  mockToolRequiresApproval: vi.fn().mockReturnValue(false),
+  mockToolRequiresApprovalLane: vi.fn().mockReturnValue(false),
 }))
 
 vi.mock('@/lib/copilot/request/http', () => ({
@@ -27,7 +26,7 @@ vi.mock('@/lib/copilot/environment-context', () => ({
 
 vi.mock('@/lib/copilot/tool-executor', () => ({
   ensureHandlersRegistered: vi.fn(),
-  toolRequiresApproval: mockToolRequiresApproval,
+  toolRequiresApprovalLane: mockToolRequiresApprovalLane,
 }))
 
 vi.mock('@/lib/copilot/tool-executor/executor', () => ({
@@ -75,7 +74,7 @@ describe('POST /api/copilot/tools/execute (in-band)', () => {
   beforeEach(() => {
     vi.clearAllMocks()
     mockCheckInternalApiKey.mockReturnValue({ success: true })
-    mockToolRequiresApproval.mockReturnValue(false)
+    mockToolRequiresApprovalLane.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.
@@ -170,17 +169,20 @@ describe('POST /api/copilot/tools/execute (in-band)', () => {
     })
   })
 
+  /**
+   * Whether a tool needs an approval-capable lane is decided by
+   * `toolRequiresApprovalLane` (covered against the real flag and catalog in
+   * the tool-executor router tests). What matters here is what the route does
+   * with that answer.
+   */
   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)
+    it('refuses a tool that needs an approval-capable lane, without executing it', async () => {
+      mockToolRequiresApprovalLane.mockReturnValue(true)
       mockHandler.mockResolvedValue({ success: true, output: { ran: true } })
 
       const res = await POST(
@@ -200,36 +202,14 @@ describe('POST /api/copilot/tools/execute (in-band)', () => {
       expect(body.error).toContain('checkpoint lane')
     })
 
-    it('still runs a tool the catalog does not gate when permissions are enabled', async () => {
-      setEnvFlags({ isCopilotToolPermissionsEnabled: true })
+    it('still runs a tool that does not need an approval-capable lane', async () => {
       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 () => {

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

@@ -10,15 +10,14 @@ 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,
   projectToolErrorMessageForCopilot,
 } from '@/lib/copilot/request/tools/resolved-secret-result'
 import { handleResourceSideEffects } from '@/lib/copilot/request/tools/resources'
 import type { ToolCallResult } from '@/lib/copilot/request/types'
-import { ensureHandlersRegistered } from '@/lib/copilot/tool-executor'
+import { ensureHandlersRegistered, toolRequiresApprovalLane } from '@/lib/copilot/tool-executor'
 import { executeTool } from '@/lib/copilot/tool-executor/executor'
 import { TOOL_EFFECT_PHASE } from '@/lib/copilot/tool-executor/types'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'

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

@@ -2,8 +2,7 @@
  * @vitest-environment node
  */
 
-import { resetEnvFlagsMock, setEnvFlags } from '@sim/testing/mocks/env-flags.mock'
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { TraceCollector } from '@/lib/copilot/request/trace'
 
 const { toolRequiresApproval, waitForToolPermissionDecision } = vi.hoisted(() => ({
@@ -29,7 +28,6 @@ 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'
 
@@ -75,38 +73,6 @@ 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,7 +27,6 @@ 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')
 
@@ -52,31 +51,16 @@ 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.
  *
  * Headless one-shot executions are never gated: nobody is there to answer, and
  * blocking them would hang the run until the orchestration timeout.
+ *
+ * This is the dispatch lane's answer, and it needs a streaming context. A lane
+ * that has none — the in-band route — asks `toolRequiresApprovalLane` instead,
+ * which lives beside the tool router so a caller needing only the predicate does
+ * not pull this module's permission pub/sub in with it.
  */
 export function toolCallNeedsApproval(
   toolName: string,

apps/sim/lib/copilot/tool-executor/index.ts

@@ -1,3 +1,8 @@
 export { executeTool } from './executor'
 export { ensureHandlersRegistered } from './register-handlers'
-export { getToolEntry, isSimExecuted, toolRequiresApproval } from './router'
+export {
+  getToolEntry,
+  isSimExecuted,
+  toolRequiresApproval,
+  toolRequiresApprovalLane,
+} from './router'

apps/sim/lib/copilot/tool-executor/router.test.ts

@@ -2,7 +2,8 @@
  * @vitest-environment node
  */
 
-import { describe, expect, it, vi } from 'vitest'
+import { resetEnvFlagsMock, setEnvFlags } from '@sim/testing/mocks/env-flags.mock'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 
 /**
  * The handler map is a wiring table from tool id to implementation. Only its
@@ -54,6 +55,7 @@ import {
   getToolEntry,
   isSimExecuted,
   toolRequiresApproval,
+  toolRequiresApprovalLane,
 } from '@/lib/copilot/tool-executor/router'
 import { executeCancelWorkflowRun } from '@/lib/copilot/tools/handlers/workflow/mutations'
 
@@ -75,3 +77,34 @@ describe('workflow-run cancellation tool routing', () => {
     expect(buildHandlerMap().cancel_workflow_run).toBe(executeCancelWorkflowRun)
   })
 })
+
+describe('toolRequiresApprovalLane', () => {
+  afterEach(resetEnvFlagsMock)
+
+  /**
+   * 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 copilot tool permissions are off, whatever the catalog says', () => {
+    expect(toolRequiresApproval('run_function')).toBe(true)
+    expect(toolRequiresApprovalLane('run_function')).toBe(false)
+  })
+
+  it('is true for a catalog-gated tool once the feature is on', () => {
+    setEnvFlags({ isCopilotToolPermissionsEnabled: true })
+    expect(toolRequiresApprovalLane('run_function')).toBe(true)
+  })
+
+  it('is false for a tool the catalog does not gate, feature on', () => {
+    setEnvFlags({ isCopilotToolPermissionsEnabled: true })
+    expect(toolRequiresApproval('read')).toBe(false)
+    expect(toolRequiresApprovalLane('read')).toBe(false)
+  })
+
+  it('is false for a tool that is not in the catalog at all', () => {
+    setEnvFlags({ isCopilotToolPermissionsEnabled: true })
+    expect(toolRequiresApprovalLane('not_a_real_tool')).toBe(false)
+  })
+})

apps/sim/lib/copilot/tool-executor/router.ts

@@ -1,4 +1,5 @@
 import { TOOL_CATALOG, type ToolCatalogEntry } from '@/lib/copilot/generated/tool-catalog-v1'
+import { isCopilotToolPermissionsEnabled } from '@/lib/core/config/env-flags'
 
 export function isToolInCatalog(toolId: string): boolean {
   return toolId in TOOL_CATALOG
@@ -24,3 +25,27 @@ export function isKnownTool(toolId: string): boolean {
 export function toolRequiresApproval(toolId: string): boolean {
   return getToolEntry(toolId)?.requiresApproval === true
 }
+
+/**
+ * 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.
+ *
+ * Lives here rather than beside the dispatch gate so that asking the question
+ * costs only the catalog. The gate module reaches the permission persistence
+ * layer, which opens a pub/sub channel when it loads.
+ *
+ * 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(toolId: string): boolean {
+  return isCopilotToolPermissionsEnabled && toolRequiresApproval(toolId)
+}