Keep activated tools advertised across resume and rebuild

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

@@ -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,9 +182,15 @@ export function createActivatedToolTracker(): ActivatedToolTracker {
       }
       return changed;
     },
+    has(name: string): boolean {
+      return activeNames.has(name);
+    },
     list(): string[] {
       return [...activeNames];
     },
+    clear(): void {
+      activeNames.clear();
+    },
   };
 }
 

src/agent/tools.ts

@@ -218,6 +218,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;
@@ -362,10 +366,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,
@@ -382,6 +390,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,
@@ -404,11 +415,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,
@@ -417,6 +430,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 } : {}),
     };
@@ -566,6 +580,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,
@@ -680,13 +697,31 @@ export async function runExec(config: Config): Promise<ExecResult> {
       getArchive: () => evidenceArchiveHolder.current,
     });
 
-    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.
+    const unadvertisedCallable = new Set<string>([
+      submitOutputDefinition.name,
+      ...(isCodexProviderName(config.providerName)
+        ? [shellDefinition.name, updatePlanDefinition.name]
+        : []),
+    ]);
+    agentToolset.dynamicRunner.setCallGate(
+      (name) => unadvertisedCallable.has(name) || isAdvertised(name),
+    );
 
     const { directorHolder, buildAgent } = assembleChatAgent({
       toolsId: `${ID_PREFIX}/exec-tools`,
@@ -726,6 +761,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) => {

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(

src/session/active-run.ts

@@ -22,6 +22,10 @@ export interface RunStateHandle {
   startedAt: number;
   turnsUsed: number;
   model?: string;
+  // Latest tool_search-activated tool names, synced on every snapshot so the
+  // crash/signal terminal write can carry them into run.json for the resume
+  // seed.
+  activatedTools?: string[];
 }
 
 // Keep the crash/signal handle in step with every persisted snapshot so a
@@ -34,6 +38,7 @@ export function syncRunStateHandle(
     task: string;
     startedAt: number;
     model?: string;
+    activatedTools?: string[];
   },
 ): void {
   handle.turnsUsed = snapshot.turnsUsed;
@@ -42,6 +47,9 @@ export function syncRunStateHandle(
   if (snapshot.model !== undefined) {
     handle.model = snapshot.model;
   }
+  if (snapshot.activatedTools !== undefined) {
+    handle.activatedTools = snapshot.activatedTools;
+  }
 }
 
 let activeRun: RunStateHandle | null = null;

src/session/assemble-runtime.test.ts

@@ -73,6 +73,34 @@ describe("createAdvertisedToolset", () => {
     const { computeAdvertised } = createAdvertisedToolset(wiring());
     expect(computeAdvertised([])).toEqual([]);
   });
+
+  test("isAdvertised tracks prefix, pinned, and activated names", () => {
+    const { activated, isAdvertised } = createAdvertisedToolset(
+      wiring({ pinnedTools: ["mcp__linear__save_issue"] }),
+    );
+    expect(isAdvertised("read_file")).toBe(true);
+    expect(isAdvertised("mcp__linear__save_issue")).toBe(true);
+    expect(isAdvertised("mcp__acme__do")).toBe(false);
+    activated.activate(["mcp__acme__do"]);
+    expect(isAdvertised("mcp__acme__do")).toBe(true);
+  });
+
+  test("pinned tools are advertised before any activation and survive clear", () => {
+    const { activated, computeAdvertised } = createAdvertisedToolset(
+      wiring({ pinnedTools: ["mcp__linear__save_issue"] }),
+    );
+    const defs = [def("read_file"), def("mcp__linear__save_issue")];
+    expect(computeAdvertised(defs).map((d) => d.name)).toContain(
+      "mcp__linear__save_issue",
+    );
+    // A pinned name is part of the prefix, not the activation set — session
+    // rotation clearing activations does not drop it off the wire.
+    activated.activate(["mcp__acme__do"]);
+    activated.clear();
+    const names = computeAdvertised(defs).map((d) => d.name);
+    expect(names).toContain("mcp__linear__save_issue");
+    expect(names).not.toContain("mcp__acme__do");
+  });
 });
 
 describe("loadSessionLocalSettings", () => {

src/session/assemble-runtime.ts

@@ -325,22 +325,36 @@ export function resolveLiveSessionSources(
 export interface AdvertisedToolset {
   activated: ActivatedToolTracker;
   computeAdvertised: (all: readonly ToolDefinition[]) => ToolDefinition[];
+  // Whether a name is part of the advertised wire set: built-in prefix,
+  // project-pinned, or tool_search-activated. The dispatch gate keys off this
+  // so a registered-but-unadvertised call surfaces as a tool_search error
+  // instead of silently dispatching.
+  isAdvertised: (name: string) => boolean;
 }
 
 /**
  * Fixed built-in prefix plus session-activated tools, family-gated for the
  * wire. The provider identity is read per call so a live model switch
  * re-gates without rebuilding the agent.
+ *
+ * `pinnedTools` (local settings) merge into the prefix — advertised from the
+ * first turn and exempt from activation state, so a resume needs no
+ * tool_search round-trip for the project's hottest integrations.
  */
 export function createAdvertisedToolset(args: {
   sessionMode: SessionMode;
   toolAvailability: ToolAvailability;
   getProvider: () => { providerName: string; model: string };
   builtInPrefix?: readonly string[] | undefined;
+  pinnedTools?: readonly string[] | undefined;
 }): AdvertisedToolset {
-  const prefix =
+  const builtIn =
     args.builtInPrefix ??
     advertisedToolNamesForSessionMode(args.sessionMode, args.toolAvailability);
+  const prefix = [
+    ...builtIn,
+    ...(args.pinnedTools ?? []).filter((name) => !builtIn.includes(name)),
+  ];
   const activated = createActivatedToolTracker();
   // Advertise then family-gate wire schemas (kimi gets a non-recursive present).
   const computeAdvertised = (
@@ -352,7 +366,9 @@ export function createAdvertisedToolset(args: {
         ...args.getProvider(),
       },
     );
-  return { activated, computeAdvertised };
+  const isAdvertised = (name: string): boolean =>
+    prefix.includes(name) || activated.has(name);
+  return { activated, computeAdvertised, isAdvertised };
 }
 
 // ---------------------------------------------------------------------------