lael-labs/executor

executor/packages/core/src/adapters/in/process/execution-adapter.test.ts+5−2

 import { expect, test } from "bun:test";
-import { APPROVAL_DENIED_PREFIX } from "../../../execution-constants";
+import { ToolCallControlError } from "../../../tool-call-control";
 import { InProcessExecutionAdapter } from "./execution-adapter";
 test("returns run mismatch without invoking tool", async () => {
   const adapter = new InProcessExecutionAdapter({
     runId: "run_1",
     invokeTool: async () => {
-      throw new Error(`${APPROVAL_DENIED_PREFIX}approval required`);
+      throw new ToolCallControlError({
+        kind: "approval_denied",
+        reason: "approval required",
+      });
     },
   });

executor/packages/core/src/adapters/in/process/execution-adapter.ts+8−6

-import { APPROVAL_DENIED_PREFIX, APPROVAL_PENDING_PREFIX } from "../../../execution-constants";
+import { decodeToolCallControlSignal } from "../../../tool-call-control";
 import type {
   ExecutionAdapter,
   ToolCallRequest,
       const value = await this.options.invokeTool(call);
       return { ok: true, value };
     } catch (error) {
-      const message = describeError(error);
+      const controlSignal = decodeToolCallControlSignal(error);
-      if (message.startsWith(APPROVAL_DENIED_PREFIX)) {
+      if (controlSignal?.kind === "approval_denied") {
         return {
           ok: false,
           kind: "denied",
-          error: message.replace(APPROVAL_DENIED_PREFIX, "").trim(),
+          error: controlSignal.reason,
         };
       }
-      if (message.startsWith(APPROVAL_PENDING_PREFIX)) {
+      if (controlSignal?.kind === "approval_pending") {
         return {
           ok: false,
           kind: "pending",
-          approvalId: message.replace(APPROVAL_PENDING_PREFIX, "").trim(),
+          approvalId: controlSignal.approvalId,
           retryAfterMs: 500,
           error: "Approval pending",
         };
       }
+      const message = describeError(error);
       return {
         ok: false,
         kind: "failed",

executor/packages/core/src/runtimes/runtime-core.ts+9−4

 // string version of similar logic, built from sandbox-fragments.ts. Changes to
 // the core helpers here (createToolsProxy, console proxy, execution
 // loop, result mapping) should be mirrored there.
-import { APPROVAL_DENIED_PREFIX, TASK_TIMEOUT_MARKER } from "../execution-constants";
+import { TASK_TIMEOUT_MARKER } from "../execution-constants";
 import { Result } from "better-result";
 import { Script, createContext } from "node:vm";
+import { decodeToolCallControlSignal, ToolCallControlError } from "../tool-call-control";
 import type {
   ExecutionAdapter,
   SandboxExecutionRequest,
             retryDelayMs = clampRetryDelayMs(retryDelayMs * RETRY_BACKOFF_MULTIPLIER);
             continue;
           case "denied":
-            throw new Error(`${APPROVAL_DENIED_PREFIX}${result.error}`);
+            throw new ToolCallControlError({
+              kind: "approval_denied",
+              reason: result.error,
+            });
           case "failed":
           default:
             throw new Error(result.error);
     };
   }
-  if (message.startsWith(APPROVAL_DENIED_PREFIX)) {
+  const controlSignal = decodeToolCallControlSignal(error);
+  if (controlSignal?.kind === "approval_denied") {
     return {
       status: "denied",
-      message: message.replace(APPROVAL_DENIED_PREFIX, "").trim(),
+      message: controlSignal.reason,
     };
   }

executor/packages/core/src/tool-call-control.ts+42−0

@@ -0,0 +1,42 @@
	1	import {
	2	APPROVAL_DENIED_PREFIX,
	3	APPROVAL_PENDING_PREFIX,
	4	} from "./execution-constants";
	5
	6	export type ToolCallControlSignal =
	7	\| { kind: "approval_pending"; approvalId: string }
	8	\| { kind: "approval_denied"; reason: string };
	9
	10	export function encodeToolCallControlSignal(signal: ToolCallControlSignal): string {
	11	if (signal.kind === "approval_pending") {
	12	return `${APPROVAL_PENDING_PREFIX}${signal.approvalId}`;
	13	}
	14
	15	return `${APPROVAL_DENIED_PREFIX}${signal.reason}`;
	16	}
	17
	18	export function decodeToolCallControlSignal(value: unknown): ToolCallControlSignal \| null {
	19	const message = value instanceof Error ? value.message : String(value ?? "");
	20
	21	if (message.startsWith(APPROVAL_PENDING_PREFIX)) {
	22	const approvalId = message.replace(APPROVAL_PENDING_PREFIX, "").trim();
	23	return { kind: "approval_pending", approvalId };
	24	}
	25
	26	if (message.startsWith(APPROVAL_DENIED_PREFIX)) {
	27	const reason = message.replace(APPROVAL_DENIED_PREFIX, "").trim();
	28	return { kind: "approval_denied", reason };
	29	}
	30
	31	return null;
	32	}
	33
	34	export class ToolCallControlError extends Error {
	35	readonly signal: ToolCallControlSignal;
	36
	37	constructor(signal: ToolCallControlSignal) {
	38	super(encodeToolCallControlSignal(signal));
	39	this.name = "ToolCallControlError";
	40	this.signal = signal;
	41	}
	42	}

executor/packages/database/src/executor/handlers.ts+70−19

   scheduler?: Pick<MutationCtx, "scheduler">["scheduler"];
 };
+async function createTaskDocument(
+  ctx: TaskCreateContext,
+  internal: Internal,
+  args: {
+    id: string;
+    code: string;
+    runtimeId: string;
+    timeoutMs: number;
+    metadata?: unknown;
+    workspaceId: Id<"workspaces">;
+    actorId: string;
+    clientId?: string;
+  },
+): Promise<TaskRecord> {
+  return await ctx.runMutation(internal.database.createTask, args) as TaskRecord;
+}
+async function resolveApprovalDocument(
+  ctx: MutationCtx,
+  internal: Internal,
+  args: {
+    approvalId: string;
+    decision: "approved" | "denied";
+    reviewerId?: string;
+    reason?: string;
+  },
+): Promise<ApprovalRecord | null> {
+  return await ctx.runMutation(internal.database.resolveApproval, args) as ApprovalRecord | null;
+}
+async function getTaskById(
+  ctx: Pick<MutationCtx, "runQuery">,
+  internal: Internal,
+  taskId: string,
+): Promise<TaskRecord | null> {
+  return await ctx.runQuery(internal.database.getTask, { taskId }) as TaskRecord | null;
+}
+async function createTaskInternal(
+  ctx: Pick<ActionCtx, "runMutation">,
+  internal: Internal,
+  args: {
+    code: string;
+    timeoutMs?: number;
+    runtimeId?: string;
+    metadata?: unknown;
+    workspaceId: Id<"workspaces">;
+    actorId: string;
+    clientId?: string;
+    scheduleAfterCreate?: boolean;
+  },
+): Promise<{ task: TaskRecord }> {
+  return await ctx.runMutation(internal.executor.createTaskInternal, args) as { task: TaskRecord };
+}
 async function createTaskRecord(
   ctx: TaskCreateContext,
   internal: Internal,
   }
   const taskId = `task_${crypto.randomUUID()}`;
-  const task = (await ctx.runMutation(internal.database.createTask, {
+  const task = await createTaskDocument(ctx, internal, {
     id: taskId,
     code: args.code,
     runtimeId,
     workspaceId: args.workspaceId,
     actorId: args.actorId,
     clientId: args.clientId,
-  })) as TaskRecord;
+  });
   await createTaskEvent(ctx, {
     taskId,
     return null;
   }
-  const approval = (await ctx.runMutation(internal.database.resolveApproval, {
+  const approval = await resolveApprovalDocument(ctx, internal, {
     approvalId: args.approvalId,
     decision: args.decision,
     reviewerId: args.reviewerId,
     reason: args.reason,
-  })) as ApprovalRecord | null;
+  });
   if (!approval) {
     return null;
   }
     },
   });
-  const task = (await ctx.runQuery(internal.database.getTask, {
+  const task = await getTaskById(ctx, internal, approval.taskId);
-    taskId: approval.taskId,
-  })) as TaskRecord | null;
   if (!task) {
     throw new Error(`Task ${approval.taskId} missing while resolving approval`);
   }
   assertMatchesCanonicalActorId(args.actorId, canonicalActorId);
   const waitForResult = args.waitForResult ?? false;
-  const created = await ctx.runMutation(internal.executor.createTaskInternal, {
+  const created = await createTaskInternal(ctx, internal, {
     code: args.code,
     timeoutMs: args.timeoutMs,
     runtimeId: args.runtimeId,
   });
   if (!waitForResult) {
-    return { task: created.task as TaskRecord };
+    return { task: created.task };
   }
   const runOutcome = await ctx.runAction(internal.executorNode.runTask, {
 }
 export async function resolveApprovalHandler(
-  ctx: unknown,
+  ctx: MutationCtx & {
+    account: { _id: string; provider: string; providerAccountId: string };
+    workspaceId: Id<"workspaces">;
+  },
   internal: Internal,
   args: {
     approvalId: string;
     reason?: string;
   },
 ): Promise<{ approval: ApprovalRecord; task: TaskRecord } | null> {
-  const typedCtx = ctx as MutationCtx & {
+  const canonicalActorId = actorIdForAccount(ctx.account);
-    account: { _id: string; provider: string; providerAccountId: string };
-    workspaceId: Id<"workspaces">;
-  };
-  const canonicalActorId = actorIdForAccount(typedCtx.account);
   assertMatchesCanonicalActorId(args.reviewerId, canonicalActorId, "reviewerId");
-  return await resolveApprovalRecord(typedCtx, internal, {
+  return await resolveApprovalRecord(ctx, internal, {
     ...args,
-    workspaceId: typedCtx.workspaceId,
+    workspaceId: ctx.workspaceId,
     reviewerId: canonicalActorId,
   });
 }
     durationMs?: number;
   },
 ) {
-  const task = (await ctx.runQuery(internal.database.getTask, { taskId: args.runId })) as TaskRecord | null;
+  const task = await getTaskById(ctx, internal, args.runId);
   if (!task) {
     return { ok: false as const, error: `Run not found: ${args.runId}` };
   }

executor/packages/database/src/runtime/external_tool_call.ts+13−10

 import type { ActionCtx } from "../../convex/_generated/server";
 import { internal } from "../../convex/_generated/api";
-import { APPROVAL_DENIED_PREFIX, APPROVAL_PENDING_PREFIX } from "../../../core/src/execution-constants";
 import type { TaskRecord, ToolCallResult } from "../../../core/src/types";
+import { decodeToolCallControlSignal } from "../../../core/src/tool-call-control";
 import { describeError } from "../../../core/src/utils";
 import { invokeTool } from "./tool_invocation";
+async function getTaskById(ctx: ActionCtx, taskId: string): Promise<TaskRecord | null> {
+  return await ctx.runQuery(internal.database.getTask, { taskId }) as TaskRecord | null;
+}
 export async function handleExternalToolCallRequest(
   ctx: ActionCtx,
   args: {
     input?: unknown;
   },
 ): Promise<ToolCallResult> {
-  const task = (await ctx.runQuery(internal.database.getTask, {
+  const task = await getTaskById(ctx, args.runId);
-    taskId: args.runId,
-  })) as TaskRecord | null;
   if (!task) {
     return {
       ok: false,
     });
     return { ok: true, value };
   } catch (error) {
-    const message = describeError(error);
+    const controlSignal = decodeToolCallControlSignal(error);
-    if (message.startsWith(APPROVAL_PENDING_PREFIX)) {
+    if (controlSignal?.kind === "approval_pending") {
-      const approvalId = message.replace(APPROVAL_PENDING_PREFIX, "").trim();
       return {
         ok: false,
         kind: "pending",
-        approvalId,
+        approvalId: controlSignal.approvalId,
         retryAfterMs: 0,
         error: "Approval pending",
       };
     }
-    if (message.startsWith(APPROVAL_DENIED_PREFIX)) {
+    if (controlSignal?.kind === "approval_denied") {
       return {
         ok: false,
         kind: "denied",
-        error: message.replace(APPROVAL_DENIED_PREFIX, "").trim(),
+        error: controlSignal.reason,
       };
     }
+    const message = describeError(error);
     return {
       ok: false,
       kind: "failed",

executor/packages/database/src/runtime/task_runner.ts+19−7

 import type { ActionCtx } from "../../convex/_generated/server";
 import { internal } from "../../convex/_generated/api";
 import { InProcessExecutionAdapter } from "../../../core/src/adapters/in/process/execution-adapter";
-import { APPROVAL_DENIED_PREFIX } from "../../../core/src/execution-constants";
 import { dispatchCodeWithCloudflareWorkerLoader } from "../../../core/src/runtimes/cloudflare/worker/loader-runtime";
+import { decodeToolCallControlSignal } from "../../../core/src/tool-call-control";
 import {
   CLOUDFLARE_WORKER_LOADER_RUNTIME_ID,
   isCloudflareWorkerLoaderConfigured,
 import { markTaskFinished } from "../task/finish";
 import { invokeTool } from "./tool_invocation";
+async function getTaskById(ctx: ActionCtx, taskId: string): Promise<TaskRecord | null> {
+  return await ctx.runQuery(internal.database.getTask, { taskId }) as TaskRecord | null;
+}
+async function markTaskRunning(
+  ctx: ActionCtx,
+  taskId: string,
+): Promise<TaskRecord | null> {
+  return await ctx.runMutation(internal.database.markTaskRunning, {
+    taskId,
+  }) as TaskRecord | null;
+}
 async function markTaskFailedAndPublish(
   ctx: ActionCtx,
   args: { taskId: string; error: string },
   ctx: ActionCtx,
   args: { taskId: string },
 ): Promise<TaskExecutionOutcome | null> {
-  const task = (await ctx.runQuery(internal.database.getTask, { taskId: args.taskId })) as TaskRecord | null;
+  const task = await getTaskById(ctx, args.taskId);
   if (!task || task.status !== "queued") {
     return null;
   }
   }
   try {
-    const running = (await ctx.runMutation(internal.database.markTaskRunning, {
+    const running = await markTaskRunning(ctx, args.taskId);
-      taskId: args.taskId,
-    })) as TaskRecord | null;
     if (!running) {
       return null;
     }
     };
   } catch (error) {
     const message = describeError(error);
-    const denied = message.startsWith(APPROVAL_DENIED_PREFIX);
+    const controlSignal = decodeToolCallControlSignal(error);
+    const denied = controlSignal?.kind === "approval_denied";
     const finished = await markTaskFinished(ctx, {
       taskId: args.taskId,
       status: denied ? "denied" : "failed",
-      error: denied ? message.replace(APPROVAL_DENIED_PREFIX, "") : message,
+      error: denied ? controlSignal.reason : message,
     });
     if (finished) {

executor/packages/database/src/runtime/tool_call_credentials.ts+5−2

 import type { ActionCtx } from "../../convex/_generated/server";
 import { internal } from "../../convex/_generated/api";
 import { resolveCredentialPayload } from "../../../core/src/credential-providers";
-import { APPROVAL_DENIED_PREFIX } from "../../../core/src/execution-constants";
 import type { ResolvedToolCredential, TaskRecord, ToolCallRecord, ToolCredentialSpec } from "../../../core/src/types";
+import { ToolCallControlError } from "../../../core/src/tool-call-control";
 import { asPayload } from "../lib/object";
 export async function resolveCredentialHeaders(
   }
   if (persistedCall.status === "denied") {
-    throw new Error(`${APPROVAL_DENIED_PREFIX}${persistedCall.error ?? persistedCall.toolPath}`);
+    throw new ToolCallControlError({
+      kind: "approval_denied",
+      reason: persistedCall.error ?? persistedCall.toolPath,
+    });
   }
 }

executor/packages/database/src/runtime/tool_call_lifecycle.ts+5−2

 import type { ActionCtx } from "../../convex/_generated/server";
 import { internal } from "../../convex/_generated/api";
-import { APPROVAL_DENIED_PREFIX } from "../../../core/src/execution-constants";
 import type { TaskRecord } from "../../../core/src/types";
+import { ToolCallControlError } from "../../../core/src/tool-call-control";
 import { publishTaskEvent } from "./events";
 async function finishToolCall(
     ...(args.approvalId ? { approvalId: args.approvalId } : {}),
     ...(args.reason ? { reason: args.reason } : {}),
   });
-  throw new Error(`${APPROVAL_DENIED_PREFIX}${args.deniedMessage}`);
+  throw new ToolCallControlError({
+    kind: "approval_denied",
+    reason: args.deniedMessage,
+  });
 }
 export async function completeToolCall(

executor/packages/database/src/runtime/tool_call_resolution.ts+37−6

 import { normalizeToolPathForLookup, toPreferredToolPath } from "./tool_paths";
 import { baseTools } from "./workspace_tools";
+type RegistrySerializedToolEntry = {
+  path: string;
+  serializedToolJson: string;
+};
+async function searchRegistryEntries(
+  ctx: ActionCtx,
+  args: { workspaceId: TaskRecord["workspaceId"]; buildId: string; query: string; limit: number },
+): Promise<Array<{ preferredPath: string }>> {
+  return await ctx.runQuery(internal.toolRegistry.searchTools, args) as Array<{ preferredPath: string }>;
+}
+async function getRegistryToolByPath(
+  ctx: ActionCtx,
+  args: { workspaceId: TaskRecord["workspaceId"]; buildId: string; path: string },
+): Promise<RegistrySerializedToolEntry | null> {
+  return await ctx.runQuery(internal.toolRegistry.getToolByPath, args) as RegistrySerializedToolEntry | null;
+}
+async function getRegistryToolsByNormalizedPath(
+  ctx: ActionCtx,
+  args: {
+    workspaceId: TaskRecord["workspaceId"];
+    buildId: string;
+    normalizedPath: string;
+    limit: number;
+  },
+): Promise<RegistrySerializedToolEntry[]> {
+  return await ctx.runQuery(internal.toolRegistry.getToolsByNormalizedPath, args) as RegistrySerializedToolEntry[];
+}
 export function getGraphqlDecision(
   task: TaskRecord,
   tool: ToolDefinition,
   toolPath: string,
 ): Promise<string[]> {
   const term = toolPath.split(".").filter(Boolean).join(" ");
-  const hits = await ctx.runQuery(internal.toolRegistry.searchTools, {
+  const hits = await searchRegistryEntries(ctx, {
     workspaceId,
     buildId,
     query: term,
     limit: 3,
-  }) as Array<{ preferredPath: string }>;
+  });
   return hits.map((hit) => hit.preferredPath);
 }
   });
   let resolvedToolPath = toolPath;
-  let entry = await ctx.runQuery(internal.toolRegistry.getToolByPath, {
+  let entry = await getRegistryToolByPath(ctx, {
     workspaceId: task.workspaceId,
     buildId,
     path: toolPath,
-  }) as null | { path: string; serializedToolJson: string };
+  });
   if (!entry) {
     const normalized = normalizeToolPathForLookup(toolPath);
-    const hits = await ctx.runQuery(internal.toolRegistry.getToolsByNormalizedPath, {
+    const hits = await getRegistryToolsByNormalizedPath(ctx, {
       workspaceId: task.workspaceId,
       buildId,
       normalizedPath: normalized,
       limit: 5,
-    }) as Array<{ path: string; serializedToolJson: string }>;
+    });
     if (hits.length > 0) {
       // Prefer exact match on preferred path formatting, otherwise shortest canonical path.

executor/packages/database/src/runtime/tool_invocation.ts+63−22

 import type { ActionCtx } from "../../convex/_generated/server";
 import { internal } from "../../convex/_generated/api";
-import {
-  APPROVAL_DENIED_PREFIX,
-  APPROVAL_PENDING_PREFIX,
-} from "../../../core/src/execution-constants";
 import type {
   AccessPolicyRecord,
   PolicyDecision,
   ToolRunContext,
 } from "../../../core/src/types";
 import { describeError } from "../../../core/src/utils";
+import {
+  decodeToolCallControlSignal,
+  ToolCallControlError,
+} from "../../../core/src/tool-call-control";
 import { asPayload } from "../lib/object";
 import { getToolDecision, getDecisionForContext } from "./policy";
 import { baseTools } from "./workspace_tools";
   displayOutput?: string;
 };
+async function upsertRequestedToolCall(
+  ctx: ActionCtx,
+  args: { taskId: string; callId: string; workspaceId: TaskRecord["workspaceId"]; toolPath: string },
+): Promise<ToolCallRecord> {
+  return await ctx.runMutation(internal.database.upsertToolCallRequested, args) as ToolCallRecord;
+}
+async function listWorkspaceAccessPolicies(
+  ctx: ActionCtx,
+  workspaceId: TaskRecord["workspaceId"],
+): Promise<AccessPolicyRecord[]> {
+  return await ctx.runQuery(internal.database.listAccessPolicies, { workspaceId }) as AccessPolicyRecord[];
+}
+async function listRegistryNamespaces(
+  ctx: ActionCtx,
+  args: { workspaceId: TaskRecord["workspaceId"]; buildId: string; limit: number },
+): Promise<Array<{ namespace: string; toolCount: number; samplePaths: string[] }>> {
+  return await ctx.runQuery(internal.toolRegistry.listNamespaces, args) as Array<{
+    namespace: string;
+    toolCount: number;
+    samplePaths: string[];
+  }>;
+}
+async function searchRegistryTools(
+  ctx: ActionCtx,
+  args: { workspaceId: TaskRecord["workspaceId"]; buildId: string; query: string; limit: number },
+): Promise<RegistryToolEntry[]> {
+  return await ctx.runQuery(internal.toolRegistry.searchTools, args) as RegistryToolEntry[];
+}
+async function listRegistryToolsByNamespace(
+  ctx: ActionCtx,
+  args: { workspaceId: TaskRecord["workspaceId"]; buildId: string; namespace: string; limit: number },
+): Promise<RegistryToolEntry[]> {
+  return await ctx.runQuery(internal.toolRegistry.listToolsByNamespace, args) as RegistryToolEntry[];
+}
 async function denyToolCallForApproval(
   ctx: ActionCtx,
   args: {
 export async function invokeTool(ctx: ActionCtx, task: TaskRecord, call: ToolCallRequest): Promise<unknown> {
   const { toolPath, input, callId } = call;
-  const persistedCall = (await ctx.runMutation(internal.database.upsertToolCallRequested, {
+  const persistedCall = await upsertRequestedToolCall(ctx, {
     taskId: task.id,
     callId,
     workspaceId: task.workspaceId,
     toolPath,
-  })) as ToolCallRecord;
+  });
   assertPersistedCallRunnable(persistedCall, callId);
   let effectiveToolPath = toolPath;
   try {
-    const policies = await ctx.runQuery(internal.database.listAccessPolicies, { workspaceId: task.workspaceId });
+    const typedPolicies = await listWorkspaceAccessPolicies(ctx, task.workspaceId);
-    const typedPolicies = policies as AccessPolicyRecord[];
     const finalizeImmediateTool = async (value: unknown): Promise<unknown> => {
       if (persistedCall.status === "requested") {
         await publishTaskEvent(ctx, task.id, "task", "tool.call.started", {
     // Fast system tools are handled server-side from the registry.
     if (toolPath === "discover" || toolPath === "catalog.namespaces" || toolPath === "catalog.tools") {
-      const toolRegistry = internal.toolRegistry;
       const buildId = await getReadyRegistryBuildId(ctx, {
         workspaceId: task.workspaceId,
         actorId: task.actorId,
       if (toolPath === "catalog.namespaces") {
         const limit = Math.max(1, Math.min(200, Number(payload.limit ?? 200)));
-        const namespaces = await ctx.runQuery(toolRegistry.listNamespaces, {
+        const namespaces = await listRegistryNamespaces(ctx, {
           workspaceId: task.workspaceId,
           buildId,
           limit,
-        }) as Array<{ namespace: string; toolCount: number; samplePaths: string[] }>;
+        });
         return await finalizeImmediateTool({ namespaces, total: namespaces.length });
       }
         const limit = Math.max(1, Math.min(200, Number(payload.limit ?? 50)));
         const raw = query
-          ? await ctx.runQuery(toolRegistry.searchTools, {
+          ? await searchRegistryTools(ctx, {
               workspaceId: task.workspaceId,
               buildId,
               query,
               limit,
             })
           : namespace
-            ? await ctx.runQuery(toolRegistry.listToolsByNamespace, {
+            ? await listRegistryToolsByNamespace(ctx, {
                 workspaceId: task.workspaceId,
                 buildId,
                 namespace,
               })
             : [];
-        const results = (raw as RegistryToolEntry[])
+        const results = raw
           .filter((entry) => !namespace || String(entry.preferredPath ?? entry.path ?? "").toLowerCase().startsWith(`${namespace}.`))
           .filter((entry) => isAllowed(entry.path, entry.approval))
           .slice(0, limit)
       const query = String(payload.query ?? "").trim();
       const limit = Math.max(1, Math.min(50, Number(payload.limit ?? 8)));
       const compact = payload.compact === false ? false : true;
-      const hits = await ctx.runQuery(toolRegistry.searchTools, {
+      const hits = await searchRegistryTools(ctx, {
         workspaceId: task.workspaceId,
         buildId,
         query,
         limit: Math.max(limit * 2, limit),
-      }) as RegistryToolEntry[];
+      });
       const filtered = hits
         .filter((entry) => isAllowed(entry.path, entry.approval))
       }
       if (existingApproval.status === "pending") {
-        throw new Error(`${APPROVAL_PENDING_PREFIX}${existingApproval.id}`);
+        throw new ToolCallControlError({
+          kind: "approval_pending",
+          approvalId: existingApproval.id,
+        });
       }
       if (existingApproval.status === "denied") {
       });
       if (approval.status === "pending") {
-        throw new Error(`${APPROVAL_PENDING_PREFIX}${approval.id}`);
+        throw new ToolCallControlError({
+          kind: "approval_pending",
+          approvalId: approval.id,
+        });
       }
       if (approval.status === "denied") {
     return value;
   } catch (error) {
     const message = describeError(error);
-    const isApprovalControlSignal =
+    const controlSignal = decodeToolCallControlSignal(error);
-      message.startsWith(APPROVAL_PENDING_PREFIX) ||
-      message.startsWith(APPROVAL_DENIED_PREFIX);
-    if (!isApprovalControlSignal) {
+    if (!controlSignal) {
       await failToolCall(ctx, {
         taskId: task.id,
         callId,