@devries-cameron20 / t3code-1 / commits / 34a7ab3641
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

fix(pi): T3 tools are callable by Pi's own mcp__t3_code__ names (#26845)

Julius Marminge committed Nov 19, 2026 at 12:43 UTC 34a7ab3641d39dd4eb5e863f2d6f38bc09b9bcbf
4 files changed +212 -26
docs/orchestration-v2/orchestrator-mcp-server.md
+6 -3
@@ -167,9 +167,12 @@ T3_MCP_BEARER_TOKEN=<provider-session-token>
167 ```
168
169 The extension preserves public names under `mcp__t3-code__` for saved loadouts
170 -and tool selectors. Modern Pi also receives hidden `mcp__t3_code__` aliases,
171 -which reserve the normalized namespace against configured MCP servers without
172 -adding declarations or search results. On Pi 0.99+,
170 +and tool selectors. Modern Pi also receives `mcp__t3_code__` aliases, Pi's own
171 +name for the server, which reserve it against configured MCP servers. They are
172 +`model-only` and hide their own declarations, so the model can call them without
173 +added declarations, search results, or codemode entries. An alias follows its
174 +public tool: dropped when that tool is excluded, and off while a direct one is
175 +off. Pi's `hidden` exposure would make them unreachable. On Pi 0.99+,
176 `orchestrator_capabilities`, `delegate_task`, and `task_status` remain directly
177 available; optional tools are discovered through Pi's builtin `tool_search`.
178 On older Pi or without builtin search, all tools remain directly available.
packages/provider-pi/src/server/mcpBridge.testkit.ts
+57
@@ -13,6 +13,12 @@ interface RegisteredTool {
13 readonly exposure?: string;
14 readonly promptSnippet?: string;
15 readonly promptGuidelines?: ReadonlyArray<string>;
16 + readonly prepareLoadout?: (loadout: {
17 + readonly declared: ReadonlyArray<RegisteredTool>;
18 + readonly callable: ReadonlyArray<RegisteredTool>;
19 + readonly registered: ReadonlyArray<RegisteredTool>;
20 + readonly getExposure: (name: string) => string;
21 + }) => { readonly hiddenDeclarations?: ReadonlyArray<string> } | undefined;
22 readonly execute: (
23 id: string,
24 args: Record<string, unknown>,
@@ -40,12 +46,20 @@ type AgentStartHook = (
46 },
47 ) => Promise<{ systemPrompt: string } | undefined>;
48
49 +function activatesOnRegistration(tool: RegisteredTool) {
50 + return (
51 + tool.exposure === undefined || tool.exposure === "direct" || tool.exposure === "model-only"
52 + );
53 +}
54 +
55 export async function loadMcpBridge(
56 options: {
57 readonly modern?: boolean;
58 readonly result?: unknown;
59 readonly toolSearchAvailable?: boolean;
60 readonly toolSearchDisabled?: boolean;
61 + // Pi activates direct and model-only tools when they are registered.
62 + readonly activatesOnRegistration?: boolean;
63 readonly allowsTool?: (name: string) => boolean;
64 readonly runtimeMode?: string;
65 readonly inputSchema?: Record<string, unknown>;
@@ -131,8 +145,17 @@ export async function loadMcpBridge(
145 registerTool: (tool: RegisteredTool) => {
146 if (options.allowsTool && !options.allowsTool(tool.name)) return;
147 const index = tools.findIndex((current) => current.name === tool.name);
148 + const previous = index === -1 ? undefined : tools[index];
149 if (index === -1) tools.push(tool);
150 else tools[index] = tool;
151 + if (
152 + options.activatesOnRegistration &&
153 + activatesOnRegistration(tool) &&
154 + (previous === undefined || !activatesOnRegistration(previous)) &&
155 + !activeTools.includes(tool.name)
156 + ) {
157 + activeTools = [...activeTools, tool.name];
158 + }
159 },
160 getActiveTools: () => activeTools,
161 setActiveTools: (names: string[]) => {
@@ -155,9 +178,43 @@ export async function loadMcpBridge(
178 : {}),
179 },
180 });
181 + const exposureOf = (name: string) =>
182 + tools.find((tool) => tool.name === name)?.exposure ?? "direct";
183 + // Pi resolves model tool calls against the active, non-hidden tools only.
184 + const modelTools = () =>
185 + tools.filter((tool) => activeTools.includes(tool.name) && exposureOf(tool.name) !== "hidden");
186 + // Pi's ctx.executeTool() catalog, which codemode scripts search and list.
187 + const callableTools = () =>
188 + tools.filter(
189 + (tool) =>
190 + ["codemode", "deferred"].includes(exposureOf(tool.name)) ||
191 + (exposureOf(tool.name) === "direct" && activeTools.includes(tool.name)),
192 + );
193 + const declaredTools = () => {
194 + const active = modelTools();
195 + const loadout = {
196 + declared: active,
197 + callable: callableTools(),
198 + registered: tools,
199 + getExposure: exposureOf,
200 + };
201 + const hidden = new Set(
202 + active.flatMap((tool) => tool.prepareLoadout?.(loadout)?.hiddenDeclarations ?? []),
203 + );
204 + return active.map((tool) => tool.name).filter((name) => !hidden.has(name));
205 + };
206 return {
207 handlers,
208 tools,
209 + declaredTools,
210 + callableTools: () => callableTools().map((tool) => tool.name),
211 + callModelTool: async (name: string, args: Record<string, unknown>) => {
212 + const tool = modelTools().find((candidate) => candidate.name === name);
213 + if (tool === undefined) {
214 + return { content: [{ type: "text", text: `Tool ${name} not found` }], isError: true };
215 + }
216 + return tool.execute("model-call", args);
217 + },
218 setBridgeSourcePath: (path: string) => {
219 bridgeSourcePath = path;
220 },
packages/provider-pi/src/server/mcpExtensionSource.test.ts
+109 -13
@@ -183,7 +183,11 @@ describe("Pi MCP tool exposure", () => {
183 };
184
185 it("keeps orchestration direct and optional bridge tools discoverable on modern Pi", async () => {
186 - const bridge = await loadMcpBridge({ modern: true, toolSearchAvailable: true });
186 + const bridge = await loadMcpBridge({
187 + modern: true,
188 + toolSearchAvailable: true,
189 + activatesOnRegistration: true,
190 + });
191 await bridge.handlers.get("session_start")!({ systemPrompt: "" }, discoveryContext);
192 const start = bridge.handlers.get("before_agent_start");
193 assert.isDefined(start);
@@ -191,10 +195,27 @@ describe("Pi MCP tool exposure", () => {
195 assert.include(prompt?.systemPrompt ?? "", "orchestrator_capabilities");
196 assert.equal(bridge.servers.length, 0);
197 assert.equal(bridge.tools.length, 8);
194 - assert.deepEqual(bridge.getActiveTools(), ["read", "tool_search"]);
198 + const aliases = [
199 + "mcp__t3_code__orchestrator_capabilities",
200 + "mcp__t3_code__delegate_task",
201 + "mcp__t3_code__task_status",
202 + "mcp__t3_code__preview_snapshot",
203 + ];
204 + const publicDirect = [
205 + "mcp__t3-code__orchestrator_capabilities",
206 + "mcp__t3-code__delegate_task",
207 + "mcp__t3-code__task_status",
208 + ];
209 + assert.sameMembers(bridge.getActiveTools(), [
210 + "read",
211 + "tool_search",
212 + ...publicDirect,
213 + ...aliases,
214 + ]);
215 + assert.deepEqual(bridge.declaredTools(), publicDirect);
216 assert.deepEqual(
217 bridge.tools
197 - .filter((tool) => tool.exposure !== "hidden")
218 + .filter((tool) => tool.name.startsWith("mcp__t3-code__"))
219 .map((tool) => [tool.name, tool.exposure]),
220 [
221 ["mcp__t3-code__orchestrator_capabilities", "direct"],
@@ -204,13 +225,10 @@ describe("Pi MCP tool exposure", () => {
225 ],
226 );
227 assert.deepEqual(
207 - bridge.tools.filter((tool) => tool.exposure === "hidden").map((tool) => tool.name),
208 - [
209 - "mcp__t3_code__orchestrator_capabilities",
210 - "mcp__t3_code__delegate_task",
211 - "mcp__t3_code__task_status",
212 - "mcp__t3_code__preview_snapshot",
213 - ],
228 + bridge.tools
229 + .filter((tool) => tool.name.startsWith("mcp__t3_code__"))
230 + .map((tool) => [tool.name, tool.exposure]),
231 + aliases.map((name) => [name, "model-only"]),
232 );
233 const result = await bridge.tools
234 .find((tool) => tool.name === "mcp__t3-code__preview_snapshot")!
@@ -224,9 +242,11 @@ describe("Pi MCP tool exposure", () => {
242 modern: true,
243 toolSearchAvailable: true,
244 allowsTool: (name) => name !== "mcp__t3-code__delegate_task",
245 + activatesOnRegistration: true,
246 });
247 const event = { systemPrompt: "" };
248 await bridge.handlers.get("session_start")!(event, discoveryContext);
249 + assert.notInclude(bridge.getActiveTools(), "mcp__t3_code__delegate_task");
250 const gatewayContext = { model: { api: "openai-completions" }, ui: { notify: assert.fail } };
251 await bridge.handlers.get("model_select")!(event, gatewayContext);
252 bridge.restoreActiveTools(["read", "mcp__t3-code__task_status"]);
@@ -237,6 +257,9 @@ describe("Pi MCP tool exposure", () => {
257 "tool_search",
258 "mcp__t3-code__orchestrator_capabilities",
259 "mcp__t3-code__preview_snapshot",
260 + "mcp__t3_code__orchestrator_capabilities",
261 + "mcp__t3_code__task_status",
262 + "mcp__t3_code__preview_snapshot",
263 ]);
264 await bridge.handlers.get("model_select")!(event, discoveryContext);
265 assert.equal(
@@ -246,6 +269,74 @@ describe("Pi MCP tool exposure", () => {
269 assert.include(bridge.getActiveTools(), "mcp__t3-code__preview_snapshot");
270 });
271
272 + it("keeps Pi's canonical MCP tool names callable by the model without declaring them twice", async () => {
273 + const bridge = await loadMcpBridge({
274 + modern: true,
275 + toolSearchAvailable: true,
276 + activatesOnRegistration: true,
277 + });
278 + const canonicalNames = [
279 + "mcp__t3_code__orchestrator_capabilities",
280 + "mcp__t3_code__delegate_task",
281 + "mcp__t3_code__task_status",
282 + "mcp__t3_code__preview_snapshot",
283 + ];
284 + const unreachableCanonicalNames = async () => {
285 + const unreachable: string[] = [];
286 + for (const name of canonicalNames) {
287 + const result = await bridge.callModelTool(name, {});
288 + if (result.isError === true) unreachable.push(name);
289 + }
290 + return unreachable;
291 + };
292 + const declaredCanonicalNames = () =>
293 + bridge.declaredTools().filter((name) => name.startsWith("mcp__t3_code__"));
294 + const event = { systemPrompt: "" };
295 +
296 + await bridge.handlers.get("session_start")!(event, discoveryContext);
297 + assert.deepEqual(
298 + await unreachableCanonicalNames(),
299 + [],
300 + "model calls to these names fail with Tool not found after session start",
301 + );
302 + assert.deepEqual(declaredCanonicalNames(), [], "declared twice after session start");
303 + assert.equal(bridge.requests.at(-1)?.method, "tools/call");
304 +
305 + bridge.restoreActiveTools([
306 + "read",
307 + "mcp__t3-code__orchestrator_capabilities",
308 + "mcp__t3-code__delegate_task",
309 + "mcp__t3-code__task_status",
310 + ]);
311 + await bridge.handlers.get("session_tree")!(event, discoveryContext);
312 + assert.deepEqual(
313 + await unreachableCanonicalNames(),
314 + [],
315 + "model calls to these names fail with Tool not found after an older tree loadout",
316 + );
317 + assert.deepEqual(declaredCanonicalNames(), [], "declared twice after an older tree loadout");
318 + assert.isFalse(
319 + bridge.callableTools().some((name) => name.startsWith("mcp__t3_code__")),
320 + "aliases duplicate the codemode catalog",
321 + );
322 +
323 + const requestCount = bridge.requests.length;
324 + bridge.restoreActiveTools(
325 + bridge.getActiveTools().filter((name) => name !== "mcp__t3-code__delegate_task"),
326 + );
327 + const late = await bridge.callModelTool("mcp__t3_code__delegate_task", {});
328 + assert.isTrue(late.isError, "an alias runs after its public tool was switched off");
329 + assert.equal(bridge.requests.length, requestCount);
330 +
331 + bridge.restoreActiveTools(["read", "mcp__t3-code__task_status"]);
332 + await bridge.handlers.get("session_tree")!(event, discoveryContext);
333 + assert.deepEqual(
334 + await unreachableCanonicalNames(),
335 + ["mcp__t3_code__orchestrator_capabilities", "mcp__t3_code__delegate_task"],
336 + "an alias stays callable while its direct public tool is off",
337 + );
338 + });
339 +
340 it.each(["legacy Pi", "disabled tool search"])(
341 "keeps tool execution available with %s",
342 async (mode) => {
@@ -258,11 +349,16 @@ describe("Pi MCP tool exposure", () => {
349 const start = bridge.handlers.get("session_start");
350 await start!({ systemPrompt: "Pi system prompt" }, discoveryContext);
351 }
261 - assert.equal(bridge.tools.filter((tool) => tool.exposure !== "hidden").length, 4);
352 + const publicTools = bridge.tools.filter((tool) => tool.name.startsWith("mcp__t3-code__"));
353 + assert.equal(publicTools.length, 4);
354 assert.isTrue(
355 + publicTools.every((tool) => tool.exposure === undefined || tool.exposure === "direct"),
356 + );
357 + assert.deepEqual(
358 bridge.tools
264 - .filter((tool) => tool.exposure !== "hidden")
265 - .every((tool) => tool.exposure === undefined || tool.exposure === "direct"),
359 + .filter((tool) => tool.name.startsWith("mcp__t3_code__"))
360 + .map((tool) => tool.exposure),
361 + mode === "legacy Pi" ? [] : ["model-only", "model-only", "model-only", "model-only"],
362 );
363 const tool = bridge.tools.find((tool) => tool.name === "mcp__t3-code__preview_snapshot");
364 assert.isDefined(tool);
packages/provider-pi/src/server/mcpExtensionSource.ts
+40 -10
@@ -397,31 +397,52 @@ export default async function t3McpExtension(pi: ExtensionAPI) {
397 // bridge as the credential owner: mcp.json overrides native registrations.
398 const supportsExposure = "registerMcpServer" in pi && typeof pi.registerMcpServer === "function";
399 const directTools = new Set(["orchestrator_capabilities", "delegate_task", "task_status"]);
400 + const ALIAS_PREFIX = "mcp__t3_code__";
401 let deferOptionalTools = supportsExposure;
402 + const isDeferred = (name: string) => deferOptionalTools && !directTools.has(name);
403 + // An alias follows its public tool: gone when --exclude-tools removed it,
404 + // off while a direct one is off.
405 + const followsPublicTool = (
406 + name: string,
407 + registered: ReadonlySet<string>,
408 + active: ReadonlyArray<string>,
409 + ) =>
410 + registered.has("mcp__t3-code__" + name) &&
411 + (isDeferred(name) || active.includes("mcp__t3-code__" + name));
412 let catalog: ReadonlyArray<McpTool> = [];
413
414 const client = createMcpClient(endpoint, token);
415 let started: Promise<void> | undefined;
416
417 const registerTools = () => {
407 - // Preserve public names for saved loadouts and tool selectors. Hidden
408 - // canonical names reserve ownership against Pi's configured MCP servers.
409 - const prefixes = supportsExposure ? ["mcp__t3-code__", "mcp__t3_code__"] : ["mcp__t3-code__"];
418 + // Preserve public names for saved loadouts and tool selectors. The alias,
419 + // Pi's own MCP name for T3, reserves it against Pi's configured MCP servers.
420 + // model-only keeps it out of codemode; it hides its own declaration.
421 + const prefixes = supportsExposure ? ["mcp__t3-code__", ALIAS_PREFIX] : ["mcp__t3-code__"];
422 readOnlyMcpTools.clear();
423 for (const tool of catalog) {
424 const name = tool.name;
425 for (const prefix of prefixes) {
414 - if (tool.annotations?.readOnlyHint === true) readOnlyMcpTools.add(\`\${prefix}\${name}\`);
415 - const exposure = prefix === "mcp__t3_code__" ? "hidden" :
416 - deferOptionalTools && !directTools.has(name) ? "deferred" : "direct";
426 + const toolName = \`\${prefix}\${name}\`;
427 + if (tool.annotations?.readOnlyHint === true) readOnlyMcpTools.add(toolName);
428 + const isAlias = prefix === ALIAS_PREFIX;
429 + const exposure = isAlias ? "model-only" : isDeferred(name) ? "deferred" : "direct";
430 pi.registerTool({
418 - name: \`\${prefix}\${name}\`,
431 + name: toolName,
432 label: name,
433 description: tool.description ?? name,
434 parameters: jsonSchemaToTypebox(tool.inputSchema),
435 ...(supportsExposure ? { outputSchema: mcpOutputSchema(tool) } : {}),
436 ...(supportsExposure ? { exposure } : {}),
437 + ...(isAlias ? { prepareLoadout: () => ({ hiddenDeclarations: [toolName] }) } : {}),
438 async execute(_toolCallId, params, signal) {
439 + // Another extension may switch the public tool off after reconciliation.
440 + if (
441 + isAlias &&
442 + !followsPublicTool(name, new Set(pi.getAllTools().map((tool) => tool.name)), pi.getActiveTools())
443 + ) {
444 + return { content: [{ type: "text", text: \`Tool \${toolName} not found\` }], details: {}, isError: true };
445 + }
446 const result = await client.callTool(
447 name,
448 (params ?? {}) as Record<string, unknown>,
@@ -470,7 +491,6 @@ export default async function t3McpExtension(pi: ExtensionAPI) {
491 const exposureChanged = deferOptionalTools !== hasToolSearch;
492 deferOptionalTools = hasToolSearch;
493 if (exposureChanged) registerTools();
473 - const active = pi.getActiveTools();
494 // Completion gateways can silently drop calls to undeclared tools named
495 // in history or guidance. Eagerly load T3 schemas, including after tree
496 // restores, while retaining deferred exposure for Pi's allowlist rules.
@@ -479,8 +499,18 @@ export default async function t3McpExtension(pi: ExtensionAPI) {
499 ...(hasToolSearch ? ["tool_search"] : []),
500 ...(ctx.model?.api === "openai-completions" ? catalog.map((tool) => "mcp__t3-code__" + tool.name) : []),
501 ];
482 - const missing = required.filter((name) => !active.includes(name));
483 - if (missing.length > 0) pi.setActiveTools([...active, ...missing]);
502 + const current = pi.getActiveTools();
503 + const missing = required.filter((name) => !current.includes(name));
504 + if (missing.length > 0) pi.setActiveTools([...current, ...missing]);
505 + // An alias is callable only while active.
506 + const registered = new Set(pi.getAllTools().map((tool) => tool.name));
507 + const loaded = pi.getActiveTools();
508 + const aliases = catalog
509 + .filter((tool) => registered.has(ALIAS_PREFIX + tool.name) && followsPublicTool(tool.name, registered, loaded))
510 + .map((tool) => ALIAS_PREFIX + tool.name);
511 + const kept = loaded.filter((name) => !name.startsWith(ALIAS_PREFIX) || aliases.includes(name));
512 + const added = aliases.filter((name) => !loaded.includes(name));
513 + if (added.length > 0 || kept.length !== loaded.length) pi.setActiveTools([...kept, ...added]);
514 };
515
516 // Tree navigation restores its saved loadout after session_start.