Keep activated tools advertised across resume and rebuild (#912)

* Keep activated tools advertised across resume and rebuild

* Wire exec tool_search promotion into the call gate

Exec installed the same advertised-set call gate as the TUI but left tool_search's promoter as a no-op, so MCP names the model was told to call were refused.

* Include pinnedTools in the local settings load fixture

Author: TheGreatAxios

docs/MCP.md

@@ -88,7 +88,21 @@ global or local `exa` entry disables or overrides it as described above.
 Tools from connected servers are not advertised to the model up front; they are
 registered for dispatch as soon as the server connects (including later in the
 same turn) and surfaced on demand through dynamic tool discovery
-(`tool_search`).
+(`tool_search`). Names activated via `tool_search` persist in the session's
+`run.json` and are re-advertised on resume and after rebuilds.
+
+For integrations a project calls constantly, `pinnedTools` in local
+`.corbits/settings.json` keeps those names on the wire permanently — no
+`tool_search` activation needed:
+
+```jsonc
+{
+  "pinnedTools": ["mcp__linear__save_issue", "mcp__linear__get_issue"],
+}
+```
+
+Pinned names apply to any registered tool (MCP, plugin, or otherwise); a name
+with no matching tool is inert.
 
 In the TUI, `/mcp` opens the live server surface. Press **Alt+A**
 to add a named absolute HTTP(S) endpoint to global settings and connect it in the

src/agent/tool-search.ts

@@ -7,14 +7,14 @@ import type { SessionMode } from "../config/session-mode.js";
 import { sessionModeEnablesSubAgents } from "../config/session-mode.js";
 
 // Tools whose full schema is always advertised to the model. Everything else is
-// registered and dispatchable but discovered on demand via tool_search, keeping
-// the per-turn context small. Shared by the system prompt and the advertised-set
-// gate so the two never drift.
+// registered but discovered on demand via tool_search, which promotes matches
+// onto the advertised set and the call gate. Shared by the system prompt and
+// the advertised-set gate so the two never drift.
 //
 // `present` is deliberately absent: most sessions never render a view, and at
-// 2,793 chars it is the second-largest schema on the wire. It stays fully
-// dispatchable — the model finds it via tool_search when a session actually
-// needs it.
+// 2,793 chars it is the second-largest schema on the wire. It stays off the
+// advertised prefix — the model finds it via tool_search when a session
+// actually needs it.
 //
 // Product mutation tools (write_file / edit_file / delete_file) sit in CORE so
 // the primary Skywalker session can DIY tiny/bounded edits without a
@@ -162,7 +162,11 @@ export function advertisedTools(
 export interface ActivatedToolTracker {
   // Adds any new names and returns whether the set actually changed.
   activate(names: readonly string[]): boolean;
+  has(name: string): boolean;
   list(): string[];
+  // Session rotation (/clear, /new) mints a new transcript whose model never
+  // saw the activations — the advertised set starts clean with it.
+  clear(): void;
 }
 
 export function createActivatedToolTracker(): ActivatedToolTracker {
@@ -178,16 +182,22 @@ export function createActivatedToolTracker(): ActivatedToolTracker {
       }
       return changed;
     },
+    has(name: string): boolean {
+      return activeNames.has(name);
+    },
     list(): string[] {
       return [...activeNames];
     },
+    clear(): void {
+      activeNames.clear();
+    },
   };
 }
 
 export const toolSearchDefinition: ToolDefinition = {
   name: "tool_search",
   description:
-    "Discover callable tools by capability. Most tools — MCP servers, present, and other integrations — are dispatchable but not advertised in the tools list. Core tools (read_file, run_shell, web_fetch, web_search, spawn_agent, wait_agents, …) are already on the wire — do not tool_search for them. Call this with a short description of what you need (e.g. 'issue tracker', 'render layout', 'granola notes') to get matching tools' names, descriptions, and input schemas. The returned tools are already callable — invoke them directly, no separate load step.",
+    "Discover callable tools by capability. Most tools — MCP servers, present, and other integrations — are not advertised until this search promotes them onto the wire. Core tools (read_file, run_shell, web_fetch, web_search, spawn_agent, wait_agents, …) are already on the wire — do not tool_search for them. Call this with a short description of what you need (e.g. 'issue tracker', 'render layout', 'granola notes') to get matching tools' names, descriptions, and input schemas. Matched tools are promoted and callable on return — invoke them directly, no separate load step.",
   inputSchema: {
     type: "object",
     properties: {
@@ -257,9 +267,9 @@ export function createToolIndex(
 export interface ToolSearchDeps {
   search: (query: string) => string[];
   lookup: (name: string) => ToolDefinition | undefined;
-  // Make the matched tools' names part of the advertised wire set on the next
-  // inference. Every registered tool is already dispatchable via `run`, so this
-  // only affects what the model can see without an intervening tool_search.
+  // Promote matches onto the advertised set and the call gate so the model can
+  // invoke them this turn. The next inference also declares them on the wire
+  // for strict providers.
   promote: (names: string[]) => void;
 }
 

src/agent/tools.ts

@@ -217,6 +217,10 @@ export interface AgentToolsetArgs {
   // Real sessions always pass their detected values — see tool-search.ts for
   // why these must be fixed for the session's life.
   toolAvailability?: ToolAvailability;
+  // Per-project pinned tool names (local settings). They join the advertised
+  // prefix at the session layer; here they are excluded from tool_search so
+  // discovery only surfaces names not already on the wire.
+  pinnedTools?: readonly string[];
   // Records skill loads and sub-agent dispatch. Omitted (tests, ad-hoc
   // toolsets) means those events are never emitted.
   telemetry?: Telemetry;
@@ -361,10 +365,10 @@ export async function createAgentToolset(
       ? createLazyBlobReader(getBlobReader)
       : undefined;
   const subAgentsEnabled = sessionModeEnablesSubAgents(sessionMode);
-  const advertisedBuiltIns = advertisedToolNamesForSessionMode(
-    sessionMode,
-    toolAvailability,
-  );
+  const advertisedBuiltIns = [
+    ...advertisedToolNamesForSessionMode(sessionMode, toolAvailability),
+    ...(args.pinnedTools ?? []),
+  ];
   const skills =
     args.skills !== undefined
       ? [...args.skills]

src/config/settings.ts

@@ -401,6 +401,11 @@ export interface LocalSettings {
   // addition to the process's own inherited environment). Configuration
   // instead of a shell command that mutates the environment mid-session.
   env?: Record<string, string>;
+  // Tool names always advertised on the wire for this project — e.g. hot MCP
+  // integrations ("mcp__linear__save_issue") that should never need a
+  // tool_search activation round-trip. Names that resolve to no registered
+  // tool are inert.
+  pinnedTools?: string[];
 }
 
 // The provider fields the runtime consumes, identical to what the env vars used
@@ -603,6 +608,7 @@ const LocalSettingsSchema = type({
   "sessionMode?": "'single' | 'orchestrator'",
 
   "env?": "Record<string, string>",
+  "pinnedTools?": "string[]",
   // Reject any other key so local settings can never smuggle credentials.
   "+": "reject",
 });
@@ -793,6 +799,7 @@ export const LOCAL_SETTINGS_OPTIONAL_KEYS = [
   "mcpServers",
   "sessionMode",
   "env",
+  "pinnedTools",
 ] as const satisfies readonly (keyof OptionalLocalSettingsFields)[];
 
 /**
@@ -1045,6 +1052,7 @@ function pickLocalFields(
       sessionMode:
         s.sessionMode === "orchestrator" ? "orchestrator" : undefined,
       env: s.env as Record<string, string> | undefined,
+      pinnedTools: s.pinnedTools as string[] | undefined,
     };
   }
   return {
@@ -1069,6 +1077,9 @@ function pickLocalFields(
             ),
           )
         : undefined,
+    pinnedTools: Array.isArray(s.pinnedTools)
+      ? s.pinnedTools.filter((name): name is string => typeof name === "string")
+      : undefined,
   };
 }
 
@@ -1084,7 +1095,7 @@ function coerceLocalSettings(
         {
           path,
           message: `Local settings in ${path} is not a JSON object.`,
-          fix: `Edit ${path} to a JSON object with only: provider, model, reasoningEffort, mcpServers, sessionMode, env.`,
+          fix: `Edit ${path} to a JSON object with only: provider, model, reasoningEffort, mcpServers, sessionMode, env, pinnedTools.`,
         },
       ],
     };
@@ -1141,7 +1152,7 @@ function coerceLocalSettings(
     diagnostics.push({
       path,
       message: `Local settings in ${path} had invalid values and were partially ignored.`,
-      fix: `Edit ${path}: only "provider", "model", "reasoningEffort", "mcpServers", "sessionMode", and "env" are allowed (no credentials).`,
+      fix: `Edit ${path}: only "provider", "model", "reasoningEffort", "mcpServers", "sessionMode", "env", and "pinnedTools" are allowed (no credentials).`,
     });
   }
   const settings = pickDefined(optional);
@@ -1336,7 +1347,7 @@ export async function saveLocalSettings(
 ): Promise<void> {
   if (!isLocalSettings(local)) {
     throw new Error(
-      `Refusing to write invalid local settings: only "provider", "model", "reasoningEffort", "mcpServers", and "sessionMode" are allowed.`,
+      `Refusing to write invalid local settings: only "provider", "model", "reasoningEffort", "mcpServers", "sessionMode", "env", and "pinnedTools" are allowed.`,
     );
   }
   const payload = JSON.stringify(local, null, 2);

src/exec/runner.ts

@@ -17,9 +17,17 @@ import { xaiProfileFromProviderName } from "../config/xai-providers.js";
 import { formatDirectorSystemPrompt } from "../agent/directors/identity.js";
 import { DIRECTOR_REGISTRY } from "../agent/directors/registry.js";
 import type { DirectorId } from "../agent/directors/types.js";
+import { submitOutputDefinition } from "../agent/director.js";
+import {
+  shellDefinition,
+  updatePlanDefinition,
+} from "../agent/codex-tool-proxies.js";
 import { getValidCodexToken } from "../auth/codex/session.js";
 import { getValidXaiToken } from "../auth/xai/session.js";
-import { type ToolAvailability } from "../agent/tool-search.js";
+import {
+  type ActivatedToolTracker,
+  type ToolAvailability,
+} from "../agent/tool-search.js";
 import { detectLanguageServerAvailable } from "../agent/lsp-availability.js";
 import {
   resolveSessionMode,
@@ -36,6 +44,7 @@ import type {
   ContextStore,
   InferenceSource,
   InboundMessage,
+  ToolDefinition,
 } from "@intx/types/runtime";
 import { OPERATOR_ORIGINATED_FLAG } from "../agent/message-provenance.js";
 import { loadAgentProfiles } from "../agent/profiles.js";
@@ -329,6 +338,33 @@ export interface ExecResult {
   model?: string;
 }
 
+export function createExecToolCallGate(
+  isAdvertised: (name: string) => boolean,
+  options: { isCodex: boolean },
+): (name: string) => boolean {
+  const unadvertisedCallable = new Set<string>([
+    submitOutputDefinition.name,
+    ...(options.isCodex
+      ? [shellDefinition.name, updatePlanDefinition.name]
+      : []),
+  ]);
+  return (name) => unadvertisedCallable.has(name) || isAdvertised(name);
+}
+
+export function createExecToolPromoter(args: {
+  activate: (names: readonly string[]) => boolean;
+  currentDefinitions: () => readonly ToolDefinition[];
+  computeAdvertised: (all: readonly ToolDefinition[]) => ToolDefinition[];
+  updateDirectorTools: (defs: ToolDefinition[]) => void;
+  persist?: () => void;
+}): (names: string[]) => void {
+  return (names) => {
+    if (!args.activate(names)) return;
+    args.updateDirectorTools(args.computeAdvertised(args.currentDefinitions()));
+    args.persist?.();
+  };
+}
+
 /**
  * Product non-TUI agent path (`corbits exec "prompt"`).
  *
@@ -383,6 +419,9 @@ export async function runExec(config: Config): Promise<ExecResult> {
   let providerFailureObserved = false;
   let providerError: InferenceErrorLike | undefined;
   let result: ExecResult | undefined;
+  // Assigned once the advertised toolset exists (below); persist reads it live
+  // so a snapshot taken before that point still writes, just without the field.
+  const activatedToolsRef: { current?: ActivatedToolTracker } = {};
   const activeRunHandle: RunStateHandle = {
     sessionId,
     cwd: config.cwd,
@@ -405,11 +444,13 @@ export async function runExec(config: Config): Promise<ExecResult> {
     }
     const model = `${config.providerName}:${config.model}`;
     const nextTurnsUsed = runSink?.getTurnCount() ?? turnsUsed;
+    const activatedTools = activatedToolsRef.current?.list() ?? [];
     syncRunStateHandle(activeRunHandle, {
       turnsUsed: nextTurnsUsed,
       task,
       startedAt,
       model,
+      activatedTools,
     });
     const snapshot = {
       status,
@@ -418,6 +459,7 @@ export async function runExec(config: Config): Promise<ExecResult> {
       startedAt,
       model,
       mcpServers: connectedMcp,
+      ...(activatedTools.length > 0 ? { activatedTools } : {}),
       ...(status !== "running" ? { finishedAt: Date.now() } : {}),
       ...(extra?.error !== undefined ? { error: extra.error } : {}),
     };
@@ -567,6 +609,9 @@ export async function runExec(config: Config): Promise<ExecResult> {
       ...(localSettingsForMode?.env !== undefined
         ? { shellEnv: localSettingsForMode.env }
         : {}),
+      ...(localSettingsForMode?.pinnedTools !== undefined
+        ? { pinnedTools: localSettingsForMode.pinnedTools }
+        : {}),
       getBlobWriter: () => currentStorage?.writeBlob,
       getEvidenceArchive: () => evidenceArchiveHolder.current,
       getContextDir: () => workdir,
@@ -695,13 +740,27 @@ export async function runExec(config: Config): Promise<ExecResult> {
       },
     });
 
-    const { activated: activatedToolNames, computeAdvertised } =
-      createAdvertisedToolset({
-        sessionMode,
-        toolAvailability,
-        getProvider: () => config,
-        builtInPrefix: overlay.advertisedAllow,
-      });
+    const {
+      activated: activatedToolNames,
+      computeAdvertised,
+      isAdvertised,
+    } = createAdvertisedToolset({
+      sessionMode,
+      toolAvailability,
+      getProvider: () => config,
+      builtInPrefix: overlay.advertisedAllow,
+      ...(localSettingsForMode?.pinnedTools !== undefined
+        ? { pinnedTools: localSettingsForMode.pinnedTools }
+        : {}),
+    });
+    activatedToolsRef.current = activatedToolNames;
+    // Same wire contract as the TUI: a registered tool the model was never
+    // shown errors toward tool_search instead of dispatching blind.
+    agentToolset.dynamicRunner.setCallGate(
+      createExecToolCallGate(isAdvertised, {
+        isCodex: isCodexProviderName(config.providerName),
+      }),
+    );
 
     const { directorHolder, buildAgent } = assembleChatAgent({
       toolsId: `${ID_PREFIX}/exec-tools`,
@@ -741,6 +800,10 @@ export async function runExec(config: Config): Promise<ExecResult> {
       getCompactor: () =>
         createSessionPruningCompactor({
           summarize: summarizeForCompaction,
+          summaryContext: () => {
+            const tools = activatedToolNames.list();
+            return tools.length > 0 ? { activatedTools: tools } : undefined;
+          },
           telemetry: liveTelemetry,
         }),
       onBuilt: (agent, storage) => {
@@ -750,6 +813,23 @@ export async function runExec(config: Config): Promise<ExecResult> {
       evidenceArchiveHolder,
     });
 
+    // tool_search starts as a no-op promoter; without this, the call gate
+    // refuses MCP/present/plugin names the result just told the model to
+    // invoke.
+    agentToolset.setToolPromoter(
+      createExecToolPromoter({
+        activate: (names) => activatedToolNames.activate(names),
+        currentDefinitions: () =>
+          agentToolset.dynamicRunner.currentDefinitions(),
+        computeAdvertised,
+        updateDirectorTools: (defs) =>
+          directorHolder.instance?.updateToolDefinitions(defs),
+        persist: () => {
+          void persist("running");
+        },
+      }),
+    );
+
     const workflowHost = new WorkflowHost({
       cwd: config.cwd,
       getSessionId: () => sessionId,

src/index.ts

@@ -228,6 +228,9 @@ async function finalizeActiveRunOnCrash(error: unknown): Promise<void> {
       finishedAt: Date.now(),
       error: message,
       ...(run.model !== undefined ? { model: run.model } : {}),
+      ...(run.activatedTools !== undefined
+        ? { activatedTools: run.activatedTools }
+        : {}),
     });
   } catch (saveErr: unknown) {
     process.stderr.write(
@@ -273,6 +276,9 @@ async function finalizeActiveRunOnSignal(
       finishedAt: Date.now(),
       error: `terminated by ${signal}`,
       ...(run.model !== undefined ? { model: run.model } : {}),
+      ...(run.activatedTools !== undefined
+        ? { activatedTools: run.activatedTools }
+        : {}),
     });
   } catch (saveErr: unknown) {
     process.stderr.write(