@desplega.ai/agent-swarm 1.166.0 → 1.168.0

package/src/providers/codex-oauth/auth-json.ts

@@ -2,7 +2,7 @@
  * Conversion utilities between CodexOAuthCredentials (our internal type)
  * and ~/.codex/auth.json (the format the Codex CLI reads natively).
  *
- * The Codex CLI expects auth.json in this exact format:
+ * The Codex CLI expects these native auth.json fields:
  * {
  *   "auth_mode": "chatgpt",
  *   "OPENAI_API_KEY": null,
@@ -14,6 +14,7 @@
  *   },
  *   "last_refresh": "<ISO 8601>"
  * }
+ * Swarm also writes optional `expires` metadata for lossless conversion.
  *
  * Note: `id_token` is set to the `access_token` value because the token
  * exchange endpoint doesn't return a separate `id_token`. This matches
@@ -23,7 +24,7 @@
  */
 
 import { codexPlanFromClaim } from "../../utils/subscription-plans.js";
-import { extractChatgptPlanType, extractChatgptUserId } from "./flow.js";
+import { decodeJwt, extractChatgptPlanType, extractChatgptUserId } from "./flow.js";
 import type { CodexAuthJson, CodexOAuthCredentials } from "./types.js";
 
 /**
@@ -96,15 +97,31 @@ export function credentialsToAuthJson(
       refresh_token: includeRefreshToken ? creds.refresh : "",
       account_id: creds.accountId,
     },
-    last_refresh: new Date(creds.expires).toISOString(),
+    last_refresh: new Date().toISOString(),
+    // Swarm-only metadata keeps opaque-token round trips lossless. Codex
+    // ignores this field and may drop it when it rewrites auth.json.
+    expires: creds.expires,
   };
 }
 
 export function authJsonToCredentials(auth: CodexAuthJson): CodexOAuthCredentials {
+  // A CLI refresh may replace the access token and discard our metadata.
+  // Prefer its JWT expiry, which describes the token actually in the file.
+  const exp = decodeJwt(auth.tokens.access_token)?.exp;
+  const jwtExpires = typeof exp === "number" ? exp * 1000 : NaN;
+  const expires =
+    Number.isFinite(jwtExpires) && jwtExpires >= 0
+      ? jwtExpires
+      : typeof auth.expires === "number" && Number.isFinite(auth.expires)
+        ? auth.expires
+        : new Date(auth.last_refresh).getTime();
+
   return {
     access: auth.tokens.access_token,
     refresh: auth.tokens.refresh_token,
-    expires: new Date(auth.last_refresh).getTime(),
+    // Legacy swarm files put expiry in last_refresh; keep that fallback
+    // only when neither the token nor the explicit metadata carries it.
+    expires,
     accountId: auth.tokens.account_id,
   };
 }

package/src/providers/codex-oauth/types.ts

@@ -28,6 +28,8 @@ export type CodexAuthJson = {
     account_id: string;
   };
   last_refresh: string;
+  /** Swarm-only access-token expiry (milliseconds); native Codex files omit it. */
+  expires?: number;
 };
 
 type TokenResult =

package/src/providers/dsh-adapter.ts

@@ -9,7 +9,10 @@ import {
 } from "../utils/context-window";
 import { addDshStepUsage, type DshStepUsage, normalizeDshStepUsage } from "../utils/dsh-usage";
 import { swarmRuntimeInstanceId } from "../utils/multi-runtime";
-import { getOpenRouterBaseUrl } from "../utils/openrouter-base-url";
+import {
+  getOpenRouterAttributionHeaders,
+  getOpenRouterBaseUrl,
+} from "../utils/openrouter-base-url";
 import {
   detachedProcessGroup,
   registerProcessGroup,
@@ -34,7 +37,7 @@ import type {
 } from "./types";
 
 // npm's `latest` is older and lacks the JSON/stdin contract used here.
-export const DSH_PACKAGE = "@deepseek-ai/dsh@0.2.1-alpha.1";
+export const DSH_PACKAGE = "@deepseek-ai/dsh@0.2.1-alpha.2";
 
 export function checkDshCredentials(env: Record<string, string | undefined>): CredStatus {
   return env.DEEPSEEK_API_KEY?.trim() || env.OPENROUTER_API_KEY?.trim()
@@ -342,6 +345,9 @@ export class DshAdapter implements ProviderAdapter {
     const directory = await mkdtemp(join(tmpdir(), "swarm-dsh-"));
     try {
       const patchPath = join(directory, "patch.json");
+      const openRouterHeaders = openrouter
+        ? getOpenRouterAttributionHeaders(getOpenRouterBaseUrl(env), env)
+        : {};
       const runtimeInstanceId = swarmRuntimeInstanceId();
       // JSON is valid YAML. Values stay data, including arbitrary system prompts.
       await writeFile(
@@ -364,6 +370,9 @@ export class DshAdapter implements ProviderAdapter {
                     openrouter: {
                       apiKeyEnv: keyEnv,
                       baseURL: getOpenRouterBaseUrl(env),
+                      ...(Object.keys(openRouterHeaders).length > 0
+                        ? { headers: openRouterHeaders }
+                        : {}),
                       api: "openai-completions",
                       // Declare the selected ID even if the bundled catalog predates it.
                       models: [

package/src/providers/grok-adapter.ts

@@ -3,7 +3,10 @@ import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { normalizeGrokModel } from "@desplega/model-catalog";
-import { getOpenRouterBaseUrl } from "../utils/openrouter-base-url";
+import {
+  getOpenRouterAttributionHeaders,
+  getOpenRouterBaseUrl,
+} from "../utils/openrouter-base-url";
 import { registerVolatileSecret } from "../utils/secret-scrubber";
 import { ACPAdapter } from "./acp-adapter";
 import { grokTargetProfile, isGrokOpenRouterModel } from "./acp-targets";
@@ -64,6 +67,8 @@ export interface GrokCustomModel {
   baseUrl: string;
   /** Env var holding the endpoint's API key. */
   envKey: string;
+  /** Sent verbatim on every request to the endpoint (`extra_headers`). */
+  headers?: Record<string, string>;
 }
 
 /** `openrouter/<vendor>/<id>` -> a `[model."openrouter/<vendor>/<id>"]` block on OpenRouter. */
@@ -73,14 +78,24 @@ export function grokOpenRouterModel(
 ): GrokCustomModel | null {
   const id = model.trim();
   if (!isGrokOpenRouterModel(id)) return null;
+  const baseUrl = getOpenRouterBaseUrl(env);
   return {
     id,
     model: id.slice("openrouter/".length),
-    baseUrl: getOpenRouterBaseUrl(env),
+    baseUrl,
     envKey: "OPENROUTER_API_KEY",
+    headers: getOpenRouterAttributionHeaders(baseUrl, env),
   };
 }
 
+/** `key = { "k" = "v", ... }`, or nothing for an empty map. JSON strings are valid TOML basic strings. */
+function tomlInlineTable(key: string, entries: Record<string, string> | undefined): string[] {
+  const pairs = Object.entries(entries ?? {});
+  if (pairs.length === 0) return [];
+  const body = pairs.map(([k, v]) => `${JSON.stringify(k)} = ${JSON.stringify(v)}`).join(", ");
+  return [`${key} = { ${body} }`];
+}
+
 /** `$GROK_HOME/config.toml` for one swarm session. */
 export function buildGrokConfigToml(
   disabledPlugins: readonly string[],
@@ -95,6 +110,7 @@ export function buildGrokConfigToml(
         `base_url = ${JSON.stringify(customModel.baseUrl)}`,
         `env_key = ${JSON.stringify(customModel.envKey)}`,
         `api_backend = "chat_completions"`,
+        ...tomlInlineTable("extra_headers", customModel.headers),
       ]
     : [];
   return [

package/src/providers/opencode-adapter.ts

@@ -20,7 +20,11 @@ import {
 import { validateOpencodeCredentials } from "../utils/credentials";
 import { fetchInstalledMcpServers } from "../utils/mcp-server-fetcher";
 import { swarmRuntimeInstanceId } from "../utils/multi-runtime";
-import { DEFAULT_OPENROUTER_BASE_URL, getOpenRouterBaseUrl } from "../utils/openrouter-base-url";
+import {
+  DEFAULT_OPENROUTER_BASE_URL,
+  getOpenRouterAttributionHeaders,
+  getOpenRouterBaseUrl,
+} from "../utils/openrouter-base-url";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { resolveSlashSkillPrompt } from "./codex-skill-resolver";
 import { CTX_MODE_NUDGE_EVERY } from "./ctx-mode-env";
@@ -177,22 +181,34 @@ function formatUnknownError(err: unknown): string {
  * Route OpenRouter traffic through the configured gateway (see
  * src/utils/openrouter-base-url.ts). opencode's bundled openrouter provider
  * honors `provider.openrouter.options.baseURL`. Mutates `opencodeConfig` in
- * place; no-op when `OPENROUTER_BASE_URL` is unset/blank/default, so default
- * openrouter.ai behavior is preserved. Exported for tests.
+ * place, and attribute direct OpenRouter requests to Agent Swarm.
  */
 export function applyOpenRouterBaseUrlOverride(
   opencodeConfig: Config,
   env: Record<string, string | undefined> = process.env,
 ): void {
   const openRouterBaseUrl = getOpenRouterBaseUrl(env as NodeJS.ProcessEnv);
-  if (openRouterBaseUrl === DEFAULT_OPENROUTER_BASE_URL) return;
+  const headers = getOpenRouterAttributionHeaders(openRouterBaseUrl, env);
+  const overrideBaseUrl = openRouterBaseUrl !== DEFAULT_OPENROUTER_BASE_URL;
+  if (!overrideBaseUrl && Object.keys(headers).length === 0) return;
   opencodeConfig.provider = {
     ...opencodeConfig.provider,
     openrouter: {
       ...opencodeConfig.provider?.openrouter,
       options: {
         ...opencodeConfig.provider?.openrouter?.options,
-        baseURL: openRouterBaseUrl,
+        ...(overrideBaseUrl ? { baseURL: openRouterBaseUrl } : {}),
+        ...(Object.keys(headers).length > 0
+          ? {
+              headers: {
+                ...(opencodeConfig.provider?.openrouter?.options?.headers as
+                  | Record<string, string>
+                  | undefined),
+                ...headers,
+                "X-Title": "Agent Swarm",
+              },
+            }
+          : {}),
       },
     },
   };

package/src/providers/pi-mono-extension.ts

@@ -11,6 +11,7 @@ import { buildRatingsFromLlm, fetchRetrievalsForTask, postRatings } from "../be/
 import { checkToolLoop, clearToolHistory } from "../hooks/tool-loop-detection";
 import { summarizeSession as runSummarize } from "../utils/internal-ai";
 import { getMemoryRaterNames } from "../utils/memory-raters";
+import { getOpenRouterAttributionHeaders } from "../utils/openrouter-base-url";
 import { scrubSecrets } from "../utils/secret-scrubber";
 
 export interface SwarmHooksConfig {
@@ -421,6 +422,24 @@ export async function summarizeSessionForPi(
   }
 }
 
+/** `customType` of the advisory messages this extension sends to the model. */
+export const SWARM_NUDGE_CUSTOM_TYPE = "swarm-nudge";
+
+/**
+ * Deliver an advisory nudge to the model. pi runs extensions in-process and
+ * never feeds their stdout to the model, so a console.log here only reaches
+ * the worker log. `sendMessage` steers the text in after the current tool
+ * batch while the agent is streaming, and otherwise appends it to the session
+ * so the next prompt carries it.
+ */
+function sendNudge(pi: Parameters<ExtensionFactory>[0], text: string): void {
+  pi.sendMessage({
+    customType: SWARM_NUDGE_CUSTOM_TYPE,
+    content: [{ type: "text", text }],
+    display: false,
+  });
+}
+
 /**
  * Create the swarm hooks extension factory for pi-mono.
  *
@@ -431,6 +450,13 @@ export function createSwarmHooksExtension(config: SwarmHooksConfig): ExtensionFa
   return (pi) => {
     let lastContextPostTime = 0;
 
+    pi.on("before_provider_headers", (event, ctx) => {
+      Object.assign(
+        event.headers,
+        getOpenRouterAttributionHeaders(ctx.model?.baseUrl ?? "", config.env),
+      );
+    });
+
     // === session_start → SessionStart ===
     pi.on("session_start", async (_event, _ctx) => {
       // Installed MCP servers: pi's MCP extension connects them in the
@@ -458,7 +484,7 @@ export function createSwarmHooksExtension(config: SwarmHooksConfig): ExtensionFa
       if (config.isLead) {
         const ctx = await fetchConcurrentContext(config);
         if (ctx) {
-          console.log(ctx);
+          sendNudge(pi, ctx);
         }
       }
     });
@@ -498,7 +524,7 @@ export function createSwarmHooksExtension(config: SwarmHooksConfig): ExtensionFa
         }
 
         if (loopResult.severity === "warning" && loopResult.reason) {
-          console.log(`Warning: ${loopResult.reason}`);
+          sendNudge(pi, `Warning: ${loopResult.reason}`);
         }
       }
 
@@ -586,7 +612,8 @@ export function createSwarmHooksExtension(config: SwarmHooksConfig): ExtensionFa
 
       // Reminders
       if (config.isLead && event.toolName?.endsWith("send-task")) {
-        console.log(
+        sendNudge(
+          pi,
           "Task sent successfully. Monitor progress using the get-task-details tool periodically.",
         );
       }
@@ -594,29 +621,30 @@ export function createSwarmHooksExtension(config: SwarmHooksConfig): ExtensionFa
       return undefined;
     });
 
-    // === context → PreCompact ===
-    // The context event allows injecting messages before compaction.
-    // We log the goal reminder to console (it gets captured in context).
-    pi.on("context", async (_event, ctx) => {
-      if (!config.taskId) return undefined;
-
-      try {
-        const taskDetails = await fetchTaskDetails(config);
-        if (taskDetails) {
-          const reminder = [
-            "=== GOAL REMINDER (injected before context compaction) ===",
-            `Task ID: ${taskDetails.id}`,
-            `Task: ${taskDetails.task}`,
-          ];
-          if (taskDetails.progress) {
-            reminder.push(`Current Progress: ${taskDetails.progress}`);
-          }
-          reminder.push("=== Continue working on this task after compaction ===");
-          console.log(reminder.join("\n"));
+    // === session_compact → PreCompact ===
+    // Re-anchor the model on its task once compaction has summarized the
+    // history. `context` fires before every LLM call, so it cannot carry this.
+    pi.on("session_compact", async () => {
+      if (!config.taskId) return;
+
+      const taskDetails = await fetchTaskDetails(config);
+      if (taskDetails) {
+        const reminder = [
+          "=== GOAL REMINDER (injected before context compaction) ===",
+          `Task ID: ${taskDetails.id}`,
+          `Task: ${taskDetails.task}`,
+        ];
+        if (taskDetails.progress) {
+          reminder.push(`Current Progress: ${taskDetails.progress}`);
         }
-      } catch {
-        /* don't block compaction */
+        reminder.push("=== Continue working on this task after compaction ===");
+        sendNudge(pi, reminder.join("\n"));
       }
+    });
+
+    // === context (before every LLM call) ===
+    pi.on("context", async (_event, ctx) => {
+      if (!config.taskId) return undefined;
 
       // Report context usage as a compaction event
       const usage = ctx.getContextUsage?.();
@@ -644,7 +672,10 @@ export function createSwarmHooksExtension(config: SwarmHooksConfig): ExtensionFa
         const { cancelled, reason } = await isTaskCancelled(config);
         if (cancelled) {
           const cancelReason = reason || "Task cancelled by lead or creator";
-          console.log(
+          // "handled" skips the turn; the nudge lands in the session for the
+          // next one instead of paying for a turn on a cancelled task.
+          sendNudge(
+            pi,
             `🛑 TASK CANCELLED: ${cancelReason}. Stop working and use store-progress to acknowledge.`,
           );
           return { action: "handled" as const };

package/src/providers/pricing-sources.md

@@ -178,6 +178,8 @@ and heartbeat-classified roots are omitted, and the metrics remain separate.
 - **Codex usage:** the app-server reports cumulative token counters, including cache writes.
   The adapter calculates each turn's delta before adding it to the session total.
   This prevents repeated billing of earlier turns when the adapter processes queued input.
+  Context occupancy is separate: it comes from the per-request `tokenUsage.last`
+  snapshot (and `modelContextWindow` when present), never from the turn delta.
 - **Claude breakdown validity is all-or-nothing:** the claude adapter drops the
   entire `modelUsage` breakdown when any entry carries a missing, non-finite,
   or negative token counter — zero-filling would let the server price a

package/src/scheduler/scheduler.ts

@@ -15,6 +15,7 @@ import {
   getUserById,
   getWorkflow,
   getWorkflowRun,
+  recordInlineScriptRun,
   type UpdateScheduledTaskData,
   updateScheduledTask,
 } from "@/be/db";
@@ -32,6 +33,7 @@ import { startWorkflowExecution } from "@/workflows/engine";
 import type { ExecutorRegistry } from "@/workflows/executors/registry";
 import { handleScheduleTrigger } from "@/workflows/triggers";
 import { ensure } from "../utils/business-use";
+import { scrubObject, scrubSecrets } from "../utils/secret-scrubber";
 
 import {
   dispatchDeferredTaskWait,
@@ -83,23 +85,90 @@ async function executeScheduleScript(schedule: ScheduledTask): Promise<void> {
   }
 
   const agentId = schedule.createdByAgentId ?? "schedule";
-  const output = await runScript({
-    source: script.source,
-    args: schedule.scriptArgs ?? {},
-    fsMode: "none",
+  const args = schedule.scriptArgs ?? {};
+  const record = {
     agentId,
-    egressSecrets: await buildScriptCredentialBindings({ agentId }),
-    apiConnections: getScriptApiConnectionDescriptors({ agentId }),
-    mcpConnections: getScriptMcpConnectionDescriptors({ agentId }),
-    timeoutMs: 60_000,
-  });
+    scriptName: schedule.scriptName,
+    // A pointer, not a copy: script schedules fire as often as every minute and
+    // script_runs has no retention sweep, so copying the source on every fire
+    // would grow the table by tens of MB a day. script_versions keeps the text.
+    source: `// Scheduled run of '${script.name}' v${script.version} (global, contentHash ${script.contentHash}) by schedule '${schedule.name}'.\n// Full source: script_versions row for this version.\n`,
+    args,
+    startedAt: new Date().toISOString(),
+  };
+
+  let output: Awaited<ReturnType<typeof runScript>>;
+  try {
+    output = await runScript({
+      source: script.source,
+      args,
+      fsMode: "none",
+      agentId,
+      egressSecrets: await buildScriptCredentialBindings({ agentId }),
+      apiConnections: getScriptApiConnectionDescriptors({ agentId }),
+      mcpConnections: getScriptMcpConnectionDescriptors({ agentId }),
+      timeoutMs: 60_000,
+    });
+  } catch (err) {
+    await recordScheduleScriptRun({
+      ...record,
+      status: "failed",
+      error: err instanceof Error ? err.message : String(err),
+    });
+    throw err;
+  }
 
   if (output.exitCode !== 0 || output.error) {
-    throw new Error(
+    const message =
       output.stderr ||
-        `Script '${schedule.scriptName}' exited with code ${output.exitCode}${
-          output.error ? ` (${output.error})` : ""
-        }`,
+      `Script '${schedule.scriptName}' exited with code ${output.exitCode}${
+        output.error ? ` (${output.error})` : ""
+      }`;
+    await recordScheduleScriptRun({
+      ...record,
+      status: "failed",
+      output: output.result,
+      error: message,
+    });
+    throw new Error(message);
+  }
+
+  await recordScheduleScriptRun({ ...record, status: "completed", output: output.result });
+}
+
+/**
+ * Persist a scheduled script fire as a terminal `script_runs` row, so script
+ * audits see schedule-driven runs the same way as POST /api/scripts/run.
+ * Best effort: a persistence error never changes the schedule's outcome.
+ */
+async function recordScheduleScriptRun(run: {
+  agentId: string;
+  scriptName: string;
+  source: string;
+  args: unknown;
+  startedAt: string;
+  status: "completed" | "failed";
+  output?: unknown;
+  error?: string;
+}): Promise<void> {
+  try {
+    await recordInlineScriptRun({
+      id: crypto.randomUUID(),
+      agentId: run.agentId,
+      scriptName: run.scriptName,
+      source: run.source,
+      args: scrubObject(run.args),
+      status: run.status,
+      output: scrubObject(run.output),
+      error: run.error === undefined ? undefined : scrubSecrets(run.error),
+      startedAt: run.startedAt,
+      finishedAt: new Date().toISOString(),
+    });
+  } catch (err) {
+    console.warn(
+      `[scheduler] could not record script run for '${run.scriptName}': ${scrubSecrets(
+        err instanceof Error ? err.message : String(err),
+      )}`,
     );
   }
 }

package/src/scripts-runtime/executors/registry.ts

@@ -8,7 +8,7 @@ const EXECUTORS: Record<string, () => ScriptExecutor> = {
 };
 
 export function getScriptExecutor(name = process.env.SCRIPT_EXECUTOR ?? "native"): ScriptExecutor {
-  const factory = EXECUTORS[name];
+  const factory = EXECUTORS[name.trim()];
   if (!factory) {
     throw new Error(
       `Unknown SCRIPT_EXECUTOR: ${name}. Available: ${Object.keys(EXECUTORS).join(", ")}`,

package/src/server.ts

@@ -196,6 +196,7 @@ import {
   registerTriggerWorkflowTool,
   registerUpdateWorkflowTool,
 } from "./tools/workflows";
+import { parseEnabledTools } from "./utils/enabled-tools";
 import { resolveScriptsOnlyMode } from "./utils/scripts-only-mode";
 
 // Every known capability, including the ones disabled by default. Exported for
@@ -293,18 +294,75 @@ export function isScriptsOnlyMcp(): boolean {
   return resolveScriptsOnlyMode({ env: process.env.SCRIPTS_ONLY_MCP });
 }
 
+const loggedToolAllowlistWarnings = new Set<string>();
+
+function warnToolAllowlistOnce(message: string): void {
+  if (loggedToolAllowlistWarnings.has(message)) return;
+  loggedToolAllowlistWarnings.add(message);
+  console.warn(message);
+}
+
+/**
+ * SWARM_ENABLED_TOOLS: an optional explicit allowlist for the externally
+ * exposed MCP surface. Returns undefined (capability-driven surface) when the
+ * value is unset, blank, or invalid. Never logs the raw value.
+ */
+function resolveToolAllowlist(value: string | undefined): string[] | undefined {
+  if (value === undefined) return undefined;
+  try {
+    const tools = parseEnabledTools(value);
+    if (!tools) {
+      warnToolAllowlistOnce("[MCP] SWARM_ENABLED_TOOLS is set but lists no tools; ignoring it");
+    }
+    return tools;
+  } catch {
+    warnToolAllowlistOnce("[MCP] Invalid SWARM_ENABLED_TOOLS; ignoring it");
+    return undefined;
+  }
+}
+
+/** Drop every registered tool the allowlist does not name; warn on unknown names. */
+function applyToolAllowlist(server: McpServer, allowlist: readonly string[]): void {
+  const tools = (server as unknown as { _registeredTools: Record<string, { remove(): void }> })
+    ._registeredTools;
+  const allowed = new Set(allowlist);
+  for (const [name, tool] of Object.entries(tools)) {
+    if (!allowed.has(name)) tool.remove();
+  }
+  const unknown = allowlist.filter((name) => !Object.hasOwn(tools, name));
+  if (unknown.length > 0) {
+    warnToolAllowlistOnce(
+      `[MCP] SWARM_ENABLED_TOOLS names unknown tools, ignoring them: ${unknown.join(", ")}`,
+    );
+  }
+}
+
 export async function createServer(
-  opts: { scriptsOnly?: boolean; fullSurface?: boolean; preloadedTools?: readonly string[] } = {},
+  opts: {
+    scriptsOnly?: boolean;
+    fullSurface?: boolean;
+    preloadedTools?: readonly string[];
+    /** Raw SWARM_ENABLED_TOOLS value for this session; defaults to the env. */
+    enabledTools?: string;
+  } = {},
 ) {
   // Reload env
   await loadGlobalConfigsIntoEnv(true);
 
+  // The tool allowlist replaces CAPABILITIES and SCRIPTS_ONLY_MCP when set.
+  // Full-surface consumers (the scripts SDK bridge) ignore it.
+  const toolAllowlist =
+    opts.fullSurface === true
+      ? undefined
+      : resolveToolAllowlist(opts.enabledTools ?? process.env.SWARM_ENABLED_TOOLS);
+
   // Capability flags shape the externally exposed MCP tool list only. Internal
   // full-surface consumers (the scripts SDK bridge, drift-check tests) pass
   // fullSurface to register every tool group regardless of CAPABILITIES.
+  // An allowlist also registers every group, then prunes to the listed names.
   // This shadows the module-level hasCapability for the registrations below.
   const hasCapability = (cap: CAPABILITIES_T): boolean =>
-    opts.fullSurface === true || getCapabilities().has(cap);
+    opts.fullSurface === true || toolAllowlist !== undefined || getCapabilities().has(cap);
 
   // Initialize database with WAL mode
   // Uses DATABASE_PATH env var for Docker volume compatibility (WAL needs .sqlite, .sqlite-wal, .sqlite-shm on same filesystem)
@@ -355,7 +413,7 @@ export async function createServer(
   // Scripts-only surface (experimental code-mode): register just the script
   // catalog tools and stop. script-connections / script-apis stay out — they
   // are lead-only security admin and excluded from the scripts SDK too.
-  if (opts.scriptsOnly ?? isScriptsOnlyMcp()) {
+  if (toolAllowlist === undefined && (opts.scriptsOnly ?? isScriptsOnlyMcp())) {
     registerScriptSearchTool(server);
     registerScriptRunTool(server);
     registerScriptUpsertTool(server);
@@ -630,5 +688,7 @@ export async function createServer(
     registerUpdateServiceStatusTool(server);
   }
 
+  if (toolAllowlist) applyToolAllowlist(server, toolAllowlist);
+
   return server;
 }