@selesai/code 0.13.40 → 0.14.3

package/dist/extensions/pi-subagents/test/unit/inspect-rpc.test.ts

@@ -136,12 +136,12 @@ describe("inspect-rpc resolution and ownership", () => {
 		const reply = buildInspectReply({ requestId: "r3", asyncId: "run-x" }, makeDeps(root, resultsDir, makeState(root, null)));
 		assert.equal(reply.error?.code, "no_active_session");
 	});
-	it("returns stale when artifacts are gone", () => {
+	it("does not infer a run from a directory without status or result evidence", () => {
 		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-inspect-stale-"));
 		const asyncRoot = path.join(root, "runs");
 		fs.mkdirSync(path.join(asyncRoot, "run-stale"), { recursive: true });
 		const reply = buildInspectReply({ requestId: "r4", asyncId: "run-stale" }, makeDeps(root, path.join(root, "results")));
-		assert.equal(reply.error?.code, "stale");
+		assert.equal(reply.error?.code, "not_found");
 	});
 });
 
@@ -614,4 +614,4 @@ describe("inspect-rpc command surface", () => {
 		assert.equal(parsed.kind, INSPECT_REPLY_KIND);
 		assert.equal(parsed.requestId, "r13");
 	});
-});
+});

package/dist/extensions/pi-subagents/test/unit/inspector-authority-policy.test.ts

@@ -0,0 +1,144 @@
+import assert from "node:assert/strict";
+import * as os from "node:os";
+import * as path from "node:path";
+import { describe, it } from "node:test";
+import { createSubagentExecutor } from "../../src/runs/foreground/subagent-executor.ts";
+import type { AuthorityPolicyConfig, SubagentState } from "../../src/shared/types.ts";
+
+function createState(): SubagentState {
+	return {
+		baseCwd: "",
+		currentSessionId: null,
+		asyncJobs: new Map(),
+		foregroundRuns: new Map(),
+		foregroundControls: new Map(),
+		lastForegroundControlId: null,
+		pendingForegroundControlNotices: new Map(),
+		cleanupTimers: new Map(),
+		lastUiContext: null,
+		poller: null,
+		completionSeen: new Map(),
+		watcher: null,
+		watcherRestartTimer: null,
+		resultFileCoalescer: { schedule: () => false, clear: () => {} },
+	};
+}
+
+function createExecutor(authorityPolicy?: AuthorityPolicyConfig, childSafe = false) {
+	return createSubagentExecutor({
+		pi: { events: { emit() {}, on() { return () => {}; } }, getSessionName() { return "parent"; } } as any,
+		state: createState(),
+		config: { maxSubagentDepth: 2, control: {}, intercomBridge: {}, ...(authorityPolicy ? { authorityPolicy } : {}) } as any,
+		...(childSafe ? { allowMutatingManagementActions: false } : {}),
+		asyncByDefault: false,
+		tempArtifactsDir: os.tmpdir(),
+		getSubagentSessionRoot: () => os.tmpdir(),
+		expandTilde: (value) => value,
+		discoverAgents: () => ({ agents: [] }),
+	});
+}
+
+function ctx(ui?: { confirm: () => Promise<boolean> }) {
+	return {
+		cwd: os.tmpdir(),
+		hasUI: Boolean(ui),
+		...(ui ? { ui } : {}),
+		sessionManager: { getSessionId() { return "session"; }, getSessionFile() { return null; } },
+		modelRegistry: { getAvailable() { return []; } },
+	} as any;
+}
+
+async function run(action: string, policy?: AuthorityPolicyConfig, ui?: { confirm: () => Promise<boolean> }, childSafe = false): Promise<{ text: string; isError?: boolean }> {
+	const result = await createExecutor(policy, childSafe).execute(action, { action }, new AbortController().signal, undefined, ctx(ui));
+	return { text: result.content.find((entry) => entry.type === "text")?.text ?? "", ...(result.isError === undefined ? {} : { isError: result.isError }) };
+}
+
+// `project.open` spawns the Herdr CLI, so point the client at a path that cannot
+// exist whenever the policy is expected to let the action through.
+async function withoutHerdr<T>(body: () => Promise<T>): Promise<T> {
+	const previous = process.env.HERDR_BIN;
+	process.env.HERDR_BIN = path.join(os.tmpdir(), "pi-subagents-absent-herdr-binary");
+	try {
+		return await body();
+	} finally {
+		if (previous === undefined) delete process.env.HERDR_BIN;
+		else process.env.HERDR_BIN = previous;
+	}
+}
+
+describe("inspector and project pane authority policy", () => {
+	it("requires confirmation for project.open and fails closed without an interactive UI", async () => {
+		const { text, isError } = await run("project.open");
+
+		assert.equal(isError, true);
+		assert.match(text, /requires user confirmation for action 'project\.open'/);
+	});
+
+	it("cancels project.open when the operator declines the confirmation", async () => {
+		let asked = 0;
+		const { text } = await run("project.open", undefined, { confirm: async () => { asked += 1; return false; } });
+
+		assert.equal(asked, 1);
+		assert.match(text, /Action 'project\.open' canceled; authority was not granted\./);
+	});
+
+	it("forbids project.open outright when the policy says so", async () => {
+		const { text, isError } = await run("project.open", { projectOpen: "forbid" });
+
+		assert.equal(isError, true);
+		assert.match(text, /Authority policy forbids action 'project\.open'\./);
+	});
+
+	it("runs project.open unprompted when the policy opts back in to auto", async () => {
+		const { text } = await withoutHerdr(() => run("project.open", { projectOpen: "auto" }));
+
+		assert.doesNotMatch(text, /Authority policy/);
+		assert.match(text, /Herdr/);
+	});
+
+	it("leaves inspector.open automatic by default so the plugin gate still decides", async () => {
+		const { text } = await run("inspector.open");
+
+		assert.doesNotMatch(text, /Authority policy/);
+		assert.match(text, /Inspector actions require id or dir/);
+	});
+
+	it("forbids inspector.open when the policy says so", async () => {
+		const { text, isError } = await run("inspector.open", { inspectorOpen: "forbid" });
+
+		assert.equal(isError, true);
+		assert.match(text, /Authority policy forbids action 'inspector\.open'\./);
+	});
+
+	it("requires confirmation for inspector.open when the operator opts in", async () => {
+		const { text, isError } = await run("inspector.open", { inspectorOpen: "confirm" });
+
+		assert.equal(isError, true);
+		assert.match(text, /requires user confirmation for action 'inspector\.open'/);
+	});
+
+	it("refuses project.open in child-safe fanout mode without prompting for authority", async () => {
+		let asked = 0;
+		const { text, isError } = await run("project.open", undefined, { confirm: async () => { asked += 1; return true; } }, true);
+
+		assert.equal(asked, 0);
+		assert.equal(isError, true);
+		assert.match(text, /Action 'project\.open' is not available from child-safe subagent fanout mode\./);
+	});
+
+	it("reports the child-safe restriction for inspector.open rather than the policy that also forbids it", async () => {
+		const { text, isError } = await run("inspector.open", { inspectorOpen: "forbid" }, undefined, true);
+
+		assert.equal(isError, true);
+		assert.match(text, /Action 'inspector\.open' is not available from child-safe subagent fanout mode\./);
+	});
+
+	it("refuses schedule.create in child-safe fanout mode without prompting for authority", async () => {
+		let asked = 0;
+		const { text, isError } = await run("schedule.create", { scheduleCreate: "confirm" }, { confirm: async () => { asked += 1; return true; } }, true);
+
+		assert.equal(asked, 0);
+		assert.equal(isError, true);
+		assert.match(text, /Action 'schedule\.create' is not available from child-safe subagent fanout mode\./);
+	});
+});

package/dist/extensions/pi-subagents/test/unit/inspector-registration.test.ts

@@ -0,0 +1,128 @@
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { describe, it } from "node:test";
+import { createEventBus } from "@selesai/code";
+import { INSPECTOR_REGISTER_EVENT, registerInspector, type InspectorPlugin, type InspectorRegistrationRequest } from "../../src/api/inspectors.ts";
+import { handleInspectorAction } from "../../src/inspectors/actions.ts";
+import { getInspectorPlugins, registerInspectorEventListener } from "../../src/inspectors/plugins.ts";
+
+function provider(name = "test-host"): InspectorPlugin {
+	return {
+		name,
+		available: () => true,
+		owns: () => false,
+		open: async () => ({ content: [{ type: "text", text: "opened" }], details: { mode: "management", results: [] } }),
+	};
+}
+
+describe("external inspector registration", () => {
+	it("registers through the owner, preserves built-in preference, and disposes across reloads", (t) => {
+		const owner = { events: createEventBus() };
+		const consumer = { events: owner.events };
+		const otherOwner = { events: createEventBus() };
+		const shutdown = registerInspectorEventListener(owner);
+		t.after(shutdown);
+		t.after(registerInspectorEventListener(otherOwner));
+		const plugin = provider();
+		const registration = registerInspector(consumer, plugin);
+		assert.deepEqual(getInspectorPlugins(owner).map((item) => item.name), ["herdr", "ghostty", "test-host"]);
+		assert.equal(getInspectorPlugins(otherOwner).length, 2);
+		assert.throws(() => registerInspector(consumer, plugin), /already registered/);
+		assert.throws(() => registerInspector(consumer, provider("herdr")), /already registered/);
+		assert.throws(() => registerInspector(consumer, provider("ghostty")), /already registered/);
+		registration.dispose();
+		registerInspector(consumer, plugin);
+		registration.dispose();
+		assert.equal(getInspectorPlugins(owner).length, 3, "an old disposer must not remove a new registration");
+		shutdown();
+		assert.equal(getInspectorPlugins(owner).length, 2);
+		assert.throws(() => registerInspector(consumer, plugin), /not installed, not ready/);
+		t.after(registerInspectorEventListener(owner));
+		registerInspector(consumer, plugin);
+		shutdown();
+		assert.equal(getInspectorPlugins(owner).length, 3, "old runtime cleanup must not clear a replacement");
+	});
+
+	it("keeps a registration when a duplicate runtime on the same bus replaces the one that claimed it", () => {
+		const events = createEventBus();
+		const claimed = { events };
+		const replacement = { events };
+		const cleanupClaimed = registerInspectorEventListener(claimed);
+		const registration = registerInspector({ events }, provider());
+		const cleanupReplacement = registerInspectorEventListener(replacement);
+		cleanupClaimed();
+		assert.deepEqual(getInspectorPlugins(replacement).map((item) => item.name), ["herdr", "ghostty", "test-host"]);
+		registration.dispose();
+		assert.equal(getInspectorPlugins(replacement).length, 2);
+		registerInspector({ events }, provider()).dispose();
+		cleanupReplacement();
+	});
+
+	it("rejects malformed event requests without registering callbacks", (t) => {
+		const owner = { events: createEventBus() };
+		t.after(registerInspectorEventListener(owner));
+		const invalid = [
+			{ version: 2, plugin: provider() },
+			{ version: 1 },
+			{ version: 1, plugin: provider("invalid name") },
+			{ version: 1, plugin: { ...provider(), open: "not callable" } },
+			{ version: 1, plugin: { ...provider(), close: false } },
+		];
+		for (const input of invalid) {
+			// SAFETY: undefined is a valid initial result; the synchronous owner fills it during emit.
+			const request = { ...input, result: undefined as InspectorRegistrationRequest["result"] };
+			owner.events.emit(INSPECTOR_REGISTER_EVENT, request);
+			assert.equal(request.result?.ok, false);
+			if (request.result?.ok === false) assert.ok(request.result.error instanceof Error);
+		}
+		assert.equal(getInspectorPlugins(owner).length, 2);
+	});
+
+	it("routes existing inspector actions and launch permissions to a registered provider without fallback on failure", async (t) => {
+		const root = fs.mkdtempSync(path.join(os.tmpdir(), "pi-inspector-registration-"));
+		t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+		const asyncDir = path.join(root, "run-provider");
+		fs.mkdirSync(asyncDir);
+		fs.writeFileSync(path.join(asyncDir, "status.json"), JSON.stringify({
+			runId: "run-provider", mode: "single", state: "running", cwd: root,
+			steps: [{ agent: "worker", status: "running" }],
+		}));
+		const owner = { events: createEventBus() };
+		t.after(registerInspectorEventListener(owner));
+		const calls: string[] = [];
+		const reply = (text: string) => ({ content: [{ type: "text" as const, text }], details: { mode: "management" as const, results: [] } });
+		registerInspector(owner, { ...provider("unavailable"), available: () => false, open: async () => assert.fail("unavailable provider opened") });
+		const registration = registerInspector(owner, {
+			...provider(),
+			owns: (context) => context.target.runId === "run-provider",
+			open: async (context, launch, params) => {
+				assert.equal(context.target.index, 0);
+				assert.equal(params.focus, true);
+				assert.equal(launch.allowSteer, false);
+				assert.equal(launch.allowStop, false);
+				assert.ok(launch.argv.includes(asyncDir));
+				calls.push("open");
+				return reply("opened");
+			},
+			status: async () => { calls.push("status"); return reply("present"); },
+			close: async () => { calls.push("close"); return reply("closed"); },
+		});
+		const deps = () => ({
+			cwd: root, asyncDirRoot: root, env: {}, plugins: getInspectorPlugins(owner),
+			authorityPolicy: { steerRun: "forbid" as const, stopRun: "forbid" as const },
+		});
+		const params = { id: "run-provider", index: 0, focus: true };
+		await handleInspectorAction("inspector.command", params, deps());
+		assert.deepEqual(calls, [], "standalone command generation must not invoke a provider");
+		for (const action of ["inspector.open", "inspector.status", "inspector.close"] as const) {
+			assert.notEqual((await handleInspectorAction(action, params, deps())).isError, true);
+		}
+		assert.deepEqual(calls, ["open", "status", "close"]);
+		registration.dispose();
+		registerInspector(owner, { ...provider("failing"), open: async () => { throw new Error("host failed after opening"); } });
+		registerInspector(owner, { ...provider("fallback"), open: async () => assert.fail("must not open a second pane after failure") });
+		await assert.rejects(handleInspectorAction("inspector.open", params, deps()), /host failed after opening/);
+	});
+});

package/dist/extensions/pi-subagents/test/unit/intercom-bridge.test.ts

@@ -12,8 +12,10 @@ import {
 	resolveIntercomSessionTarget,
 	resolveSubagentIntercomTarget,
 	resolveIntercomBridgeMode,
+	validateIntercomBridgeConfig,
 	type IntercomBridgeState,
 } from "../../src/intercom/intercom-bridge.ts";
+import { agentDefinitionDigest } from "../../src/shared/launch-contract.ts";
 
 function makeAgent(overrides: Partial<AgentConfig> = {}): AgentConfig {
 	return {
@@ -148,11 +150,22 @@ describe("resolveIntercomBridge", () => {
 			});
 			assert.equal(bridge.active, true);
 			assert.match(bridge.instruction, /Custom bridge for main/);
+			assert.equal(bridge.interpolatesOrchestratorTarget, true);
 		} finally {
 			fs.rmSync(tempDir, { recursive: true, force: true });
 		}
 	});
 
+	it("keeps the default instruction independent of the parent session", () => {
+		const first = resolveIntercomBridge({ config: { mode: "always" }, context: "fresh", orchestratorTarget: "subagent-chat-first" });
+		const second = resolveIntercomBridge({ config: { mode: "always" }, context: "fresh", orchestratorTarget: "subagent-chat-second" });
+		assert.equal(first.active, true);
+		assert.equal(first.interpolatesOrchestratorTarget, false);
+		assert.equal(first.instruction, second.instruction);
+		assert.doesNotMatch(first.instruction, /subagent-chat-first/);
+		assert.equal(first.orchestratorTarget, "subagent-chat-first");
+	});
+
 	it("uses stronger default instructions for fork-aware coordination", () => {
 		const bridge = resolveIntercomBridge({
 			config: { mode: "always" },
@@ -177,8 +190,19 @@ describe("applyIntercomBridgeToAgent", () => {
 		orchestratorTarget: "main",
 		extensionDir: NATIVE_INTERCOM_EXTENSION_DIR,
 		instruction: "Intercom orchestration channel:\n- Need a decision or blocked: contact_supervisor({ reason: \"need_decision\", message: \"<question>\" })\n- Blocked/update: contact_supervisor({ reason: \"progress_update\", message: \"UPDATE: <summary>\" })",
+		interpolatesOrchestratorTarget: false,
 	};
 
+	it("preserves the parsed definition digest across the overlay", () => {
+		const agent = makeAgent({ tools: ["read"] });
+		const parsedDigest = agentDefinitionDigest(agent);
+		const bridged = applyIntercomBridgeToAgent(agent, activeBridge);
+		assert.equal(bridged.definitionDigest, parsedDigest);
+		assert.equal(agentDefinitionDigest(bridged), parsedDigest);
+		assert.equal(agentDefinitionDigest(applyIntercomBridgeToAgent(bridged, activeBridge)), parsedDigest);
+		assert.equal(agent.definitionDigest, undefined);
+	});
+
 	it("injects contact_supervisor and prompt instructions", () => {
 		const updated = applyIntercomBridgeToAgent(makeAgent({ tools: ["read", "bash"] }), activeBridge);
 		assert.deepEqual(updated.tools, ["read", "bash", "contact_supervisor"]);
@@ -217,4 +241,28 @@ describe("applyIntercomBridgeToAgent", () => {
 		assert.deepEqual(mcpOnly.mcpDirectTools, ["github/search_repositories"]);
 		assert.match(mcpOnly.systemPrompt, /contact_supervisor/);
 	});
-});
+});
+
+describe("validateIntercomBridgeConfig", () => {
+	it("accepts the documented fields and drops nothing", () => {
+		const result = validateIntercomBridgeConfig({ value: { mode: "fork-only", instructionFile: "./bridge.md", resultDelivery: true }, label: "intercomBridge" });
+		assert.deepEqual(result, { ok: true, value: { mode: "fork-only", instructionFile: "./bridge.md", resultDelivery: true } });
+		assert.deepEqual(validateIntercomBridgeConfig({ value: {}, label: "intercomBridge" }), { ok: true, value: {} });
+	});
+
+	it("rejects unknown fields and wrong types with the caller's label", () => {
+		const cases: Array<[unknown, RegExp]> = [
+			[null, /^bridge must be an object\.$/],
+			[[], /^bridge must be an object\.$/],
+			[{ extra: 1 }, /^bridge\.extra is not supported\.$/],
+			[{ mode: "loud" }, /^bridge\.mode is invalid\.$/],
+			[{ instructionFile: 1 }, /^bridge\.instructionFile must be a string\.$/],
+			[{ resultDelivery: "yes" }, /^bridge\.resultDelivery must be a boolean\.$/],
+		];
+		for (const [value, expected] of cases) {
+			const result = validateIntercomBridgeConfig({ value, label: "bridge" });
+			assert.equal(result.ok, false);
+			if (!result.ok) assert.match(result.error, expected);
+		}
+	});
+});

package/dist/extensions/pi-subagents/test/unit/mcp-direct-tool-grant.test.ts

@@ -152,4 +152,77 @@ test("matches adapter mcp-prefixed policy names", () => {
 	});
 
 	assert.deepEqual(grant.selections, [{ name: "demo_search_records", selector: "demo/search_records" }]);
-});
+});
+
+test("keeps a tool name that already carries the server prefix, matching adapter registration", () => {
+	for (const [toolPrefix, serverName, expectedName] of [
+		["server", "codegraph", "codegraph_explore"],
+		["short", "codegraph-mcp", "codegraph_explore"],
+		["none", "codegraph", "codegraph_explore"],
+	] as const) {
+		const grant = planMcpDirectToolGrant({
+			selectors: [`${serverName}/codegraph_explore`],
+			servers: { [serverName]: {} },
+			metadata: { [serverName]: { tools: [{ name: "codegraph_explore" }, { name: "codegraph_status" }] } },
+			toolPrefix,
+		});
+
+		assert.deepEqual(grant.selections, [{ name: expectedName, selector: `${serverName}/codegraph_explore` }]);
+	}
+});
+
+test("sanitizes server prefixes the way adapter registration does", () => {
+	for (const [toolPrefix, serverName, expectedName] of [
+		["server", "my server.x", "my_20_server_2e_x_ping"],
+		["short", "weird  server-mcp", "weird_20__20_server_ping"],
+		["mcp", "my server.x", "mcp__my_20_server_2e_x_ping"],
+	] as const) {
+		const grant = planMcpDirectToolGrant({
+			selectors: [serverName],
+			servers: { [serverName]: {} },
+			metadata: { [serverName]: { tools: [{ name: "ping" }] } },
+			toolPrefix,
+		});
+
+		assert.deepEqual(grant.selections, [{ name: expectedName, selector: `${serverName}/ping` }]);
+	}
+});
+
+test("supports the adapter mcp prefix mode", () => {
+	const grant = planMcpDirectToolGrant({
+		selectors: ["codegraph"],
+		servers: { codegraph: {} },
+		metadata: { codegraph: { tools: [{ name: "ping" }, { name: "codegraph_explore" }] } },
+		toolPrefix: "mcp",
+	});
+
+	assert.deepEqual(grant.selections, [
+		{ name: "mcp__codegraph_ping", selector: "codegraph/ping" },
+		{ name: "mcp__codegraph_codegraph_explore", selector: "codegraph/codegraph_explore" },
+	]);
+});
+
+test("honours a per-server toolPrefix over the global setting", () => {
+	const grant = planMcpDirectToolGrant({
+		selectors: ["demo", "demo-mcp"],
+		servers: { demo: { toolPrefix: "none" }, "demo-mcp": { toolPrefix: "short" } },
+		metadata: { demo: { tools: [{ name: "ping" }] }, "demo-mcp": { tools: [{ name: "ping" }] } },
+		toolPrefix: "server",
+	});
+
+	assert.deepEqual(grant.selections, [
+		{ name: "ping", selector: "demo/ping" },
+		{ name: "demo_ping", selector: "demo-mcp/ping" },
+	]);
+});
+
+test("sanitizes dotted tool names the way adapter registration does", () => {
+	const grant = planMcpDirectToolGrant({
+		selectors: ["github"],
+		servers: { github: {} },
+		metadata: { github: { tools: [{ name: "repo.search" }] } },
+		toolPrefix: "server",
+	});
+
+	assert.deepEqual(grant.selections, [{ name: "github_repo_search", selector: "github/repo.search" }]);
+});

package/dist/extensions/pi-subagents/test/unit/mcp-direct-tool-resolution.test.ts

@@ -0,0 +1,112 @@
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { after, beforeEach, describe, it } from "node:test";
+import type { McpServerDefinition } from "../../src/runs/shared/mcp-config-sources.ts";
+
+// The resolver captures the generic `~/.config/mcp/mcp.json` and import paths
+// from the home directory when its module loads, and it resolves servers and the
+// metadata cache through the Pi agent directory. Isolate the home environment
+// before importing it, so a direct `node --test` run without the repository test
+// preload neither reads a developer's real MCP config nor touches a real agent
+// directory.
+const managedEnv = ["HOME", "USERPROFILE", "SELESAI_CODING_AGENT_DIR"] as const;
+const previousEnv: Record<string, string | undefined> = {};
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "mcp-resolution-"));
+const homeDir = path.join(tempRoot, "home");
+const agentDir = path.join(homeDir, ".selesai", "agent");
+const projectDir = path.join(tempRoot, "project");
+for (const name of managedEnv) previousEnv[name] = process.env[name];
+process.env.HOME = homeDir;
+process.env.USERPROFILE = homeDir;
+process.env.SELESAI_CODING_AGENT_DIR = agentDir;
+assert.equal(os.homedir(), homeDir, "test isolation must redirect the home directory before the resolver loads");
+
+const { computeMcpServerHash, resolveMcpDirectToolResolution } = await import("../../src/runs/shared/mcp-direct-tool-allowlist.ts");
+const { getAgentDir, getProjectConfigDir } = await import("../../src/shared/utils.ts");
+
+const SELECTORS = ["codegraph/codegraph_explore", "codegraph/codegraph_node", "codegraph/codegraph_status"];
+const SELECTED_NAMES = ["codegraph_explore", "codegraph_node", "codegraph_status"];
+const CURRENT_DEFINITION: McpServerDefinition = {
+	command: "npx",
+	args: ["-y", "@colbymchenry/codegraph@1.6.0", "serve", "--mcp"],
+	env: { CODEGRAPH_MCP_TOOLS: "explore,node,status" },
+};
+
+function writeServerConfig(configPath: string, definition: McpServerDefinition): void {
+	fs.mkdirSync(path.dirname(configPath), { recursive: true });
+	fs.writeFileSync(configPath, JSON.stringify({ mcpServers: { codegraph: definition } }, null, 2), "utf-8");
+}
+
+function writeMetadataCache(definition: McpServerDefinition): void {
+	const cachePath = path.join(getAgentDir(), "mcp-cache.json");
+	fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+	fs.writeFileSync(cachePath, JSON.stringify({
+		version: 1,
+		servers: {
+			codegraph: {
+				configHash: computeMcpServerHash(definition),
+				tools: SELECTED_NAMES.map((name) => ({ name })),
+				cachedAt: Date.now(),
+			},
+		},
+	}), "utf-8");
+}
+
+after(() => {
+	for (const name of managedEnv) {
+		const value = previousEnv[name];
+		if (value === undefined) delete process.env[name];
+		else process.env[name] = value;
+	}
+	fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+describe("MCP direct-tool resolution config sources", () => {
+	beforeEach(() => {
+		assert.equal(getAgentDir(), agentDir, "test isolation must redirect the Pi agent directory");
+		fs.rmSync(projectDir, { recursive: true, force: true });
+		fs.mkdirSync(projectDir, { recursive: true });
+		for (const name of ["mcp.json", "mcp-adapter.json", "mcp-cache.json"]) {
+			fs.rmSync(path.join(agentDir, name), { force: true });
+		}
+	});
+
+	it("resolves direct tools declared in the Pi-global mcp-adapter.json", () => {
+		writeServerConfig(path.join(agentDir, "mcp-adapter.json"), CURRENT_DEFINITION);
+		writeMetadataCache(CURRENT_DEFINITION);
+
+		const resolution = resolveMcpDirectToolResolution(SELECTORS, projectDir);
+
+		assert.deepEqual(resolution.selections.map((selection) => selection.name), SELECTED_NAMES);
+		assert.deepEqual(resolution.unresolvedSelectors, []);
+	});
+
+	it("computes config hashes identical to pi-mcp-adapter 3.1.0 for stdio servers", () => {
+		// Values reproduced from pi-mcp-adapter 3.1.0's real cache; drift breaks stdio direct-tool resolution.
+		assert.equal(computeMcpServerHash(CURRENT_DEFINITION), "d2b80559f0b1c85ccc625a4c7f875f64e0defc60648f56d2a51cbe5dfa3d967e");
+		assert.equal(computeMcpServerHash({ ...CURRENT_DEFINITION, inheritEnv: false }), "345b359732aa3ece7fdf8b98b9927809243685846c2b375e98a312a80e89e333");
+	});
+
+	it("ignores Pi's own mcp.json files, which the adapter no longer reads", () => {
+		writeServerConfig(path.join(agentDir, "mcp.json"), CURRENT_DEFINITION);
+		writeServerConfig(path.join(getProjectConfigDir(projectDir), "mcp.json"), CURRENT_DEFINITION);
+		writeMetadataCache(CURRENT_DEFINITION);
+
+		const resolution = resolveMcpDirectToolResolution(SELECTORS, projectDir);
+
+		assert.deepEqual(resolution.selections, []);
+		assert.deepEqual(resolution.unresolvedSelectors, SELECTORS);
+	});
+
+	it("resolves direct tools declared in the project mcp-adapter.json", () => {
+		writeServerConfig(path.join(getProjectConfigDir(projectDir), "mcp-adapter.json"), CURRENT_DEFINITION);
+		writeMetadataCache(CURRENT_DEFINITION);
+
+		const resolution = resolveMcpDirectToolResolution(SELECTORS, projectDir);
+
+		assert.deepEqual(resolution.selections.map((selection) => selection.name), SELECTED_NAMES);
+		assert.deepEqual(resolution.unresolvedSelectors, []);
+	});
+});