Commit 2f85686d9dca5ec98c892a2a26c321e09d746d71 | the-knife

apps/server/src/mcp/McpDeviceToolkit.test.ts+3

apps/server/src/mcp/McpHttpServer.test.ts+3

 @@ -17,6 +17,7 @@ import { HttpBody, HttpClient, HttpRouter, HttpServerResponse } from "effect/htt
 import * as ProjectService from "../project/ProjectService.ts";
 import * as ServerConfig from "../config.ts";
 import * as McpHttpServer from "./McpHttpServer.ts";
+import * as McpToolAccessTestkit from "./McpToolAccess.testkit.ts";
 import * as McpInvocationContext from "./McpInvocationContext.ts";
 import * as PreviewAutomationBroker from "./PreviewAutomationBroker.ts";
 @@ -51,12 +52,14 @@ const client = McpSchema.McpServerClient.of({
 });
 const layerTest = McpHttpServer.layerPreviewToolkit.pipe(
   Layer.provideMerge(McpServer.McpServer.layer),
+  Layer.provideMerge(McpToolAccessTestkit.liveThreadsLayer),
   Layer.provideMerge(PreviewAutomationBroker.layer),
   Layer.provideMerge(ServerConfig.layerTest(process.cwd(), { prefix: "t3-mcp-http-server-test-" })),
   Layer.provideMerge(NodeServices.layer),
 );
 const layerPullRequestsTest = McpHttpServer.layerPullRequestsToolkit.pipe(
   Layer.provideMerge(McpServer.McpServer.layer),
+  Layer.provideMerge(McpToolAccessTestkit.liveThreadsLayer),
   Layer.provide(
     Layer.mergeAll(
       Layer.mock(ProjectService.ProjectService)({}),

apps/server/src/mcp/McpHttpServer.ts+68-36

 @@ -11,7 +11,7 @@ import * as Schema from "effect/Schema";
 import * as Sink from "effect/Sink";
 import * as Stream from "effect/Stream";
 import type * as Types from "effect/Types";
-import { AiError, McpProtocol, McpSchema, McpServer, Tool } from "effect/ai";
+import { AiError, McpProtocol, McpSchema, McpServer, Tool, type Toolkit } from "effect/ai";
 import { HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
 import { OrchestratorMcpFailure, PreviewAutomationError } from "@t3tools/contracts";
 @@ -19,7 +19,9 @@ import packageJson from "../../package.json" with { type: "json" };
 import * as ServerConfig from "../config.ts";
 import * as DeviceService from "../device/DeviceService.ts";
 import * as HtmlRender from "../htmlRender/HtmlRender.ts";
+import * as ThreadManagementService from "../orchestration-v2/ThreadManagementService.ts";
 import * as McpInvocationContext from "./McpInvocationContext.ts";
+import * as McpToolAccess from "./McpToolAccess.ts";
 import * as OrchestratorMcpService from "./OrchestratorMcpService.ts";
 import { PreviewControlsToolkit } from "./toolkits/previewControls/tools.ts";
 import * as PreviewControlsHandlers from "./toolkits/previewControls/handlers.ts";
 @@ -396,6 +398,7 @@ const previewSnapshotFailure = <E>(cause: Cause.Cause<E>) => {
 const registerPreviewSnapshot = Effect.fn("McpHttpServer.registerPreviewSnapshot")(function* () {
   const server = yield* McpServer.McpServer;
   const broker = yield* PreviewAutomationBroker.PreviewAutomationBroker;
+  const threads = yield* ThreadManagementService.ThreadManagementService;
   // The MCP tool runner only supplies the client, so hand the save path its services here.
   const saveServices = yield* Effect.context<
     ServerConfig.ServerConfig | FileSystem.FileSystem | Path.Path | Crypto.Crypto
 @@ -430,6 +433,7 @@ const registerPreviewSnapshot = Effect.fn("McpHttpServer.registerPreviewSnapshot
           Stream.run(Sink.last()),
           Effect.flatMap(Effect.fromOption),
           Effect.provideService(PreviewAutomationBroker.PreviewAutomationBroker, broker),
+          Effect.provideService(ThreadManagementService.ThreadManagementService, threads),
           Effect.provideService(McpInvocationContext.McpInvocationContext, invocation),
           Effect.flatMap(({ encodedResult }) =>
             Effect.gen(function* () {
 @@ -655,6 +659,7 @@ const registerImageTool = <T extends Tool.Any, E, R>(
 const registerDeviceScreenshot = Effect.fn("McpHttpServer.registerDeviceScreenshot")(function* () {
   const devices = yield* DeviceService.DeviceService;
+  const threads = yield* ThreadManagementService.ThreadManagementService;
   const built = yield* DeviceScreenshotToolkit;
   yield* registerImageTool(
     DeviceScreenshotTool,
 @@ -662,7 +667,11 @@ const registerDeviceScreenshot = Effect.fn("McpHttpServer.registerDeviceScreensh
       built
         .handle("device_screenshot", payload)
         .pipe(Stream.unwrap, Stream.run(Sink.last()), Effect.flatMap(Effect.fromOption)),
-    (effect) => effect.pipe(Effect.provideService(DeviceService.DeviceService, devices)),
+    (effect) =>
+      effect.pipe(
+        Effect.provideService(DeviceService.DeviceService, devices),
+        Effect.provideService(ThreadManagementService.ThreadManagementService, threads),
+      ),
     "screenshot",
     "Device screenshot failed.",
   );
 @@ -672,6 +681,7 @@ const isOrchestratorMcpFailure = Schema.is(OrchestratorMcpFailure);
 const registerHtmlPreview = Effect.fn("McpHttpServer.registerHtmlPreview")(function* () {
   const htmlRender = yield* HtmlRender.HtmlRender;
+  const threads = yield* ThreadManagementService.ThreadManagementService;
   const built = yield* HtmlPreviewToolkit;
   yield* registerImageTool(
     HtmlPreviewTool,
 @@ -679,7 +689,11 @@ const registerHtmlPreview = Effect.fn("McpHttpServer.registerHtmlPreview")(funct
       built
         .handle("html_preview", payload)
         .pipe(Stream.unwrap, Stream.run(Sink.last()), Effect.flatMap(Effect.fromOption)),
-    (effect) => effect.pipe(Effect.provideService(HtmlRender.HtmlRender, htmlRender)),
+    (effect) =>
+      effect.pipe(
+        Effect.provideService(HtmlRender.HtmlRender, htmlRender),
+        Effect.provideService(ThreadManagementService.ThreadManagementService, threads),
+      ),
     "preview",
     // Parameter errors and HTML render errors are both written by the server for the agent.
     (error) =>
 @@ -689,17 +703,34 @@ const registerHtmlPreview = Effect.fn("McpHttpServer.registerHtmlPreview")(funct
   );
 });
+/**
+ * `McpServer.toolkit` for handlers that declared their access (see
+ * `McpToolAccess`). Every toolkit on `/mcp` registers through this.
+ */
+export const toolkitRegistration = <Tools extends Record<string, Tool.Any>, EX, RX>(
+  toolkit: Toolkit.Toolkit<Tools>,
+  handlers: McpToolAccess.HandlersLayer<Tools, EX, RX>,
+) => McpServer.toolkit(toolkit).pipe(Layer.provide(McpToolAccess.HandlersLayer.layer(handlers)));
+/** A hand-registered tool, also only with handlers that declared their access. */
+const imageToolRegistration = <Tools extends Record<string, Tool.Any>, A, E, R, EX, RX>(
+  register: Effect.Effect<A, E, R>,
+  handlers: McpToolAccess.HandlersLayer<Tools, EX, RX>,
+) => Layer.effectDiscard(register).pipe(Layer.provide(McpToolAccess.HandlersLayer.layer(handlers)));
 export const layerHtmlToolkit = Layer.mergeAll(
-  McpServer.toolkit(HtmlRenderToolkit).pipe(Layer.provide(HtmlHandlers.layerRender)),
+  toolkitRegistration(HtmlRenderToolkit, HtmlHandlers.layerRender),
-  Layer.effectDiscard(registerHtmlPreview()).pipe(Layer.provide(HtmlHandlers.layerPreview)),
+  imageToolRegistration(registerHtmlPreview(), HtmlHandlers.layerPreview),
 ).pipe(Layer.provide(HtmlRender.layer));
-const layerPreviewStandardToolkitRegistration = McpServer.toolkit(PreviewStandardToolkit).pipe(
+const layerPreviewStandardToolkitRegistration = toolkitRegistration(
-  Layer.provide(PreviewHandlers.layerStandard),
+  PreviewStandardToolkit,
+  PreviewHandlers.layerStandard,
 );
-const layerPreviewSnapshotRegistration = Layer.effectDiscard(registerPreviewSnapshot()).pipe(
+const layerPreviewSnapshotRegistration = imageToolRegistration(
-  Layer.provide(PreviewHandlers.layerSnapshot),
+  registerPreviewSnapshot(),
+  PreviewHandlers.layerSnapshot,
 );
 export const layerPreviewToolkit = Layer.mergeAll(
 @@ -707,47 +738,48 @@ export const layerPreviewToolkit = Layer.mergeAll(
   layerPreviewSnapshotRegistration,
 );
-export const layerOrchestratorToolkit = McpServer.toolkit(OrchestratorToolkit).pipe(
+export const layerOrchestratorToolkit = toolkitRegistration(
-  Layer.provide(OrchestratorHandlers.layer),
+  OrchestratorToolkit,
-  Layer.provide(OrchestratorMcpService.layer),
+  OrchestratorHandlers.layer,
-  Layer.provide(ThreadMetadataMcpService.layer),
+).pipe(Layer.provide(OrchestratorMcpService.layer), Layer.provide(ThreadMetadataMcpService.layer));
-);
-export const layerThreadToolkit = McpServer.toolkit(ThreadToolkit).pipe(
+export const layerThreadToolkit = toolkitRegistration(ThreadToolkit, ThreadHandlers.layer);
-  Layer.provide(ThreadHandlers.layer),
-);
-const layerWorktreeToolkitRegistration = McpServer.toolkit(WorktreeToolkit).pipe(
+const layerWorktreeToolkitRegistration = toolkitRegistration(
-  Layer.provide(WorktreeHandlers.layer),
+  WorktreeToolkit,
-  Layer.provide(WorktreeMcpService.layer),
+  WorktreeHandlers.layer,
-);
+).pipe(Layer.provide(WorktreeMcpService.layer));
-const layerPreviewControlsRegistration = McpServer.toolkit(PreviewControlsToolkit).pipe(
+const layerPreviewControlsRegistration = toolkitRegistration(
-  Layer.provide(PreviewControlsHandlers.layer),
+  PreviewControlsToolkit,
+  PreviewControlsHandlers.layer,
 );
-const layerEnvironmentRegistration = McpServer.toolkit(EnvironmentToolkit).pipe(
+const layerEnvironmentRegistration = toolkitRegistration(
-  Layer.provide(EnvironmentHandlers.layer),
+  EnvironmentToolkit,
+  EnvironmentHandlers.layer,
 );
-const layerProjectRegistration = McpServer.toolkit(ProjectToolkit).pipe(
+const layerProjectRegistration = toolkitRegistration(ProjectToolkit, ProjectHandlers.layer);
-  Layer.provide(ProjectHandlers.layer),
-);
-const layerAttachmentRegistration = McpServer.toolkit(AttachmentToolkit).pipe(
+const layerAttachmentRegistration = toolkitRegistration(
-  Layer.provide(AttachmentHandlers.layer),
+  AttachmentToolkit,
+  AttachmentHandlers.layer,
 );
-export const layerPullRequestsToolkit = McpServer.toolkit(PullRequestsToolkit).pipe(
+export const layerPullRequestsToolkit = toolkitRegistration(
-  Layer.provide(PullRequestsHandlers.layer),
+  PullRequestsToolkit,
+  PullRequestsHandlers.layer,
 );
-const layerDeviceStandardToolkitRegistration = McpServer.toolkit(DeviceStandardToolkit).pipe(
+const layerDeviceStandardToolkitRegistration = toolkitRegistration(
-  Layer.provide(DeviceHandlers.layerStandard),
+  DeviceStandardToolkit,
+  DeviceHandlers.layerStandard,
 );
-const layerDeviceScreenshotRegistration = Layer.effectDiscard(registerDeviceScreenshot()).pipe(
+const layerDeviceScreenshotRegistration = imageToolRegistration(
-  Layer.provide(DeviceHandlers.layerScreenshot),
+  registerDeviceScreenshot(),
+  DeviceHandlers.layerScreenshot,
 );
 export const layerDeviceToolkit = Layer.mergeAll(

apps/server/src/mcp/McpToolAccess.race.test.ts created+200

...	@@ -0,0 +1,200 @@
1	import { assert, it } from "@effect/vitest";
2	import {
3	CommandId,
4	EnvironmentId,
5	OrchestratorMcpFailure,
6	ProjectId,
7	ProviderDriverKind,
8	ProviderInstanceId,
9	ThreadId,
10	} from "@t3tools/contracts";
11	import * as Effect from "effect/Effect";
12	import * as Layer from "effect/Layer";
13	import * as Ref from "effect/Ref";
14	import * as Schema from "effect/Schema";
15	import { McpSchema, McpServer, Tool, Toolkit } from "effect/ai";
16
17	import * as SqlitePersistence from "../persistence/Sqlite.ts";
18	import { DispatchModeLimit } from "../orchestration-v2/DispatchModeLimit.ts";
19	import { CodexProviderCapabilitiesV2 } from "../orchestration-v2/Adapters/CodexAdapterV2.ts";
20	import * as Orchestrator from "../orchestration-v2/Orchestrator.ts";
21	import * as ProjectionStore from "../orchestration-v2/ProjectionStore.ts";
22	import type { ProviderAdapterV2Shape } from "../orchestration-v2/ProviderAdapter.ts";
23	import * as ProviderAdapterRegistry from "../orchestration-v2/ProviderAdapterRegistry.ts";
24	import * as ThreadManagement from "../orchestration-v2/ThreadManagementService.ts";
25	import * as ProviderReplayHarness from "../orchestration-v2/testkit/ProviderReplayHarness.ts";
26	import * as McpHttpServer from "./McpHttpServer.ts";
27	import * as McpInvocationContext from "./McpInvocationContext.ts";
28	import * as McpToolAccess from "./McpToolAccess.ts";
29
30	// A Supervised outside agent renames a thread through a `writesThreads` tool.
31	// The thread's user raises it to full access after the tool's check but
32	// before its write: the race the orchestrator closes under the thread's lock.
33
34	const instanceId = ProviderInstanceId.make("codex");
35	const adapter = {
36	instanceId,
37	driver: ProviderDriverKind.make("codex"),
38	getCapabilities: () => Effect.succeed(CodexProviderCapabilitiesV2),
39	planSelectionTransition: () => Effect.succeed({ type: "apply_on_next_turn" as const }),
40	openSession: () => Effect.die("No provider process needed for metadata commands"),
41	} as ProviderAdapterV2Shape;
42	const layerDatabase = SqlitePersistence.layerMemory;
43	const layerOrchestrator = Layer.mergeAll(
44	layerDatabase,
45	ProjectionStore.layer.pipe(Layer.provide(layerDatabase)),
46	ProviderReplayHarness.layerWithRegistry(
47	{ name: "mcp-mode-race" },
48	ProviderAdapterRegistry.layerFromAdapters([adapter]),
49	{ databaseLayer: layerDatabase, runEffectWorker: false },
50	),
51	);
52
53	const RenameTool = Tool.make("rename", {
54	parameters: Schema.Struct({ threadId: ThreadId }),
55	success: Schema.Struct({ renamed: Schema.Boolean }),
56	failure: OrchestratorMcpFailure,
57	failureMode: "return",
58	dependencies: [
59	McpInvocationContext.McpInvocationContext,
60	ThreadManagement.ThreadManagementService,
61	],
62	});
63	const RenameToolkit = Toolkit.make(RenameTool);
64
65	const supervisedClient: McpInvocationContext.McpInvocationScope = {
66	environmentId: EnvironmentId.make("environment"),
67	requestNamespace: "client:race",
68	thread: undefined,
69	client: { sessionId: "race", label: "Claude Code", runtimeModeCeiling: "approval-required" },
70	capabilities: new Set(["orchestration"]),
71	issuedAt: 0,
72	};
73
74	const mcpClient = McpSchema.McpServerClient.of({
75	clientId: 1,
76	protocolVersion: "2025-06-18",
77	clientCapabilities: {},
78	clientInfo: { name: "mcp-race", version: "1" },
79	initializePayload: {
80	protocolVersion: "2025-06-18",
81	capabilities: {},
82	clientInfo: { name: "mcp-race", version: "1" },
83	},
84	getClient: Effect.die("unused"),
85	});
86
87	const decodeOutcome = Schema.decodeUnknownEffect(
88	Schema.fromJsonString(
89	Schema.Union([
90	Schema.Struct({ renamed: Schema.Boolean }),
91	Schema.Struct({ code: Schema.String }),
92	]),
93	),
94	);
95
96	/** Renames `threadId` as the Supervised client; the user may raise it in between. */
97	const renameRacingTheUser = (threadId: ThreadId, userRaises: boolean) =>
98	Effect.gen(function* () {
99	const orchestrator = yield* Orchestrator.OrchestratorV2;
100	const threads = yield* ThreadManagement.ThreadManagementService;
101	const raised = yield* Ref.make(false);
102	const handlers = McpToolAccess.toLayer(RenameToolkit, {
103	rename: McpToolAccess.writesThreads(
104	(input) => [input.threadId],
105	(input) =>
106	Effect.gen(function* () {
107	// The tool's own check has passed; the user acts before the write.
108	if (userRaises) {
109	// The user's own command carries no limit, so it lands.
110	yield* orchestrator
111	.dispatch({
112	type: "thread.runtime-mode.set",
113	commandId: CommandId.make("user-raise"),
114	threadId: input.threadId,
115	runtimeMode: "full-access",
116	})
117	.pipe(Effect.provideService(DispatchModeLimit, undefined), Effect.orDie);
118	yield* Ref.set(raised, true);
119	}
120	yield* threads
121	.dispatch({
122	type: "thread.metadata.update",
123	commandId: CommandId.make(`agent-rename:${userRaises}`),
124	threadId: input.threadId,
125	title: "Renamed by the agent",
126	})
127	.pipe(
128	Effect.mapError(
129	() =>
130	new OrchestratorMcpFailure({
131	code: "orchestration_error",
132	message: "The rename failed.",
133	}),
134	),
135	);
136	return { renamed: true };
137	}),
138	),
139	});
140	const outcome = yield* McpServer.McpServer.pipe(
141	Effect.flatMap((server) => server.callTool({ name: "rename", arguments: { threadId } })),
142	Effect.flatMap(({ content }) =>
143	decodeOutcome(content.map((part) => (part.type === "text" ? part.text : "")).join("")),
144	),
145	Effect.provideService(McpInvocationContext.McpInvocationContext, supervisedClient),
146	Effect.provideService(McpSchema.McpServerClient, mcpClient),
147	Effect.provide(
148	McpHttpServer.toolkitRegistration(RenameToolkit, handlers).pipe(
149	Layer.provideMerge(McpServer.McpServer.layer),
150	),
151	),
152	);
153	assert.equal(yield* Ref.get(raised), userRaises);
154	return outcome;
155	});
156
157	const createSupervisedThread = (threadId: ThreadId) =>
158	Effect.gen(function* () {
159	const orchestrator = yield* Orchestrator.OrchestratorV2;
160	yield* orchestrator.dispatch({
161	type: "thread.create",
162	commandId: CommandId.make(`create:${threadId}`),
163	threadId,
164	projectId: ProjectId.make("project:mcp-race"),
165	title: "Before",
166	modelSelection: { instanceId, model: "gpt-5" },
167	runtimeMode: "approval-required",
168	interactionMode: "default",
169	branch: null,
170	worktreePath: null,
171	createdBy: "user",
172	creationSource: "web",
173	});
174	});
175
176	it.layer(layerOrchestrator)("writesThreads against a mode raise", (it) => {
177	it.effect("refuses the write when the user raises the thread after the check", () =>
178	Effect.gen(function* () {
179	const projections = yield* ProjectionStore.ProjectionStoreV2;
180	const threadId = ThreadId.make("thread:race-raised");
181	yield* createSupervisedThread(threadId);
182	const outcome = yield* renameRacingTheUser(threadId, true);
183	assert.deepEqual(outcome, { code: "runtime_mode_escalation_denied" });
184	const shell = yield* projections.getThreadShell(threadId);
185	assert.equal(shell?.runtimeMode, "full-access");
186	assert.equal(shell?.title, "Before");
187	}).pipe(Effect.provide(ThreadManagement.layer)),
188	);
189
190	it.effect("lets the write through when the thread stays within the caller's modes", () =>
191	Effect.gen(function* () {
192	const projections = yield* ProjectionStore.ProjectionStoreV2;
193	const threadId = ThreadId.make("thread:race-steady");
194	yield* createSupervisedThread(threadId);
195	const outcome = yield* renameRacingTheUser(threadId, false);
196	assert.deepEqual(outcome, { renamed: true });
197	assert.equal((yield* projections.getThreadShell(threadId))?.title, "Renamed by the agent");
198	}).pipe(Effect.provide(ThreadManagement.layer)),
199	);
200	});

apps/server/src/mcp/McpToolAccess.test.ts created+306

...	@@ -0,0 +1,306 @@
1	import { expect, it } from "@effect/vitest";
2	import {
3	EnvironmentId,
4	OrchestratorMcpFailure,
5	ProviderInstanceId,
6	ProviderInteractionMode,
7	RuntimeMode,
8	ThreadId,
9	} from "@t3tools/contracts";
10	import * as Effect from "effect/Effect";
11	import * as Layer from "effect/Layer";
12	import * as Schema from "effect/Schema";
13	import { McpSchema, McpServer, Tool, Toolkit } from "effect/ai";
14
15	import { OrchestratorProjectionError } from "../orchestration-v2/Orchestrator.ts";
16	import * as ThreadManagement from "../orchestration-v2/ThreadManagementService.ts";
17	import * as McpHttpServer from "./McpHttpServer.ts";
18	import * as McpInvocationContext from "./McpInvocationContext.ts";
19	import * as McpToolAccess from "./McpToolAccess.ts";
20	import { liveThreadShell } from "./McpToolAccess.testkit.ts";
21
22	const supervisedThreadId = ThreadId.make("thread:supervised");
23	const planThreadId = ThreadId.make("thread:plan");
24	const fullAccessThreadId = ThreadId.make("thread:full-access");
25	const endedThreadId = ThreadId.make("thread:ended");
26
27	const shells = new Map([
28	[supervisedThreadId, liveThreadShell(supervisedThreadId, { runtimeMode: "approval-required" })],
29	[
30	planThreadId,
31	liveThreadShell(planThreadId, { runtimeMode: "approval-required", interactionMode: "plan" }),
32	],
33	[fullAccessThreadId, liveThreadShell(fullAccessThreadId)],
34	[endedThreadId, liveThreadShell(endedThreadId, { activeRunId: null })],
35	]);
36
37	const threadCaller = (threadId: ThreadId): McpInvocationContext.McpInvocationScope => ({
38	environmentId: EnvironmentId.make("environment"),
39	requestNamespace: `provider:${threadId}`,
40	thread: {
41	threadId,
42	providerSessionId: `provider:${threadId}`,
43	providerInstanceId: ProviderInstanceId.make("codex"),
44	},
45	client: undefined,
46	capabilities: new Set(["orchestration"]),
47	issuedAt: 0,
48	});
49
50	const clientCaller = (
51	runtimeModeCeiling: RuntimeMode,
52	): McpInvocationContext.McpInvocationScope => ({
53	environmentId: EnvironmentId.make("environment"),
54	requestNamespace: "client:session",
55	thread: undefined,
56	client: { sessionId: "session", label: "Claude Code", runtimeModeCeiling },
57	capabilities: new Set(["orchestration"]),
58	issuedAt: 0,
59	});
60
61	const mcpClient = McpSchema.McpServerClient.of({
62	clientId: 1,
63	protocolVersion: "2025-06-18",
64	clientCapabilities: {},
65	clientInfo: { name: "mcp-test", version: "1" },
66	initializePayload: {
67	protocolVersion: "2025-06-18",
68	capabilities: {},
69	clientInfo: { name: "mcp-test", version: "1" },
70	},
71	getClient: Effect.die("unused"),
72	});
73
74	// One tool per declaration, each answering with the modes it was handed, so
75	// the table below reads what the gate let through.
76	const probe = {
77	success: Schema.Struct({ ran: Schema.String }),
78	failure: OrchestratorMcpFailure,
79	failureMode: "return" as const,
80	dependencies: [
81	McpInvocationContext.McpInvocationContext,
82	ThreadManagement.ThreadManagementService,
83	],
84	};
85	const ProbeToolkit = Toolkit.make(
86	Tool.make("reads", probe),
87	Tool.make("reads_as_caller", probe),
88	Tool.make("acts_as_caller", probe),
89	Tool.make("writes", probe),
90	Tool.make("writes_threads", {
91	...probe,
92	parameters: Schema.Struct({ threadId: Schema.optional(ThreadId) }),
93	}),
94	Tool.make("starts_threads", {
95	...probe,
96	parameters: Schema.Struct({
97	runtimeMode: Schema.optional(RuntimeMode),
98	interactionMode: Schema.optional(ProviderInteractionMode),
99	}),
100	}),
101	Tool.make("writes_environment", probe),
102	);
103	const ran = Effect.succeed({ ran: "ran" });
104	const probeHandlers: McpToolAccess.Handlers<typeof ProbeToolkit.tools> = {
105	reads: McpToolAccess.reads(() => ran),
106	reads_as_caller: McpToolAccess.readsAsCaller(() => ran),
107	acts_as_caller: McpToolAccess.actsAsCaller(() => ran),
108	writes: McpToolAccess.writes(() => ran),
109	writes_threads: McpToolAccess.writesThreads(
110	(input) => [input.threadId],
111	() => ran,
112	),
113	starts_threads: McpToolAccess.startsThreads(
114	(input) => input,
115	(_, modes) => Effect.succeed({ ran: `${modes.runtimeMode}/${modes.interactionMode}` }),
116	),
117	writes_environment: McpToolAccess.writesEnvironment(() => ran),
118	};
119	const layerProbeHandlers = McpToolAccess.toLayer(ProbeToolkit, probeHandlers);
120
121	const unchecked = () => ran;
122
123	// What the compiler refuses: each line below must fail to typecheck, and its
124	// `@ts-expect-error` fails the build if one ever compiles. Never called.
125	export const refusedAtCompileTime = () => {
126	McpToolAccess.toLayer(ProbeToolkit, {
127	...probeHandlers,
128	// @ts-expect-error a handler that skips its declaration
129	reads: unchecked,
130	});
131	McpToolAccess.toLayer(ProbeToolkit, {
132	...probeHandlers,
133	// @ts-expect-error a declaration's fields copied onto an unchecked handler
134	reads: Object.assign(
135	unchecked,
136	McpToolAccess.reads(() => ran),
137	),
138	});
139	// @ts-expect-error a declaration built outside McpToolAccess
140	McpToolAccess.Declaration.make(unchecked);
141	// @ts-expect-error a declaration constructed directly
142	new McpToolAccess.Declaration(unchecked);
143	// @ts-expect-error a handlers layer built outside McpToolAccess
144	McpToolAccess.HandlersLayer.make(Layer.empty);
145	// The refused layer below types its error and services as unknown, which is fine here.
146	// @effect-diagnostics-next-line anyUnknownInErrorContext:off
147	McpHttpServer.toolkitRegistration(
148	ProbeToolkit,
149	// @ts-expect-error a handlers layer that skipped `McpToolAccess.toLayer`
150	ProbeToolkit.toLayer({
151	reads: unchecked,
152	reads_as_caller: unchecked,
153	acts_as_caller: unchecked,
154	writes: unchecked,
155	writes_threads: unchecked,
156	starts_threads: unchecked,
157	writes_environment: unchecked,
158	}),
159	);
160	};
161
162	const probeServer = (threads: Layer.Layer<ThreadManagement.ThreadManagementService>) =>
163	McpHttpServer.toolkitRegistration(ProbeToolkit, layerProbeHandlers).pipe(
164	Layer.provideMerge(McpServer.McpServer.layer),
165	Layer.provideMerge(threads),
166	);
167
168	/** A probe's answer, or the gate's refusal, as the result's JSON text. */
169	const decodeOutcome = Schema.decodeUnknownEffect(
170	Schema.fromJsonString(
171	Schema.Union([Schema.Struct({ ran: Schema.String }), Schema.Struct({ code: Schema.String })]),
172	),
173	);
174
175	const call = (
176	tool: string,
177	scope: McpInvocationContext.McpInvocationScope,
178	args: Record<string, unknown> = {},
179	) =>
180	McpServer.McpServer.pipe(
181	Effect.flatMap((server) => server.callTool({ name: tool, arguments: args })),
182	Effect.flatMap(({ content }) =>
183	decodeOutcome(content.map((part) => (part.type === "text" ? part.text : "")).join("")),
184	),
185	Effect.map((outcome) => ("code" in outcome ? outcome.code : outcome.ran)),
186	Effect.provideService(McpInvocationContext.McpInvocationContext, scope),
187	Effect.provideService(McpSchema.McpServerClient, mcpClient),
188	);
189
190	const supervised = threadCaller(supervisedThreadId);
191	const plan = threadCaller(planThreadId);
192	const fullAccess = threadCaller(fullAccessThreadId);
193	const ended = threadCaller(endedThreadId);
194	const supervisedClient = clientCaller("approval-required");
195	const fullAccessClient = clientCaller("full-access");
196	// A live full-access thread whose credential may use its browser but not control threads.
197	const previewOnly = { ...fullAccess, capabilities: new Set(["preview"] as const) };
198
199	it.effect.each([
200	// Reads are open to every caller, even one whose turn ended.
201	["reads", ended, {}, "ran"],
202	["reads", supervisedClient, {}, "ran"],
203
204	// What belongs to the calling thread needs one; changing it needs its live turn.
205	["reads_as_caller", ended, {}, "ran"],
206	["reads_as_caller", fullAccessClient, {}, "thread_credential_required"],
207	["acts_as_caller", supervised, {}, "ran"],
208	["acts_as_caller", ended, {}, "parent_not_active"],
209	["acts_as_caller", fullAccessClient, {}, "thread_credential_required"],
210
211	// Any change needs a thread caller's live turn; a client has none to lose.
212	["writes", supervised, {}, "ran"],
213	["writes", ended, {}, "parent_not_active"],
214	["writes", supervisedClient, {}, "ran"],
215	// Uploads, scheduled tasks, projects and settings need a credential that controls threads.
216	["writes", previewOnly, {}, "capability_denied"],
217	["writes_environment", previewOnly, {}, "capability_denied"],
218
219	// Changing a thread: only one that runs within the caller's modes.
220	["writes_threads", supervised, {}, "ran"],
221	["writes_threads", supervised, { threadId: planThreadId }, "ran"],
222	[
223	"writes_threads",
224	supervised,
225	{ threadId: fullAccessThreadId },
226	"runtime_mode_escalation_denied",
227	],
228	["writes_threads", plan, { threadId: supervisedThreadId }, "interaction_mode_escalation_denied"],
229	["writes_threads", fullAccess, { threadId: supervisedThreadId }, "ran"],
230	["writes_threads", ended, { threadId: supervisedThreadId }, "parent_not_active"],
231	["writes_threads", supervisedClient, { threadId: supervisedThreadId }, "ran"],
232	[
233	"writes_threads",
234	supervisedClient,
235	{ threadId: fullAccessThreadId },
236	"runtime_mode_escalation_denied",
237	],
238	// A thread that does not exist is the tool's to report.
239	["writes_threads", supervised, { threadId: "thread:missing" }, "ran"],
240
241	// Starting a thread: the caller's own modes or narrower.
242	["starts_threads", supervised, {}, "approval-required/default"],
243	["starts_threads", supervised, { runtimeMode: "full-access" }, "runtime_mode_escalation_denied"],
244	["starts_threads", plan, {}, "approval-required/plan"],
245	["starts_threads", plan, { interactionMode: "default" }, "interaction_mode_escalation_denied"],
246	["starts_threads", fullAccess, { runtimeMode: "auto", interactionMode: "plan" }, "auto/plan"],
247	["starts_threads", ended, {}, "parent_not_active"],
248	["starts_threads", supervisedClient, {}, "approval-required/default"],
249	["starts_threads", supervisedClient, { runtimeMode: "auto" }, "runtime_mode_escalation_denied"],
250	["starts_threads", fullAccessClient, { runtimeMode: "full-access" }, "full-access/default"],
251
252	// Projects and environment settings need full access.
253	["writes_environment", fullAccess, {}, "ran"],
254	["writes_environment", supervised, {}, "capability_denied"],
255	["writes_environment", plan, {}, "capability_denied"],
256	["writes_environment", fullAccessClient, {}, "ran"],
257	["writes_environment", supervisedClient, {}, "capability_denied"],
258	] as const)("%s from %o with %o: %s", ([tool, scope, args, expected]) =>
259	call(tool, scope, args).pipe(
260	Effect.map((outcome) => expect(outcome).toBe(expected)),
261	Effect.provide(
262	probeServer(
263	Layer.mock(ThreadManagement.ThreadManagementService)({
264	getThreadShell: (threadId) => Effect.succeed(shells.get(threadId) ?? null),
265	}),
266	),
267	),
268	),
269	);
270
271	it("refuses a declaration or handlers layer built outside McpToolAccess", () => {
272	// Private constructors only bind the type checker; Reflect.construct reaches them anyway.
273	expect(() => Reflect.construct(McpToolAccess.Declaration, [unchecked])).toThrow(TypeError);
274	expect(() => Reflect.construct(McpToolAccess.HandlersLayer, [Layer.empty])).toThrow(TypeError);
275	});
276
277	it("refuses a declaration or handlers layer that only wears another's fields", () => {
278	// The types already refuse these; at runtime the private fields are missing too.
279	const copiedDeclaration = Object.assign(
280	unchecked,
281	McpToolAccess.reads(() => ran),
282	);
283	expect(() =>
284	McpToolAccess.toLayer(ProbeToolkit, {
285	...probeHandlers,
286	// @ts-expect-error a declaration's fields copied onto an unchecked handler
287	reads: copiedDeclaration,
288	}),
289	).toThrow(TypeError);
290	const copiedLayer = Object.assign(Layer.empty, layerProbeHandlers);
291	expect(() => McpToolAccess.HandlersLayer.layer(copiedLayer)).toThrow(TypeError);
292	});
293
294	it.effect("refuses a change when the calling thread cannot be read", () =>
295	call("writes", supervised).pipe(
296	Effect.map((outcome) => expect(outcome).toBe("orchestration_error")),
297	Effect.provide(
298	probeServer(
299	Layer.mock(ThreadManagement.ThreadManagementService)({
300	getThreadShell: (threadId) =>
301	Effect.fail(new OrchestratorProjectionError({ threadId, cause: "unreadable" })),
302	}),
303	),
304	),
305	),
306	);

apps/server/src/mcp/McpToolAccess.testkit.ts created+115

...	@@ -0,0 +1,115 @@
1	import {
2	type OrchestrationV2ThreadProjection,
3	type OrchestrationV2ThreadShell,
4	ProjectId,
5	type ProviderInteractionMode,
6	ProviderInstanceId,
7	RunId,
8	type RuntimeMode,
9	type ThreadId,
10	} from "@t3tools/contracts";
11	import * as DateTime from "effect/DateTime";
12	import * as Effect from "effect/Effect";
13	import * as Layer from "effect/Layer";
14
15	import * as ThreadManagement from "../orchestration-v2/ThreadManagementService.ts";
16
17	const EPOCH = DateTime.makeUnsafe("2026-01-01T00:00:00.000Z");
18
19	/**
20	* A thread in the middle of a turn on the `codex` instance: the shape the
21	* access gate reads for a thread caller, and for the threads a caller targets.
22	*/
23	export const liveThreadShell = (
24	id: ThreadId,
25	modes: {
26	readonly runtimeMode?: RuntimeMode;
27	readonly interactionMode?: ProviderInteractionMode;
28	readonly activeRunId?: RunId \| null;
29	} = {},
30	): OrchestrationV2ThreadShell => {
31	const providerInstanceId = ProviderInstanceId.make("codex");
32	return {
33	id,
34	projectId: ProjectId.make("project:mcp-test"),
35	title: id,
36	providerInstanceId,
37	modelSelection: { instanceId: providerInstanceId, model: "gpt-5" },
38	runtimeMode: modes.runtimeMode ?? "full-access",
39	interactionMode: modes.interactionMode ?? "default",
40	branch: null,
41	worktreePath: null,
42	createdBy: "user",
43	creationSource: "web",
44	activeProviderThreadId: null,
45	lineage: { rootThreadId: id, parentThreadId: null, relationshipToParent: null },
46	forkedFrom: null,
47	latestRunId: null,
48	activeRunId: modes.activeRunId === undefined ? RunId.make("run:mcp-test") : modes.activeRunId,
49	status: "running",
50	pendingRuntimeRequest: null,
51	latestVisibleMessage: null,
52	latestUserMessageAt: null,
53	hasActionableProposedPlan: false,
54	itemCount: 0,
55	visibleItemCount: 0,
56	createdAt: EPOCH,
57	updatedAt: EPOCH,
58	archivedAt: null,
59	settledOverride: null,
60	settledAt: null,
61	lastVisitedAt: null,
62	deletedAt: null,
63	};
64	};
65
66	/**
67	* `ThreadManagementService` that answers only the access gate's lookups,
68	* every thread a live full-access one. For tests of a tool rather than of who
69	* may call it.
70	*/
71	export const liveThreadsLayer = Layer.mock(ThreadManagement.ThreadManagementService)({
72	getThreadShell: (threadId) => Effect.succeed(liveThreadShell(threadId)),
73	});
74
75	/**
76	* The thread of `shell` with no runs, messages or other records: what a
77	* caller looks like once its turn has ended.
78	*/
79	export const idleThreadProjection = (
80	shell: OrchestrationV2ThreadShell,
81	): OrchestrationV2ThreadProjection => {
82	const {
83	status: _status,
84	activeRunId: _activeRunId,
85	latestRunId: _latestRunId,
86	pendingRuntimeRequest: _pendingRuntimeRequest,
87	latestVisibleMessage: _latestVisibleMessage,
88	latestUserMessageAt: _latestUserMessageAt,
89	hasActionableProposedPlan: _hasActionableProposedPlan,
90	itemCount: _itemCount,
91	visibleItemCount: _visibleItemCount,
92	lastVisitedAt,
93	...thread
94	} = shell;
95	return {
96	thread: { ...thread, lastVisitedAt: lastVisitedAt ?? null },
97	runs: [],
98	attempts: [],
99	nodes: [],
100	subagents: [],
101	providerSessions: [],
102	providerThreads: [],
103	providerTurns: [],
104	runtimeRequests: [],
105	messages: [],
106	plans: [],
107	turnItems: [],
108	checkpointScopes: [],
109	checkpoints: [],
110	contextHandoffs: [],
111	contextTransfers: [],
112	visibleTurnItems: [],
113	updatedAt: shell.updatedAt,
114	};
115	};

apps/server/src/mcp/McpToolAccess.ts created+295

...	@@ -0,0 +1,295 @@
1	import {
2	OrchestratorMcpFailure,
3	type ProviderInteractionMode,
4	type RuntimeMode,
5	type ThreadId,
6	} from "@t3tools/contracts";
7	import * as Effect from "effect/Effect";
8	import * as Ref from "effect/Ref";
9	import * as Struct from "effect/Struct";
10	import type * as Layer from "effect/Layer";
11	import type * as Scope from "effect/Scope";
12	import type { Tool, Toolkit } from "effect/ai";
13
14	import {
15	DispatchModeLimit,
16	type DispatchModeRefusal,
17	} from "../orchestration-v2/DispatchModeLimit.ts";
18	import * as McpInvocationContext from "./McpInvocationContext.ts";
19	import { resolveInteractionMode, resolveRuntimeMode } from "./OrchestratorMcpService.ts";
20	import {
21	assertFullAccess,
22	assertLiveCaller,
23	assertTargetWithinLimits,
24	type Caller,
25	loadCaller,
26	readCaller,
27	unavailable,
28	} from "./threadAccess.ts";
29
30	// Only the classes below assign these, from their static blocks, so nothing
31	// outside this module can build a declaration or a handlers layer.
32
33	/**
34	* Both constructors demand this. Their private constructors only stop the type
35	* checker; this also stops `Reflect.construct` and friends at runtime.
36	*/
37	const builtHere: unique symbol = Symbol("t3/mcp/McpToolAccess/builtHere");
38
39	const refuseOutsideConstruction = (token: symbol) => {
40	if (token !== builtHere) {
41	throw new TypeError("Only McpToolAccess builds MCP tool declarations and handler layers.");
42	}
43	};
44
45	/** Builds a declaration; only the declaration functions below call it. */
46	let declare: <P, A, E, R>(
47	handle: (params: P) => Effect.Effect<A, E, R>,
48	) => Declaration<(params: P) => Effect.Effect<A, E, R>>;
49
50	type CheckedHandlerOf<D> = D extends Declaration<infer Handler> ? Handler : never;
51
52	/** Turns each declaration back into the handler it checks, keeping its type. */
53	interface CheckedHandler extends Struct.Lambda {
54	<Handler>(declaration: Declaration<Handler>): Handler;
55	readonly "~lambda.out": CheckedHandlerOf<this["~lambda.in"]>;
56	}
57	let checkedHandler: CheckedHandler;
58
59	/** Only `toLayer` below builds one. */
60	let handlersLayer: <Tools extends Record<string, Tool.Any>, EX, RX>(
61	layer: Layer.Layer<Tool.HandlersFor<Tools>, EX, RX>,
62	) => HandlersLayer<Tools, EX, RX>;
63
64	/**
65	* Who may call a T3 MCP tool. Every handler is built by one of the
66	* declarations below, which say what the tool does. `toLayer` accepts only
67	* declarations, and `/mcp` registers only layers `toLayer` built, so a tool
68	* without a decision here does not compile. Both are nominal classes, so a
69	* handler or layer cannot pass for one by copying its fields. Effect's own
70	* registration functions accept any handler, so the
71	* `t3code/no-raw-mcp-registration` lint rule keeps Effect's `McpServer` inside
72	* McpHttpServer.
73	*
74	* Parameters choose the target; the caller sets the limits: a thread caller
75	* its own runtime and interaction modes, an outside client the ceiling it was
76	* approved with. Nothing a caller starts or changes may run with broader
77	* modes, and a thread caller changes things only while its own run is live.
78	* A refusal is an `OrchestratorMcpFailure`, so the compiler requires it in the
79	* tool's failure schema, and `ThreadManagementService` in its dependencies.
80	*
81	* The declaration checks the caller before the handler runs. Handlers still
82	* check what only they can see, such as a queued run belonging to its thread.
83	*/
84	export class Declaration<out Handler> {
85	// A private field makes the class nominal, and only this module can build
86	// one: its constructor is private and the static block hands the only way
87	// in to module-scoped functions. Copying a declaration's fields onto
88	// anything else fails to typecheck and, at runtime, to run.
89	readonly #handle: Handler;
90	private constructor(token: typeof builtHere, handle: Handler) {
91	refuseOutsideConstruction(token);
92	this.#handle = handle;
93	}
94	static {
95	declare = (handle) => new Declaration(builtHere, handle);
96	checkedHandler = Struct.lambda<CheckedHandler>((declaration) => declaration.#handle);
97	}
98	}
99
100	/**
101	* The caller of a tool that changes something. Tools that act for a
102	* capability of their own (preview, device, worktree, pull requests) check it
103	* themselves.
104	*/
105	const writingCaller = loadCaller().pipe(Effect.tap(assertLiveCaller));
106
107	/** The same, for tools whose only capability is controlling threads. */
108	const orchestratingCaller = readCaller().pipe(Effect.tap(assertLiveCaller));
109
110	const requireThreadCaller = McpInvocationContext.McpInvocationContext.pipe(
111	Effect.flatMap((scope) => McpInvocationContext.requireThreadScope(scope, "This tool")),
112	);
113
114	/** Changes nothing, so every caller may call it. */
115	export const reads = <P, A, E, R>(handle: (params: P) => Effect.Effect<A, E, R>) =>
116	declare((params: P) => handle(params));
117
118	/** Reads what belongs to the calling T3 thread, such as its preview tabs or devices. */
119	export const readsAsCaller = <P, A, E, R>(handle: (params: P) => Effect.Effect<A, E, R>) =>
120	declare((params: P) => requireThreadCaller.pipe(Effect.flatMap(() => handle(params))));
121
122	/**
123	* Acts as the calling T3 thread (its subagents, preview tabs, devices,
124	* worktree) while that thread's run is live. Only an agent running inside a
125	* T3 thread has one.
126	*/
127	export const actsAsCaller = <P, A, E, R>(handle: (params: P) => Effect.Effect<A, E, R>) =>
128	declare((params: P) =>
129	requireThreadCaller.pipe(
130	Effect.flatMap(() => writingCaller),
131	Effect.flatMap(() => handle(params)),
132	),
133	);
134
135	/** Changes something that belongs to no thread, such as a pending upload or a scheduled task. */
136	export const writes = <P, A, E, R>(handle: (params: P) => Effect.Effect<A, E, R>) =>
137	declare((params: P) => orchestratingCaller.pipe(Effect.flatMap(() => handle(params))));
138
139	/**
140	* Changes the threads `threads` names. An omitted id is the caller's own
141	* thread; any other thread must run within the caller's modes, checked here
142	* and again by the orchestrator when it applies each command. A thread that
143	* does not exist is the handler's to report.
144	*/
145	export const writesThreads = <P, A, E, R>(
146	threads: (params: P) => ReadonlyArray<ThreadId \| undefined>,
147	handle: (params: P) => Effect.Effect<A, E, R>,
148	) =>
149	declare((params: P) =>
150	Effect.gen(function* () {
151	const caller = yield* writingCaller;
152	for (const threadId of threads(params)) {
153	if (threadId === undefined \|\| threadId === caller.scope.thread?.threadId) continue;
154	const target = yield* caller.threads
155	.getThreadShell(threadId)
156	.pipe(Effect.mapError(unavailable));
157	if (target !== null && target.deletedAt === null) {
158	yield* assertTargetWithinLimits(caller.limits, target);
159	}
160	}
161	// The target's user can raise its modes after the check above; the
162	// orchestrator checks again under the thread's lock and records its
163	// refusal here, since handlers wrap dispatch errors their own way.
164	const refused = yield* Ref.make<DispatchModeRefusal \| undefined>(undefined);
165	return yield* handle(params).pipe(
166	Effect.provideService(DispatchModeLimit, { ...caller.limits, refused }),
167	Effect.catch((error) =>
168	Effect.flatMap(Ref.get(refused), (refusal) =>
169	Effect.fail<E \| OrchestratorMcpFailure>(
170	refusal === undefined ? error : escalationDenied(refusal),
171	),
172	),
173	),
174	);
175	}),
176	);
177
178	/** How an agent hears that a thread it targets was raised above its modes mid-call. */
179	const escalationDenied = (refusal: DispatchModeRefusal) =>
180	new OrchestratorMcpFailure({
181	code:
182	refusal.mode === "runtime"
183	? "runtime_mode_escalation_denied"
184	: "interaction_mode_escalation_denied",
185	message: `Thread ${refusal.threadId} now runs in ${refusal.runtimeMode}/${refusal.interactionMode} mode, above this caller's. Its user changed it while this call ran.`,
186	});
187
188	/** The modes a started thread runs with: those requested, else the caller's own. */
189	export interface StartedModes {
190	readonly runtimeMode: RuntimeMode;
191	readonly interactionMode: ProviderInteractionMode;
192	}
193
194	/** Starts threads with the modes `modes` requests, which may not be broader than the caller's. */
195	export const startsThreads = <P, A, E, R>(
196	modes: (params: P) => {
197	readonly runtimeMode?: RuntimeMode \| undefined;
198	readonly interactionMode?: ProviderInteractionMode \| undefined;
199	},
200	handle: (params: P, modes: StartedModes) => Effect.Effect<A, E, R>,
201	) =>
202	declare((params: P) =>
203	Effect.gen(function* () {
204	const { limits } = yield* writingCaller;
205	const requested = modes(params);
206	const started: StartedModes = {
207	runtimeMode: yield* resolveRuntimeMode(limits.runtimeMode, requested.runtimeMode),
208	interactionMode: yield* resolveInteractionMode(
209	limits.interactionMode,
210	requested.interactionMode,
211	),
212	};
213	return yield* handle(params, started);
214	}),
215	);
216
217	const fullAccessRequired =
218	"Changing projects or environment settings needs a live full-access/default calling thread or a full-access client.";
219
220	/**
221	* Changes projects or environment settings, which needs a full-access/default
222	* caller. `check` re-checks the caller wherever the handler waits before
223	* writing, such as for a lock, since the caller's modes can change meanwhile.
224	*/
225	export const writesEnvironment = <P, A, E, R>(
226	handle: (
227	params: P,
228	check: Effect.Effect<Caller, OrchestratorMcpFailure, CheckServices>,
229	) => Effect.Effect<A, E, R>,
230	) => {
231	const check = orchestratingCaller.pipe(
232	Effect.tap((caller) => assertFullAccess(caller, fullAccessRequired)),
233	);
234	return declare((params: P) => check.pipe(Effect.flatMap(() => handle(params, check))));
235	};
236
237	/** What a declaration's own check needs. */
238	type CheckServices = Effect.Services<typeof orchestratingCaller>;
239
240	/**
241	* Each handler of `Handlers`, built by one of the declarations above. A
242	* declaration is never callable, which rules out a handler function wearing a
243	* declaration's fields.
244	*/
245	type Declarations<Handlers> = {
246	readonly [Name in keyof Handlers]: Declaration<Handlers[Name]> & NotCallable;
247	};
248
249	/** Anything but a function. */
250	type NotCallable = { readonly call?: never } & { readonly apply?: never };
251
252	/** A toolkit's handlers, each built by one of the declarations above. */
253	export type Handlers<Tools extends Record<string, Tool.Any>> = Declarations<
254	Toolkit.HandlersFrom<Tools>
255	>;
256
257	/**
258	* A toolkit's handler layer built by `toLayer`, the only kind `/mcp`
259	* registers. Like a declaration it is nominal, so nothing else passes for one.
260	*/
261	export class HandlersLayer<Tools extends Record<string, Tool.Any>, EX = never, RX = never> {
262	readonly #layer: Layer.Layer<Tool.HandlersFor<Tools>, EX, RX>;
263	private constructor(
264	token: typeof builtHere,
265	layer: Layer.Layer<Tool.HandlersFor<Tools>, EX, RX>,
266	) {
267	refuseOutsideConstruction(token);
268	this.#layer = layer;
269	}
270	static {
271	handlersLayer = (layer) => new HandlersLayer(builtHere, layer);
272	}
273	/** The handlers, for registering this toolkit on the MCP server. */
274	static layer<Tools extends Record<string, Tool.Any>, EX, RX>(
275	handlers: HandlersLayer<Tools, EX, RX>,
276	) {
277	return handlers.#layer;
278	}
279	}
280
281	const checkedHandlers = <Handlers>(declarations: Declarations<Handlers>): Handlers =>
282	Struct.map(declarations, checkedHandler);
283
284	/** `Toolkit.toLayer` for handlers that all declare their access. */
285	export const toLayer = <Tools extends Record<string, Tool.Any>, EX = never, RX = never>(
286	toolkit: Toolkit.Toolkit<Tools>,
287	build: Handlers<Tools> \| Effect.Effect<Handlers<Tools>, EX, RX>,
288	): HandlersLayer<Tools, EX, Exclude<RX, Scope.Scope>> =>
289	handlersLayer(
290	toolkit.toLayer(
291	Effect.isEffect(build)
292	? Effect.map(build, checkedHandlers<Toolkit.HandlersFrom<Tools>>)
293	: checkedHandlers(build),
294	),
295	);

apps/server/src/mcp/OrchestratorMcpService.test.ts+494-1

...	@@ -1,8 +1,12 @@	...	@@ -1,8 +1,12 @@
1	import * as NodeServices from "@effect/platform-node/NodeServices";	1	import * as NodeServices from "@effect/platform-node/NodeServices";
2	import { assert, describe, it } from "@effect/vitest";	2	import { assert, describe, it } from "@effect/vitest";
3	import {	3	import {
		4	CommandId,
4	EnvironmentId,	5	EnvironmentId,
5	NodeId,	6	NodeId,
		7	type OrchestrationV2ThreadShell,
		8	type ScheduledTask,
		9	ScheduledTaskId,
6	ProjectId,	10	ProjectId,
7	ProviderDriverKind,	11	ProviderDriverKind,
8	ProviderInstanceId,	12	ProviderInstanceId,
...	@@ -16,7 +20,14 @@ import * as Effect from "effect/Effect";	...	@@ -16,7 +20,14 @@ import * as Effect from "effect/Effect";
16	import * as Layer from "effect/Layer";	20	import * as Layer from "effect/Layer";
17	import * as Ref from "effect/Ref";	21	import * as Ref from "effect/Ref";
18		22
19	import { OrchestratorProjectionError } from "../orchestration-v2/Orchestrator.ts";	23	import {
		24	DispatchModeLimit,
		25	type DispatchModeRefusal,
		26	} from "../orchestration-v2/DispatchModeLimit.ts";
		27	import {
		28	OrchestratorProjectionError,
		29	OrchestratorThreadAboveModeLimitError,
		30	} from "../orchestration-v2/Orchestrator.ts";
20	import type { ProviderAdapterV2Shape } from "../orchestration-v2/ProviderAdapter.ts";	31	import type { ProviderAdapterV2Shape } from "../orchestration-v2/ProviderAdapter.ts";
21	import * as ProviderAdapterRegistry from "../orchestration-v2/ProviderAdapterRegistry.ts";	32	import * as ProviderAdapterRegistry from "../orchestration-v2/ProviderAdapterRegistry.ts";
22	import * as ThreadManagementService from "../orchestration-v2/ThreadManagementService.ts";	33	import * as ThreadManagementService from "../orchestration-v2/ThreadManagementService.ts";
...	@@ -26,6 +37,7 @@ import * as ProjectService from "../project/ProjectService.ts";	...	@@ -26,6 +37,7 @@ import * as ProjectService from "../project/ProjectService.ts";
26	import * as ScheduledTaskService from "../scheduledTasks/ScheduledTaskService.ts";	37	import * as ScheduledTaskService from "../scheduledTasks/ScheduledTaskService.ts";
27	import * as SecretRequests from "../secrets/SecretRequests.ts";	38	import * as SecretRequests from "../secrets/SecretRequests.ts";
28	import type { McpInvocationScope } from "./McpInvocationContext.ts";	39	import type { McpInvocationScope } from "./McpInvocationContext.ts";
		40	import { idleThreadProjection, liveThreadShell } from "./McpToolAccess.testkit.ts";
29	import * as OrchestratorMcpService from "./OrchestratorMcpService.ts";	41	import * as OrchestratorMcpService from "./OrchestratorMcpService.ts";
30		42
31	describe("OrchestratorMcpService", () => {	43	describe("OrchestratorMcpService", () => {
...	@@ -283,6 +295,8 @@ describe("OrchestratorMcpService", () => {	...	@@ -283,6 +295,8 @@ describe("OrchestratorMcpService", () => {
283	Layer.mock(ThreadManagementService.ThreadManagementService)({	295	Layer.mock(ThreadManagementService.ThreadManagementService)({
284	getThreadRecords: (threadId) =>	296	getThreadRecords: (threadId) =>
285	Effect.succeed(threadId === parentThreadId ? parentProjection : childProjection),	297	Effect.succeed(threadId === parentThreadId ? parentProjection : childProjection),
		298	// The child still runs within the parent's modes.
		299	getThreadShell: (threadId) => Effect.succeed(liveThreadShell(threadId)),
286	dispatch: (command) =>	300	dispatch: (command) =>
287	Ref.update(dispatched, (commands) => [...commands, command]).pipe(	301	Ref.update(dispatched, (commands) => [...commands, command]).pipe(
288	Effect.as({} as never),	302	Effect.as({} as never),
...	@@ -357,6 +371,8 @@ describe("OrchestratorMcpService", () => {	...	@@ -357,6 +371,8 @@ describe("OrchestratorMcpService", () => {
357	Layer.mock(ThreadManagementService.ThreadManagementService)({	371	Layer.mock(ThreadManagementService.ThreadManagementService)({
358	getThreadRecords: (threadId) =>	372	getThreadRecords: (threadId) =>
359	Effect.succeed(threadId === parentThreadId ? parentProjection : childProjection),	373	Effect.succeed(threadId === parentThreadId ? parentProjection : childProjection),
		374	// The child still runs within the parent's modes.
		375	getThreadShell: (threadId) => Effect.succeed(liveThreadShell(threadId)),
360	dispatch: (command) =>	376	dispatch: (command) =>
361	Ref.update(dispatched, (commands) => [...commands, command]).pipe(	377	Ref.update(dispatched, (commands) => [...commands, command]).pipe(
362	Effect.andThen(Effect.fail(new Error("simulated stop failure") as never)),	378	Effect.andThen(Effect.fail(new Error("simulated stop failure") as never)),
...	@@ -434,6 +450,8 @@ describe("OrchestratorMcpService", () => {	...	@@ -434,6 +450,8 @@ describe("OrchestratorMcpService", () => {
434	Layer.mock(ThreadManagementService.ThreadManagementService)({	450	Layer.mock(ThreadManagementService.ThreadManagementService)({
435	getThreadRecords: (threadId) =>	451	getThreadRecords: (threadId) =>
436	Effect.succeed(threadId === parentThreadId ? parentProjection : childProjection),	452	Effect.succeed(threadId === parentThreadId ? parentProjection : childProjection),
		453	// The child still runs within the parent's modes.
		454	getThreadShell: (threadId) => Effect.succeed(liveThreadShell(threadId)),
437	dispatch: (command) =>	455	dispatch: (command) =>
438	Ref.update(dispatched, (commands) => [...commands, command]).pipe(	456	Ref.update(dispatched, (commands) => [...commands, command]).pipe(
439	Effect.andThen(	457	Effect.andThen(
...	@@ -479,6 +497,258 @@ describe("OrchestratorMcpService", () => {	...	@@ -479,6 +497,258 @@ describe("OrchestratorMcpService", () => {
479	}).pipe(Effect.provide(OrchestratorMcpService.layer.pipe(Layer.provide(layerDependencies))));	497	}).pipe(Effect.provide(OrchestratorMcpService.layer.pipe(Layer.provide(layerDependencies))));
480	}),	498	}),
481	);	499	);
		500
		501	it.effect("refuses to cancel a task whose child now runs above the parent's modes", () =>
		502	Effect.gen(function* () {
		503	const parentThreadId = ThreadId.make("thread:mcp-cancel-dispose-failed-parent");
		504	const childThreadId = ThreadId.make("thread:mcp-cancel-dispose-failed-child");
		505	const childRunId = RunId.make("run:mcp-cancel-dispose-failed-child");
		506	const taskId = NodeId.make("node:mcp-cancel-dispose-failed-task");
		507	const dispatched = yield* Ref.make<ReadonlyArray<unknown>>([]);
		508	// The parent runs Supervised in plan mode.
		509	const parentProjection = {
		510	thread: { id: parentThreadId, runtimeMode: "approval-required", interactionMode: "plan" },
		511	runs: [],
		512	contextTransfers: [],
		513	subagents: [
		514	{
		515	id: taskId,
		516	threadId: parentThreadId,
		517	origin: "app_owned",
		518	childThreadId,
		519	driver: "codex",
		520	model: "gpt-5.6-terra",
		521	result: null,
		522	completionDelivery: { state: "pending" },
		523	},
		524	],
		525	} as unknown as OrchestrationV2ThreadProjection;
		526	const childProjection = {
		527	thread: { id: childThreadId },
		528	runs: [{ id: childRunId, status: "running" }],
		529	contextTransfers: [],
		530	messages: [],
		531	subagents: [],
		532	providerThreads: [],
		533	} as unknown as OrchestrationV2ThreadProjection;
		534	const layerDependencies = Layer.mergeAll(
		535	NodeServices.layer,
		536	Layer.mock(ThreadManagementService.ThreadManagementService)({
		537	getThreadRecords: (threadId) =>
		538	Effect.succeed(threadId === parentThreadId ? parentProjection : childProjection),
		539	// Its user has since raised the child to full access.
		540	getThreadShell: (threadId) => Effect.succeed(liveThreadShell(threadId)),
		541	dispatch: (command) =>
		542	Ref.update(dispatched, (commands) => [...commands, command]).pipe(
		543	Effect.andThen(
		544	command.type === "delegated_task.completion-delivery.dispose"
		545	? Effect.fail(new Error("simulated disposal failure") as never)
		546	: Effect.succeed({} as never),
		547	),
		548	),
		549	stopDelegatedTasks: () => Effect.void,
		550	}),
		551	Layer.mock(ProviderRegistry.ProviderRegistry)({ getProviders: Effect.succeed([]) }),
		552	Layer.mock(ProviderAdapterRegistry.ProviderAdapterRegistryV2)({
		553	list: () => Effect.succeed([]),
		554	}),
		555	Layer.mock(ProjectService.ProjectService)({}),
		556	Layer.mock(SecretRequests.SecretRequests)({}),
		557	Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
		558	);
		559	const scope: McpInvocationScope = {
		560	environmentId: EnvironmentId.make("environment:mcp-cancel-dispose-failed"),
		561	requestNamespace: "provider-session:mcp-cancel-dispose-failed",
		562	thread: {
		563	threadId: parentThreadId,
		564	providerSessionId: "provider-session:mcp-cancel-dispose-failed",
		565	providerInstanceId: ProviderInstanceId.make("codex"),
		566	},
		567	client: undefined,
		568	capabilities: new Set(["orchestration"]),
		569	issuedAt: 1,
		570	};
		571
		572	yield* Effect.gen(function* () {
		573	const service = yield* OrchestratorMcpService.OrchestratorMcpService;
		574	const error = yield* service
		575	.cancelTask(scope, { taskId, clientRequestId: "cancel-above-modes" })
		576	.pipe(Effect.flip);
		577	assert.equal(error.code, "runtime_mode_escalation_denied");
		578	assert.deepEqual(yield* Ref.get(dispatched), []);
		579	}).pipe(Effect.provide(OrchestratorMcpService.layer.pipe(Layer.provide(layerDependencies))));
		580	}),
		581	);
		582
		583	/**
		584	* A Supervised parent cancels its Supervised child, under which a task
		585	* now runs at full access. Reports what the cancel did.
		586	*/
		587	const cancelOverRaisedGrandchild = (child: {
		588	readonly deleted: boolean;
		589	/** The grandchild passes the check, and its user raises it before the stop reaches it. */
		590	readonly raisedDuringStop?: boolean;
		591	}) =>
		592	Effect.gen(function* () {
		593	const parentThreadId = ThreadId.make("thread:mcp-cancel-grandchild-parent");
		594	const childThreadId = ThreadId.make("thread:mcp-cancel-grandchild-child");
		595	const grandchildThreadId = ThreadId.make("thread:mcp-cancel-grandchild-grandchild");
		596	const taskId = NodeId.make("node:mcp-cancel-grandchild-task");
		597	const dispatched = yield* Ref.make<ReadonlyArray<unknown>>([]);
		598	const stoppedBelow = yield* Ref.make(false);
		599	const appOwnedTask = (id: string, threadId: ThreadId, childId: ThreadId) => ({
		600	id: NodeId.make(id),
		601	threadId,
		602	origin: "app_owned",
		603	childThreadId: childId,
		604	driver: "codex",
		605	model: "gpt-5.6-terra",
		606	result: null,
		607	completionDelivery: { state: "pending" },
		608	});
		609	// A Supervised parent delegated a Supervised child, which delegated a task of its own.
		610	const projections = new Map([
		611	[
		612	parentThreadId,
		613	{
		614	thread: {
		615	id: parentThreadId,
		616	runtimeMode: "approval-required",
		617	interactionMode: "default",
		618	},
		619	runs: [],
		620	contextTransfers: [],
		621	subagents: [appOwnedTask(taskId, parentThreadId, childThreadId)],
		622	},
		623	],
		624	[
		625	childThreadId,
		626	{
		627	thread: { id: childThreadId },
		628	runs: [{ id: RunId.make("run:mcp-cancel-grandchild-child"), status: "running" }],
		629	contextTransfers: [],
		630	messages: [],
		631	subagents: [
		632	appOwnedTask("node:mcp-cancel-grandchild-below", childThreadId, grandchildThreadId),
		633	],
		634	providerThreads: [],
		635	},
		636	],
		637	[
		638	grandchildThreadId,
		639	{
		640	thread: { id: grandchildThreadId },
		641	runs: [],
		642	contextTransfers: [],
		643	messages: [],
		644	subagents: [],
		645	providerThreads: [],
		646	},
		647	],
		648	]) as unknown as ReadonlyMap<ThreadId, OrchestrationV2ThreadProjection>;
		649	const layerDependencies = Layer.mergeAll(
		650	NodeServices.layer,
		651	Layer.mock(ThreadManagementService.ThreadManagementService)({
		652	getThreadRecords: (threadId) => Effect.succeed(projections.get(threadId)!),
		653	// The child still runs Supervised; its user has since raised the task under it
		654	// to full access.
		655	getThreadShell: (threadId) =>
		656	Effect.succeed(
		657	threadId === grandchildThreadId && child.raisedDuringStop !== true
		658	? liveThreadShell(threadId)
		659	: threadId === childThreadId && child.deleted
		660	? null
		661	: liveThreadShell(threadId, { runtimeMode: "approval-required" }),
		662	),
		663	dispatch: (command) =>
		664	Ref.update(dispatched, (commands) => [...commands, command]).pipe(
		665	Effect.as({} as never),
		666	),
		667	// Stands in for the orchestrator, which finds the grandchild raised
		668	// under its lock, when the stop runs under the parent's limit.
		669	stopDelegatedTasks: () =>
		670	Effect.gen(function* () {
		671	const limit = yield* DispatchModeLimit;
		672	if (child.raisedDuringStop === true && limit?.refused !== undefined) {
		673	const refusal: DispatchModeRefusal = {
		674	threadId: grandchildThreadId,
		675	mode: "runtime",
		676	runtimeMode: "full-access",
		677	interactionMode: "default",
		678	};
		679	yield* Ref.set(limit.refused, refusal);
		680	return yield* new OrchestratorThreadAboveModeLimitError({
		681	commandId: CommandId.make("stop-grandchild"),
		682	threadId: grandchildThreadId,
		683	mode: "runtime",
		684	runtimeMode: "full-access",
		685	interactionMode: "default",
		686	});
		687	}
		688	yield* Ref.set(stoppedBelow, true);
		689	}),
		690	}),
		691	Layer.mock(ProviderRegistry.ProviderRegistry)({ getProviders: Effect.succeed([]) }),
		692	Layer.mock(ProviderAdapterRegistry.ProviderAdapterRegistryV2)({
		693	list: () => Effect.succeed([]),
		694	}),
		695	Layer.mock(ProjectService.ProjectService)({}),
		696	Layer.mock(SecretRequests.SecretRequests)({}),
		697	Layer.mock(ScheduledTaskService.ScheduledTaskService)({}),
		698	);
		699	const scope: McpInvocationScope = {
		700	environmentId: EnvironmentId.make("environment:mcp-cancel-grandchild"),
		701	requestNamespace: "provider-session:mcp-cancel-grandchild",
		702	thread: {
		703	threadId: parentThreadId,
		704	providerSessionId: "provider-session:mcp-cancel-grandchild",
		705	providerInstanceId: ProviderInstanceId.make("codex"),
		706	},
		707	client: undefined,
		708	capabilities: new Set(["orchestration"]),
		709	issuedAt: 1,
		710	};
		711
		712	return yield* Effect.gen(function* () {
		713	const service = yield* OrchestratorMcpService.OrchestratorMcpService;
		714	const error = yield* service
		715	.cancelTask(scope, { taskId, clientRequestId: "cancel-grandchild-above-modes" })
		716	.pipe(Effect.flip);
		717	return {
		718	code: error.code,
		719	dispatched: yield* Ref.get(dispatched),
		720	stoppedBelow: yield* Ref.get(stoppedBelow),
		721	};
		722	}).pipe(Effect.provide(OrchestratorMcpService.layer.pipe(Layer.provide(layerDependencies))));
		723	});
		724
		725	it.effect("refuses to cancel a task when a task under it now runs above the parent's modes", () =>
		726	Effect.gen(function* () {
		727	assert.deepEqual(yield* cancelOverRaisedGrandchild({ deleted: false }), {
		728	code: "runtime_mode_escalation_denied",
		729	dispatched: [],
		730	stoppedBelow: false,
		731	});
		732	}),
		733	);
		734
		735	it.effect("reports a task under the child that its user raises while it is being stopped", () =>
		736	Effect.gen(function* () {
		737	const outcome = yield* cancelOverRaisedGrandchild({ deleted: false, raisedDuringStop: true });
		738	assert.equal(outcome.code, "runtime_mode_escalation_denied");
		739	assert.isFalse(outcome.stoppedBelow);
		740	}),
		741	);
		742
		743	it.effect("checks the tasks under a deleted child before cancelling it", () =>
		744	Effect.gen(function* () {
		745	assert.deepEqual(yield* cancelOverRaisedGrandchild({ deleted: true }), {
		746	code: "runtime_mode_escalation_denied",
		747	dispatched: [],
		748	stoppedBelow: false,
		749	});
		750	}),
		751	);
482	});	752	});
483		753
484	describe("OrchestratorMcpService provider resolution", () => {	754	describe("OrchestratorMcpService provider resolution", () => {
...	@@ -1294,4 +1564,227 @@ describe("OrchestratorMcpService provider resolution", () => {	...	@@ -1294,4 +1564,227 @@ describe("OrchestratorMcpService provider resolution", () => {
1294	}	1564	}
1295	}),	1565	}),
1296	);	1566	);
		1567
		1568	describe("scheduled tasks at modes above the caller's", () => {
		1569	const projectId = ProjectId.make("project:scheduled");
		1570	const boundThreadId = ThreadId.make("thread:scheduled-bound");
		1571	const task = (overrides: Partial<ScheduledTask>): ScheduledTask => ({
		1572	id: ScheduledTaskId.make("scheduled-task:webhook"),
		1573	title: "On push",
		1574	prompt: "Do {{body.instruction}}",
		1575	enabled: true,
		1576	schedule: { type: "webhook", signature: null },
		1577	projectId,
		1578	threadId: null,
		1579	workspaceStrategy: { type: "root" },
		1580	modelSelection: { instanceId: ProviderInstanceId.make("codex"), model: "gpt-5" },
		1581	runtimeMode: "approval-required",
		1582	interactionMode: "default",
		1583	createdBy: "agent",
		1584	creationSource: "mcp",
		1585	createdAt: "2026-10-05T00:00:00.000Z",
		1586	updatedAt: "2026-10-05T00:00:00.000Z",
		1587	nextRunAt: null,
		1588	lastRunAt: null,
		1589	lastRunStatus: "never",
		1590	lastRunError: null,
		1591	runCount: 0,
		1592	webhook: {
		1593	path: "/hooks/scheduled-task/secret",
		1594	url: "https://t3.example/hooks/secret",
		1595	hasSecret: false,
		1596	},
		1597	...overrides,
		1598	});
		1599	const supervisedClient: McpInvocationScope = {
		1600	environmentId: EnvironmentId.make("environment:scheduled"),
		1601	requestNamespace: "client:scheduled",
		1602	thread: undefined,
		1603	client: {
		1604	sessionId: "scheduled",
		1605	label: "Claude Code",
		1606	runtimeModeCeiling: "approval-required",
		1607	},
		1608	capabilities: new Set(["orchestration"]),
		1609	issuedAt: 1,
		1610	};
		1611	const service = (
		1612	tasks: ReadonlyArray<ScheduledTask>,
		1613	boundThread: OrchestrationV2ThreadShell \| null,
		1614	upserted: Ref.Ref<number>,
		1615	) =>
		1616	OrchestratorMcpService.layer.pipe(
		1617	Layer.provide(
		1618	Layer.mergeAll(
		1619	NodeServices.layer,
		1620	Layer.mock(ThreadManagementService.ThreadManagementService)({
		1621	getThreadShell: (threadId) =>
		1622	Effect.succeed(threadId === boundThreadId ? boundThread : null),
		1623	}),
		1624	Layer.mock(ProviderRegistry.ProviderRegistry)({ getProviders: Effect.succeed([]) }),
		1625	Layer.mock(ProviderAdapterRegistry.ProviderAdapterRegistryV2)({
		1626	list: () => Effect.succeed([]),
		1627	}),
		1628	Layer.mock(ProjectService.ProjectService)({}),
		1629	Layer.mock(SecretRequests.SecretRequests)({}),
		1630	Layer.mock(ScheduledTaskService.ScheduledTaskService)({
		1631	list: () => Effect.succeed({ tasks }),
		1632	upsert: () =>
		1633	Ref.update(upserted, (count) => count + 1).pipe(Effect.as({ task: tasks[0]! })),
		1634	}),
		1635	),
		1636	),
		1637	);
		1638
		1639	it.effect("hides a webhook URL from a caller below the task's modes", () =>
		1640	Effect.gen(function* () {
		1641	const upserted = yield* Ref.make(0);
		1642	const listed = yield* OrchestratorMcpService.OrchestratorMcpService.pipe(
		1643	Effect.flatMap((mcp) => mcp.listScheduledTasks(supervisedClient, { projectId })),
		1644	Effect.provide(
		1645	service(
		1646	[
		1647	task({ runtimeMode: "full-access" }),
		1648	task({ id: ScheduledTaskId.make("scheduled-task:supervised") }),
		1649	],
		1650	null,
		1651	upserted,
		1652	),
		1653	),
		1654	);
		1655	assert.deepEqual(
		1656	listed.tasks.map((summary) => summary.webhookUrl),
		1657	[undefined, "https://t3.example/hooks/secret"],
		1658	);
		1659	}),
		1660	);
		1661
		1662	it.effect("hides a webhook URL from a thread whose turn has ended", () =>
		1663	Effect.gen(function* () {
		1664	const callerId = ThreadId.make("thread:scheduled-ended");
		1665	const shell = liveThreadShell(callerId, { activeRunId: null });
		1666	const listed = yield* OrchestratorMcpService.OrchestratorMcpService.pipe(
		1667	Effect.flatMap((mcp) =>
		1668	mcp.listScheduledTasks(
		1669	{
		1670	...supervisedClient,
		1671	requestNamespace: "provider:scheduled-ended",
		1672	thread: {
		1673	threadId: callerId,
		1674	providerSessionId: "provider:scheduled-ended",
		1675	providerInstanceId: shell.providerInstanceId,
		1676	},
		1677	client: undefined,
		1678	},
		1679	{ projectId },
		1680	),
		1681	),
		1682	Effect.provide(
		1683	OrchestratorMcpService.layer.pipe(
		1684	Layer.provide(
		1685	Layer.mergeAll(
		1686	NodeServices.layer,
		1687	Layer.mock(ThreadManagementService.ThreadManagementService)({
		1688	getThreadShell: () => Effect.succeed(null),
		1689	// Its turn ended: no run is active.
		1690	getThreadRecords: () => Effect.succeed(idleThreadProjection(shell)),
		1691	}),
		1692	Layer.mock(ProviderRegistry.ProviderRegistry)({
		1693	getProviders: Effect.succeed([]),
		1694	}),
		1695	Layer.mock(ProviderAdapterRegistry.ProviderAdapterRegistryV2)({
		1696	list: () => Effect.succeed([]),
		1697	}),
		1698	Layer.mock(ProjectService.ProjectService)({}),
		1699	Layer.mock(SecretRequests.SecretRequests)({}),
		1700	Layer.mock(ScheduledTaskService.ScheduledTaskService)({
		1701	list: () => Effect.succeed({ tasks: [task({})] }),
		1702	}),
		1703	),
		1704	),
		1705	),
		1706	),
		1707	);
		1708	assert.equal(listed.tasks[0]?.webhookUrl, undefined);
		1709	}),
		1710	);
		1711
		1712	it.effect("checks a bound task against its thread's current modes", () =>
		1713	Effect.gen(function* () {
		1714	const upserted = yield* Ref.make(0);
		1715	// Scheduled while the thread was Supervised; the thread now runs in full access.
		1716	const bound = task({ threadId: boundThreadId });
		1717	const layer = service(
		1718	[bound],
		1719	liveThreadShell(boundThreadId, { runtimeMode: "full-access" }),
		1720	upserted,
		1721	);
		1722	const mcp = yield* OrchestratorMcpService.OrchestratorMcpService.pipe(
		1723	Effect.provide(layer),
		1724	);
		1725	const listed = yield* mcp.listScheduledTasks(supervisedClient, { projectId });
		1726	assert.equal(listed.tasks[0]?.webhookUrl, undefined);
		1727	const error = yield* mcp
		1728	.updateScheduledTask(supervisedClient, {
		1729	scheduledTaskId: bound.id,
		1730	prompt: "Something else",
		1731	})
		1732	.pipe(Effect.flip);
		1733	assert.equal(error.code, "runtime_mode_escalation_denied");
		1734	assert.equal(yield* Ref.get(upserted), 0);
		1735	}),
		1736	);
		1737
		1738	it.effect("reports a saved task even when its bound thread cannot be read", () =>
		1739	Effect.gen(function* () {
		1740	const upserted = yield* Ref.make(0);
		1741	const bound = task({ threadId: boundThreadId });
		1742	const lookups = yield* Ref.make(0);
		1743	// The edit's own check reads the thread; the read after the save fails.
		1744	const mcp = yield* OrchestratorMcpService.OrchestratorMcpService.pipe(
		1745	Effect.provide(
		1746	OrchestratorMcpService.layer.pipe(
		1747	Layer.provide(
		1748	Layer.mergeAll(
		1749	NodeServices.layer,
		1750	Layer.mock(ThreadManagementService.ThreadManagementService)({
		1751	getThreadShell: (threadId) =>
		1752	Ref.getAndUpdate(lookups, (count) => count + 1).pipe(
		1753	Effect.flatMap((count) =>
		1754	count === 0
		1755	? Effect.succeed(
		1756	liveThreadShell(threadId, { runtimeMode: "approval-required" }),
		1757	)
		1758	: Effect.fail(new OrchestratorProjectionError({ threadId })),
		1759	),
		1760	),
		1761	}),
		1762	Layer.mock(ProviderRegistry.ProviderRegistry)({
		1763	getProviders: Effect.succeed([]),
		1764	}),
		1765	Layer.mock(ProviderAdapterRegistry.ProviderAdapterRegistryV2)({
		1766	list: () => Effect.succeed([]),
		1767	}),
		1768	Layer.mock(ProjectService.ProjectService)({}),
		1769	Layer.mock(SecretRequests.SecretRequests)({}),
		1770	Layer.mock(ScheduledTaskService.ScheduledTaskService)({
		1771	list: () => Effect.succeed({ tasks: [bound] }),
		1772	upsert: () =>
		1773	Ref.update(upserted, (count) => count + 1).pipe(Effect.as({ task: bound })),
		1774	}),
		1775	),
		1776	),
		1777	),
		1778	),
		1779	);
		1780	const updated = yield* mcp.updateScheduledTask(supervisedClient, {
		1781	scheduledTaskId: bound.id,
		1782	prompt: "Something else",
		1783	});
		1784	assert.equal(yield* Ref.get(upserted), 1);
		1785	assert.equal(updated.scheduledTaskId, bound.id);
		1786	assert.equal(updated.webhookUrl, undefined);
		1787	}),
		1788	);
		1789	});
1297	});	1790	});

apps/server/src/mcp/OrchestratorMcpService.ts+134-15

...	@@ -66,6 +66,7 @@ import * as Effect from "effect/Effect";	...	@@ -66,6 +66,7 @@ import * as Effect from "effect/Effect";
66	import * as Exit from "effect/Exit";	66	import * as Exit from "effect/Exit";
67	import * as Layer from "effect/Layer";	67	import * as Layer from "effect/Layer";
68	import * as Option from "effect/Option";	68	import * as Option from "effect/Option";
		69	import * as Ref from "effect/Ref";
69	import * as Schema from "effect/Schema";	70	import * as Schema from "effect/Schema";
70	import * as Stream from "effect/Stream";	71	import * as Stream from "effect/Stream";
71		72
...	@@ -74,6 +75,10 @@ import {	...	@@ -74,6 +75,10 @@ import {
74	subagentResultForRun,	75	subagentResultForRun,
75	delegatedTaskProgress,	76	delegatedTaskProgress,
76	} from "../orchestration-v2/SubagentProjection.ts";	77	} from "../orchestration-v2/SubagentProjection.ts";
		78	import {
		79	DispatchModeLimit,
		80	type DispatchModeRefusal,
		81	} from "../orchestration-v2/DispatchModeLimit.ts";
77	import * as ThreadManagementService from "../orchestration-v2/ThreadManagementService.ts";	82	import * as ThreadManagementService from "../orchestration-v2/ThreadManagementService.ts";
78	import * as ProjectService from "../project/ProjectService.ts";	83	import * as ProjectService from "../project/ProjectService.ts";
79	import * as ProviderRegistry from "../provider/ProviderRegistry.ts";	84	import * as ProviderRegistry from "../provider/ProviderRegistry.ts";
...	@@ -225,7 +230,12 @@ function scheduledTaskWorkspaceStrategy(	...	@@ -225,7 +230,12 @@ function scheduledTaskWorkspaceStrategy(
225	: { type: "worktree", baseRef: "main", startFromOrigin: true };	230	: { type: "worktree", baseRef: "main", startFromOrigin: true };
226	}	231	}
227		232
228	function scheduledTaskSummary(task: ScheduledTask): OrchestratorMcpScheduledTask {	233	/**
		234	* A scheduled task as an agent sees it. `mayRun` says whether the caller may
		235	* run it: a webhook's URL carries the secret that starts the task's runs, so
		236	* only such a caller sees it.
		237	*/
		238	function scheduledTaskSummary(task: ScheduledTask, mayRun: boolean): OrchestratorMcpScheduledTask {
229	return {	239	return {
230	scheduledTaskId: task.id,	240	scheduledTaskId: task.id,
231	title: task.title,	241	title: task.title,
...	@@ -237,7 +247,7 @@ function scheduledTaskSummary(task: ScheduledTask): OrchestratorMcpScheduledTask	...	@@ -237,7 +247,7 @@ function scheduledTaskSummary(task: ScheduledTask): OrchestratorMcpScheduledTask
237	nextRunAt: task.nextRunAt,	247	nextRunAt: task.nextRunAt,
238	lastRunStatus: task.lastRunStatus,	248	lastRunStatus: task.lastRunStatus,
239	// A bare path is not a URL anyone can call, so agents never get one to share.	249	// A bare path is not a URL anyone can call, so agents never get one to share.
240	...(task.webhook?.url == null ? {} : { webhookUrl: task.webhook.url }),	250	...(task.webhook?.url == null \|\| !mayRun ? {} : { webhookUrl: task.webhook.url }),
241	...(task.webhook === undefined	251	...(task.webhook === undefined
242	? {}	252	? {}
243	: { webhookSignature: task.webhook.hasSecret ? "set" : "none" }),	253	: { webhookSignature: task.webhook.hasSecret ? "set" : "none" }),
...	@@ -1364,9 +1374,65 @@ const make = Effect.gen(function* () {	...	@@ -1364,9 +1374,65 @@ const make = Effect.gen(function* () {
1364	}).pipe(Effect.timeoutOption(Duration.millis(timeoutMs)), Effect.map(Option.flatten));	1374	}).pipe(Effect.timeoutOption(Duration.millis(timeoutMs)), Effect.map(Option.flatten));
1365		1375
1366	/**	1376	/**
1367	* A scheduled task the caller may change: one whose modes are no broader	1377	* The modes a task's runs execute at: its own, or for a task bound to a
1368	* than the caller's own, so editing its prompt cannot run work above the	1378	* thread, also that thread's modes as they are now, since its runs are
1369	* caller's limits.	1379	* messages to that thread.
		1380	*/
		1381	const scheduledTaskRunModes = (task: ScheduledTask) =>
		1382	Effect.gen(function* () {
		1383	const modes = [{ runtimeMode: task.runtimeMode, interactionMode: task.interactionMode }];
		1384	if (task.threadId === null) return modes;
		1385	const bound = yield* threadManagement
		1386	.getThreadShell(task.threadId)
		1387	.pipe(Effect.mapError(threadManagementFailure));
		1388	return bound === null \|\| bound.deletedAt !== null ? modes : [...modes, bound];
		1389	});
		1390
		1391	const withinLimits = (
		1392	limits: {
		1393	readonly runtimeMode: RuntimeMode;
		1394	readonly interactionMode: ProviderInteractionMode;
		1395	},
		1396	modes: { readonly runtimeMode: RuntimeMode; readonly interactionMode: ProviderInteractionMode },
		1397	) =>
		1398	runtimeModeRank(modes.runtimeMode) <= runtimeModeRank(limits.runtimeMode) &&
		1399	interactionModeRank(modes.interactionMode) <= interactionModeRank(limits.interactionMode);
		1400
		1401	/**
		1402	* A task as the caller may see it. Its webhook URL starts runs, so only a
		1403	* caller that may start one sees it: a thread caller with a live turn, at
		1404	* modes covering every mode the task runs at.
		1405	*/
		1406	const summarizeScheduledTask = (
		1407	scope: McpInvocationScope,
		1408	caller: {
		1409	readonly parent: Pick<OrchestrationV2ThreadProjection, "thread" \| "runs"> \| undefined;
		1410	readonly limits: {
		1411	readonly runtimeMode: RuntimeMode;
		1412	readonly interactionMode: ProviderInteractionMode;
		1413	};
		1414	},
		1415	task: ScheduledTask,
		1416	) =>
		1417	Effect.gen(function* () {
		1418	const live =
		1419	caller.parent === undefined \|\|
		1420	Exit.isSuccess(yield* Effect.exit(assertLiveCaller(scope, caller.parent)));
		1421	// This runs after a save, so a failed lookup of the bound thread hides
		1422	// the webhook URL instead of reporting a saved task as an error.
		1423	const modes = yield* scheduledTaskRunModes(task).pipe(Effect.option);
		1424	return scheduledTaskSummary(
		1425	task,
		1426	live &&
		1427	Option.isSome(modes) &&
		1428	modes.value.every((mode) => withinLimits(caller.limits, mode)),
		1429	);
		1430	});
		1431
		1432	/**
		1433	* A scheduled task the caller may change: one whose runs execute at modes no
		1434	* broader than the caller's own, so editing its prompt cannot run work above
		1435	* the caller's limits.
1370	*/	1436	*/
1371	const loadScheduledTask = (	1437	const loadScheduledTask = (
1372	scheduledTaskId: ScheduledTask["id"],	1438	scheduledTaskId: ScheduledTask["id"],
...	@@ -1387,8 +1453,10 @@ const make = Effect.gen(function* () {	...	@@ -1387,8 +1453,10 @@ const make = Effect.gen(function* () {
1387	if (task === undefined) {	1453	if (task === undefined) {
1388	return yield* failure("task_not_found", `Scheduled task ${scheduledTaskId} was not found.`);	1454	return yield* failure("task_not_found", `Scheduled task ${scheduledTaskId} was not found.`);
1389	}	1455	}
1390	yield* resolveRuntimeMode(limits.runtimeMode, task.runtimeMode);	1456	for (const modes of yield* scheduledTaskRunModes(task)) {
1391	yield* resolveInteractionMode(limits.interactionMode, task.interactionMode);	1457	yield* resolveRuntimeMode(limits.runtimeMode, modes.runtimeMode);
		1458	yield* resolveInteractionMode(limits.interactionMode, modes.interactionMode);
		1459	}
1392	return task;	1460	return task;
1393	});	1461	});
1394		1462
...	@@ -1451,11 +1519,11 @@ const make = Effect.gen(function* () {	...	@@ -1451,11 +1519,11 @@ const make = Effect.gen(function* () {
1451	failure("orchestration_error", `Could not schedule task: ${error.message}`),	1519	failure("orchestration_error", `Could not schedule task: ${error.message}`),
1452	),	1520	),
1453	);	1521	);
1454	return scheduledTaskSummary(task);	1522	return yield* summarizeScheduledTask(scope, { parent, limits }, task);
1455	}),	1523	}),
1456	listScheduledTasks: (scope, input) =>	1524	listScheduledTasks: (scope, input) =>
1457	Effect.gen(function* () {	1525	Effect.gen(function* () {
1458	const { parent } = yield* loadCaller(scope);	1526	const { parent, limits } = yield* loadCaller(scope);
1459	const projectId = input.projectId ?? parent?.thread.projectId;	1527	const projectId = input.projectId ?? parent?.thread.projectId;
1460	const { tasks } = yield* scheduledTasks	1528	const { tasks } = yield* scheduledTasks
1461	.list()	1529	.list()
...	@@ -1465,9 +1533,10 @@ const make = Effect.gen(function* () {	...	@@ -1465,9 +1533,10 @@ const make = Effect.gen(function* () {
1465	),	1533	),
1466	);	1534	);
1467	return {	1535	return {
1468	tasks: tasks	1536	tasks: yield* Effect.forEach(
1469	.filter((task) => projectId === undefined \|\| task.projectId === projectId)	1537	tasks.filter((task) => projectId === undefined \|\| task.projectId === projectId),
1470	.map(scheduledTaskSummary),	1538	(task) => summarizeScheduledTask(scope, { parent, limits }, task),
		1539	),
1471	};	1540	};
1472	}),	1541	}),
1473	updateScheduledTask: (scope, input) =>	1542	updateScheduledTask: (scope, input) =>
...	@@ -1521,7 +1590,7 @@ const make = Effect.gen(function* () {	...	@@ -1521,7 +1590,7 @@ const make = Effect.gen(function* () {
1521	failure("orchestration_error", `Could not update scheduled task: ${error.message}`),	1590	failure("orchestration_error", `Could not update scheduled task: ${error.message}`),
1522	),	1591	),
1523	);	1592	);
1524	return scheduledTaskSummary(task);	1593	return yield* summarizeScheduledTask(scope, { parent, limits }, task);
1525	}),	1594	}),
1526	deleteScheduledTask: (scope, input) =>	1595	deleteScheduledTask: (scope, input) =>
1527	Effect.gen(function* () {	1596	Effect.gen(function* () {
...	@@ -1851,6 +1920,32 @@ const make = Effect.gen(function* () {	...	@@ -1851,6 +1920,32 @@ const make = Effect.gen(function* () {
1851	const current = yield* readTask(scope, input.taskId);	1920	const current = yield* readTask(scope, input.taskId);
1852	const key = yield* requestKey(input.clientRequestId);	1921	const key = yield* requestKey(input.clientRequestId);
1853	const parentProjection = yield* loadProjection(scope.thread.threadId);	1922	const parentProjection = yield* loadProjection(scope.thread.threadId);
		1923	// Cancelling stops the child and every task under it, each a write to a
		1924	// thread its user may have raised above the parent's modes since it was
		1925	// delegated. All of them are checked before anything is stopped.
		1926	const assertStoppable = (threadId: ThreadId): Effect.Effect<void, OrchestratorMcpFailure> =>
		1927	Effect.gen(function* () {
		1928	const shell = yield* threadManagement
		1929	.getThreadShell(threadId)
		1930	.pipe(Effect.mapError(threadManagementFailure));
		1931	// A deleted thread takes no stop, but the tasks under it still do.
		1932	if (shell !== null && shell.deletedAt === null) {
		1933	yield* resolveRuntimeMode(parentProjection.thread.runtimeMode, shell.runtimeMode);
		1934	yield* resolveInteractionMode(
		1935	parentProjection.thread.interactionMode,
		1936	shell.interactionMode,
		1937	);
		1938	}
		1939	const { subagents } = yield* threadManagement
		1940	.getThreadRecords(threadId, ["subagents"])
		1941	.pipe(Effect.mapError(threadManagementFailure));
		1942	for (const task of subagents) {
		1943	if (task.origin === "app_owned" && task.childThreadId !== null) {
		1944	yield* assertStoppable(task.childThreadId);
		1945	}
		1946	}
		1947	});
		1948	yield* assertStoppable(current.childThreadId);
1854	const parentTask = parentProjection.subagents.find(	1949	const parentTask = parentProjection.subagents.find(
1855	(task) => task.id === input.taskId && task.origin === "app_owned",	1950	(task) => task.id === input.taskId && task.origin === "app_owned",
1856	);	1951	);
...	@@ -1910,8 +2005,32 @@ const make = Effect.gen(function* () {	...	@@ -1910,8 +2005,32 @@ const make = Effect.gen(function* () {
1910	),	2005	),
1911	);	2006	);
1912	});	2007	});
		2008	// Checked above; a user raising one of these threads meanwhile is
		2009	// caught again under that thread's lock, which leaves it running.
		2010	const refused = yield* Ref.make<DispatchModeRefusal \| undefined>(undefined);
		2011	const stopWithinLimit = stopChild.pipe(
		2012	Effect.provideService(DispatchModeLimit, {
		2013	runtimeMode: parentProjection.thread.runtimeMode,
		2014	interactionMode: parentProjection.thread.interactionMode,
		2015	refused,
		2016	}),
		2017	Effect.catch((error) =>
		2018	Effect.flatMap(Ref.get(refused), (refusal) =>
		2019	Effect.fail(
		2020	refusal === undefined
		2021	? error
		2022	: failure(
		2023	refusal.mode === "runtime"
		2024	? "runtime_mode_escalation_denied"
		2025	: "interaction_mode_escalation_denied",
		2026	`Thread ${refusal.threadId} now runs in ${refusal.runtimeMode}/${refusal.interactionMode} mode, above this thread's; its user changed it while the task was being cancelled.`,
		2027	),
		2028	),
		2029	),
		2030	),
		2031	);
1913	if (isTerminalTaskStatus(current.status)) {	2032	if (isTerminalTaskStatus(current.status)) {
1914	yield* stopChild;	2033	yield* stopWithinLimit;
1915	yield* disposeCompletionDelivery;	2034	yield* disposeCompletionDelivery;
1916	return {	2035	return {
1917	taskId: input.taskId,	2036	taskId: input.taskId,
...	@@ -1930,7 +2049,7 @@ const make = Effect.gen(function* () {	...	@@ -1930,7 +2049,7 @@ const make = Effect.gen(function* () {
1930	`Delegated task ${input.taskId} has no interruptible child run.`,	2049	`Delegated task ${input.taskId} has no interruptible child run.`,
1931	);	2050	);
1932	}	2051	}
1933	yield* stopChild;	2052	yield* stopWithinLimit;
1934	yield* disposeCompletionDelivery.pipe(	2053	yield* disposeCompletionDelivery.pipe(
1935	Effect.catchCause((cause) =>	2054	Effect.catchCause((cause) =>
1936	Effect.logWarning("orchestrator-mcp.cancel-task.delivery-dispose-failed", {	2055	Effect.logWarning("orchestrator-mcp.cancel-task.delivery-dispose-failed", {

apps/server/src/mcp/ThreadMetadataMcpService.test.ts-88

...	@@ -78,91 +78,3 @@ it.effect("keeps calling-thread storage failures as orchestration errors", () =>	...	@@ -78,91 +78,3 @@ it.effect("keeps calling-thread storage failures as orchestration errors", () =>
78	expect(error.code).toBe("orchestration_error");	78	expect(error.code).toBe("orchestration_error");
79	}),	79	}),
80	);	80	);
81
82	it.effect("refuses to change a thread that runs above the caller's modes", () =>
83	Effect.gen(function* () {
84	const fullAccessThread = ThreadId.make("thread:metadata-full-access");
85	const shells = new Map([
86	[
87	threadId,
88	{
89	id: threadId,
90	projectId: "project",
91	runtimeMode: "auto",
92	interactionMode: "default",
93	activeRunId: "run-live",
94	archivedAt: null,
95	providerInstanceId: "codex",
96	deletedAt: null,
97	},
98	],
99	[
100	fullAccessThread,
101	{
102	id: fullAccessThread,
103	projectId: "project",
104	runtimeMode: "full-access",
105	interactionMode: "default",
106	deletedAt: null,
107	},
108	],
109	]);
110	const error = yield* Effect.gen(function* () {
111	const service = yield* ThreadMetadataMcp.ThreadMetadataMcpService;
112	return yield* service.update(scope, {
113	threadId: fullAccessThread,
114	action: "rename",
115	title: "Renamed from a narrower thread",
116	});
117	}).pipe(
118	Effect.provide(layerService((id) => Effect.succeed((shells.get(id) ?? null) as never))),
119	Effect.flip,
120	);
121
122	expect(error.code).toBe("runtime_mode_escalation_denied");
123	}),
124	);
125
126	it.effect("refuses another thread's metadata to a thread caller whose run has ended", () =>
127	Effect.gen(function* () {
128	const otherThread = ThreadId.make("thread:metadata-other");
129	const shells = new Map([
130	[
131	threadId,
132	{
133	id: threadId,
134	projectId: "project",
135	runtimeMode: "full-access",
136	interactionMode: "default",
137	activeRunId: null,
138	archivedAt: null,
139	providerInstanceId: "codex",
140	deletedAt: null,
141	},
142	],
143	[
144	otherThread,
145	{
146	id: otherThread,
147	projectId: "project",
148	runtimeMode: "approval-required",
149	interactionMode: "default",
150	deletedAt: null,
151	},
152	],
153	]);
154	const error = yield* Effect.gen(function* () {
155	const service = yield* ThreadMetadataMcp.ThreadMetadataMcpService;
156	return yield* service.update(scope, {
157	threadId: otherThread,
158	action: "rename",
159	title: "Renamed after the run ended",
160	});
161	}).pipe(
162	Effect.provide(layerService((id) => Effect.succeed((shells.get(id) ?? null) as never))),
163	Effect.flip,
164	);
165
166	expect(error.code).toBe("parent_not_active");
167	}),
168	);

apps/server/src/mcp/ThreadMetadataMcpService.ts-37

...	@@ -16,7 +16,6 @@ import * as Layer from "effect/Layer";	...	@@ -16,7 +16,6 @@ import * as Layer from "effect/Layer";
16		16
17	import * as ThreadManagementService from "../orchestration-v2/ThreadManagementService.ts";	17	import * as ThreadManagementService from "../orchestration-v2/ThreadManagementService.ts";
18	import type { McpInvocationScope } from "./McpInvocationContext.ts";	18	import type { McpInvocationScope } from "./McpInvocationContext.ts";
19	import { assertTargetWithinLimits } from "./threadAccess.ts";
20		19
21	export class ThreadMetadataMcpService extends Context.Service<	20	export class ThreadMetadataMcpService extends Context.Service<
22	ThreadMetadataMcpService,	21	ThreadMetadataMcpService,
...	@@ -167,42 +166,6 @@ const make = Effect.gen(function* () {	...	@@ -167,42 +166,6 @@ const make = Effect.gen(function* () {
167	if (shell === null \|\| shell.deletedAt !== null) {	166	if (shell === null \|\| shell.deletedAt !== null) {
168	return yield* failure("thread_not_found", `Thread ${threadId} was not found.`);	167	return yield* failure("thread_not_found", `Thread ${threadId} was not found.`);
169	}	168	}
170	// Another thread may only be changed if it runs within the caller's own modes.
171	if (threadId !== scope.thread?.threadId) {
172	const limits =
173	scope.thread === undefined
174	? {
175	runtimeMode: scope.client?.runtimeModeCeiling ?? ("approval-required" as const),
176	interactionMode: "default" as const,
177	}
178	: yield* threadManagement.getThreadShell(scope.thread.threadId).pipe(
179	Effect.mapError((error) =>
180	failure(
181	"orchestration_error",
182	`Unable to locate calling thread: ${errorMessage(error)}`,
183	),
184	),
185	Effect.flatMap((caller) =>
186	caller === null
187	? Effect.fail(failure("thread_not_found", "The calling thread was not found."))
188	: // Like every other cross-thread write, a thread caller needs its live run.
189	caller.archivedAt !== null \|\|
190	caller.activeRunId === null \|\|
191	caller.providerInstanceId !== scope.thread?.providerInstanceId
192	? Effect.fail(
193	failure(
194	"parent_not_active",
195	"The calling provider no longer owns an active thread run.",
196	),
197	)
198	: Effect.succeed({
199	runtimeMode: caller.runtimeMode,
200	interactionMode: caller.interactionMode,
201	}),
202	),
203	);
204	yield* assertTargetWithinLimits(limits, shell);
205	}
206	const target = yield* threadManagement	169	const target = yield* threadManagement
207	.getProjectThreadRecords({ projectId: shell.projectId, threadId }, [])	170	.getProjectThreadRecords({ projectId: shell.projectId, threadId }, [])
208	.pipe(Effect.mapError(threadLookupFailure));	171	.pipe(Effect.mapError(threadLookupFailure));

apps/server/src/mcp/threadAccess.ts+22-37

 @@ -60,6 +60,15 @@ export const readCaller = Effect.fn("mcp.readCaller")(function* () {
       message: "This credential cannot control threads.",
     });
   }
+  return yield* loadCaller();
+});
+/**
+ * The caller and its limits, whichever tools its credential grants. Tools
+ * check their own capability; `McpToolAccess` uses this for every tool.
+ */
+export const loadCaller = Effect.fn("mcp.loadCaller")(function* () {
+  const scope = yield* McpInvocationContext.McpInvocationContext;
   const threads = yield* ThreadManagement.ThreadManagementService;
   if (scope.thread === undefined) {
     return {
 @@ -104,7 +113,12 @@ export const assertTargetWithinLimits = (
     Effect.asVoid,
   );
-function assertLiveCaller({ caller, scope }: Caller) {
+/**
+ * A thread caller acts only while it owns a live run of a thread that is not
+ * archived, so a provider token that outlived its session cannot act. An
+ * OAuth client has no run; its session and ceiling are its authority.
+ */
+export function assertLiveCaller({ caller, scope }: Caller) {
   if (caller === undefined) return Effect.void;
   return caller.archivedAt !== null ||
     caller.activeRunId === null ||
 @@ -119,34 +133,14 @@ function assertLiveCaller({ caller, scope }: Caller) {
 }
 /**
- * Mutations from a thread need that thread's live run, so an agent whose turn
+ * Actions that change the environment itself (projects, preferences) need full
- * ended cannot keep acting. An OAuth client has no run; its session and
+ * access: a thread caller in full-access/default mode, or a client approved
- * ceiling are its authority.
+ * with a full-access ceiling.
- */
-export const readMutationCaller = Effect.fn("mcp.readMutationCaller")(function* () {
-  const context = yield* readCaller();
-  yield* assertLiveCaller(context);
-  return context;
-});
-/**
- * Actions that change the environment itself (projects, preferences, launching
- * outside a project) need full access: a thread caller in full-access/default
- * mode, or a client approved with a full-access ceiling.
  */
-export const readFullAccessCaller = Effect.fn("mcp.readFullAccessCaller")(function* (
+export const assertFullAccess = (context: Caller, message: string) =>
-  message: string,
+  context.limits.runtimeMode === "full-access" && context.limits.interactionMode === "default"
-) {
+    ? Effect.void
-  const context = yield* readMutationCaller();
+    : Effect.fail(new OrchestratorMcpFailure({ code: "capability_denied", message }));
-  if (
-    (context.caller !== undefined && context.caller.archivedAt !== null) ||
-    context.limits.runtimeMode !== "full-access" ||
-    context.limits.interactionMode !== "default"
-  ) {
-    return yield* new OrchestratorMcpFailure({ code: "capability_denied", message });
-  }
-  return context;
-});
 /** A target project: the one passed, else the calling thread's. */
 export const resolveProjectId = (context: Caller, projectId: ProjectId | undefined) =>
 @@ -204,15 +198,6 @@ export const readThread = Effect.fn("mcp.readThread")(function* <
   return { ...context, projection };
 });
-export const readWritableThread = Effect.fn("mcp.readWritableThread")(function* <
-  K extends ProjectionRecordField = never,
->(threadId?: ThreadId, fields: ReadonlyArray<K> = []) {
-  const context = yield* readThread(threadId, fields);
-  yield* assertLiveCaller(context);
-  yield* assertTargetWithinLimits(context.limits, context.projection.thread);
-  return context;
-});
 export const newCommandId = Effect.fn("mcp.newCommandId")(function* () {
   const crypto = yield* Crypto.Crypto;
   return CommandId.make(`mcp:${yield* crypto.randomUUIDv4.pipe(Effect.orDie)}`);

apps/server/src/mcp/toolkits/attachment/handlers.ts+51-59

...	@@ -3,12 +3,8 @@ import * as Effect from "effect/Effect";	...	@@ -3,12 +3,8 @@ import * as Effect from "effect/Effect";
3	import * as Upload from "../../../assets/AttachmentUpload.ts";	3	import * as Upload from "../../../assets/AttachmentUpload.ts";
4	import * as Claims from "../../../orchestration-v2/AttachmentClaims.ts";	4	import * as Claims from "../../../orchestration-v2/AttachmentClaims.ts";
5	import * as ThreadMessageIntake from "../../../orchestration-v2/ThreadMessageIntake.ts";	5	import * as ThreadMessageIntake from "../../../orchestration-v2/ThreadMessageIntake.ts";
6	import {	6	import * as McpToolAccess from "../../McpToolAccess.ts";
7	newCommandId,	7	import { newCommandId, readThread, unavailable } from "../../threadAccess.ts";
8	readMutationCaller,
9	readWritableThread,
10	unavailable,
11	} from "../../threadAccess.ts";
12	import { AttachmentToolkit } from "./tools.ts";	8	import { AttachmentToolkit } from "./tools.ts";
13		9
14	export function resolveAttachmentReferences(	10	export function resolveAttachmentReferences(
...	@@ -31,57 +27,53 @@ export function resolveAttachmentReferences(	...	@@ -31,57 +27,53 @@ export function resolveAttachmentReferences(
31	});	27	});
32	}	28	}
33		29
34	export const layer = AttachmentToolkit.toLayer({	30	export const layer = McpToolAccess.toLayer(AttachmentToolkit, {
35	t3_attachment_prepare_upload: (input) =>	31	t3_attachment_prepare_upload: McpToolAccess.writes((input) =>
36	Effect.gen(function* () {	32	Upload.issueAttachmentUploadUrl(input.upload).pipe(Effect.mapError(unavailable)),
37	yield* readMutationCaller();	33	),
38	return yield* Upload.issueAttachmentUploadUrl(input.upload).pipe(	34	t3_attachment_discard: McpToolAccess.writes((input) =>
39	Effect.mapError(unavailable),	35	Upload.deletePendingAttachment(input.attachmentId).pipe(Effect.as({})),
40	);	36	),
41	}),	37	t3_thread_send_attachments: McpToolAccess.writesThreads(
42	t3_attachment_discard: (input) =>	38	(input) => [input.threadId],
43	Effect.gen(function* () {	39	(input) =>
44	yield* readMutationCaller();	40	Effect.gen(function* () {
45	yield* Upload.deletePendingAttachment(input.attachmentId);	41	const { caller, projection } = yield* readThread(input.threadId, ["messages"]);
46	return {};	42	if (projection.thread.archivedAt !== null)
47	}),	43	return yield* new OrchestratorMcpFailure({
48	t3_thread_send_attachments: (input) =>	44	code: "invalid_request",
49	Effect.gen(function* () {	45	message: "Unarchive the target thread before sending attachments.",
50	const { caller, projection } = yield* readWritableThread(input.threadId, ["messages"]);	46	});
51	if (projection.thread.archivedAt !== null)	47	const attachments = yield* resolveAttachmentReferences(
52	return yield* new OrchestratorMcpFailure({	48	input.attachments,
53	code: "invalid_request",	49	projection.messages.flatMap((message) => message.attachments),
54	message: "Unarchive the target thread before sending attachments.",	50	);
55	});	51	const commandId = yield* newCommandId();
56	const attachments = yield* resolveAttachmentReferences(	52	const messageId = MessageId.make(commandId);
57	input.attachments,	53	const result = yield* ThreadMessageIntake.sendToThread({
58	projection.messages.flatMap((message) => message.attachments),	54	projectId: projection.thread.projectId,
59	);	55	threadId: projection.thread.id,
60	const commandId = yield* newCommandId();	56	commandId,
61	const messageId = MessageId.make(commandId);	57	messageId,
62	const result = yield* ThreadMessageIntake.sendToThread({	58	...(caller === undefined ? {} : { senderThreadId: caller.id }),
63	projectId: projection.thread.projectId,	59	text: input.message ?? "",
64	threadId: projection.thread.id,	60	attachments,
65	commandId,	61	mode: "auto",
66	messageId,	62	createdBy: "agent",
67	...(caller === undefined ? {} : { senderThreadId: caller.id }),	63	creationSource: "mcp",
68	text: input.message ?? "",	64	}).pipe(
69	attachments,	65	Effect.mapError((error) =>
70	mode: "auto",	66	error._tag === "AttachmentClaimError"
71	createdBy: "agent",	67	? new OrchestratorMcpFailure({ code: "orchestration_error", message: error.message })
72	creationSource: "mcp",	68	: unavailable(),
73	}).pipe(	69	),
74	Effect.mapError((error) =>	70	);
75	error._tag === "AttachmentClaimError"	71	return {
76	? new OrchestratorMcpFailure({ code: "orchestration_error", message: error.message })	72	threadId: projection.thread.id,
77	: unavailable(),	73	messageId,
78	),	74	runId: result.run.id,
79	);	75	status: result.run.status,
80	return {	76	};
81	threadId: projection.thread.id,	77	}),
82	messageId,	78	),
83	runId: result.run.id,
84	status: result.run.status,
85	};
86	}),
87	});	79	});

apps/server/src/mcp/toolkits/core.test.ts+6-9

...	@@ -36,6 +36,7 @@ import * as SecretRequests from "../../secrets/SecretRequests.ts";	...	@@ -36,6 +36,7 @@ import * as SecretRequests from "../../secrets/SecretRequests.ts";
36	import * as ScheduledTaskService from "../../scheduledTasks/ScheduledTaskService.ts";	36	import * as ScheduledTaskService from "../../scheduledTasks/ScheduledTaskService.ts";
37	import * as McpHttpServer from "../McpHttpServer.ts";	37	import * as McpHttpServer from "../McpHttpServer.ts";
38	import * as McpInvocationContext from "../McpInvocationContext.ts";	38	import * as McpInvocationContext from "../McpInvocationContext.ts";
		39	import * as McpToolAccessTestkit from "../McpToolAccess.testkit.ts";
39	import { dispatchFailure } from "../threadAccess.ts";	40	import { dispatchFailure } from "../threadAccess.ts";
40	import { OrchestratorToolkit } from "./orchestrator/tools.ts";	41	import { OrchestratorToolkit } from "./orchestrator/tools.ts";
41	import { PreviewToolkit } from "./preview/tools.ts";	42	import { PreviewToolkit } from "./preview/tools.ts";
...	@@ -131,7 +132,7 @@ const client = McpSchema.McpServerClient.of({	...	@@ -131,7 +132,7 @@ const client = McpSchema.McpServerClient.of({
131	getClient: Effect.die("unused"),	132	getClient: Effect.die("unused"),
132	});	133	});
133		134
134	it.effect("checks capability before accessing services through the production registration", () =>	135	it.effect("checks capability through the production registration", () =>
135	Effect.gen(function* () {	136	Effect.gen(function* () {
136	const server = yield* McpServer.McpServer;	137	const server = yield* McpServer.McpServer;
137	expect(server.tools.some(({ tool }) => tool.name === "t3_thread_organize")).toBe(true);	138	expect(server.tools.some(({ tool }) => tool.name === "t3_thread_organize")).toBe(true);
...	@@ -152,7 +153,7 @@ it.effect("checks capability before accessing services through the production re	...	@@ -152,7 +153,7 @@ it.effect("checks capability before accessing services through the production re
152	McpHttpServer.layerThreadToolkit.pipe(	153	McpHttpServer.layerThreadToolkit.pipe(
153	Layer.provideMerge(McpServer.McpServer.layer),	154	Layer.provideMerge(McpServer.McpServer.layer),
154	Layer.provide(NodeCrypto.layer),	155	Layer.provide(NodeCrypto.layer),
155	Layer.provide(Layer.mock(ThreadManagement.ThreadManagementService)({})),	156	Layer.provide(McpToolAccessTestkit.liveThreadsLayer),
156	),	157	),
157	),	158	),
158	),	159	),
...	@@ -453,12 +454,8 @@ it.effect("a client caller targets any thread within its ceiling and cannot act	...	@@ -453,12 +454,8 @@ it.effect("a client caller targets any thread within its ceiling and cannot act
453	Layer.provide(NodeCrypto.layer),	454	Layer.provide(NodeCrypto.layer),
454	Layer.provide(	455	Layer.provide(
455	Layer.mock(ThreadManagement.ThreadManagementService)({	456	Layer.mock(ThreadManagement.ThreadManagementService)({
456	getThreadShell: () =>	457	getThreadShell: (id) =>
457	Effect.succeed({	458	Effect.succeed(McpToolAccessTestkit.liveThreadShell(id, { runtimeMode: "auto" })),
458	id: ThreadId.make("other-project-thread"),
459	projectId: "other-project",
460	deletedAt: null,
461	} as never),
462	getProjectThreadRecords: () =>	459	getProjectThreadRecords: () =>
463	Effect.succeed({	460	Effect.succeed({
464	thread: {	461	thread: {
...	@@ -469,7 +466,7 @@ it.effect("a client caller targets any thread within its ceiling and cannot act	...	@@ -469,7 +466,7 @@ it.effect("a client caller targets any thread within its ceiling and cannot act
469	deletedAt: null,	466	deletedAt: null,
470	},	467	},
471	} as never),	468	} as never),
472	dispatch: () => Effect.succeed({ sequence: 7 } as never),	469	dispatch: () => Effect.succeed({ sequence: 7, storedEvents: [] }),
473	}),	470	}),
474	),	471	),
475	),	472	),

apps/server/src/mcp/toolkits/device/handlers.ts+12-7

...	@@ -16,6 +16,7 @@ import { nodeRuntimeUnavailableMessage } from "@t3tools/shared/nodeRuntime";	...	@@ -16,6 +16,7 @@ import { nodeRuntimeUnavailableMessage } from "@t3tools/shared/nodeRuntime";
16		16
17	import * as DeviceService from "../../../device/DeviceService.ts";	17	import * as DeviceService from "../../../device/DeviceService.ts";
18	import * as McpInvocationContext from "../../McpInvocationContext.ts";	18	import * as McpInvocationContext from "../../McpInvocationContext.ts";
		19	import * as McpToolAccess from "../../McpToolAccess.ts";
19	import { DeviceScreenshotToolkit, DeviceStandardToolkit, DeviceToolkit } from "./tools.ts";	20	import { DeviceScreenshotToolkit, DeviceStandardToolkit, DeviceToolkit } from "./tools.ts";
20		21
21	/** The flags that pin every agent-device command to one device. */	22	/** The flags that pin every agent-device command to one device. */
...	@@ -119,7 +120,7 @@ const pickDevice = (	...	@@ -119,7 +120,7 @@ const pickDevice = (
119	const toolError = (error: DeviceError \| DeviceToolUnavailableError) => error;	120	const toolError = (error: DeviceError \| DeviceToolUnavailableError) => error;
120		121
121	const handlers = {	122	const handlers = {
122	device_list: (input) =>	123	device_list: McpToolAccess.readsAsCaller((input) =>
123	Effect.gen(function* () {	124	Effect.gen(function* () {
124	const scope = yield* requireDeviceAccess;	125	const scope = yield* requireDeviceAccess;
125	const devices = yield* DeviceService.DeviceService;	126	const devices = yield* DeviceService.DeviceService;
...	@@ -145,7 +146,8 @@ const handlers = {	...	@@ -145,7 +146,8 @@ const handlers = {
145	open,	146	open,
146	};	147	};
147	}).pipe(Effect.mapError(toolError)),	148	}).pipe(Effect.mapError(toolError)),
148	device_open: (input) =>	149	),
		150	device_open: McpToolAccess.actsAsCaller((input) =>
149	Effect.gen(function* () {	151	Effect.gen(function* () {
150	const scope = yield* requireDeviceAccess;	152	const scope = yield* requireDeviceAccess;
151	const devices = yield* DeviceService.DeviceService;	153	const devices = yield* DeviceService.DeviceService;
...	@@ -203,7 +205,8 @@ const handlers = {	...	@@ -203,7 +205,8 @@ const handlers = {
203	quickStart: agentDeviceQuickStart(device, targetArgs, command),	205	quickStart: agentDeviceQuickStart(device, targetArgs, command),
204	};	206	};
205	}).pipe(Effect.mapError(toolError)),	207	}).pipe(Effect.mapError(toolError)),
206	device_screenshot: (input) =>	208	),
		209	device_screenshot: McpToolAccess.readsAsCaller((input) =>
207	Effect.gen(function* () {	210	Effect.gen(function* () {
208	const scope = yield* requireDeviceAccess;	211	const scope = yield* requireDeviceAccess;
209	const devices = yield* DeviceService.DeviceService;	212	const devices = yield* DeviceService.DeviceService;
...	@@ -229,7 +232,8 @@ const handlers = {	...	@@ -229,7 +232,8 @@ const handlers = {
229	},	232	},
230	};	233	};
231	}).pipe(Effect.mapError(toolError)),	234	}).pipe(Effect.mapError(toolError)),
232	device_close: (input) =>	235	),
		236	device_close: McpToolAccess.actsAsCaller((input) =>
233	Effect.gen(function* () {	237	Effect.gen(function* () {
234	const scope = yield* requireDeviceAccess;	238	const scope = yield* requireDeviceAccess;
235	const devices = yield* DeviceService.DeviceService;	239	const devices = yield* DeviceService.DeviceService;
...	@@ -241,7 +245,8 @@ const handlers = {	...	@@ -241,7 +245,8 @@ const handlers = {
241	});	245	});
242	return {};	246	return {};
243	}).pipe(Effect.mapError(toolError)),	247	}).pipe(Effect.mapError(toolError)),
244	} satisfies Parameters<typeof DeviceToolkit.toLayer>[0];	248	),
		249	} satisfies McpToolAccess.Handlers<typeof DeviceToolkit.tools>;
245		250
246	/** Width and height from the IHDR chunk; a PNG that lacks one reports 0×0. */	251	/** Width and height from the IHDR chunk; a PNG that lacks one reports 0×0. */
247	export function pngDimensions(png: Uint8Array): { width: number; height: number } {	252	export function pngDimensions(png: Uint8Array): { width: number; height: number } {
...	@@ -258,8 +263,8 @@ export function pngDimensions(png: Uint8Array): { width: number; height: number	...	@@ -258,8 +263,8 @@ export function pngDimensions(png: Uint8Array): { width: number; height: number
258		263
259	const { device_screenshot, ...standardHandlers } = handlers;	264	const { device_screenshot, ...standardHandlers } = handlers;
260		265
261	export const layerStandard = DeviceStandardToolkit.toLayer(standardHandlers);	266	export const layerStandard = McpToolAccess.toLayer(DeviceStandardToolkit, standardHandlers);
262		267
263	export const layerScreenshot = DeviceScreenshotToolkit.toLayer({	268	export const layerScreenshot = McpToolAccess.toLayer(DeviceScreenshotToolkit, {
264	device_screenshot,	269	device_screenshot,
265	});	270	});

apps/server/src/mcp/toolkits/device/tools.ts+14-5

...	@@ -1,4 +1,5 @@	...	@@ -1,4 +1,5 @@
1	import {	1	import {
		2	OrchestratorMcpFailure,
2	DeviceToolCloseInput,	3	DeviceToolCloseInput,
3	DeviceToolError,	4	DeviceToolError,
4	DeviceToolListResult,	5	DeviceToolListResult,
...	@@ -15,8 +16,16 @@ import { Tool, Toolkit } from "effect/ai";	...	@@ -15,8 +16,16 @@ import { Tool, Toolkit } from "effect/ai";
15		16
16	import * as McpInvocationContext from "../../McpInvocationContext.ts";	17	import * as McpInvocationContext from "../../McpInvocationContext.ts";
17	import * as DeviceService from "../../../device/DeviceService.ts";	18	import * as DeviceService from "../../../device/DeviceService.ts";
		19	import * as ThreadManagementService from "../../../orchestration-v2/ThreadManagementService.ts";
18		20
19	const dependencies = [McpInvocationContext.McpInvocationContext, DeviceService.DeviceService];	21	const dependencies = [
		22	McpInvocationContext.McpInvocationContext,
		23	ThreadManagementService.ThreadManagementService,
		24	DeviceService.DeviceService,
		25	];
		26
		27	/** What a device tool fails with, including the access gate's refusal. */
		28	const DeviceToolFailure = Schema.Union([DeviceToolError, OrchestratorMcpFailure]);
20		29
21	/**	30	/**
22	* Deliberately a small surface: lifecycle, visibility for the user, and one	31	* Deliberately a small surface: lifecycle, visibility for the user, and one
...	@@ -36,7 +45,7 @@ const DeviceListTool = Tool.make("device_list", {	...	@@ -36,7 +45,7 @@ const DeviceListTool = Tool.make("device_list", {
36	),	45	),
37	}),	46	}),
38	success: DeviceToolListResult,	47	success: DeviceToolListResult,
39	failure: DeviceToolError,	48	failure: DeviceToolFailure,
40	dependencies,	49	dependencies,
41	})	50	})
42	.annotate(Tool.Title, "List devices")	51	.annotate(Tool.Title, "List devices")
...	@@ -50,7 +59,7 @@ const DeviceOpenTool = Tool.make("device_open", {	...	@@ -50,7 +59,7 @@ const DeviceOpenTool = Tool.make("device_open", {
50	"Open a simulator or emulator for this thread: boots it if needed, starts its live stream, and shows it in the user's Device panel so they can watch. Returns the agent-device CLI invocation pinned to the device; drive the device with that CLI afterwards.",	59	"Open a simulator or emulator for this thread: boots it if needed, starts its live stream, and shows it in the user's Device panel so they can watch. Returns the agent-device CLI invocation pinned to the device; drive the device with that CLI afterwards.",
51	parameters: DeviceToolOpenInput,	60	parameters: DeviceToolOpenInput,
52	success: DeviceToolOpenResult,	61	success: DeviceToolOpenResult,
53	failure: DeviceToolError,	62	failure: DeviceToolFailure,
54	dependencies: [...dependencies, FileSystem.FileSystem, Path.Path, ServerConfig.ServerConfig],	63	dependencies: [...dependencies, FileSystem.FileSystem, Path.Path, ServerConfig.ServerConfig],
55	})	64	})
56	.annotate(Tool.Title, "Open device")	65	.annotate(Tool.Title, "Open device")
...	@@ -64,7 +73,7 @@ export const DeviceScreenshotTool = Tool.make("device_screenshot", {	...	@@ -64,7 +73,7 @@ export const DeviceScreenshotTool = Tool.make("device_screenshot", {
64	"Capture the current screen of an open device as a PNG image. Use it to see what the user sees; for taps and text use the agent-device CLI.",	73	"Capture the current screen of an open device as a PNG image. Use it to see what the user sees; for taps and text use the agent-device CLI.",
65	parameters: DeviceToolTargetInput,	74	parameters: DeviceToolTargetInput,
66	success: DeviceToolScreenshotResult,	75	success: DeviceToolScreenshotResult,
67	failure: DeviceToolError,	76	failure: DeviceToolFailure,
68	dependencies,	77	dependencies,
69	})	78	})
70	.annotate(Tool.Title, "Screenshot device")	79	.annotate(Tool.Title, "Screenshot device")
...	@@ -80,7 +89,7 @@ const DeviceCloseTool = Tool.make("device_close", {	...	@@ -80,7 +89,7 @@ const DeviceCloseTool = Tool.make("device_close", {
80	success: Schema.Record(Schema.String, Schema.Never).annotate({	89	success: Schema.Record(Schema.String, Schema.Never).annotate({
81	description: "The device was closed.",	90	description: "The device was closed.",
82	}),	91	}),
83	failure: DeviceToolError,	92	failure: DeviceToolFailure,
84	dependencies,	93	dependencies,
85	})	94	})
86	.annotate(Tool.Title, "Close device")	95	.annotate(Tool.Title, "Close device")

apps/server/src/mcp/toolkits/environment/handlers.test.ts created+100

...	@@ -0,0 +1,100 @@
1	import { expect, it } from "@effect/vitest";
2	import {
3	DEFAULT_SERVER_SETTINGS,
4	EnvironmentId,
5	ProviderInstanceId,
6	ThreadId,
7	type OrchestrationV2ThreadShell,
8	} from "@t3tools/contracts";
9	import * as Deferred from "effect/Deferred";
10	import * as Effect from "effect/Effect";
11	import * as Fiber from "effect/Fiber";
12	import * as Layer from "effect/Layer";
13	import * as Ref from "effect/Ref";
14	import * as Stream from "effect/Stream";
15
16	import * as Environment from "../../../environment/ServerEnvironment.ts";
17	import * as ThreadCommandExecutor from "../../../orchestration-v2/ThreadCommandExecutor.ts";
18	import * as ThreadManagement from "../../../orchestration-v2/ThreadManagementService.ts";
19	import * as Settings from "../../../serverSettings.ts";
20	import * as McpInvocationContext from "../../McpInvocationContext.ts";
21	import * as McpToolAccess from "../../McpToolAccess.ts";
22	import { liveThreadShell } from "../../McpToolAccess.testkit.ts";
23	import * as EnvironmentHandlers from "./handlers.ts";
24	import { EnvironmentToolkit } from "./tools.ts";
25
26	const environmentId = EnvironmentId.make("environment:preferences");
27	const threadId = ThreadId.make("thread:preferences");
28
29	it.effect("refuses a preferences update when the caller's turn ends while it waits", () =>
30	Effect.gen(function* () {
31	const caller = yield* Ref.make<OrchestrationV2ThreadShell>(liveThreadShell(threadId));
32	const updates = yield* Ref.make(0);
33	// Completes once the declaration's own check has read the caller.
34	const checked = yield* Deferred.make<void>();
35	const layerDependencies = Layer.mergeAll(
36	ThreadCommandExecutor.layer,
37	Layer.succeed(McpInvocationContext.McpInvocationContext, {
38	environmentId,
39	requestNamespace: "provider:preferences",
40	thread: {
41	threadId,
42	providerSessionId: "provider:preferences",
43	providerInstanceId: ProviderInstanceId.make("codex"),
44	},
45	client: undefined,
46	capabilities: new Set(["orchestration" as const]),
47	issuedAt: 0,
48	}),
49	Layer.mock(ThreadManagement.ThreadManagementService)({
50	getThreadShell: () =>
51	Ref.get(caller).pipe(Effect.tap(() => Deferred.succeed(checked, undefined))),
52	}),
53	Layer.mock(Environment.ServerEnvironment)({
54	getDescriptor: Effect.succeed({
55	environmentId,
56	label: "Test",
57	platform: { os: "linux", arch: "x64" },
58	serverVersion: "0.0.0",
59	capabilities: { repositoryIdentity: false },
60	}),
61	}),
62	Layer.mock(Settings.ServerSettingsService)({
63	getSettings: Effect.succeed(DEFAULT_SERVER_SETTINGS),
64	updateSettings: () =>
65	Ref.update(updates, (count) => count + 1).pipe(Effect.as(DEFAULT_SERVER_SETTINGS)),
66	}),
67	);
68	yield* Effect.gen(function* () {
69	const toolkit = yield* EnvironmentToolkit;
70	const executor = yield* ThreadCommandExecutor.ThreadCommandExecutor;
71	const held = yield* Deferred.make<void>();
72	const release = yield* Deferred.make<void>();
73	// A turn-completion command holds the thread's lock.
74	const holder = yield* executor
75	.withLock(
76	threadId,
77	Deferred.succeed(held, undefined).pipe(Effect.andThen(Deferred.await(release))),
78	)
79	.pipe(Effect.forkChild);
80	yield* Deferred.await(held);
81	const update = yield* toolkit
82	.handle("t3_environment_preferences_update", { newWorktreesStartFromOrigin: true })
83	.pipe(Stream.unwrap, Stream.runCollect, Effect.forkChild);
84	// The update passed its first check and waits for the lock; the turn then ends.
85	yield* Deferred.await(checked);
86	yield* Ref.update(caller, (shell) => ({ ...shell, activeRunId: null }));
87	yield* Deferred.succeed(release, undefined);
88	yield* Fiber.join(holder);
89	const result = yield* Fiber.join(update);
90	expect(result.at(-1)?.result).toMatchObject({ code: "parent_not_active" });
91	expect(yield* Ref.get(updates)).toBe(0);
92	}).pipe(
93	Effect.provide(
94	McpToolAccess.HandlersLayer.layer(EnvironmentHandlers.layer).pipe(
95	Layer.provideMerge(layerDependencies),
96	),
97	),
98	);
99	}),
100	);

apps/server/src/mcp/toolkits/environment/handlers.ts+22-22

 @@ -4,7 +4,8 @@ import * as Environment from "../../../environment/ServerEnvironment.ts";
 import * as ThreadCommandExecutor from "../../../orchestration-v2/ThreadCommandExecutor.ts";
 import * as Settings from "../../../serverSettings.ts";
 import * as McpInvocationContext from "../../McpInvocationContext.ts";
-import { readCaller, readFullAccessCaller, unavailable } from "../../threadAccess.ts";
+import * as McpToolAccess from "../../McpToolAccess.ts";
+import { readCaller, unavailable } from "../../threadAccess.ts";
 import { EnvironmentToolkit } from "./tools.ts";
 export function preferences(settings: ServerSettings) {
 @@ -28,26 +29,21 @@ export function preferences(settings: ServerSettings) {
     },
   };
 }
-const access = (writable = false) =>
+const access = Effect.gen(function* () {
-  Effect.gen(function* () {
+  const context = yield* readCaller();
-    const context = yield* writable
+  const environment = yield* Environment.ServerEnvironment;
-      ? readFullAccessCaller(
+  const descriptor = yield* environment.getDescriptor;
-          "Preference updates require a live full-access/default thread or a full-access client.",
+  if (descriptor.environmentId !== context.scope.environmentId)
-        )
+    return yield* new OrchestratorMcpFailure({
-      : readCaller();
+      code: "capability_denied",
-    const environment = yield* Environment.ServerEnvironment;
+      message: "This credential belongs to another environment.",
-    const descriptor = yield* environment.getDescriptor;
+    });
-    if (descriptor.environmentId !== context.scope.environmentId)
+  return { ...context, descriptor, settings: yield* Settings.ServerSettingsService };
-      return yield* new OrchestratorMcpFailure({
+});
-        code: "capability_denied",
+export const layer = McpToolAccess.toLayer(EnvironmentToolkit, {
-        message: "This credential belongs to another environment.",
+  t3_environment_read: McpToolAccess.reads(() =>
-      });
-    return { ...context, descriptor, settings: yield* Settings.ServerSettingsService };
-  });
-export const layer = EnvironmentToolkit.toLayer({
-  t3_environment_read: () =>
     Effect.gen(function* () {
-      const { descriptor, settings } = yield* access();
+      const { descriptor, settings } = yield* access;
       const current = yield* settings.getSettings.pipe(Effect.mapError(unavailable));
       return {
         environmentId: descriptor.environmentId,
 @@ -57,12 +53,15 @@ export const layer = EnvironmentToolkit.toLayer({
         preferences: preferences(current),
       };
     }),
-  t3_environment_preferences_update: (patch) =>
+  ),
+  t3_environment_preferences_update: McpToolAccess.writesEnvironment((patch, check) =>
     Effect.gen(function* () {
       const scope = yield* McpInvocationContext.McpInvocationContext;
       const executor = yield* ThreadCommandExecutor.ThreadCommandExecutor;
       const update = Effect.gen(function* () {
-        const { settings } = yield* access(true);
+        // The turn may have ended, or the thread's modes changed, while this waited for the lock.
+        yield* check;
+        const { settings } = yield* access;
         return preferences(
           yield* settings.updateSettings(patch).pipe(Effect.mapError(unavailable)),
         );
 @@ -72,4 +71,5 @@ export const layer = EnvironmentToolkit.toLayer({
         ? update
         : executor.withLock(scope.thread.threadId, update);
     }),
+  ),
 });

apps/server/src/mcp/toolkits/html/handlers.ts+12-15

 @@ -3,7 +3,7 @@ import * as Effect from "effect/Effect";
 import * as HtmlRender from "../../../htmlRender/HtmlRender.ts";
 import * as McpInvocationContext from "../../McpInvocationContext.ts";
-import { readMutationCaller } from "../../threadAccess.ts";
+import * as McpToolAccess from "../../McpToolAccess.ts";
 import { HtmlPreviewToolkit, HtmlRenderToolkit, type HtmlToolkit } from "./tools.ts";
 const INVALID_PAGE_ERRORS = new Set([
 @@ -20,14 +20,10 @@ const toFailure = (error: { readonly _tag: string; readonly message: string }) =
   });
 const handlers = {
-  html_preview: (input) =>
+  // The headless browser runs on the host and can open local files, so only
+  // agents T3 launched, which already work on this machine, get it.
+  html_preview: McpToolAccess.readsAsCaller((input) =>
     Effect.gen(function* () {
-      // The headless browser runs on the host and can open local files, so
-      // only agents T3 launched, which already work on this machine, get it.
-      yield* McpInvocationContext.requireThreadScope(
-        yield* McpInvocationContext.McpInvocationContext,
-        "html_preview",
-      );
       const htmlRender = yield* HtmlRender.HtmlRender;
       const { png, ...preview } = yield* htmlRender.preview(input).pipe(Effect.mapError(toFailure));
       return {
 @@ -40,11 +36,11 @@ const handlers = {
         },
       };
     }),
-  html_render: (input) =>
+  ),
+  // The page is stored in the calling thread, so it needs that thread's live run.
+  html_render: McpToolAccess.actsAsCaller((input) =>
     Effect.gen(function* () {
-      // The page is stored in the calling thread, so it needs that thread's
+      const scope = yield* McpInvocationContext.McpInvocationContext;
-      // live run, like any other write.
-      const { scope } = yield* readMutationCaller();
       const { thread } = yield* McpInvocationContext.requireThreadScope(scope, "html_render");
       const htmlRender = yield* HtmlRender.HtmlRender;
       const reference = yield* htmlRender
 @@ -56,12 +52,13 @@ const handlers = {
           "Shown to the reader above your reply. Don't mention or describe the page; reply with only what it doesn't already say.",
       };
     }),
-} satisfies Parameters<typeof HtmlToolkit.toLayer>[0];
+  ),
+} satisfies McpToolAccess.Handlers<typeof HtmlToolkit.tools>;
-export const layerPreview = HtmlPreviewToolkit.toLayer({
+export const layerPreview = McpToolAccess.toLayer(HtmlPreviewToolkit, {
   html_preview: handlers.html_preview,
 });
-export const layerRender = HtmlRenderToolkit.toLayer({
+export const layerRender = McpToolAccess.toLayer(HtmlRenderToolkit, {
   html_render: handlers.html_render,
 });

apps/server/src/mcp/toolkits/html/tools.ts+5-1

 @@ -56,7 +56,11 @@ export const HtmlPreviewTool = Tool.make("html_preview", {
     }),
   }),
   failure: OrchestratorMcpFailure,
-  dependencies: [McpInvocationContext.McpInvocationContext, HtmlRender.HtmlRender],
+  dependencies: [
+    McpInvocationContext.McpInvocationContext,
+    ThreadManagementService.ThreadManagementService,
+    HtmlRender.HtmlRender,
+  ],
 })
   .annotate(Tool.Title, "Preview HTML")
   .annotate(Tool.Readonly, true)

apps/server/src/mcp/toolkits/orchestrator/handlers.ts+67-38

 @@ -2,106 +2,135 @@ import { OrchestratorToolkit } from "./tools.ts";
 import * as Effect from "effect/Effect";
 import * as McpInvocationContext from "../../McpInvocationContext.ts";
+import * as McpToolAccess from "../../McpToolAccess.ts";
 import * as OrchestratorMcpService from "../../OrchestratorMcpService.ts";
 import * as ThreadMetadataMcpService from "../../ThreadMetadataMcpService.ts";
 const handlers = {
-  orchestrator_capabilities: () =>
+  orchestrator_capabilities: McpToolAccess.reads(() =>
     Effect.gen(function* () {
       const scope = yield* McpInvocationContext.McpInvocationContext;
       const service = yield* OrchestratorMcpService.OrchestratorMcpService;
       return yield* service.capabilities(scope);
     }),
-  delegate_task: (input) =>
+  ),
+  delegate_task: McpToolAccess.actsAsCaller((input) =>
     Effect.gen(function* () {
       const scope = yield* McpInvocationContext.McpInvocationContext;
       const service = yield* OrchestratorMcpService.OrchestratorMcpService;
       return yield* service.delegateTask(scope, input);
     }),
-  task_status: ({ taskId }) =>
+  ),
+  task_status: McpToolAccess.actsAsCaller(({ taskId }) =>
     Effect.gen(function* () {
       const scope = yield* McpInvocationContext.McpInvocationContext;
       const service = yield* OrchestratorMcpService.OrchestratorMcpService;
       return yield* service.taskStatus(scope, taskId);
     }),
-  task_cancel: (input) =>
+  ),
+  task_cancel: McpToolAccess.actsAsCaller((input) =>
     Effect.gen(function* () {
       const scope = yield* McpInvocationContext.McpInvocationContext;
       const service = yield* OrchestratorMcpService.OrchestratorMcpService;
       return yield* service.cancelTask(scope, input);
     }),
-  schedule_task: (input) =>
+  ),
-    Effect.gen(function* () {
+  schedule_task: McpToolAccess.startsThreads(
-      const scope = yield* McpInvocationContext.McpInvocationContext;
+    // A scheduled task runs with the caller's own modes.
-      const service = yield* OrchestratorMcpService.OrchestratorMcpService;
+    () => ({}),
-      return yield* service.scheduleTask(scope, input);
+    (input) =>
-    }),
+      Effect.gen(function* () {
-  list_scheduled_tasks: (input) =>
+        const scope = yield* McpInvocationContext.McpInvocationContext;
+        const service = yield* OrchestratorMcpService.OrchestratorMcpService;
+        return yield* service.scheduleTask(scope, input);
+      }),
+  ),
+  list_scheduled_tasks: McpToolAccess.reads((input) =>
     Effect.gen(function* () {
       const scope = yield* McpInvocationContext.McpInvocationContext;
       const service = yield* OrchestratorMcpService.OrchestratorMcpService;
       return yield* service.listScheduledTasks(scope, input);
     }),
-  update_scheduled_task: (input) =>
+  ),
+  update_scheduled_task: McpToolAccess.writes((input) =>
     Effect.gen(function* () {
       const scope = yield* McpInvocationContext.McpInvocationContext;
       const service = yield* OrchestratorMcpService.OrchestratorMcpService;
       return yield* service.updateScheduledTask(scope, input);
     }),
-  delete_scheduled_task: (input) =>
+  ),
+  delete_scheduled_task: McpToolAccess.writes((input) =>
     Effect.gen(function* () {
       const scope = yield* McpInvocationContext.McpInvocationContext;
       const service = yield* OrchestratorMcpService.OrchestratorMcpService;
       return yield* service.deleteScheduledTask(scope, input);
     }),
-  request_secret: (input) =>
+  ),
+  request_secret: McpToolAccess.actsAsCaller((input) =>
     Effect.gen(function* () {
       const scope = yield* McpInvocationContext.McpInvocationContext;
       const service = yield* OrchestratorMcpService.OrchestratorMcpService;
       return yield* service.requestSecret(scope, input);
     }),
-  create_threads: (input) =>
+  ),
+  create_threads: McpToolAccess.actsAsCaller((input) =>
     Effect.gen(function* () {
       const scope = yield* McpInvocationContext.McpInvocationContext;
       const service = yield* OrchestratorMcpService.OrchestratorMcpService;
       return yield* service.createThreads(scope, input);
     }),
-  t3_thread_list: (input) =>
+  ),
+  t3_thread_list: McpToolAccess.reads((input) =>
     Effect.gen(function* () {
       const scope = yield* McpInvocationContext.McpInvocationContext;
       const service = yield* OrchestratorMcpService.OrchestratorMcpService;
       return yield* service.listThreads(scope, input);
     }),
-  t3_thread_read: (input) =>
+  ),
+  // Reading a child's finished result also acknowledges its delivery to the
+  // reader's own thread. That is bookkeeping on the caller's own subagent, not
+  // a change to anything it reads, so this stays a read.
+  t3_thread_read: McpToolAccess.reads((input) =>
     Effect.gen(function* () {
       const scope = yield* McpInvocationContext.McpInvocationContext;
       const service = yield* OrchestratorMcpService.OrchestratorMcpService;
       return yield* service.readThread(scope, input);
     }),
-  t3_thread_update: (input) =>
+  ),
-    Effect.gen(function* () {
+  t3_thread_update: McpToolAccess.writesThreads(
-      const scope = yield* McpInvocationContext.McpInvocationContext;
+    (input) => [input.threadId],
-      const service = yield* ThreadMetadataMcpService.ThreadMetadataMcpService;
+    (input) =>
-      return yield* service.update(scope, input);
+      Effect.gen(function* () {
-    }),
+        const scope = yield* McpInvocationContext.McpInvocationContext;
-  t3_thread_send: (input) =>
+        const service = yield* ThreadMetadataMcpService.ThreadMetadataMcpService;
-    Effect.gen(function* () {
+        return yield* service.update(scope, input);
-      const scope = yield* McpInvocationContext.McpInvocationContext;
+      }),
-      const service = yield* OrchestratorMcpService.OrchestratorMcpService;
+  ),
-      return yield* service.sendToThread(scope, input);
+  t3_thread_send: McpToolAccess.writesThreads(
-    }),
+    (input) => [input.threadId],
-  t3_thread_wait: (input) =>
+    (input) =>
+      Effect.gen(function* () {
+        const scope = yield* McpInvocationContext.McpInvocationContext;
+        const service = yield* OrchestratorMcpService.OrchestratorMcpService;
+        return yield* service.sendToThread(scope, input);
+      }),
+  ),
+  t3_thread_wait: McpToolAccess.reads((input) =>
     Effect.gen(function* () {
       const scope = yield* McpInvocationContext.McpInvocationContext;
       const service = yield* OrchestratorMcpService.OrchestratorMcpService;
       return yield* service.waitForThread(scope, input);
     }),
-  t3_thread_interrupt: (input) =>
+  ),
-    Effect.gen(function* () {
+  t3_thread_interrupt: McpToolAccess.writesThreads(
-      const scope = yield* McpInvocationContext.McpInvocationContext;
+    (input) => [input.threadId],
-      const service = yield* OrchestratorMcpService.OrchestratorMcpService;
+    (input) =>
-      return yield* service.interruptThread(scope, input);
+      Effect.gen(function* () {
-    }),
+        const scope = yield* McpInvocationContext.McpInvocationContext;
-} satisfies Parameters<typeof OrchestratorToolkit.toLayer>[0];
+        const service = yield* OrchestratorMcpService.OrchestratorMcpService;
+        return yield* service.interruptThread(scope, input);
+      }),
+  ),
+} satisfies McpToolAccess.Handlers<typeof OrchestratorToolkit.tools>;
-export const layer = OrchestratorToolkit.toLayer(handlers);
+export const layer = McpToolAccess.toLayer(OrchestratorToolkit, handlers);

apps/server/src/mcp/toolkits/orchestrator/tools.ts+3

 @@ -32,16 +32,19 @@ import {
 } from "@t3tools/contracts";
 import { Tool, Toolkit } from "effect/ai";
+import * as ThreadManagementService from "../../../orchestration-v2/ThreadManagementService.ts";
 import * as McpInvocationContext from "../../McpInvocationContext.ts";
 import * as OrchestratorMcpService from "../../OrchestratorMcpService.ts";
 import * as ThreadMetadataMcpService from "../../ThreadMetadataMcpService.ts";
 const dependencies = [
   McpInvocationContext.McpInvocationContext,
+  ThreadManagementService.ThreadManagementService,
   OrchestratorMcpService.OrchestratorMcpService,
 ];
 const threadMetadataDependencies = [
   McpInvocationContext.McpInvocationContext,
+  ThreadManagementService.ThreadManagementService,
   ThreadMetadataMcpService.ThreadMetadataMcpService,
 ];

apps/server/src/mcp/toolkits/preview/handlers.ts+48-23

 @@ -29,6 +29,7 @@ import {
 import { resolveAttachmentRelativePath } from "../../../attachmentPaths.ts";
 import * as ServerConfig from "../../../config.ts";
 import * as McpInvocationContext from "../../McpInvocationContext.ts";
+import * as McpToolAccess from "../../McpToolAccess.ts";
 import * as PreviewAutomationBroker from "../../PreviewAutomationBroker.ts";
 import { PreviewSnapshotToolkit, PreviewStandardToolkit, PreviewToolkit } from "./tools.ts";
 @@ -189,41 +190,64 @@ export const claimPreviewRecording = Effect.fn("PreviewToolkit.claimRecording")(
 });
 const handlers = {
-  preview_dialog: (input) => invokeTargeted<PreviewAutomationStatus>("dialog", input),
+  preview_dialog: McpToolAccess.actsAsCaller((input) =>
-  preview_status: (input) => invokeTargeted<PreviewAutomationStatus>("status", input ?? {}),
+    invokeTargeted<PreviewAutomationStatus>("dialog", input),
-  preview_open: (input) =>
+  ),
+  preview_status: McpToolAccess.readsAsCaller((input) =>
+    invokeTargeted<PreviewAutomationStatus>("status", input ?? {}),
+  ),
+  preview_open: McpToolAccess.actsAsCaller((input) =>
     invokeTargeted<PreviewAutomationStatus>("open", normalizePreviewOpenInput(input)),
-  preview_navigate: (input) =>
+  ),
+  preview_navigate: McpToolAccess.actsAsCaller((input) =>
     invokeTargeted<PreviewAutomationStatus>("navigate", input, input.timeoutMs),
-  preview_resize: (input) =>
+  ),
+  preview_resize: McpToolAccess.actsAsCaller((input) =>
     invokeTargeted<PreviewAutomationResizeResult>("resize", input, input.timeoutMs),
-  preview_set_appearance: (input) =>
+  ),
+  preview_set_appearance: McpToolAccess.actsAsCaller((input) =>
     invokeTargeted<PreviewAutomationSetColorSchemeResult>("setColorScheme", input),
-  preview_snapshot: (input) => {
+  ),
+  preview_snapshot: McpToolAccess.readsAsCaller((input) => {
     // Output selection and saving are MCP-only; the browser still produces a complete snapshot.
     const { includeImage: _includeImage, save: _save, ...operationInput } = input ?? {};
     return invokeTargeted<PreviewAutomationSnapshot>("snapshot", operationInput);
-  },
+  }),
-  preview_click: (input) => invokeTargeted<object>("click", input, input.timeoutMs),
+  preview_click: McpToolAccess.actsAsCaller((input) =>
-  preview_type: (input) => invokeTargeted<object>("type", input, input.timeoutMs),
+    invokeTargeted<object>("click", input, input.timeoutMs),
-  preview_hover: (input) => invokeTargeted<object>("hover", input, input.timeoutMs),
+  ),
-  preview_select: (input) =>
+  preview_type: McpToolAccess.actsAsCaller((input) =>
+    invokeTargeted<object>("type", input, input.timeoutMs),
+  ),
+  preview_hover: McpToolAccess.actsAsCaller((input) =>
+    invokeTargeted<object>("hover", input, input.timeoutMs),
+  ),
+  preview_select: McpToolAccess.actsAsCaller((input) =>
     invokeTargeted<PreviewAutomationSelectResult>("select", input, input.timeoutMs),
-  preview_drag: (input) => invokeTargeted<object>("drag", input, input.timeoutMs),
+  ),
-  preview_upload: (input) => invokeTargeted<object>("upload", input, input.timeoutMs),
+  preview_drag: McpToolAccess.actsAsCaller((input) =>
-  preview_press: (input) => invokeTargeted<object>("press", input),
+    invokeTargeted<object>("drag", input, input.timeoutMs),
-  preview_scroll: (input) => invokeTargeted<object>("scroll", input),
+  ),
-  preview_evaluate: ({ tabId, ...input }) =>
+  preview_upload: McpToolAccess.actsAsCaller((input) =>
+    invokeTargeted<object>("upload", input, input.timeoutMs),
+  ),
+  preview_press: McpToolAccess.actsAsCaller((input) => invokeTargeted<object>("press", input)),
+  preview_scroll: McpToolAccess.actsAsCaller((input) => invokeTargeted<object>("scroll", input)),
+  preview_evaluate: McpToolAccess.actsAsCaller(({ tabId, ...input }) =>
     invoke<unknown>("evaluate", input, undefined, tabId).pipe(
       Effect.map(({ result, toolIcon }) => ({
         value: result ?? null,
         ...(toolIcon ? { toolIcon } : {}),
       })),
     ),
-  preview_wait_for: (input) => invokeTargeted<object>("waitFor", input, input.timeoutMs),
+  ),
-  preview_recording_start: (input) =>
+  preview_wait_for: McpToolAccess.readsAsCaller((input) =>
+    invokeTargeted<object>("waitFor", input, input.timeoutMs),
+  ),
+  preview_recording_start: McpToolAccess.actsAsCaller((input) =>
     invokeTargeted<PreviewAutomationRecordingStatus>("recordingStart", input ?? {}),
-  preview_recording_stop: (input) =>
+  ),
+  preview_recording_stop: McpToolAccess.actsAsCaller((input) =>
     Effect.gen(function* () {
       const scope = yield* McpInvocationContext.requireThreadMcpCapability("preview");
       const { tabId, ...operationInput } = input;
 @@ -236,12 +260,13 @@ const handlers = {
       const artifact = yield* claimPreviewRecording(scope.thread.threadId, response.result);
       return { ...artifact, ...(response.toolIcon ? { toolIcon: response.toolIcon } : {}) };
     }),
-} satisfies Parameters<typeof PreviewToolkit.toLayer>[0];
+  ),
+} satisfies McpToolAccess.Handlers<typeof PreviewToolkit.tools>;
 const { preview_snapshot, ...standardHandlers } = handlers;
-export const layerStandard = PreviewStandardToolkit.toLayer(standardHandlers);
+export const layerStandard = McpToolAccess.toLayer(PreviewStandardToolkit, standardHandlers);
-export const layerSnapshot = PreviewSnapshotToolkit.toLayer({
+export const layerSnapshot = McpToolAccess.toLayer(PreviewSnapshotToolkit, {
   preview_snapshot,
 });

apps/server/src/mcp/toolkits/preview/tools.ts+25-19

apps/server/src/mcp/toolkits/previewControls/handlers.test.ts+8-1

 @@ -17,6 +17,8 @@ import * as ServerConfig from "../../../config.ts";
 import * as Preview from "../../../preview/Manager.ts";
 import * as ServerSettings from "../../../serverSettings.ts";
 import * as McpInvocationContext from "../../McpInvocationContext.ts";
+import * as McpToolAccess from "../../McpToolAccess.ts";
+import * as McpToolAccessTestkit from "../../McpToolAccess.testkit.ts";
 import * as PreviewAutomationBroker from "../../PreviewAutomationBroker.ts";
 import * as PreviewControlsHandlers from "./handlers.ts";
 import { PreviewControlsToolkit } from "./tools.ts";
 @@ -64,12 +66,17 @@ it.effect.each([
         PreviewAutomationBroker.layer.pipe(Layer.provide(NodeServices.layer)),
         Layer.succeed(Preview.PreviewManager, manager),
         Layer.succeed(McpInvocationContext.McpInvocationContext, scope),
+        McpToolAccessTestkit.liveThreadsLayer,
         Layer.mock(ServerSettings.ServerSettingsService)({
           getSettings: Effect.succeed(settings),
         }),
       );
       const toolkit = yield* PreviewControlsToolkit.pipe(
-        Effect.provide(PreviewControlsHandlers.layer.pipe(Layer.provide(layerDependencies))),
+        Effect.provide(
+          McpToolAccess.HandlersLayer.layer(PreviewControlsHandlers.layer).pipe(
+            Layer.provide(layerDependencies),
+          ),
+        ),
       );
       const listed = yield* toolkit
         .handle("t3_preview_list", {})

apps/server/src/mcp/toolkits/previewControls/handlers.ts+6-3

apps/server/src/mcp/toolkits/previewControls/tools.ts+2

apps/server/src/mcp/toolkits/project/handlers.test.ts+101-7

...	@@ -10,6 +10,8 @@ import {	...	@@ -10,6 +10,8 @@ import {
10	import * as NodeCrypto from "@effect/platform-node/NodeCrypto";	10	import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
11	import * as NodeServices from "@effect/platform-node/NodeServices";	11	import * as NodeServices from "@effect/platform-node/NodeServices";
12	import * as Effect from "effect/Effect";	12	import * as Effect from "effect/Effect";
		13	import * as FileSystem from "effect/FileSystem";
		14	import * as Path from "effect/Path";
13	import * as Layer from "effect/Layer";	15	import * as Layer from "effect/Layer";
14	import * as Option from "effect/Option";	16	import * as Option from "effect/Option";
15	import * as Stream from "effect/Stream";	17	import * as Stream from "effect/Stream";
...	@@ -19,7 +21,10 @@ import * as ThreadManagement from "../../../orchestration-v2/ThreadManagementSer	...	@@ -19,7 +21,10 @@ import * as ThreadManagement from "../../../orchestration-v2/ThreadManagementSer
19	import * as ServerConfig from "../../../config.ts";	21	import * as ServerConfig from "../../../config.ts";
20	import * as Project from "../../../project/ProjectService.ts";	22	import * as Project from "../../../project/ProjectService.ts";
21	import * as ManagedProjectFolders from "../../../project/ManagedProjectFolders.ts";	23	import * as ManagedProjectFolders from "../../../project/ManagedProjectFolders.ts";
		24	import * as GitVcsDriver from "../../../vcs/GitVcsDriver.ts";
		25	import * as VcsProcess from "../../../vcs/VcsProcess.ts";
22	import * as McpInvocationContext from "../../McpInvocationContext.ts";	26	import * as McpInvocationContext from "../../McpInvocationContext.ts";
		27	import * as McpToolAccess from "../../McpToolAccess.ts";
23	import * as ProjectHandlers from "./handlers.ts";	28	import * as ProjectHandlers from "./handlers.ts";
24	import { ProjectToolkit } from "./tools.ts";	29	import { ProjectToolkit } from "./tools.ts";
25		30
...	@@ -73,13 +78,18 @@ it.effect("attributes a launched thread's first message to the calling thread",	...	@@ -73,13 +78,18 @@ it.effect("attributes a launched thread's first message to the calling thread",
73	}),	78	}),
74	Layer.mock(Project.ProjectService)({}),	79	Layer.mock(Project.ProjectService)({}),
75	Layer.mock(ManagedProjectFolders.ManagedProjectFolders)({ namedProjectsRoot: "/projects" }),	80	Layer.mock(ManagedProjectFolders.ManagedProjectFolders)({ namedProjectsRoot: "/projects" }),
		81	Layer.mock(GitVcsDriver.GitVcsDriver)({}),
76	NodeServices.layer,	82	NodeServices.layer,
77	ServerConfig.layerTest(process.cwd(), { prefix: "t3-source-link-" }).pipe(	83	ServerConfig.layerTest(process.cwd(), { prefix: "t3-source-link-" }).pipe(
78	Layer.provide(NodeServices.layer),	84	Layer.provide(NodeServices.layer),
79	),	85	),
80	);	86	);
81	const toolkit = yield* ProjectToolkit.pipe(	87	const toolkit = yield* ProjectToolkit.pipe(
82	Effect.provide(ProjectHandlers.layer.pipe(Layer.provide(layerDependencies))),	88	Effect.provide(
		89	McpToolAccess.HandlersLayer.layer(ProjectHandlers.layer).pipe(
		90	Layer.provide(layerDependencies),
		91	),
		92	),
83	);	93	);
84	const result = yield* toolkit	94	const result = yield* toolkit
85	.handle("t3_thread_launch", { title: "Audit", message: "Review the change" })	95	.handle("t3_thread_launch", { title: "Audit", message: "Review the change" })
...	@@ -142,13 +152,18 @@ it.effect("launches a scratch thread into the Scratch project", () =>	...	@@ -142,13 +152,18 @@ it.effect("launches a scratch thread into the Scratch project", () =>
142	namedProjectsRoot: "/projects",	152	namedProjectsRoot: "/projects",
143	ensureScratchProject: Effect.succeed({ projectId: scratchProjectId }),	153	ensureScratchProject: Effect.succeed({ projectId: scratchProjectId }),
144	}),	154	}),
		155	Layer.mock(GitVcsDriver.GitVcsDriver)({}),
145	NodeServices.layer,	156	NodeServices.layer,
146	ServerConfig.layerTest(process.cwd(), { prefix: "t3-scratch-launch-" }).pipe(	157	ServerConfig.layerTest(process.cwd(), { prefix: "t3-scratch-launch-" }).pipe(
147	Layer.provide(NodeServices.layer),	158	Layer.provide(NodeServices.layer),
148	),	159	),
149	);	160	);
150	const toolkit = yield* ProjectToolkit.pipe(	161	const toolkit = yield* ProjectToolkit.pipe(
151	Effect.provide(ProjectHandlers.layer.pipe(Layer.provide(layerDependencies))),	162	Effect.provide(
		163	McpToolAccess.HandlersLayer.layer(ProjectHandlers.layer).pipe(
		164	Layer.provide(layerDependencies),
		165	),
		166	),
152	);	167	);
153	const handle = (params: Parameters<typeof toolkit.handle<"t3_thread_launch">>[1]) =>	168	const handle = (params: Parameters<typeof toolkit.handle<"t3_thread_launch">>[1]) =>
154	toolkit	169	toolkit
...	@@ -240,13 +255,18 @@ it.effect("starts a project from just a title when workspaceRoot is omitted", ()	...	@@ -240,13 +255,18 @@ it.effect("starts a project from just a title when workspaceRoot is omitted", ()
240	};	255	};
241	}),	256	}),
242	}),	257	}),
		258	Layer.mock(GitVcsDriver.GitVcsDriver)({}),
243	NodeServices.layer,	259	NodeServices.layer,
244	ServerConfig.layerTest(process.cwd(), { prefix: "t3-named-project-" }).pipe(	260	ServerConfig.layerTest(process.cwd(), { prefix: "t3-named-project-" }).pipe(
245	Layer.provide(NodeServices.layer),	261	Layer.provide(NodeServices.layer),
246	),	262	),
247	);	263	);
248	const toolkit = yield* ProjectToolkit.pipe(	264	const toolkit = yield* ProjectToolkit.pipe(
249	Effect.provide(ProjectHandlers.layer.pipe(Layer.provide(layerDependencies))),	265	Effect.provide(
		266	McpToolAccess.HandlersLayer.layer(ProjectHandlers.layer).pipe(
		267	Layer.provide(layerDependencies),
		268	),
		269	),
250	);	270	);
251	const handle = (params: Parameters<typeof toolkit.handle<"t3_project_create">>[1]) =>	271	const handle = (params: Parameters<typeof toolkit.handle<"t3_project_create">>[1]) =>
252	toolkit	272	toolkit
...	@@ -280,6 +300,7 @@ it.effect("starts a project from just a title when workspaceRoot is omitted", ()	...	@@ -280,6 +300,7 @@ it.effect("starts a project from just a title when workspaceRoot is omitted", ()
280	const clientLaunchHarness = (input: {	300	const clientLaunchHarness = (input: {
281	readonly runtimeModeCeiling: "approval-required" \| "auto-accept-edits" \| "auto" \| "full-access";	301	readonly runtimeModeCeiling: "approval-required" \| "auto-accept-edits" \| "auto" \| "full-access";
282	readonly launched: Array<ThreadLaunch.ThreadLaunchInput>;	302	readonly launched: Array<ThreadLaunch.ThreadLaunchInput>;
		303	readonly workspaceRoot?: string;
283	}) => {	304	}) => {
284	const projectId = ProjectId.make("project:client-target");	305	const projectId = ProjectId.make("project:client-target");
285	const modelSelection = { instanceId: ProviderInstanceId.make("claude"), model: "claude-opus" };	306	const modelSelection = { instanceId: ProviderInstanceId.make("claude"), model: "claude-opus" };
...	@@ -319,15 +340,25 @@ const clientLaunchHarness = (input: {	...	@@ -319,15 +340,25 @@ const clientLaunchHarness = (input: {
319	getById: (id) =>	340	getById: (id) =>
320	Effect.succeed(	341	Effect.succeed(
321	id === projectId	342	id === projectId
322	? Option.some({ id, defaultModelSelection: modelSelection } as unknown as ProjectRecord)	343	? Option.some({
		344	id,
		345	workspaceRoot: input.workspaceRoot ?? "/projects/client-target",
		346	defaultModelSelection: modelSelection,
		347	} as unknown as ProjectRecord)
323	: Option.none(),	348	: Option.none(),
324	),	349	),
325	}),	350	}),
326	Layer.mock(ManagedProjectFolders.ManagedProjectFolders)({ namedProjectsRoot: "/projects" }),	351	Layer.mock(ManagedProjectFolders.ManagedProjectFolders)({ namedProjectsRoot: "/projects" }),
327	NodeServices.layer,	352	NodeServices.layer,
328	ServerConfig.layerTest(process.cwd(), { prefix: "t3-client-launch-" }).pipe(	353	).pipe(
329	Layer.provide(NodeServices.layer),	354	Layer.provideMerge(GitVcsDriver.layer),
		355	Layer.provideMerge(VcsProcess.layer),
		356	Layer.provideMerge(
		357	ServerConfig.layerTest(process.cwd(), { prefix: "t3-client-launch-" }).pipe(
		358	Layer.provide(NodeServices.layer),
		359	),
330	),	360	),
		361	Layer.provideMerge(NodeServices.layer),
331	);	362	);
332	return { projectId, modelSelection, dependencies: layerDependencies };	363	return { projectId, modelSelection, dependencies: layerDependencies };
333	};	364	};
...	@@ -340,7 +371,9 @@ it.effect("a client launches at its ceiling with the project's default model", (	...	@@ -340,7 +371,9 @@ it.effect("a client launches at its ceiling with the project's default model", (
340	launched,	371	launched,
341	});	372	});
342	const toolkit = yield* ProjectToolkit.pipe(	373	const toolkit = yield* ProjectToolkit.pipe(
343	Effect.provide(ProjectHandlers.layer.pipe(Layer.provide(dependencies))),	374	Effect.provide(
		375	McpToolAccess.HandlersLayer.layer(ProjectHandlers.layer).pipe(Layer.provide(dependencies)),
		376	),
344	);	377	);
345	const handle = (params: Parameters<typeof toolkit.handle<"t3_thread_launch">>[1]) =>	378	const handle = (params: Parameters<typeof toolkit.handle<"t3_thread_launch">>[1]) =>
346	toolkit	379	toolkit
...	@@ -360,3 +393,64 @@ it.effect("a client launches at its ceiling with the project's default model", (	...	@@ -360,3 +393,64 @@ it.effect("a client launches at its ceiling with the project's default model", (
360	expect(launched).toHaveLength(1);	393	expect(launched).toHaveLength(1);
361	}),	394	}),
362	);	395	);
		396
		397	it.effect("a launch binds only an existing checkout that is one of the project's worktrees", () =>
		398	Effect.gen(function* () {
		399	const fileSystem = yield* FileSystem.FileSystem;
		400	const path = yield* Path.Path;
		401	const root = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-launch-worktree-" });
		402	const repo = path.join(root, "repo");
		403	const worktree = path.join(root, "feature");
		404	const outside = path.join(root, "outside");
		405	yield* fileSystem.makeDirectory(repo);
		406	yield* fileSystem.makeDirectory(outside);
		407
		408	const launched: Array<ThreadLaunch.ThreadLaunchInput> = [];
		409	const { projectId, dependencies } = clientLaunchHarness({
		410	runtimeModeCeiling: "auto",
		411	launched,
		412	workspaceRoot: repo,
		413	});
		414	const git = yield* GitVcsDriver.GitVcsDriver.pipe(Effect.provide(dependencies));
		415	for (const args of [
		416	["init", "-b", "main"],
		417	["-c", "user.email=t@t", "-c", "user.name=t", "commit", "--allow-empty", "-m", "init"],
		418	["worktree", "add", "-b", "feature", worktree],
		419	]) {
		420	yield* git.execute({ operation: "test.setupRepo", cwd: repo, args });
		421	}
		422	const toolkit = yield* ProjectToolkit.pipe(
		423	Effect.provide(
		424	McpToolAccess.HandlersLayer.layer(ProjectHandlers.layer).pipe(Layer.provide(dependencies)),
		425	),
		426	);
		427	const launchInto = (worktreePath: string) =>
		428	toolkit
		429	.handle("t3_thread_launch", {
		430	title: "Fix",
		431	projectId,
		432	workspaceStrategy: { type: "existing_worktree", worktreePath },
		433	})
		434	.pipe(Stream.unwrap, Stream.runCollect, Effect.provide(dependencies));
		435
		436	expect((yield* launchInto(worktree)).at(-1)?.result).toMatchObject({ projectId });
		437	expect((yield* launchInto(repo)).at(-1)?.result).toMatchObject({ projectId });
		438	for (const elsewhere of [outside, path.join(worktree, "..", "outside"), "/"]) {
		439	expect((yield* launchInto(elsewhere)).at(-1)?.result).toMatchObject({
		440	code: "invalid_request",
		441	});
		442	}
		443	expect(launched.map((launch) => launch.workspaceStrategy)).toEqual([
		444	{ type: "existing_worktree", worktreePath: worktree },
		445	{ type: "existing_worktree", worktreePath: repo },
		446	]);
		447
		448	// A removed worktree stays listed as prunable until `git worktree prune`;
		449	// whatever directory is later made at its path is not one of the project's.
		450	yield* fileSystem.remove(worktree, { recursive: true });
		451	yield* fileSystem.makeDirectory(worktree);
		452	expect((yield* launchInto(worktree)).at(-1)?.result).toMatchObject({
		453	code: "invalid_request",
		454	});
		455	}).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
		456	);

apps/server/src/mcp/toolkits/project/handlers.ts+142-126

 @@ -1,20 +1,15 @@
 import { MessageId, ThreadId, OrchestratorMcpFailure, ProjectId } from "@t3tools/contracts";
 import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
 import * as Option from "effect/Option";
 import * as ThreadMessageIntake from "../../../orchestration-v2/ThreadMessageIntake.ts";
 import * as Claims from "../../../orchestration-v2/AttachmentClaims.ts";
 import * as Project from "../../../project/ProjectService.ts";
 import * as ManagedProjectFolders from "../../../project/ManagedProjectFolders.ts";
 import * as Repositories from "../../../sourceControl/SourceControlRepositoryService.ts";
-import { resolveRuntimeMode } from "../../OrchestratorMcpService.ts";
+import * as GitVcsDriver from "../../../vcs/GitVcsDriver.ts";
-import {
+import * as McpToolAccess from "../../McpToolAccess.ts";
-  newCommandId,
+import { newCommandId, readCaller, resolveProjectId, unavailable } from "../../threadAccess.ts";
-  readCaller,
-  readFullAccessCaller,
-  readMutationCaller,
-  resolveProjectId,
-  unavailable,
-} from "../../threadAccess.ts";
 import { ProjectToolkit } from "./tools.ts";
 function projectFailure(error: Project.ProjectServiceError) {
 @@ -28,121 +23,137 @@ function projectFailure(error: Project.ProjectServiceError) {
   return new OrchestratorMcpFailure({ code: "invalid_request", message });
 }
+/**
+ * An existing checkout a launch may bind: one of the project's own git
+ * worktrees. Without this check a launch could point an agent at any directory
+ * on the machine.
+ */
+const assertProjectWorktree = Effect.fn("mcp.assertProjectWorktree")(function* (
+  workspaceRoot: string,
+  worktreePath: string,
+) {
+  const git = yield* GitVcsDriver.GitVcsDriver;
+  const fileSystem = yield* FileSystem.FileSystem;
+  const real = (path: string) => fileSystem.realPath(path).pipe(Effect.orElseSucceed(() => path));
+  const worktrees = yield* git.listWorktreePaths(workspaceRoot).pipe(
+    Effect.flatMap((paths) => Effect.forEach(paths, real)),
+    Effect.orElseSucceed((): ReadonlyArray<string> => []),
+  );
+  if (!worktrees.includes(yield* real(worktreePath)))
+    return yield* new OrchestratorMcpFailure({
+      code: "invalid_request",
+      message:
+        "worktreePath must be one of the project's git worktrees. t3_worktree_list shows them.",
+    });
+});
 const access = Effect.gen(function* () {
   yield* readCaller();
   return yield* Project.ProjectService;
 });
-const mutation = Effect.gen(function* () {
+export const layer = McpToolAccess.toLayer(ProjectToolkit, {
-  yield* readFullAccessCaller(
+  t3_thread_launch: McpToolAccess.startsThreads(
-    "Project changes require a live full-access/default calling thread or a full-access client.",
+    (input) => input,
-  );
+    (input, { runtimeMode, interactionMode }) =>
-  return yield* Project.ProjectService;
+      Effect.gen(function* () {
-});
+        const context = yield* readCaller();
-export const layer = ProjectToolkit.toLayer({
+        const { caller } = context;
-  t3_thread_launch: (input) =>
+        const commandId = yield* newCommandId();
-    Effect.gen(function* () {
+        const threadId = ThreadId.make(commandId);
-      const context = yield* readMutationCaller();
+        const messageId = MessageId.make(commandId);
-      const { caller, limits } = context;
+        const attachments = input.attachments ?? [];
-      // A thread caller launches only as itself (full-access/default), as before. A client
+        if (attachments.some((attachment) => !Claims.attachmentIsPendingUpload(attachment)))
-      // launches anything up to its ceiling.
+          return yield* new OrchestratorMcpFailure({
-      if (
+            code: "invalid_request",
-        caller !== undefined &&
+            message: "A new thread accepts only pending attachment uploads.",
-        (caller.runtimeMode !== "full-access" || caller.interactionMode !== "default")
+          });
-      )
+        if (
-        return yield* new OrchestratorMcpFailure({
+          input.scratch === true &&
-          code: "capability_denied",
+          (input.projectId !== undefined || input.workspaceStrategy !== undefined)
-          message: "Project launches require a full-access/default calling thread.",
+        )
-        });
+          return yield* new OrchestratorMcpFailure({
-      const runtimeMode = yield* resolveRuntimeMode(
+            code: "invalid_request",
-        limits.runtimeMode,
+            message:
-        input.runtimeMode ?? caller?.runtimeMode,
+              "scratch:true picks its own project and folder; omit projectId and workspaceStrategy.",
-      );
+          });
-      const commandId = yield* newCommandId();
+        const projectId =
-      const threadId = ThreadId.make(commandId);
+          input.scratch === true
-      const messageId = MessageId.make(commandId);
+            ? (yield* ManagedProjectFolders.ManagedProjectFolders.pipe(
-      const attachments = input.attachments ?? [];
+                Effect.flatMap((folders) => folders.ensureScratchProject),
-      if (attachments.some((attachment) => !Claims.attachmentIsPendingUpload(attachment)))
+                Effect.mapError(
-        return yield* new OrchestratorMcpFailure({
+                  (error) =>
-          code: "invalid_request",
+                    new OrchestratorMcpFailure({
-          message: "A new thread accepts only pending attachment uploads.",
+                      code: "orchestration_error",
-        });
+                      message: error.message,
-      if (
+                    }),
-        input.scratch === true &&
+                ),
-        (input.projectId !== undefined || input.workspaceStrategy !== undefined)
+              )).projectId
-      )
+            : yield* resolveProjectId(context, input.projectId);
-        return yield* new OrchestratorMcpFailure({
+        const readProject = Project.ProjectService.pipe(
-          code: "invalid_request",
-          message:
-            "scratch:true picks its own project and folder; omit projectId and workspaceStrategy.",
-        });
-      const projectId =
-        input.scratch === true
-          ? (yield* ManagedProjectFolders.ManagedProjectFolders.pipe(
-              Effect.flatMap((folders) => folders.ensureScratchProject),
-              Effect.mapError(
-                (error) =>
-                  new OrchestratorMcpFailure({
-                    code: "orchestration_error",
-                    message: error.message,
-                  }),
-              ),
-            )).projectId
-          : yield* resolveProjectId(context, input.projectId);
-      const modelSelection =
-        input.modelSelection ??
-        caller?.modelSelection ??
-        (yield* Project.ProjectService.pipe(
           Effect.flatMap((projects) => projects.getById(projectId)),
           Effect.mapError(unavailable),
-          Effect.map((project) =>
+          Effect.map(Option.getOrUndefined),
-            Option.getOrUndefined(Option.flatMapNullishOr(project, (p) => p.defaultModelSelection)),
+        );
+        if (input.workspaceStrategy?.type === "existing_worktree") {
+          const project = yield* readProject;
+          if (project === undefined)
+            return yield* new OrchestratorMcpFailure({
+              code: "invalid_request",
+              message: "The project was not found.",
+            });
+          yield* assertProjectWorktree(project.workspaceRoot, input.workspaceStrategy.worktreePath);
+        }
+        const modelSelection =
+          input.modelSelection ??
+          caller?.modelSelection ??
+          (yield* readProject)?.defaultModelSelection ??
+          undefined;
+        if (modelSelection === undefined)
+          return yield* new OrchestratorMcpFailure({
+            code: "invalid_request",
+            message:
+              "Pass modelSelection: the project has no default model. orchestrator_capabilities lists providers and models.",
+          });
+        const result = yield* ThreadMessageIntake.launchThread({
+          commandId,
+          threadId,
+          projectId,
+          title: input.title,
+          modelSelection,
+          runtimeMode,
+          interactionMode,
+          workspaceStrategy: input.workspaceStrategy ?? { type: "root" },
+          ...(input.message === undefined && attachments.length === 0
+            ? {}
+            : {
+                initialMessage: {
+                  messageId,
+                  ...(caller === undefined ? {} : { senderThreadId: caller.id }),
+                  text: input.message ?? "",
+                  attachments,
+                },
+              }),
+          createdBy: "agent",
+          creationSource: "mcp",
+        }).pipe(
+          Effect.mapError((error) =>
+            error._tag === "AttachmentClaimError"
+              ? new OrchestratorMcpFailure({ code: "orchestration_error", message: error.message })
+              : unavailable(),
           ),
-        ));
+        );
-      if (modelSelection === undefined)
+        const thread = result.projection.thread;
-        return yield* new OrchestratorMcpFailure({
+        const run = result.projection.runs.find((run) => run.userMessageId === messageId);
-          code: "invalid_request",
+        return {
-          message:
+          threadId: thread.id,
-            "Pass modelSelection: the project has no default model. orchestrator_capabilities lists providers and models.",
+          projectId: thread.projectId,
-        });
+          modelSelection: thread.modelSelection,
-      const result = yield* ThreadMessageIntake.launchThread({
+          runId: run?.id ?? null,
-        commandId,
+          status: run?.status ?? null,
-        threadId,
+        };
-        projectId,
+      }),
-        title: input.title,
+  ),
-        modelSelection,
+  t3_project_list: McpToolAccess.reads((input) =>
-        runtimeMode,
-        interactionMode: input.interactionMode ?? caller?.interactionMode ?? "default",
-        workspaceStrategy: input.workspaceStrategy ?? { type: "root" },
-        ...(input.message === undefined && attachments.length === 0
-          ? {}
-          : {
-              initialMessage: {
-                messageId,
-                ...(caller === undefined ? {} : { senderThreadId: caller.id }),
-                text: input.message ?? "",
-                attachments,
-              },
-            }),
-        createdBy: "agent",
-        creationSource: "mcp",
-      }).pipe(
-        Effect.mapError((error) =>
-          error._tag === "AttachmentClaimError"
-            ? new OrchestratorMcpFailure({ code: "orchestration_error", message: error.message })
-            : unavailable(),
-        ),
-      );
-      const thread = result.projection.thread;
-      const run = result.projection.runs.find((run) => run.userMessageId === messageId);
-      return {
-        threadId: thread.id,
-        projectId: thread.projectId,
-        modelSelection: thread.modelSelection,
-        runId: run?.id ?? null,
-        status: run?.status ?? null,
-      };
-    }),
-  t3_project_list: (input) =>
     Effect.gen(function* () {
       const projects = yield* access;
       const snapshot = yield* projects.snapshot.pipe(Effect.mapError(unavailable));
 @@ -151,7 +162,8 @@ export const layer = ProjectToolkit.toLayer({
         end = start + (input.limit ?? 20);
       return { projects: rows.slice(start, end), nextCursor: end < rows.length ? end : null };
     }),
-  t3_project_read: (input) =>
+  ),
+  t3_project_read: McpToolAccess.reads((input) =>
     Effect.gen(function* () {
       const projects = yield* access;
       const result = yield* projects.getById(input.projectId).pipe(Effect.mapError(unavailable));
 @@ -162,9 +174,10 @@ export const layer = ProjectToolkit.toLayer({
         });
       return result.value;
     }),
-  t3_project_create: ({ workspaceRoot, ...input }) =>
+  ),
+  t3_project_create: McpToolAccess.writesEnvironment(({ workspaceRoot, ...input }) =>
     Effect.gen(function* () {
-      const projects = yield* mutation;
+      const projects = yield* Project.ProjectService;
       if (workspaceRoot === undefined) {
         // Project creation records no model default (only an update does), so
         // reject what this mode would otherwise drop silently.
 @@ -205,23 +218,25 @@ export const layer = ProjectToolkit.toLayer({
         .create({ ...input, workspaceRoot, commandId, projectId: ProjectId.make(commandId) })
         .pipe(Effect.mapError(projectFailure));
     }),
-  t3_project_update: (input) =>
+  ),
+  t3_project_update: McpToolAccess.writesEnvironment((input) =>
     Effect.gen(function* () {
-      const projects = yield* mutation;
+      const projects = yield* Project.ProjectService;
       return yield* projects
         .update({ ...input, commandId: yield* newCommandId() })
         .pipe(Effect.mapError(projectFailure));
     }),
-  t3_project_delete: (input) =>
+  ),
+  t3_project_delete: McpToolAccess.writesEnvironment((input) =>
     Effect.gen(function* () {
-      const projects = yield* mutation;
+      const projects = yield* Project.ProjectService;
       return yield* projects
         .delete({ ...input, commandId: yield* newCommandId() })
         .pipe(Effect.mapError(projectFailure));
     }),
-  t3_project_clone: (input) =>
+  ),
+  t3_project_clone: McpToolAccess.writesEnvironment((input) =>
     Effect.gen(function* () {
-      yield* mutation;
       const repositories = yield* Repositories.SourceControlRepositoryService;
       return yield* repositories.cloneRepository(input).pipe(
         Effect.mapError(
 @@ -233,4 +248,5 @@ export const layer = ProjectToolkit.toLayer({
         ),
       );
     }),
+  ),
 });

apps/server/src/mcp/toolkits/project/tools.ts+4-2

...	@@ -27,6 +27,7 @@ import * as ProjectService from "../../../project/ProjectService.ts";	...	@@ -27,6 +27,7 @@ import * as ProjectService from "../../../project/ProjectService.ts";
27	import * as ManagedProjectFolders from "../../../project/ManagedProjectFolders.ts";	27	import * as ManagedProjectFolders from "../../../project/ManagedProjectFolders.ts";
28	import * as ThreadManagementService from "../../../orchestration-v2/ThreadManagementService.ts";	28	import * as ThreadManagementService from "../../../orchestration-v2/ThreadManagementService.ts";
29	import * as SourceControlRepositoryService from "../../../sourceControl/SourceControlRepositoryService.ts";	29	import * as SourceControlRepositoryService from "../../../sourceControl/SourceControlRepositoryService.ts";
		30	import * as GitVcsDriver from "../../../vcs/GitVcsDriver.ts";
30	import * as McpInvocationContext from "../../McpInvocationContext.ts";	31	import * as McpInvocationContext from "../../McpInvocationContext.ts";
31		32
32	const shared = {	33	const shared = {
...	@@ -102,7 +103,7 @@ const ProjectCloneTool = Tool.make("t3_project_clone", {	...	@@ -102,7 +103,7 @@ const ProjectCloneTool = Tool.make("t3_project_clone", {
102	const ThreadLaunchTool = Tool.make("t3_thread_launch", {	103	const ThreadLaunchTool = Tool.make("t3_thread_launch", {
103	...shared,	104	...shared,
104	description:	105	description:
105	'Create an ordinary TOP-LEVEL thread with an explicit workspace binding before its agent starts. Use this when the user requests independent work, a new thread, or a PR stack in its own worktree; use delegate_task for child subagents. Set workspaceStrategy to {type:"worktree",baseRef:"parent-branch",branch:"new-branch",startFromOrigin:false} for a new worktree based on local commits, or {type:"existing_worktree",worktreePath:"/absolute/path",branch:"existing-branch"} to use an existing checkout. For upstream commits, set startFromOrigin:true. Omitted workspaceStrategy means the project root, NOT the caller\'s worktree. Omit projectId/modelSelection/modes to inherit those settings from the calling thread; a caller outside a T3 thread must pass projectId and gets the project\'s default model. Set scratch:true instead of projectId for a thread without a project: it runs in a fresh folder of its own, outside any repository. Put the task in message. Do not ask the agent to create its own worktree via shell: that does not update the thread binding. Each call creates a new launch with no retry key; retain threadId and use t3_thread_read/t3_thread_wait to follow preparation. After errors or lost responses, inspect t3_thread_list before retrying. Attachments must be pending uploads. Requires a full-access/default calling thread; a caller outside a T3 thread launches up to its approved permission mode.',	106	'Create an ordinary TOP-LEVEL thread with an explicit workspace binding before its agent starts. Use this when the user requests independent work, a new thread, or a PR stack in its own worktree; use delegate_task for child subagents. Set workspaceStrategy to {type:"worktree",baseRef:"parent-branch",branch:"new-branch",startFromOrigin:false} for a new worktree based on local commits, or {type:"existing_worktree",worktreePath:"/absolute/path",branch:"existing-branch"} to use an existing checkout. For upstream commits, set startFromOrigin:true. Omitted workspaceStrategy means the project root, NOT the caller\'s worktree. Omit projectId/modelSelection/modes to inherit those settings from the calling thread; a caller outside a T3 thread must pass projectId and gets the project\'s default model. Set scratch:true instead of projectId for a thread without a project: it runs in a fresh folder of its own, outside any repository. Put the task in message. Do not ask the agent to create its own worktree via shell: that does not update the thread binding. Each call creates a new launch with no retry key; retain threadId and use t3_thread_read/t3_thread_wait to follow preparation. After errors or lost responses, inspect t3_thread_list before retrying. Attachments must be pending uploads. The new thread may not run with broader runtime or interaction modes than the caller: the calling T3 thread\'s own modes, or the permission mode an outside agent was approved with.',
106	parameters: Schema.Struct({	107	parameters: Schema.Struct({
107	projectId: Schema.optional(ProjectId),	108	projectId: Schema.optional(ProjectId),
108	scratch: Schema.optional(	109	scratch: Schema.optional(
...	@@ -118,7 +119,7 @@ const ThreadLaunchTool = Tool.make("t3_thread_launch", {	...	@@ -118,7 +119,7 @@ const ThreadLaunchTool = Tool.make("t3_thread_launch", {
118	workspaceStrategy: Schema.optional(	119	workspaceStrategy: Schema.optional(
119	OrchestrationV2ThreadLaunchWorkspaceStrategy.annotate({	120	OrchestrationV2ThreadLaunchWorkspaceStrategy.annotate({
120	description:	121	description:
121	"Choose where this thread runs before starting its agent: worktree creates and binds a new checkout from baseRef; existing_worktree binds worktreePath; root uses the project checkout. Omitted means root, not the caller's worktree. For a PR stack use the parent branch as baseRef and startFromOrigin:false. Uncommitted changes are not copied.",	122	"Choose where this thread runs before starting its agent: worktree creates and binds a new checkout from baseRef; existing_worktree binds worktreePath, which must be one of the project's git worktrees; root uses the project checkout. Omitted means root, not the caller's worktree. For a PR stack use the parent branch as baseRef and startFromOrigin:false. Uncommitted changes are not copied.",
122	}),	123	}),
123	),	124	),
124	message: Schema.optional(	125	message: Schema.optional(
...	@@ -140,6 +141,7 @@ const ThreadLaunchTool = Tool.make("t3_thread_launch", {	...	@@ -140,6 +141,7 @@ const ThreadLaunchTool = Tool.make("t3_thread_launch", {
140	...shared.dependencies,	141	...shared.dependencies,
141	ThreadLaunchService.ThreadLaunchService,	142	ThreadLaunchService.ThreadLaunchService,
142	ManagedProjectFolders.ManagedProjectFolders,	143	ManagedProjectFolders.ManagedProjectFolders,
		144	GitVcsDriver.GitVcsDriver,
143	FileSystem.FileSystem,	145	FileSystem.FileSystem,
144	ServerConfig.ServerConfig,	146	ServerConfig.ServerConfig,
145	],	147	],

apps/server/src/mcp/toolkits/pullRequests/handlers.test.ts+8-1

 @@ -23,6 +23,8 @@ import {
 } from "../../../orchestration-v2/testkit/pullRequestFixtures.ts";
 import * as ProjectService from "../../../project/ProjectService.ts";
 import * as McpInvocationContext from "../../McpInvocationContext.ts";
+import * as McpToolAccess from "../../McpToolAccess.ts";
+import * as McpToolAccessTestkit from "../../McpToolAccess.testkit.ts";
 import { listThreadPullRequests } from "./handlers.ts";
 import * as PullRequestsHandlers from "./handlers.ts";
 import { PullRequestLinkFailedError, PullRequestsToolkit } from "./tools.ts";
 @@ -163,9 +165,14 @@ const makeHarness = Effect.fn("makePullRequestsToolkitHarness")(function* (
       dispatch,
     }),
     Layer.succeed(Crypto.Crypto, testCrypto),
+    McpToolAccessTestkit.liveThreadsLayer,
   );
   const toolkit = yield* PullRequestsToolkit.pipe(
-    Effect.provide(PullRequestsHandlers.layer.pipe(Layer.provide(layerDependencies))),
+    Effect.provide(
+      McpToolAccess.HandlersLayer.layer(PullRequestsHandlers.layer).pipe(
+        Layer.provide(layerDependencies),
+      ),
+    ),
   );
   const call = <Name extends keyof typeof PullRequestsToolkit.tools>(
     name: Name,

apps/server/src/mcp/toolkits/pullRequests/handlers.ts+20-54

 @@ -26,7 +26,7 @@ import * as Option from "effect/Option";
 import * as Orchestrator from "../../../orchestration-v2/Orchestrator.ts";
 import * as ProjectService from "../../../project/ProjectService.ts";
 import * as McpInvocationContext from "../../McpInvocationContext.ts";
-import { assertTargetWithinLimits } from "../../threadAccess.ts";
+import * as McpToolAccess from "../../McpToolAccess.ts";
 import {
   type ListThreadPullRequestsResult,
   PullRequestLinkFailedError,
 @@ -40,7 +40,6 @@ import {
   PullRequestWatchFailedError,
   PullRequestWatchFromSubagentError,
   PullRequestThreadNotFoundError,
-  PullRequestThreadAboveLimitsError,
   PullRequestThreadRequiredError,
   PullRequestsToolkit,
   type ThreadPullRequestEntry,
 @@ -189,47 +188,6 @@ const make = Effect.gen(function* () {
     return thread.value;
   });
-  /**
-   * A thread whose pull requests the caller may change: its own, or one that
-   * runs within the caller's modes.
-   */
-  const requireWritableThread = Effect.fn("PullRequestsToolkit.requireWritableThread")(function* (
-    Failure:
-      | typeof PullRequestLinkFailedError
-      | typeof PullRequestUnlinkFailedError
-      | typeof PullRequestWatchFailedError,
-    requested: ThreadId | undefined,
-  ) {
-    const thread = yield* requireThread(Failure, requested);
-    const scope = yield* McpInvocationContext.McpInvocationContext;
-    if (thread.id === scope.thread?.threadId) return thread;
-    const limits =
-      scope.thread === undefined
-        ? {
-            runtimeMode: scope.client?.runtimeModeCeiling ?? ("approval-required" as const),
-            interactionMode: "default" as const,
-          }
-        : yield* engine.getThreadShell(scope.thread.threadId).pipe(
-            Effect.mapError((cause) => new Failure({ cause })),
-            Effect.map((caller) =>
-              // A thread caller changes other threads only while its own run is live.
-              caller === null ||
-              caller.archivedAt !== null ||
-              caller.activeRunId === null ||
-              caller.providerInstanceId !== scope.thread?.providerInstanceId
-                ? undefined
-                : { runtimeMode: caller.runtimeMode, interactionMode: caller.interactionMode },
-            ),
-          );
-    if (limits === undefined) {
-      return yield* new PullRequestThreadAboveLimitsError({ threadId: thread.id });
-    }
-    yield* assertTargetWithinLimits(limits, thread).pipe(
-      Effect.mapError(() => new PullRequestThreadAboveLimitsError({ threadId: thread.id })),
-    );
-    return thread;
-  });
   const projectOf = (
     thread: OrchestrationV2ThreadShell,
     Failure:
 @@ -267,7 +225,7 @@ const make = Effect.gen(function* () {
     input: PullRequestTargetInput,
     watching: boolean,
   ) {
-    const thread = yield* requireWritableThread(PullRequestWatchFailedError, input.threadId);
+    const thread = yield* requireThread(PullRequestWatchFailedError, input.threadId);
     const project = yield* projectOf(thread, PullRequestWatchFailedError);
     const target = yield* resolveTarget(input, project);
     const watchedLink = (shell: OrchestrationV2ThreadShell) =>
 @@ -306,10 +264,15 @@ const make = Effect.gen(function* () {
     };
   });
-  return PullRequestsToolkit.of({
+  /** A tool that changes `threadId`, or the caller's own thread when it is omitted. */
-    link_pull_request: (input) =>
+  const writesThread = <P extends { readonly threadId?: ThreadId | undefined }, A, E, R>(
+    handle: (params: P) => Effect.Effect<A, E, R>,
+  ) => McpToolAccess.writesThreads((params: P) => [params.threadId], handle);
+  return {
+    link_pull_request: writesThread((input) =>
       Effect.gen(function* () {
-        const thread = yield* requireWritableThread(PullRequestLinkFailedError, input.threadId);
+        const thread = yield* requireThread(PullRequestLinkFailedError, input.threadId);
         const project = yield* projectOf(thread, PullRequestLinkFailedError);
         const target = yield* resolveTarget(input, project);
         const existing = threadPullRequestsOf(thread).find((link) =>
 @@ -337,9 +300,10 @@ const make = Effect.gen(function* () {
           );
         return { ...target, alreadyLinked };
       }),
-    unlink_pull_request: (input) =>
+    ),
+    unlink_pull_request: writesThread((input) =>
       Effect.gen(function* () {
-        const thread = yield* requireWritableThread(PullRequestUnlinkFailedError, input.threadId);
+        const thread = yield* requireThread(PullRequestUnlinkFailedError, input.threadId);
         const project = yield* projectOf(thread, PullRequestUnlinkFailedError);
         const target = yield* resolveTarget(input, project);
         if (!threadPullRequestsOf(thread).some((link) => threadPullRequestKeysEqual(link, target)))
 @@ -370,13 +334,15 @@ const make = Effect.gen(function* () {
           wasLinked,
         };
       }),
-    list_thread_pull_requests: (input) =>
+    ),
+    list_thread_pull_requests: McpToolAccess.reads((input) =>
       requireThread(PullRequestListFailedError, input.threadId).pipe(
         Effect.map(listThreadPullRequests),
       ),
-    watch_pull_request: (input) => setWatching(input, true),
+    ),
-    unwatch_pull_request: (input) => setWatching(input, false),
+    watch_pull_request: writesThread((input) => setWatching(input, true)),
-  });
+    unwatch_pull_request: writesThread((input) => setWatching(input, false)),
+  } satisfies McpToolAccess.Handlers<typeof PullRequestsToolkit.tools>;
 });
-export const layer = PullRequestsToolkit.toLayer(make);
+export const layer = McpToolAccess.toLayer(PullRequestsToolkit, make);

apps/server/src/mcp/toolkits/pullRequests/tools.ts+4-10

 @@ -1,5 +1,6 @@
 import {
   McpCapabilityUnavailableError,
+  OrchestratorMcpFailure,
   PositiveInt,
   PullRequestState,
   ThreadPullRequestLinkSource,
 @@ -12,10 +13,12 @@ import * as Toolkit from "effect/ai/Toolkit";
 import * as McpInvocationContext from "../../McpInvocationContext.ts";
 import * as Orchestrator from "../../../orchestration-v2/Orchestrator.ts";
+import * as ThreadManagementService from "../../../orchestration-v2/ThreadManagementService.ts";
 import * as ProjectService from "../../../project/ProjectService.ts";
 const dependencies = [
   McpInvocationContext.McpInvocationContext,
+  ThreadManagementService.ThreadManagementService,
   Orchestrator.OrchestratorV2,
   ProjectService.ProjectService,
 ];
 @@ -96,15 +99,6 @@ export class PullRequestThreadRequiredError extends Schema.TaggedError<PullReque
   }
 }
-export class PullRequestThreadAboveLimitsError extends Schema.TaggedError<PullRequestThreadAboveLimitsError>()(
-  "PullRequestThreadAboveLimitsError",
-  { threadId: Schema.String },
-) {
-  override get message(): string {
-    return `Thread ${this.threadId} cannot be changed from here: it runs with broader permissions than this caller, or the calling thread has no active run.`;
-  }
-}
 export class PullRequestThreadNotFoundError extends Schema.TaggedError<PullRequestThreadNotFoundError>()(
   "PullRequestThreadNotFoundError",
   { threadId: Schema.String },
 @@ -169,12 +163,12 @@ export class PullRequestListFailedError extends Schema.TaggedError<PullRequestLi
 }
 export const PullRequestToolError = Schema.Union([
+  OrchestratorMcpFailure,
   McpCapabilityUnavailableError,
   PullRequestUrlInvalidError,
   PullRequestTargetIncompleteError,
   PullRequestHostRequiredError,
   PullRequestThreadRequiredError,
-  PullRequestThreadAboveLimitsError,
   PullRequestThreadNotFoundError,
   PullRequestLinkFailedError,
   PullRequestUnlinkFailedError,

apps/server/src/mcp/toolkits/thread/handlers.ts+69-54

 @@ -10,13 +10,12 @@ import {
 import * as Effect from "effect/Effect";
 import { modelSelectionCommandType } from "@t3tools/shared/model";
+import * as McpToolAccess from "../../McpToolAccess.ts";
 import {
   dispatchFailure,
   newCommandId,
   readCaller,
-  readFullAccessCaller,
   readThread,
-  readWritableThread,
   unavailable,
 } from "../../threadAccess.ts";
 import * as ThreadSearch from "../../../orchestration-v2/ThreadSearch.ts";
 @@ -43,23 +42,18 @@ const dispatch = Effect.fn("mcp.dispatchThreadCommand")(function* (
   threadId: ThreadId | undefined,
   command: (common: { commandId: CommandId; threadId: ThreadId }) => OrchestrationV2Command,
 ) {
-  const { threads, projection } = yield* readWritableThread(threadId);
+  const { threads, projection } = yield* readThread(threadId);
   const result = yield* threads
     .dispatch(command({ commandId: yield* newCommandId(), threadId: projection.thread.id }))
     .pipe(Effect.mapError(dispatchFailure));
   return { sequence: result.sequence };
 });
-const readQuestion = Effect.fn("mcp.readQuestion")(function* (
+const readQuestion = Effect.fn("mcp.readQuestion")(function* (input: {
-  input: {
+  threadId?: ThreadId | undefined;
-    threadId?: ThreadId | undefined;
+  requestId: RuntimeRequestId;
-    requestId: RuntimeRequestId;
+}) {
-  },
+  const context = yield* readThread(input.threadId, ["runtimeRequests", "turnItems"]);
-  writable = false,
-) {
-  const context = yield* writable
-    ? readWritableThread(input.threadId, ["runtimeRequests", "turnItems"])
-    : readThread(input.threadId, ["runtimeRequests", "turnItems"]);
   const request = context.projection.runtimeRequests.find(
     (request) =>
       request.id === input.requestId &&
 @@ -76,12 +70,14 @@ const readQuestion = Effect.fn("mcp.readQuestion")(function* (
     });
   return { ...context, request, item };
 });
-export const layer = ThreadToolkit.toLayer({
+/** A tool that changes `threadId`, or the caller's own thread when it is omitted. */
-  run_scheduled_task_now: (input) =>
+const writesThread = <P extends { readonly threadId?: ThreadId | undefined }, A, E, R>(
+  handle: (params: P) => Effect.Effect<A, E, R>,
+) => McpToolAccess.writesThreads((params: P) => [params.threadId], handle);
+export const layer = McpToolAccess.toLayer(ThreadToolkit, {
+  run_scheduled_task_now: McpToolAccess.writesEnvironment((input) =>
     Effect.gen(function* () {
-      yield* readFullAccessCaller(
-        "Running a scheduled task requires a live full-access/default thread or a full-access client.",
-      );
       const scheduler = yield* ScheduledTasks.ScheduledTaskService;
       const { tasks } = yield* scheduler.list().pipe(Effect.mapError(unavailable));
       if (!tasks.some((task) => task.id === input.taskId))
 @@ -100,7 +96,8 @@ export const layer = ThreadToolkit.toLayer({
         nextRunAt: task.nextRunAt,
       };
     }),
-  t3_thread_search: (input) =>
+  ),
+  t3_thread_search: McpToolAccess.reads((input) =>
     Effect.gen(function* () {
       const { caller } = yield* readCaller();
       const { projectId: requested, ...query } = input;
 @@ -116,9 +113,10 @@ export const layer = ThreadToolkit.toLayer({
             : result.matches.filter((match) => match.projectId === projectId),
       };
     }),
-  t3_thread_fork: (input) =>
+  ),
+  t3_thread_fork: writesThread((input) =>
     Effect.gen(function* () {
-      const { threads, projection } = yield* readWritableThread(input.threadId);
+      const { threads, projection } = yield* readThread(input.threadId);
       const commandId = yield* newCommandId();
       const targetThreadId = ThreadId.make(`${commandId}:fork`);
       const result = yield* threads
 @@ -135,24 +133,28 @@ export const layer = ThreadToolkit.toLayer({
         .pipe(Effect.mapError(dispatchFailure));
       return { sequence: result.sequence, targetThreadId };
     }),
-  t3_thread_merge_back: (input) =>
+  ),
-    Effect.gen(function* () {
+  t3_thread_merge_back: McpToolAccess.writesThreads(
-      const context = yield* readWritableThread(input.targetThreadId);
+    (input) => [input.targetThreadId, input.sourceThreadId],
-      const source = yield* readWritableThread(input.sourceThreadId);
+    (input) =>
-      const result = yield* context.threads
+      Effect.gen(function* () {
-        .dispatch({
+        const context = yield* readThread(input.targetThreadId);
-          type: "thread.merge_back",
+        const source = yield* readThread(input.sourceThreadId);
-          commandId: yield* newCommandId(),
+        const result = yield* context.threads
-          sourceThreadId: source.projection.thread.id,
+          .dispatch({
-          targetThreadId: input.targetThreadId,
+            type: "thread.merge_back",
-          sourcePoint: input.sourcePoint,
+            commandId: yield* newCommandId(),
-          createdBy: "agent",
+            sourceThreadId: source.projection.thread.id,
-          creationSource: "mcp",
+            targetThreadId: input.targetThreadId,
-        })
+            sourcePoint: input.sourcePoint,
-        .pipe(Effect.mapError(dispatchFailure));
+            createdBy: "agent",
-      return { sequence: result.sequence, targetThreadId: input.targetThreadId };
+            creationSource: "mcp",
-    }),
+          })
-  t3_thread_transfers: (input) =>
+          .pipe(Effect.mapError(dispatchFailure));
+        return { sequence: result.sequence, targetThreadId: input.targetThreadId };
+      }),
+  ),
+  t3_thread_transfers: McpToolAccess.reads((input) =>
     Effect.gen(function* () {
       const { projection } = yield* readThread(input.threadId, ["contextTransfers"]);
       return {
 @@ -166,7 +168,8 @@ export const layer = ThreadToolkit.toLayer({
         ),
       };
     }),
-  t3_thread_configuration: (input) =>
+  ),
+  t3_thread_configuration: McpToolAccess.reads((input) =>
     Effect.gen(function* () {
       const {
         projection: { thread },
 @@ -178,12 +181,13 @@ export const layer = ThreadToolkit.toLayer({
         interactionMode: thread.interactionMode,
       };
     }),
-  t3_thread_configure: (input) =>
+  ),
+  t3_thread_configure: writesThread((input) =>
     Effect.gen(function* () {
       const {
         threads,
         projection: { thread },
-      } = yield* readWritableThread(input.threadId);
+      } = yield* readThread(input.threadId);
       const type = modelSelectionCommandType(thread.providerInstanceId, input.modelSelection);
       const result = yield* threads
         .dispatch({
 @@ -195,7 +199,8 @@ export const layer = ThreadToolkit.toLayer({
         .pipe(Effect.mapError(dispatchFailure));
       return { sequence: result.sequence };
     }),
-  t3_pending_request_list: (input) =>
+  ),
+  t3_pending_request_list: McpToolAccess.reads((input) =>
     Effect.gen(function* () {
       const { projection } = yield* readThread(input.threadId, ["runtimeRequests"]);
       return {
 @@ -204,14 +209,16 @@ export const layer = ThreadToolkit.toLayer({
           .map((request) => request.id),
       };
     }),
-  t3_pending_request_read: (input) =>
+  ),
+  t3_pending_request_read: McpToolAccess.reads((input) =>
     Effect.gen(function* () {
       const { item } = yield* readQuestion(input);
       return { requestId: input.requestId, questions: item.questions };
     }),
-  t3_pending_request_respond: (input) =>
+  ),
+  t3_pending_request_respond: writesThread((input) =>
     Effect.gen(function* () {
-      const { threads, projection } = yield* readQuestion(input, true);
+      const { threads, projection } = yield* readQuestion(input);
       const result = yield* threads
         .dispatch({
           type: "runtime-request.respond",
 @@ -223,7 +230,8 @@ export const layer = ThreadToolkit.toLayer({
         .pipe(Effect.mapError(dispatchFailure));
       return { sequence: result.sequence };
     }),
-  t3_queue_list: (input) =>
+  ),
+  t3_queue_list: McpToolAccess.reads((input) =>
     Effect.gen(function* () {
       const { projection } = yield* readThread(input.threadId, ["runs", "messages"]);
       const runs = queuedRunsInDeliveryOrder(projection);
 @@ -237,7 +245,8 @@ export const layer = ThreadToolkit.toLayer({
         nextCursor: end < runs.length ? end : null,
       };
     }),
-  t3_queue_read: (input) =>
+  ),
+  t3_queue_read: McpToolAccess.reads((input) =>
     Effect.gen(function* () {
       const { projection } = yield* readThread(input.threadId, ["runs", "messages"]);
       const entry = queueEntry(projection, input.queuedRunId, 16000);
 @@ -249,36 +258,41 @@ export const layer = ThreadToolkit.toLayer({
         }))
       );
     }),
-  t3_queue_edit: (input) =>
+  ),
+  t3_queue_edit: writesThread((input) =>
     dispatch(input.threadId, (common) => ({
       ...common,
       type: "queued-run.edit",
       runId: input.queuedRunId,
       text: input.text,
     })),
-  t3_queue_cancel: (input) =>
+  ),
+  t3_queue_cancel: writesThread((input) =>
     dispatch(input.threadId, (common) => ({
       ...common,
       type: "queued-run.cancel",
       runId: input.queuedRunId,
     })),
-  t3_queue_reorder: (input) =>
+  ),
+  t3_queue_reorder: writesThread((input) =>
     dispatch(input.threadId, (common) => ({
       ...common,
       type: "queued-run.reorder",
       runId: input.queuedRunId,
       beforeRunId: input.beforeRunId,
     })),
-  t3_queue_promote_to_steer: (input) =>
+  ),
+  t3_queue_promote_to_steer: writesThread((input) =>
     dispatch(input.threadId, (common) => ({
       ...common,
       type: "queued-message.promote-to-steer",
       queuedRunId: input.queuedRunId,
       targetRunId: input.targetRunId,
     })),
-  t3_thread_organize: (input) =>
+  ),
+  t3_thread_organize: writesThread((input) =>
     Effect.gen(function* () {
-      const { threads, projection } = yield* readWritableThread(input.threadId);
+      const { threads, projection } = yield* readThread(input.threadId);
       const common = { commandId: yield* newCommandId(), threadId: projection.thread.id };
       let command: OrchestrationV2Command;
       switch (input.action) {
 @@ -304,4 +318,5 @@ export const layer = ThreadToolkit.toLayer({
       const result = yield* threads.dispatch(command).pipe(Effect.mapError(dispatchFailure));
       return { sequence: result.sequence };
     }),
+  ),
 });

apps/server/src/mcp/toolkits/worktree/handlers.ts+9-5

 @@ -6,11 +6,12 @@ import { readThread, unavailable } from "../../threadAccess.ts";
 import * as Effect from "effect/Effect";
 import * as McpInvocationContext from "../../McpInvocationContext.ts";
+import * as McpToolAccess from "../../McpToolAccess.ts";
 import * as WorktreeMcpService from "../../WorktreeMcpService.ts";
 import { WorktreeToolkit } from "./tools.ts";
 const handlers = {
-  t3_worktree_list: (input) =>
+  t3_worktree_list: McpToolAccess.reads((input) =>
     Effect.gen(function* () {
       const context = yield* McpInvocationContext.McpInvocationContext;
       if (!context.capabilities.has("worktree"))
 @@ -34,18 +35,21 @@ const handlers = {
         .listRefs({ ...refs, cwd: thread.worktreePath ?? project.value.workspaceRoot })
         .pipe(Effect.mapError(unavailable));
     }),
-  t3_worktree_handoff: (input) =>
+  ),
+  t3_worktree_handoff: McpToolAccess.actsAsCaller((input) =>
     Effect.gen(function* () {
       const scope = yield* McpInvocationContext.McpInvocationContext;
       const service = yield* WorktreeMcpService.WorktreeMcpService;
       return yield* service.handoff(scope, input);
     }),
-  t3_worktree_status: () =>
+  ),
+  t3_worktree_status: McpToolAccess.readsAsCaller(() =>
     Effect.gen(function* () {
       const scope = yield* McpInvocationContext.McpInvocationContext;
       const service = yield* WorktreeMcpService.WorktreeMcpService;
       return yield* service.status(scope);
     }),
-} satisfies Parameters<typeof WorktreeToolkit.toLayer>[0];
+  ),
+} satisfies McpToolAccess.Handlers<typeof WorktreeToolkit.tools>;
-export const layer = WorktreeToolkit.toLayer(handlers);
+export const layer = McpToolAccess.toLayer(WorktreeToolkit, handlers);

apps/server/src/mcp/toolkits/worktree/tools.ts+6-2

 @@ -19,15 +19,19 @@ import * as WorktreeMcpService from "../../WorktreeMcpService.ts";
 const dependencies = [
   McpInvocationContext.McpInvocationContext,
+  ThreadManagementService.ThreadManagementService,
   WorktreeMcpService.WorktreeMcpService,
 ];
+/** What handoff and status fail with, including the access gate's refusal. */
+const WorktreeToolFailure = Schema.Union([WorktreeMcpFailure, OrchestratorMcpFailure]);
 const WorktreeHandoffTool = Tool.make("t3_worktree_handoff", {
   description:
     "Needs an agent running inside a T3 thread. Move this agent thread into a new git worktree. To launch a separate agent already bound to a new or existing worktree, use t3_thread_launch with workspaceStrategy instead. Creates the worktree branch (optionally from origin), re-points the thread at the worktree, and by default runs the project's setup script there. Changing the workspace detaches the live provider session, so the current turn ends shortly after the handoff is recorded; call this as the last action of the turn. To keep working after the handoff, pass continuationPrompt with the remaining work: it is queued as the thread's next message and starts a new turn inside the worktree with the conversation preserved. Without it the thread stays idle until the next message. The worktree is not removed automatically when the thread is deleted. Fails if the thread is already attached to a worktree.",
   parameters: WorktreeMcpHandoffInput,
   success: WorktreeMcpHandoffResult,
-  failure: WorktreeMcpFailure,
+  failure: WorktreeToolFailure,
   failureMode: "return",
   dependencies,
 })
 @@ -45,7 +49,7 @@ const WorktreeStatusTool = Tool.make("t3_worktree_status", {
   // Schema.Struct({}) serializes to `anyOf: [object, array]`, which is not a
   // valid MCP tool input schema and makes clients reject the whole server.
   success: WorktreeMcpStatusResult,
-  failure: WorktreeMcpFailure,
+  failure: WorktreeToolFailure,
   failureMode: "return",
   dependencies,
 })

apps/server/src/orchestration-v2/DispatchModeLimit.test.ts created+167

...	@@ -0,0 +1,167 @@
1	import { assert, it } from "@effect/vitest";
2	import {
3	CommandId,
4	ProjectId,
5	ProviderDriverKind,
6	ProviderInstanceId,
7	ThreadId,
8	} from "@t3tools/contracts";
9	import * as Effect from "effect/Effect";
10	import * as Layer from "effect/Layer";
11	import * as SqlitePersistence from "../persistence/Sqlite.ts";
12	import { CodexProviderCapabilitiesV2 } from "./Adapters/CodexAdapterV2.ts";
13	import { DispatchModeLimit } from "./DispatchModeLimit.ts";
14	import * as Orchestrator from "./Orchestrator.ts";
15	import * as ProjectionStore from "./ProjectionStore.ts";
16	import type { ProviderAdapterV2Shape } from "./ProviderAdapter.ts";
17	import * as ProviderAdapterRegistry from "./ProviderAdapterRegistry.ts";
18	import * as ProviderReplayHarness from "./testkit/ProviderReplayHarness.ts";
19
20	const instanceId = ProviderInstanceId.make("codex");
21	const adapter = {
22	instanceId,
23	driver: ProviderDriverKind.make("codex"),
24	getCapabilities: () => Effect.succeed(CodexProviderCapabilitiesV2),
25	planSelectionTransition: () => Effect.succeed({ type: "apply_on_next_turn" as const }),
26	openSession: () => Effect.die("No provider process needed for metadata commands"),
27	} as ProviderAdapterV2Shape;
28	const layerDatabase = SqlitePersistence.layerMemory;
29	const layerTest = Layer.mergeAll(
30	layerDatabase,
31	ProjectionStore.layer.pipe(Layer.provide(layerDatabase)),
32	ProviderReplayHarness.layerWithRegistry(
33	{ name: "dispatch-mode-limit" },
34	ProviderAdapterRegistry.layerFromAdapters([adapter]),
35	{ databaseLayer: layerDatabase, runEffectWorker: false },
36	),
37	);
38
39	const supervised = { runtimeMode: "approval-required", interactionMode: "default" } as const;
40
41	const createThread = (threadId: ThreadId) =>
42	Effect.gen(function* () {
43	const orchestrator = yield* Orchestrator.OrchestratorV2;
44	yield* orchestrator.dispatch({
45	type: "thread.create",
46	commandId: CommandId.make(`create:${threadId}`),
47	threadId,
48	projectId: ProjectId.make("project:dispatch-mode-limit"),
49	title: "Before",
50	modelSelection: { instanceId, model: "gpt-5" },
51	...supervised,
52	branch: null,
53	worktreePath: null,
54	createdBy: "user",
55	creationSource: "web",
56	});
57	});
58
59	it.layer(layerTest)("DispatchModeLimit", (it) => {
60	it.effect("refuses a limited command on a thread its user raised, and records nothing", () =>
61	Effect.gen(function* () {
62	const orchestrator = yield* Orchestrator.OrchestratorV2;
63	const projections = yield* ProjectionStore.ProjectionStoreV2;
64	const threadId = ThreadId.make("thread:limit-raised");
65	yield* createThread(threadId);
66	// The user raises the thread; the user's own commands have no limit.
67	yield* orchestrator.dispatch({
68	type: "thread.runtime-mode.set",
69	commandId: CommandId.make("raise"),
70	threadId,
71	runtimeMode: "full-access",
72	});
73	const rename = {
74	type: "thread.metadata.update",
75	commandId: CommandId.make("rename"),
76	threadId,
77	title: "After",
78	} as const;
79	const refused = yield* orchestrator
80	.dispatch(rename)
81	.pipe(Effect.provideService(DispatchModeLimit, supervised), Effect.flip);
82	assert.equal(refused._tag, "OrchestratorThreadAboveModeLimitError");
83	assert.equal((yield* projections.getThreadShell(threadId))?.title, "Before");
84
85	// Refused before planning, so no receipt holds the command id: once the
86	// user lowers the thread again, the same command goes through.
87	yield* orchestrator.dispatch({
88	type: "thread.runtime-mode.set",
89	commandId: CommandId.make("lower"),
90	threadId,
91	runtimeMode: "approval-required",
92	});
93	yield* orchestrator
94	.dispatch(rename)
95	.pipe(Effect.provideService(DispatchModeLimit, supervised));
96	assert.equal((yield* projections.getThreadShell(threadId))?.title, "After");
97	}),
98	);
99
100	it.effect("names the interaction mode when that is what was raised", () =>
101	Effect.gen(function* () {
102	const orchestrator = yield* Orchestrator.OrchestratorV2;
103	const threadId = ThreadId.make("thread:limit-plan");
104	yield* createThread(threadId);
105	const refused = yield* orchestrator
106	.dispatch({
107	type: "thread.metadata.update",
108	commandId: CommandId.make("rename-plan"),
109	threadId,
110	title: "After",
111	})
112	.pipe(
113	Effect.provideService(DispatchModeLimit, {
114	runtimeMode: "full-access",
115	interactionMode: "plan",
116	}),
117	Effect.flip,
118	);
119	assert.ok(refused._tag === "OrchestratorThreadAboveModeLimitError");
120	assert.equal(refused.mode, "interaction");
121	}),
122	);
123
124	it.effect("refuses to fork a source thread its user raised", () =>
125	Effect.gen(function* () {
126	const orchestrator = yield* Orchestrator.OrchestratorV2;
127	const projections = yield* ProjectionStore.ProjectionStoreV2;
128	const sourceThreadId = ThreadId.make("thread:limit-fork-source");
129	const targetThreadId = ThreadId.make("thread:limit-fork-target");
130	yield* createThread(sourceThreadId);
131	yield* orchestrator.dispatch({
132	type: "thread.runtime-mode.set",
133	commandId: CommandId.make("raise-source"),
134	threadId: sourceThreadId,
135	runtimeMode: "full-access",
136	});
137	const fork = {
138	type: "thread.fork",
139	commandId: CommandId.make("fork"),
140	sourceThreadId,
141	targetThreadId,
142	sourcePoint: { type: "latest_stable" },
143	createdBy: "agent",
144	creationSource: "mcp",
145	} as const;
146	const refused = yield* orchestrator
147	.dispatch(fork)
148	.pipe(Effect.provideService(DispatchModeLimit, supervised), Effect.flip);
149	assert.ok(refused._tag === "OrchestratorThreadAboveModeLimitError");
150	assert.equal(refused.threadId, sourceThreadId);
151	assert.isNull(yield* projections.getThreadShell(targetThreadId));
152
153	// The refusal records no receipt: once the source is lowered, the same
154	// command is planned again (and fails only for want of a finished run).
155	yield* orchestrator.dispatch({
156	type: "thread.runtime-mode.set",
157	commandId: CommandId.make("lower-source"),
158	threadId: sourceThreadId,
159	runtimeMode: "approval-required",
160	});
161	const retried = yield* orchestrator
162	.dispatch(fork)
163	.pipe(Effect.provideService(DispatchModeLimit, supervised), Effect.flip);
164	assert.equal(retried._tag, "OrchestratorDispatchError");
165	}),
166	);
167	});

apps/server/src/orchestration-v2/DispatchModeLimit.ts created+52

...	@@ -0,0 +1,52 @@
1	import type { ProviderInteractionMode, RuntimeMode, ThreadId } from "@t3tools/contracts";
2	import * as Context from "effect/Context";
3	import type * as Ref from "effect/Ref";
4
5	export interface DispatchModes {
6	readonly runtimeMode: RuntimeMode;
7	readonly interactionMode: ProviderInteractionMode;
8	}
9
10	/** A thread the orchestrator refused to touch because it ran above the limit. */
11	export interface DispatchModeRefusal extends DispatchModes {
12	readonly threadId: ThreadId;
13	readonly mode: "runtime" \| "interaction";
14	}
15
16	/**
17	* The broadest modes a command may touch, for commands an MCP caller sends.
18	* A caller checks its target's modes before dispatching, but the target's
19	* user can raise them meanwhile; the orchestrator re-checks this limit inside
20	* the thread's command lock, where nothing else can change them. Unset for
21	* the user's own commands, which have no limit.
22	*
23	* The orchestrator also records its refusal in `refused`, so the sender can
24	* report it however the code in between wrapped the dispatch error.
25	*/
26	export interface DispatchModeLimitValue extends DispatchModes {
27	readonly refused?: Ref.Ref<DispatchModeRefusal \| undefined>;
28	}
29
30	export const DispatchModeLimit = Context.Reference<DispatchModeLimitValue \| undefined>(
31	"t3/orchestration-v2/DispatchModeLimit",
32	{ defaultValue: () => undefined },
33	);
34
35	const runtimeModeRank: Record<RuntimeMode, number> = {
36	"approval-required": 0,
37	"auto-accept-edits": 1,
38	auto: 2,
39	"full-access": 3,
40	};
41	const interactionModeRank: Record<ProviderInteractionMode, number> = { plan: 0, default: 1 };
42
43	/** Which of `modes` is broader than `limit`, if either. */
44	export const exceededDispatchModeLimit = (
45	limit: DispatchModes,
46	modes: DispatchModes,
47	): "runtime" \| "interaction" \| undefined =>
48	runtimeModeRank[modes.runtimeMode] > runtimeModeRank[limit.runtimeMode]
49	? "runtime"
50	: interactionModeRank[modes.interactionMode] > interactionModeRank[limit.interactionMode]
51	? "interaction"
52	: undefined;

apps/server/src/orchestration-v2/Orchestrator.ts+69

...	@@ -46,8 +46,10 @@ import {	...	@@ -46,8 +46,10 @@ import {
46	latestProviderTurnForAttempt,	46	latestProviderTurnForAttempt,
47	orchestrationV2RunWorkStartedAt,	47	orchestrationV2RunWorkStartedAt,
48	ProviderInstanceId,	48	ProviderInstanceId,
		49	ProviderInteractionMode,
49	type ProviderSessionId,	50	type ProviderSessionId,
50	RunId,	51	RunId,
		52	RuntimeMode,
51	ThreadLinkedPullRequest,	53	ThreadLinkedPullRequest,
52	ThreadId,	54	ThreadId,
53	type TurnItemId,	55	type TurnItemId,
...	@@ -86,6 +88,7 @@ import * as EffectOutbox from "./EffectOutbox.ts";	...	@@ -86,6 +88,7 @@ import * as EffectOutbox from "./EffectOutbox.ts";
86	import type { OrchestrationEffectRequestV2, PendingOrchestrationEffectV2 } from "./EffectOutbox.ts";	88	import type { OrchestrationEffectRequestV2, PendingOrchestrationEffectV2 } from "./EffectOutbox.ts";
87	import { IdAllocatorV2 } from "./IdAllocator.ts";	89	import { IdAllocatorV2 } from "./IdAllocator.ts";
88	import * as ThreadCommandExecutor from "./ThreadCommandExecutor.ts";	90	import * as ThreadCommandExecutor from "./ThreadCommandExecutor.ts";
		91	import { DispatchModeLimit, exceededDispatchModeLimit } from "./DispatchModeLimit.ts";
89	import {	92	import {
90	applyToProjection,	93	applyToProjection,
91	emptyProjection,	94	emptyProjection,
...	@@ -187,6 +190,22 @@ export class OrchestratorSubagentThreadReadOnlyError extends Schema.TaggedError<	...	@@ -187,6 +190,22 @@ export class OrchestratorSubagentThreadReadOnlyError extends Schema.TaggedError<
187	}	190	}
188	}	191	}
189		192
		193	/** The command's thread runs above the modes its sender may touch (see `DispatchModeLimit`). */
		194	export class OrchestratorThreadAboveModeLimitError extends Schema.TaggedError<OrchestratorThreadAboveModeLimitError>()(
		195	"OrchestratorThreadAboveModeLimitError",
		196	{
		197	commandId: CommandId,
		198	threadId: ThreadId,
		199	mode: Schema.Literals(["runtime", "interaction"]),
		200	runtimeMode: RuntimeMode,
		201	interactionMode: ProviderInteractionMode,
		202	},
		203	) {
		204	override get message(): string {
		205	return `Thread ${this.threadId} now runs in ${this.runtimeMode}/${this.interactionMode} mode, above what this caller may change.`;
		206	}
		207	}
		208
190	export class OrchestratorCommandPreviouslyRejectedError extends Schema.TaggedError<OrchestratorCommandPreviouslyRejectedError>()(	209	export class OrchestratorCommandPreviouslyRejectedError extends Schema.TaggedError<OrchestratorCommandPreviouslyRejectedError>()(
191	"OrchestratorCommandPreviouslyRejectedError",	210	"OrchestratorCommandPreviouslyRejectedError",
192	{	211	{
...	@@ -236,6 +255,7 @@ export const OrchestratorV2Error = Schema.Union([	...	@@ -236,6 +255,7 @@ export const OrchestratorV2Error = Schema.Union([
236	OrchestratorCommandPreviouslyRejectedError,	255	OrchestratorCommandPreviouslyRejectedError,
237	OrchestratorCommandIdConflictError,	256	OrchestratorCommandIdConflictError,
238	OrchestratorSubagentThreadReadOnlyError,	257	OrchestratorSubagentThreadReadOnlyError,
		258	OrchestratorThreadAboveModeLimitError,
239	]);	259	]);
240	export type OrchestratorV2Error = typeof OrchestratorV2Error.Type;	260	export type OrchestratorV2Error = typeof OrchestratorV2Error.Type;
241		261
...	@@ -3418,6 +3438,33 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio	...	@@ -3418,6 +3438,33 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
3418	},	3438	},
3419	);	3439	);
3420		3440
		3441	/** Fails when a limited sender's command would touch a thread running above its limit. */
		3442	const refuseAboveDispatchModeLimit = Effect.fn("orchestrationV2.dispatch.refuseAboveModeLimit")(
		3443	function* (
		3444	command: OrchestrationV2ServerCommand,
		3445	threadId: ThreadId,
		3446	modes: {
		3447	readonly runtimeMode: RuntimeMode;
		3448	readonly interactionMode: ProviderInteractionMode;
		3449	},
		3450	) {
		3451	const limit = yield* DispatchModeLimit;
		3452	const exceeded = limit === undefined ? undefined : exceededDispatchModeLimit(limit, modes);
		3453	if (limit === undefined \|\| exceeded === undefined) return;
		3454	const refusal = {
		3455	threadId,
		3456	mode: exceeded,
		3457	runtimeMode: modes.runtimeMode,
		3458	interactionMode: modes.interactionMode,
		3459	};
		3460	if (limit.refused !== undefined) yield* Ref.set(limit.refused, refusal);
		3461	return yield* new OrchestratorThreadAboveModeLimitError({
		3462	commandId: command.commandId,
		3463	...refusal,
		3464	});
		3465	},
		3466	);
		3467
3421	const dispatchThreadFork = Effect.fn("orchestrationV2.dispatch.threadFork")(function* (	3468	const dispatchThreadFork = Effect.fn("orchestrationV2.dispatch.threadFork")(function* (
3422	command: Extract<OrchestrationV2Command, { readonly type: "thread.fork" }>,	3469	command: Extract<OrchestrationV2Command, { readonly type: "thread.fork" }>,
3423	events: Ref.Ref<Array<OrchestrationV2DomainEvent>>,	3470	events: Ref.Ref<Array<OrchestrationV2DomainEvent>>,
...	@@ -3448,6 +3495,9 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio	...	@@ -3448,6 +3495,9 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
3448	}),	3495	}),
3449	),	3496	),
3450	);	3497	);
		3498	// The source is not under this command's lock, so check the modes this
		3499	// command copies, not an earlier read the source's user could outrun.
		3500	yield* refuseAboveDispatchModeLimit(command, command.sourceThreadId, sourceProjection.thread);
3451		3501
3452	const sourceRun = runForSourcePoint(sourceProjection, command.sourcePoint);	3502	const sourceRun = runForSourcePoint(sourceProjection, command.sourcePoint);
3453		3503
...	@@ -3536,6 +3586,9 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio	...	@@ -3536,6 +3586,9 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
3536	}),	3586	}),
3537	),	3587	),
3538	);	3588	);
		3589	// The source is not under this command's lock, so check the modes this
		3590	// command copies, not an earlier read the source's user could outrun.
		3591	yield* refuseAboveDispatchModeLimit(command, command.sourceThreadId, sourceProjection.thread);
3539	const targetProjection = yield* projectionStore	3592	const targetProjection = yield* projectionStore
3540	.getThreadRecords(command.targetThreadId, ["contextTransfers"])	3593	.getThreadRecords(command.targetThreadId, ["contextTransfers"])
3541	.pipe(	3594	.pipe(
...	@@ -10404,6 +10457,19 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio	...	@@ -10404,6 +10457,19 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
10404	} satisfies OrchestratorV2DispatchResult;	10457	} satisfies OrchestratorV2DispatchResult;
10405	}	10458	}
10406		10459
		10460	// A limited sender checked these modes before dispatching; the thread's
		10461	// user may have raised them since, and only here can they not change.
		10462	const limit = yield* DispatchModeLimit;
		10463	if (limit !== undefined) {
		10464	// A fork or merge-back source is not under this lock: its dispatch
		10465	// checks the copy it reads instead.
		10466	const threadId = commandThreadId(command);
		10467	const shell = yield* projectionStore
		10468	.getThreadShell(threadId)
		10469	.pipe(Effect.mapError((cause) => new OrchestratorProjectionError({ threadId, cause })));
		10470	if (shell !== null) yield* refuseAboveDispatchModeLimit(command, threadId, shell);
		10471	}
		10472
10407	const plan = yield* dispatchOnce(command).pipe(	10473	const plan = yield* dispatchOnce(command).pipe(
10408	Effect.flatMap((planned) =>	10474	Effect.flatMap((planned) =>
10409	// A settle that finds the provider already ended everything, or a	10475	// A settle that finds the provider already ended everything, or a
...	@@ -10423,6 +10489,9 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio	...	@@ -10423,6 +10489,9 @@ const makeOrchestrator = Effect.fn("orchestrationV2.Orchestrator.layer")(functio
10423	),	10489	),
10424	Effect.catch((cause) =>	10490	Effect.catch((cause) =>
10425	Effect.gen(function* () {	10491	Effect.gen(function* () {
		10492	// Refused like the check above: nothing recorded, so the same command
		10493	// can go through once the thread's user lowers it again.
		10494	if (cause._tag === "OrchestratorThreadAboveModeLimitError") return yield* cause;
10426	const rejectedAt = yield* DateTime.now;	10495	const rejectedAt = yield* DateTime.now;
10427	const receipt = yield* eventSink	10496	const receipt = yield* eventSink
10428	.commitRejectedCommand({	10497	.commitRejectedCommand({

apps/server/src/orchestration-v2/ThreadMessageIntake.ts+1

...	@@ -23,6 +23,7 @@ function dispatchWasNotAccepted(	...	@@ -23,6 +23,7 @@ function dispatchWasNotAccepted(
23	case "OrchestratorCommandPreviouslyRejectedError":	23	case "OrchestratorCommandPreviouslyRejectedError":
24	case "OrchestratorCommandIdConflictError":	24	case "OrchestratorCommandIdConflictError":
25	case "OrchestratorSubagentThreadReadOnlyError":	25	case "OrchestratorSubagentThreadReadOnlyError":
		26	case "OrchestratorThreadAboveModeLimitError":
26	return true;	27	return true;
27	default:	28	default:
28	return false;	29	return false;

apps/server/src/provider/T3OrchestrationInstructions.ts+1-1

...	@@ -20,7 +20,7 @@ For independent implementation or a PR stack in its own worktree, use \`t3_threa	...	@@ -20,7 +20,7 @@ For independent implementation or a PR stack in its own worktree, use \`t3_threa
20	- Existing worktree: \`{"title":"Continue cleanup","workspaceStrategy":{"type":"existing_worktree","worktreePath":"/absolute/path/to/worktree","branch":"feature/ui-cleanup"},"message":"Continue the cleanup."}\`	20	- Existing worktree: \`{"title":"Continue cleanup","workspaceStrategy":{"type":"existing_worktree","worktreePath":"/absolute/path/to/worktree","branch":"feature/ui-cleanup"},"message":"Continue the cleanup."}\`
21	- Project's main checkout: \`workspaceStrategy:{"type":"root"}\`. Omitting workspaceStrategy also selects root; it does not inherit the caller's worktree.	21	- Project's main checkout: \`workspaceStrategy:{"type":"root"}\`. Omitting workspaceStrategy also selects root; it does not inherit the caller's worktree.
22		22
23	For stacked work, set \`baseRef\` to the intended parent branch and \`startFromOrigin:false\` to use its local commits. Use \`startFromOrigin:true\` when you intend to fetch and start from origin. Uncommitted edits are not copied. Use \`t3_worktree_list\` to discover existing checkout paths. Project, model selection, and modes inherit unless supplied; launch requires a full-access/default caller.	23	For stacked work, set \`baseRef\` to the intended parent branch and \`startFromOrigin:false\` to use its local commits. Use \`startFromOrigin:true\` when you intend to fetch and start from origin. Uncommitted edits are not copied. Use \`t3_worktree_list\` to discover existing checkout paths. Project, model selection, and modes inherit unless supplied; a launched thread may not run with broader modes than yours.
24		24
25	\`t3_thread_launch\` is the single-thread launch tool. Use \`create_threads\` only for a batch of threads intentionally sharing the caller's checkout: it always inherits the caller's project, branch, and worktree and has no workspace override. Asking an agent to run \`git worktree add\` or \`cd\` in its prompt does not update T3's thread binding. Select the workspace in the launch call instead. \`t3_worktree_handoff\` moves the calling thread, not another thread, and cannot move a thread already attached to a worktree.	25	\`t3_thread_launch\` is the single-thread launch tool. Use \`create_threads\` only for a batch of threads intentionally sharing the caller's checkout: it always inherits the caller's project, branch, and worktree and has no workspace override. Asking an agent to run \`git worktree add\` or \`cd\` in its prompt does not update T3's thread binding. Select the workspace in the launch call instead. \`t3_worktree_handoff\` moves the calling thread, not another thread, and cannot move a thread already attached to a worktree.
26		26

apps/server/src/vcs/GitVcsDriver.ts+5

 @@ -398,6 +398,11 @@ export class GitVcsDriver extends Context.Service<
     readonly pruneWorktrees: (input: {
       readonly cwd: string;
     }) => Effect.Effect<void, GitCommandError>;
+    /**
+     * Absolute paths of every live worktree of the repository at `cwd`, the
+     * main checkout included. Worktrees whose directory is gone are left out.
+     */
+    readonly listWorktreePaths: (cwd: string) => Effect.Effect<string[], GitCommandError>;
     readonly deleteLocalBranch: (
       input: GitDeleteLocalBranchInput,
     ) => Effect.Effect<void, GitCommandError>;

apps/server/src/vcs/GitVcsDriverCore.ts+21

...	@@ -3954,6 +3954,26 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*	...	@@ -3954,6 +3954,26 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
3954	}),	3954	}),
3955	);	3955	);
3956		3956
		3957	const listWorktreePaths: GitVcsDriver.GitVcsDriver["Service"]["listWorktreePaths"] = (cwd) =>
		3958	runGitStdout("GitVcsDriver.listWorktreePaths", cwd, [
		3959	"worktree",
		3960	"list",
		3961	"--porcelain",
		3962	"-z",
		3963	]).pipe(
		3964	// One record per worktree, each ended by an empty field. A `prunable`
		3965	// record's directory is gone, and another checkout may now sit there.
		3966	Effect.map((stdout) =>
		3967	stdout.split("\0\0").flatMap((record) => {
		3968	const fields = record.split("\0");
		3969	const worktree = fields.find((field) => field.startsWith("worktree "));
		3970	return worktree === undefined \|\| fields.some((field) => field.startsWith("prunable"))
		3971	? []
		3972	: [path.resolve(cwd, worktree.slice("worktree ".length))];
		3973	}),
		3974	),
		3975	);
		3976
3957	const withListRefsInvalidation = <A, E>(	3977	const withListRefsInvalidation = <A, E>(
3958	cwd: string,	3978	cwd: string,
3959	effect: Effect.Effect<A, E>,	3979	effect: Effect.Effect<A, E>,
...	@@ -4024,5 +4044,6 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*	...	@@ -4024,5 +4044,6 @@ export const makeGitVcsDriverCore = Effect.fn("makeGitVcsDriverCore")(function*
4024	switchRef: (input) => withListRefsInvalidation(input.cwd, switchRef(input)),	4044	switchRef: (input) => withListRefsInvalidation(input.cwd, switchRef(input)),
4025	initRepo: initRepoWithListRefsInvalidation,	4045	initRepo: initRepoWithListRefsInvalidation,
4026	listLocalBranchNames,	4046	listLocalBranchNames,
		4047	listWorktreePaths,
4027	});	4048	});
4028	});	4049	});

docs/orchestration-v2/orchestrator-mcp-server.md+2-2

...	@@ -325,8 +325,8 @@ this binding.	...	@@ -325,8 +325,8 @@ this binding.
325	Pass the task in `message`. Project, model, and modes inherit when omitted;	325	Pass the task in `message`. Project, model, and modes inherit when omitted;
326	workspace does not. `scratch: true` launches without a project, in a folder of	326	workspace does not. `scratch: true` launches without a project, in a folder of
327	its own under the environment's Scratch project. For stacked PRs, use the parent branch as `baseRef` with	327	its own under the environment's Scratch project. For stacked PRs, use the parent branch as `baseRef` with
328	`startFromOrigin: false`. Launch requires a full-access/default caller and has	328	`startFromOrigin: false`. The new thread may not run with broader runtime or
329	no retry key, so inspect existing threads after a failed or lost response before	329	interaction modes than the caller. Launch has no retry key, so inspect existing threads after a failed or lost response before
330	launching again. `create_threads` remains the batch option for a shared checkout.	330	launching again. `create_threads` remains the batch option for a shared checkout.
331		331
332	### `t3_thread_list`	332	### `t3_thread_list`

oxlint-plugin-t3code/index.ts+2

oxlint-plugin-t3code/rules/no-raw-mcp-registration.test.ts created+185

...	@@ -0,0 +1,185 @@
1	import { assert, describe } from "@effect/vitest";
2
3	import { createOxlintRuleHarness } from "../test/utils.ts";
4
5	const rule = createOxlintRuleHarness("t3code/no-raw-mcp-registration");
6	const testFile = createOxlintRuleHarness("t3code/no-raw-mcp-registration", {
7	filename: "server.test.ts",
8	});
9
10	describe("t3code/no-raw-mcp-registration", () => {
11	rule.valid(
12	"allows the rest of effect/ai and type-only McpServer imports",
13	`
14	import { McpSchema, Tool, Toolkit } from "effect/ai";
15	import type { McpServer } from "effect/ai";
16	import { type McpServer as Server } from "effect/ai";
17	export type Service = McpServer.McpServer \| Server.McpServer;
18	export const used = [McpSchema, Tool, Toolkit];
19	`,
20	);
21
22	rule.invalid(
23	"reports importing McpServer from effect/ai",
24	`
25	import { McpServer } from "effect/ai";
26	export const server = McpServer.McpServer;
27	`,
28	(output) => {
29	assert.match(output, /Only McpHttpServer may use Effect's McpServer/);
30	},
31	);
32
33	rule.invalid(
34	"reports importing McpServer under another name",
35	`
36	import { McpServer as Server } from "effect/ai";
37	export const registration = Server.toolkit(SomeToolkit);
38	`,
39	);
40
41	rule.invalid(
42	"reports a namespace import of effect/ai",
43	`
44	import * as Ai from "effect/ai";
45	export const registration = Ai.McpServer.toolkit(SomeToolkit);
46	`,
47	);
48
49	rule.invalid(
50	"reports importing the McpServer module directly",
51	`
52	import { toolkit } from "effect/ai/McpServer";
53	export const registration = toolkit(SomeToolkit);
54	`,
55	);
56
57	rule.invalid(
58	"reports re-exporting McpServer",
59	`
60	export { McpServer as Server } from "effect/ai";
61	`,
62	);
63
64	rule.invalid(
65	"reports re-exporting all of effect/ai",
66	`
67	export * from "effect/ai";
68	`,
69	);
70
71	rule.invalid(
72	"reports a dynamic import of the McpServer module",
73	`
74	export const load = () => import("effect/ai/McpServer");
75	`,
76	);
77
78	rule.invalid(
79	"reports a dynamic import written as a template",
80	`
81	export const load = () => import(\`effect/ai/McpServer\`);
82	`,
83	);
84
85	rule.invalid(
86	"reports McpServer.toolkit",
87	`
88	export const registration = McpServer.toolkit(SomeToolkit);
89	`,
90	(output) => {
91	assert.match(output, /McpServer\.toolkit registers on \/mcp/);
92	},
93	);
94
95	rule.invalid(
96	"reports McpServer.resource and McpServer.prompt",
97	`
98	export const resource = McpServer.resource({ uri: "t3://x", name: "x", content: "x" });
99	export const prompt = McpServer.prompt({ name: "x", content: () => "x" });
100	`,
101	);
102
103	rule.invalid(
104	"reports addTool on the McpServer service",
105	`
106	import * as Effect from "effect/Effect";
107	export const register = Effect.gen(function* () {
108	const server = yield* Service;
109	yield* server.addTool({ tool, annotations, handle: () => Effect.die("unchecked") });
110	});
111	`,
112	(output) => {
113	assert.match(output, /\.addTool registers on \/mcp/);
114	},
115	);
116
117	rule.invalid(
118	"reports a registration method read without calling it",
119	`
120	export const add = server.addTool;
121	`,
122	);
123
124	rule.invalid(
125	"reports a registration function taken by destructuring",
126	`
127	const { toolkit } = McpServer;
128	export const registration = toolkit(SomeToolkit);
129	`,
130	);
131
132	rule.invalid(
133	"reports a registration method taken by destructuring",
134	`
135	import * as Effect from "effect/Effect";
136	export const register = Effect.gen(function* () {
137	const { addTool } = yield* Service;
138	yield* addTool({ tool, annotations, handle: () => Effect.die("unchecked") });
139	});
140	`,
141	);
142
143	testFile.valid(
144	"lets tests import McpServer to build a server",
145	`
146	import { McpServer } from "effect/ai";
147	export const layer = McpServer.McpServer.layer;
148	`,
149	);
150
151	testFile.invalid(
152	"reports a registration in a test",
153	`
154	import { McpServer } from "effect/ai";
155	export const registration = McpServer.toolkit(SomeToolkit);
156	`,
157	);
158
159	testFile.invalid(
160	"reports a test importing McpServer under another name",
161	`
162	import { McpServer as Server } from "effect/ai";
163	export const registration = Server.toolkit(SomeToolkit);
164	`,
165	(output) => {
166	assert.match(output, /Tests import McpServer only as/);
167	},
168	);
169
170	testFile.invalid(
171	"reports a test importing effect/ai as a namespace",
172	`
173	import * as Ai from "effect/ai";
174	export const registration = Ai.McpServer.toolkit(SomeToolkit);
175	`,
176	);
177
178	testFile.invalid(
179	"reports a test importing the McpServer module directly",
180	`
181	import { toolkit } from "effect/ai/McpServer";
182	export const registration = toolkit(SomeToolkit);
183	`,
184	);
185	});

oxlint-plugin-t3code/rules/no-raw-mcp-registration.ts created+148

...	@@ -0,0 +1,148 @@
1	import { defineRule } from "@oxlint/plugins";
2	import * as Option from "effect/Option";
3
4	import { getPropertyName, isIdentifier, unwrapExpression } from "../utils.ts";
5
6	// Effect's MCP server, and the modules that re-export it.
7	const MCP_SERVER_MODULE = "effect/ai/McpServer";
8	const AI_MODULES = new Set(["effect/ai", "effect/ai/index"]);
9	// Registering anything straight on the MCP server skips McpToolAccess, where
10	// every T3 MCP tool declares who may call it. These are the module functions...
11	const MODULE_REGISTRATIONS = new Set([
12	"toolkit",
13	"registerToolkit",
14	"resource",
15	"registerResource",
16	"prompt",
17	"registerPrompt",
18	]);
19	// ...and the methods on the McpServer service itself.
20	const SERVICE_REGISTRATIONS = new Set([
21	"addTool",
22	"addResource",
23	"addResourceTemplate",
24	"addPrompt",
25	]);
26	const TEST_FILE_PATTERN = /\.(?:test\|spec)\.[cm]?[jt]sx?$/u;
27
28	const HOW =
29	"Build the handlers with McpToolAccess.toLayer and register them through McpHttpServer's toolkitRegistration.";
30	const registrationMessage = (name: string) =>
31	`${name} registers on /mcp without the access checks McpToolAccess declares. ${HOW}`;
32	const importMessage = `Only McpHttpServer may use Effect's McpServer: a registration anywhere else skips the access checks McpToolAccess declares. ${HOW}`;
33	const testImportMessage =
34	'Tests import McpServer only as `import { McpServer } from "effect/ai"`, so a registration on it is reported.';
35
36	/** A module specifier: a string, or a template with nothing substituted. */
37	const literalString = (node: unknown): Option.Option<string> =>
38	Option.flatMap(unwrapExpression(node), (expression) => {
39	if (expression.type === "Literal" && typeof expression.value === "string") {
40	return Option.some(expression.value);
41	}
42	if (expression.type === "TemplateLiteral" && expression.expressions.length === 0) {
43	return Option.fromNullishOr(expression.quasis[0]?.value.cooked);
44	}
45	return Option.none();
46	});
47
48	const namesMcpServer = (node: unknown) =>
49	Option.getOrUndefined(getPropertyName(node)) === "McpServer";
50
51	const exposesMcpServer = (source: Option.Option<string>) =>
52	Option.isSome(source) && (source.value === MCP_SERVER_MODULE \|\| AI_MODULES.has(source.value));
53
54	/**
55	* Keeps every registration on `/mcp` inside McpHttpServer, whose helpers
56	* accept only handlers McpToolAccess built; the lint config exempts that file.
57	* Elsewhere it reports runtime imports of Effect's McpServer, under any name
58	* or path, and reading a registration method or function in any form. Tests
59	* may import McpServer to build a server, but only under its own name, so a
60	* registration on it is still reported. It guards against a registration that
61	* skips the checks by accident; deliberately working around it needs a
62	* reviewed change here.
63	*/
64	export default defineRule({
65	meta: {
66	type: "problem",
67	docs: {
68	description:
69	"Disallow registering on the MCP server without McpToolAccess; tools must declare who may call them.",
70	},
71	},
72	create(context) {
73	const isTest = TEST_FILE_PATTERN.test(context.filename);
74	return {
75	ImportDeclaration(node) {
76	if (node.importKind === "type") return;
77	const source = literalString(node.source);
78	if (Option.isNone(source)) return;
79	const exposes = node.specifiers.some((specifier) => {
80	if (specifier.type !== "ImportSpecifier") return exposesMcpServer(source);
81	if (specifier.importKind === "type") return false;
82	if (source.value === MCP_SERVER_MODULE) return true;
83	return (
84	AI_MODULES.has(source.value) &&
85	namesMcpServer(specifier.imported) &&
86	// A test's `McpServer.toolkit(...)` is reported below by name.
87	!(isTest && namesMcpServer(specifier.local))
88	);
89	});
90	if (exposes) context.report({ node, message: isTest ? testImportMessage : importMessage });
91	},
92	ExportNamedDeclaration(node) {
93	if (node.source === null \|\| node.exportKind === "type") return;
94	const source = literalString(node.source);
95	if (Option.isNone(source)) return;
96	const exposes = node.specifiers.some(
97	(specifier) =>
98	specifier.exportKind !== "type" &&
99	(source.value === MCP_SERVER_MODULE \|\|
100	(AI_MODULES.has(source.value) && namesMcpServer(specifier.local))),
101	);
102	if (exposes) context.report({ node, message: importMessage });
103	},
104	ExportAllDeclaration(node) {
105	if (node.exportKind === "type") return;
106	if (exposesMcpServer(literalString(node.source))) {
107	context.report({ node, message: importMessage });
108	}
109	},
110	ImportExpression(node) {
111	if (exposesMcpServer(literalString(node.source))) {
112	context.report({ node, message: importMessage });
113	}
114	},
115	MemberExpression(node) {
116	const name = getPropertyName(node.property);
117	if (Option.isNone(name)) return;
118	if (SERVICE_REGISTRATIONS.has(name.value)) {
119	context.report({ node, message: registrationMessage(`.${name.value}`) });
120	} else if (
121	MODULE_REGISTRATIONS.has(name.value) &&
122	isIdentifier(unwrapExpression(node.object), "McpServer")
123	) {
124	context.report({ node, message: registrationMessage(`McpServer.${name.value}`) });
125	}
126	},
127	// `const { addTool } = server`, `const { toolkit } = McpServer`
128	ObjectPattern(node) {
129	const fromMcpServer =
130	node.parent.type === "VariableDeclarator" &&
131	isIdentifier(unwrapExpression(node.parent.init), "McpServer");
132	for (const property of node.properties) {
133	if (property.type !== "Property") continue;
134	const name = getPropertyName(property.key);
135	if (Option.isNone(name)) continue;
136	if (SERVICE_REGISTRATIONS.has(name.value)) {
137	context.report({ node: property, message: registrationMessage(`.${name.value}`) });
138	} else if (fromMcpServer && MODULE_REGISTRATIONS.has(name.value)) {
139	context.report({
140	node: property,
141	message: registrationMessage(`McpServer.${name.value}`),
142	});
143	}
144	}
145	},
146	};
147	},
148	});

vite.config.ts+6

 @@ -167,6 +167,7 @@ export default defineConfig({
       "t3code/no-inline-schema-compile": "warn",
       "t3code/no-manual-effect-runtime-in-tests": "error",
       "t3code/no-native-title-tooltip": "error",
+      "t3code/no-raw-mcp-registration": "error",
       "t3code/no-test-in-loop": "error",
       "t3code/no-unscoped-has": "error",
       "t3code/namespace-node-imports": "error",
 @@ -179,6 +180,11 @@ export default defineConfig({
         files: ["packages/shared/src/hostProcess.ts"],
         rules: { "t3code/no-global-process-runtime": "off" },
       },
+      {
+        // The registration helpers that only accept handlers built by McpToolAccess.
+        files: ["apps/server/src/mcp/McpHttpServer.ts"],
+        rules: { "t3code/no-raw-mcp-registration": "off" },
+      },
       {
         files: ["apps/web/src/**"],
         excludeFiles: ["apps/web/src/components/ui/**"],

author	Julius Marminge <julius0216@outlook.com> 2026-10-06 14:09:35-07:00
committer	GitHub <noreply@github.com> 2026-10-06 14:09:35-07:00
log	2f85686d9dca5ec98c892a2a26c321e09d746d71
tree	7621c9cfdc76cbe6a10f53d0c3856d81783741cd
parent	f21d6da51c9aa78ea12e7f13a378f55f1e63cb38
signature	Signed by PGP key B5690EEEBB952194

...	@@ -14,6 +14,7 @@ import * as ServerConfig from "../config.ts";	...	@@ -14,6 +14,7 @@ import * as ServerConfig from "../config.ts";
14	import * as DeviceService from "../device/DeviceService.ts";	14	import * as DeviceService from "../device/DeviceService.ts";
15	import * as McpHttpServer from "./McpHttpServer.ts";	15	import * as McpHttpServer from "./McpHttpServer.ts";
16	import * as McpInvocationContext from "./McpInvocationContext.ts";	16	import * as McpInvocationContext from "./McpInvocationContext.ts";
		17	import * as McpToolAccessTestkit from "./McpToolAccess.testkit.ts";
17		18
18	const environmentId = EnvironmentId.make("environment-device-test");	19	const environmentId = EnvironmentId.make("environment-device-test");
19	const threadId = ThreadId.make("thread-device-test");	20	const threadId = ThreadId.make("thread-device-test");
...	@@ -102,6 +103,7 @@ const layerDeviceServiceMock = Layer.mock(DeviceService.DeviceService)({	...	@@ -102,6 +103,7 @@ const layerDeviceServiceMock = Layer.mock(DeviceService.DeviceService)({
102		103
103	const layerTest = McpHttpServer.layerDeviceToolkit.pipe(	104	const layerTest = McpHttpServer.layerDeviceToolkit.pipe(
104	Layer.provideMerge(McpServer.McpServer.layer),	105	Layer.provideMerge(McpServer.McpServer.layer),
		106	Layer.provideMerge(McpToolAccessTestkit.liveThreadsLayer),
105	Layer.provideMerge(layerDeviceServiceMock),	107	Layer.provideMerge(layerDeviceServiceMock),
106	Layer.provide(ServerConfig.layerTest(process.cwd(), { prefix: "t3-mcp-device-toolkit-test-" })),	108	Layer.provide(ServerConfig.layerTest(process.cwd(), { prefix: "t3-mcp-device-toolkit-test-" })),
107	Layer.provide(NodeServices.layer),	109	Layer.provide(NodeServices.layer),
...	@@ -172,6 +174,7 @@ it.effect("rejects unavailable agent access before booting or opening a device",	...	@@ -172,6 +174,7 @@ it.effect("rejects unavailable agent access before booting or opening a device",
172	Effect.provide(	174	Effect.provide(
173	McpHttpServer.layerDeviceToolkit.pipe(	175	McpHttpServer.layerDeviceToolkit.pipe(
174	Layer.provideMerge(McpServer.McpServer.layer),	176	Layer.provideMerge(McpServer.McpServer.layer),
		177	Layer.provideMerge(McpToolAccessTestkit.liveThreadsLayer),
175	Layer.provide(layerUnavailable),	178	Layer.provide(layerUnavailable),
176	Layer.provide(NodeServices.layer),	179	Layer.provide(NodeServices.layer),
177	),	180	),

...	@@ -1,6 +1,7 @@	...	@@ -1,6 +1,7 @@
1	import * as Effect from "effect/Effect";	1	import * as Effect from "effect/Effect";
2	import * as Preview from "../../../preview/Manager.ts";	2	import * as Preview from "../../../preview/Manager.ts";
3	import { requireThreadMcpCapability } from "../../McpInvocationContext.ts";	3	import { requireThreadMcpCapability } from "../../McpInvocationContext.ts";
		4	import * as McpToolAccess from "../../McpToolAccess.ts";
4	import { unavailable } from "../../threadAccess.ts";	5	import { unavailable } from "../../threadAccess.ts";
5	import { PreviewControlsToolkit } from "./tools.ts";	6	import { PreviewControlsToolkit } from "./tools.ts";
6	import * as PreviewAutomationBroker from "../../PreviewAutomationBroker.ts";	7	import * as PreviewAutomationBroker from "../../PreviewAutomationBroker.ts";
...	@@ -10,8 +11,8 @@ const access = Effect.gen(function* () {	...	@@ -10,8 +11,8 @@ const access = Effect.gen(function* () {
10	const scope = yield* requireThreadMcpCapability("preview");	11	const scope = yield* requireThreadMcpCapability("preview");
11	return { scope, manager: yield* Preview.PreviewManager };	12	return { scope, manager: yield* Preview.PreviewManager };
12	});	13	});
13	export const layer = PreviewControlsToolkit.toLayer({	14	export const layer = McpToolAccess.toLayer(PreviewControlsToolkit, {
14	t3_preview_list: (input) =>	15	t3_preview_list: McpToolAccess.readsAsCaller((input) =>
15	Effect.gen(function* () {	16	Effect.gen(function* () {
16	const { scope, manager } = yield* access;	17	const { scope, manager } = yield* access;
17	const result = yield* manager.list({ threadId: scope.thread.threadId });	18	const result = yield* manager.list({ threadId: scope.thread.threadId });
...	@@ -23,7 +24,8 @@ export const layer = PreviewControlsToolkit.toLayer({	...	@@ -23,7 +24,8 @@ export const layer = PreviewControlsToolkit.toLayer({
23	nextCursor: end < result.sessions.length ? end : null,	24	nextCursor: end < result.sessions.length ? end : null,
24	};	25	};
25	}),	26	}),
26	t3_preview_close: (input) =>	27	),
		28	t3_preview_close: McpToolAccess.actsAsCaller((input) =>
27	Effect.gen(function* () {	29	Effect.gen(function* () {
28	const { scope, manager } = yield* access;	30	const { scope, manager } = yield* access;
29	const { sessions } = yield* manager.list({ threadId: scope.thread.threadId });	31	const { sessions } = yield* manager.list({ threadId: scope.thread.threadId });
...	@@ -41,4 +43,5 @@ export const layer = PreviewControlsToolkit.toLayer({	...	@@ -41,4 +43,5 @@ export const layer = PreviewControlsToolkit.toLayer({
41	.pipe(Effect.mapError(unavailable));	43	.pipe(Effect.mapError(unavailable));
42	return {};	44	return {};
43	}),	45	}),
		46	),
44	});	47	});

...	@@ -7,6 +7,7 @@ import {	...	@@ -7,6 +7,7 @@ import {
7	} from "@t3tools/contracts";	7	} from "@t3tools/contracts";
8	import * as Schema from "effect/Schema";	8	import * as Schema from "effect/Schema";
9	import { Tool, Toolkit } from "effect/ai";	9	import { Tool, Toolkit } from "effect/ai";
		10	import * as ThreadManagementService from "../../../orchestration-v2/ThreadManagementService.ts";
10	import * as PreviewManager from "../../../preview/Manager.ts";	11	import * as PreviewManager from "../../../preview/Manager.ts";
11	import * as PreviewAutomationBroker from "../../PreviewAutomationBroker.ts";	12	import * as PreviewAutomationBroker from "../../PreviewAutomationBroker.ts";
12	import * as McpInvocationContext from "../../McpInvocationContext.ts";	13	import * as McpInvocationContext from "../../McpInvocationContext.ts";
...	@@ -16,6 +17,7 @@ const shared = {	...	@@ -16,6 +17,7 @@ const shared = {
16	failureMode: "return" as const,	17	failureMode: "return" as const,
17	dependencies: [	18	dependencies: [
18	McpInvocationContext.McpInvocationContext,	19	McpInvocationContext.McpInvocationContext,
		20	ThreadManagementService.ThreadManagementService,
19	PreviewManager.PreviewManager,	21	PreviewManager.PreviewManager,
20	PreviewAutomationBroker.PreviewAutomationBroker,	22	PreviewAutomationBroker.PreviewAutomationBroker,
21	],	23	],

...	@@ -7,6 +7,7 @@ import noInlineSchemaCompile from "./rules/no-inline-schema-compile.ts";	...	@@ -7,6 +7,7 @@ import noInlineSchemaCompile from "./rules/no-inline-schema-compile.ts";
7	import noManualEffectRuntimeInTests from "./rules/no-manual-effect-runtime-in-tests.ts";	7	import noManualEffectRuntimeInTests from "./rules/no-manual-effect-runtime-in-tests.ts";
8	import noMobileUniwindThemeEscapeHatches from "./rules/no-mobile-uniwind-theme-escape-hatches.ts";	8	import noMobileUniwindThemeEscapeHatches from "./rules/no-mobile-uniwind-theme-escape-hatches.ts";
9	import noNativeTitleTooltip from "./rules/no-native-title-tooltip.ts";	9	import noNativeTitleTooltip from "./rules/no-native-title-tooltip.ts";
		10	import noRawMcpRegistration from "./rules/no-raw-mcp-registration.ts";
10	import noTestInLoop from "./rules/no-test-in-loop.ts";	11	import noTestInLoop from "./rules/no-test-in-loop.ts";
11	import noUnscopedHas from "./rules/no-unscoped-has.ts";	12	import noUnscopedHas from "./rules/no-unscoped-has.ts";
12	import preferCatchTags from "./rules/prefer-catch-tags.ts";	13	import preferCatchTags from "./rules/prefer-catch-tags.ts";
...	@@ -24,6 +25,7 @@ export default definePlugin({	...	@@ -24,6 +25,7 @@ export default definePlugin({
24	"no-manual-effect-runtime-in-tests": noManualEffectRuntimeInTests,	25	"no-manual-effect-runtime-in-tests": noManualEffectRuntimeInTests,
25	"no-mobile-uniwind-theme-escape-hatches": noMobileUniwindThemeEscapeHatches,	26	"no-mobile-uniwind-theme-escape-hatches": noMobileUniwindThemeEscapeHatches,
26	"no-native-title-tooltip": noNativeTitleTooltip,	27	"no-native-title-tooltip": noNativeTitleTooltip,
		28	"no-raw-mcp-registration": noRawMcpRegistration,
27	"no-test-in-loop": noTestInLoop,	29	"no-test-in-loop": noTestInLoop,
28	"no-unscoped-has": noUnscopedHas,	30	"no-unscoped-has": noUnscopedHas,
29	"prefer-catch-tags": preferCatchTags,	31	"prefer-catch-tags": preferCatchTags,

feat(server): every T3 MCP tool declares who may call it (#16335)