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.