Skip to content

Commit 05b04f7

Browse files
Synthmindsclaude
andauthored
Merge pull request #5: linked launches inherit the caller's mode, capped by the link
Wes's rule "Inherit, capped by link": - An agent in a thread that launches or delegates to a linked environment without naming a mode gets a remote thread that inherits its own modes, capped by the link. - An MCP client outside a thread keeps the project default. - Implemented with a T3-Mode-Inherit header, which only a calling thread sends and only a peer link has honoured. - Reverts 7f47d29. CI is fully green at 90458ed. Independent review approved, and mutation proofs M1–M3 fail as expected. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01A1D6J2UMPo7YBWQFvbg1br
2 parents f0924f6 + 90458ed commit 05b04f7

11 files changed

Lines changed: 121 additions & 38 deletions

File tree

‎apps/server/src/mcp/McpHttpServer.test.ts‎

Lines changed: 36 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1082,6 +1082,7 @@ it.effect(
10821082
Effect.scoped(
10831083
Effect.gen(function* () {
10841084
const clientToken = "client-payload.client-signature";
1085+
const linkToken = "link-payload.link-signature";
10851086
const clientScope: McpInvocationContext.McpInvocationScope = {
10861087
environmentId,
10871088
requestNamespace: "client:linked",
@@ -1090,6 +1091,11 @@ it.effect(
10901091
capabilities: new Set(["orchestration"]),
10911092
issuedAt: 1,
10921093
};
1094+
const linkScope: McpInvocationContext.McpInvocationScope = {
1095+
...clientScope,
1096+
requestNamespace: "client:peer-link",
1097+
client: { sessionId: "peer-link", label: "T3 Code · desk", access: "auto", linked: true },
1098+
};
10931099
// Starts a thread at the modes the gate hands it, so the outcome is those modes.
10941100
const StartsToolkit = Toolkit.make(
10951101
Tool.make("starts", {
@@ -1113,13 +1119,19 @@ it.effect(
11131119
starts: McpToolAccess.startsThreads(
11141120
(input) => input,
11151121
(_, modes) =>
1116-
Effect.succeed({ modes: `${modes.runtimeMode}/${modes.interactionMode}` }),
1122+
Effect.gen(function* () {
1123+
const scope = yield* McpInvocationContext.McpInvocationContext;
1124+
const inherits = scope.client?.inheritsModes === true ? "+inherit" : "";
1125+
return { modes: `${modes.runtimeMode}/${modes.interactionMode}${inherits}` };
1126+
}),
11171127
"stamped",
11181128
),
11191129
}),
11201130
).pipe(
11211131
Layer.provideMerge(
1122-
McpHttpServer.layerMcpTransport.pipe(Layer.provide(ServerSettings.layerTest())),
1132+
McpHttpServer.layerMcpTransport.pipe(
1133+
Layer.provide(ServerSettings.layerTest({ linkedEnvironmentsEnabled: true })),
1134+
),
11231135
),
11241136
Layer.provide(McpToolAccessTestkit.liveThreadsLayer),
11251137
Layer.provide(
@@ -1134,7 +1146,9 @@ it.effect(
11341146
Effect.succeed(
11351147
request.headers.authorization === `Bearer ${clientToken}`
11361148
? clientScope
1137-
: undefined,
1149+
: request.headers.authorization === `Bearer ${linkToken}`
1150+
? linkScope
1151+
: undefined,
11381152
),
11391153
}),
11401154
),
@@ -1161,12 +1175,17 @@ it.effect(
11611175
),
11621176
);
11631177
/** Starts a thread as the client, with `limit` as T3-Mode-Limit; the HTTP status or the outcome. */
1164-
const start = (limit: string | undefined, args: Record<string, string> = {}) =>
1178+
const start = (
1179+
limit: string | undefined,
1180+
args: Record<string, string> = {},
1181+
as: { readonly token?: string; readonly inherit?: string } = {},
1182+
) =>
11651183
Effect.gen(function* () {
11661184
const headers = {
11671185
accept: "application/json, text/event-stream",
1168-
authorization: `Bearer ${clientToken}`,
1186+
authorization: `Bearer ${as.token ?? clientToken}`,
11691187
...(limit === undefined ? {} : { "t3-mode-limit": limit }),
1188+
...(as.inherit === undefined ? {} : { "t3-mode-inherit": as.inherit }),
11701189
};
11711190
const initialize = yield* httpClient.post("/mcp", {
11721191
headers,
@@ -1218,6 +1237,18 @@ it.effect(
12181237
expect(yield* start("auto")).toBe(400);
12191238
expect(yield* start("auto/default/extra")).toBe(400);
12201239
expect(yield* start("root/default")).toBe(400);
1240+
1241+
// T3-Mode-Inherit marks a peer link's limit as its agent's own modes:
1242+
// only from a link, only beside a valid limit, and only as "1".
1243+
const link = { token: linkToken, inherit: "1" };
1244+
expect(yield* start("auto-accept-edits/plan", {}, link)).toBe(
1245+
"auto-accept-edits/plan+inherit",
1246+
);
1247+
expect(yield* start(undefined, {}, link)).toBe("auto/default");
1248+
expect(yield* start("auto/default", {}, { token: linkToken, inherit: "true" })).toBe(
1249+
"auto/default",
1250+
);
1251+
expect(yield* start("auto/default", {}, { inherit: "1" })).toBe("auto/default");
12211252
}),
12221253
).pipe(Effect.provide(NodeHttpServer.layerTest)),
12231254
);

‎apps/server/src/mcp/McpHttpServer.ts‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -170,7 +170,7 @@ const invalidModeLimit = HttpServerResponse.jsonUnsafe(
170170
{ status: 400, headers: { "cache-control": "no-store" } },
171171
);
172172

173-
/** Applies a client's requested mode limit; undefined when the header is malformed. */
173+
/** Applies a client's mode limit, and a peer link's T3-Mode-Inherit; undefined when the limit is malformed. */
174174
const withModeLimit = (
175175
invocation: McpInvocationContext.McpInvocationScope,
176176
request: HttpServerRequest.HttpServerRequest,
@@ -180,7 +180,17 @@ const withModeLimit = (
180180
const limit = parseModeLimit(header);
181181
return Option.isNone(limit)
182182
? undefined
183-
: { ...invocation, client: { ...invocation.client, narrowedTo: limit.value } };
183+
: {
184+
...invocation,
185+
client: {
186+
...invocation.client,
187+
narrowedTo: limit.value,
188+
...(invocation.client.linked === true &&
189+
request.headers[McpInvocationContext.MODE_INHERIT_HEADER] === "1"
190+
? { inheritsModes: true }
191+
: {}),
192+
},
193+
};
184194
};
185195

186196
// The Linked environments beta is off here: links wait until it is on again.

‎apps/server/src/mcp/McpInvocationContext.ts‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,8 @@ export interface McpClientCaller {
4545
* another environment passing on the limits of the agent it calls for.
4646
*/
4747
readonly narrowedTo?: ClientModes | undefined;
48+
/** `narrowedTo` is the calling agent's own running modes (`T3-Mode-Inherit`), not only a ceiling. */
49+
readonly inheritsModes?: boolean | undefined;
4850
/** The origin an outside client reached; its thread links open the web app there. */
4951
readonly webOrigin?: string | undefined;
5052
}
@@ -53,10 +55,17 @@ export interface McpClientCaller {
5355
* `T3-Mode-Limit: <runtimeMode>/<interactionMode>` lets an OAuth client cap
5456
* a request below what it was approved with: another environment passes on
5557
* the limits of the agent it calls for. It can only narrow (see
56-
* `clientModeCeiling`), so a client gains nothing by sending a broad one.
58+
* `clientModeCeiling`), so a client gains no access by sending a broad one.
5759
*/
5860
export const MODE_LIMIT_HEADER = "t3-mode-limit";
5961

62+
/**
63+
* `T3-Mode-Inherit: 1` beside `T3-Mode-Limit` marks that limit as the calling agent's own
64+
* modes, so a launch naming no mode starts there, not at the project default. Only a peer
65+
* link's is honored, and a link sends it only for a thread: a client has a ceiling, not modes.
66+
*/
67+
export const MODE_INHERIT_HEADER = "t3-mode-inherit";
68+
6069
export interface ClientModes {
6170
readonly runtimeMode: RuntimeMode;
6271
readonly interactionMode: ProviderInteractionMode;

‎apps/server/src/mcp/toolkits/project/handlers.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,8 @@ export const layer = McpToolAccess.toLayer(ProjectToolkit, {
162162
);
163163
// A caller outside a thread has nothing to inherit, so it starts with the
164164
// project's effective defaults, as the composer does. Its mode stays
165-
// within the ceiling it was approved with.
165+
// within the ceiling it was approved with. A linked thread's own modes
166+
// arrive as T3-Mode-Inherit, capped by the link, so it starts there instead.
166167
const projectDefaults =
167168
caller === undefined && !replaying
168169
? yield* ServerSettings.ServerSettingsService.pipe(
@@ -189,7 +190,9 @@ export const layer = McpToolAccess.toLayer(ProjectToolkit, {
189190
"Pass modelSelection: the project has no default model. orchestrator_capabilities lists providers and models.",
190191
});
191192
const startedRuntimeMode =
192-
projectDefaults !== undefined && input.runtimeMode === undefined
193+
projectDefaults !== undefined &&
194+
input.runtimeMode === undefined &&
195+
scope.client?.inheritsModes !== true
193196
? yield* resolveRuntimeMode(runtimeMode, projectDefaults.defaultRuntimeMode).pipe(
194197
Effect.orElseSucceed(() => runtimeMode),
195198
)

‎apps/server/src/peer/PeerForwarding.test.ts‎

Lines changed: 30 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -292,7 +292,9 @@ const makeLaptop = Effect.gen(function* () {
292292
threadId,
293293
threadId === ThreadId.make("thread:laptop-plan")
294294
? { runtimeMode: "full-access", interactionMode: "plan" }
295-
: { runtimeMode: "full-access" },
295+
: threadId === ThreadId.make("thread:laptop-auto")
296+
? { runtimeMode: "auto" }
297+
: { runtimeMode: "full-access" },
296298
),
297299
),
298300
getProjectThreadRecords: ({ threadId }) =>
@@ -317,18 +319,23 @@ const makeLaptop = Effect.gen(function* () {
317319
);
318320
const here = yield* Layer.build(layerHere);
319321
const server = Context.get(here, McpServer.McpServer);
322+
// A `client:` caller is an OAuth client outside any thread, approved for full access.
320323
const scopeOf = (
321324
caller: string,
322325
capabilities: ReadonlySet<McpInvocationContext.McpCapability> = new Set(["orchestration"]),
323326
): McpInvocationContext.McpInvocationScope => ({
324327
environmentId: laptop.environmentId,
325328
requestNamespace: `provider-session:${caller}`,
326-
thread: {
327-
threadId: ThreadId.make(caller),
328-
providerSessionId: `provider-session:${caller}`,
329-
providerInstanceId: ProviderInstanceId.make("codex"),
330-
},
331-
client: undefined,
329+
thread: caller.startsWith("client:")
330+
? undefined
331+
: {
332+
threadId: ThreadId.make(caller),
333+
providerSessionId: `provider-session:${caller}`,
334+
providerInstanceId: ProviderInstanceId.make("codex"),
335+
},
336+
client: caller.startsWith("client:")
337+
? { sessionId: caller, label: "Outside client", access: "full-access" }
338+
: undefined,
332339
capabilities,
333340
issuedAt: 1,
334341
});
@@ -506,10 +513,9 @@ it.effect("launches in a linked environment with the caller's modes, retry-safe"
506513
});
507514
const retried = yield* launch("thread:laptop-plan");
508515
const [launched, relaunched] = (yield* Ref.get(seen)).launches;
509-
// The thread there keeps the caller's plan mode and starts at the box's
510-
// default for new threads, approval-required, within the caller's modes
511-
// and the link's full access. A retry asks for the same thread.
512-
expect(launched).toMatchObject({ runtimeMode: "approval-required", interactionMode: "plan" });
516+
// The thread there runs with the caller's own modes here, below the
517+
// link's full access, and a retry asks for the same thread.
518+
expect(launched).toMatchObject({ runtimeMode: "full-access", interactionMode: "plan" });
513519
expect(relaunched?.threadId).toBe(launched?.threadId);
514520
expect(retried.structuredContent).toEqual(first.structuredContent);
515521

@@ -527,6 +533,19 @@ it.effect("launches in a linked environment with the caller's modes, retry-safe"
527533
expect(failureOf(withUpload)).toMatchObject({ code: "invalid_request" });
528534
expect(yield* Ref.get(b.bearers)).toEqual([]);
529535
expect((yield* Ref.get(seen)).launches).toHaveLength(2);
536+
537+
// A thread's own mode below the link carries over as itself: auto, not
538+
// the link's full access, and not the box default.
539+
const fromAuto = yield* launch("thread:laptop-auto", { clientRequestId: "launch-3" });
540+
expect(fromAuto.isError).toBe(false);
541+
expect((yield* Ref.get(seen)).launches[2]).toMatchObject({ runtimeMode: "auto" });
542+
// A client outside a thread has a ceiling, not modes to inherit, so its
543+
// launch there starts at that project's default, as it would here.
544+
const fromClient = yield* launch("client:outside", { clientRequestId: "launch-4" });
545+
expect(fromClient.isError).toBe(false);
546+
expect((yield* Ref.get(seen)).launches[3]).toMatchObject({
547+
runtimeMode: "approval-required",
548+
});
530549
}),
531550
).pipe(Effect.provide(NodeHttpServer.layerTest)),
532551
);

‎apps/server/src/peer/PeerForwarding.ts‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -98,15 +98,17 @@ const make = Effect.gen(function* () {
9898
const threads = yield* ThreadManagement.ThreadManagementService;
9999

100100
/**
101-
* The caller's own limits, which travel with every forwarded call: the peer sees only the
102-
* link's credential, so a caller that may not control threads here is refused here. Work a
103-
* link started never uses this environment's links, since the peer would see this
104-
* environment's session instead of that link, and its fence could not hold.
101+
* The caller's limits travel with every forwarded call, since the peer sees only the link's
102+
* credential; a thread's are its own modes, which a launch there inherits. Work a link
103+
* started never uses this environment's links: the peer would see this environment's
104+
* session instead of that link, and its fence could not hold.
105105
*/
106106
const callerLimits = (scope: Scope) =>
107107
readCaller().pipe(
108108
Effect.tap((caller) => assertNotLinked(caller, "use this environment's links")),
109-
Effect.map((caller) => caller.limits),
109+
Effect.map((caller) =>
110+
caller.caller === undefined ? caller.limits : { ...caller.limits, inherit: true },
111+
),
110112
Effect.provideService(McpInvocationContext.McpInvocationContext, scope),
111113
Effect.provideService(ThreadManagement.ThreadManagementService, threads),
112114
);

‎apps/server/src/peer/PeerMcpClient.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,8 @@ const PROTOCOL_VERSION = "2025-06-18";
2424
export interface PeerCallLimits {
2525
readonly runtimeMode: RuntimeMode;
2626
readonly interactionMode: ProviderInteractionMode;
27+
/** These are a calling thread's own modes, which a launch there inherits (`T3-Mode-Inherit`). */
28+
readonly inherit?: boolean | undefined;
2729
}
2830

2931
/**
@@ -159,6 +161,9 @@ const make = Effect.gen(function* () {
159161
.pipe(Effect.mapError(fromLinkError));
160162
const limitHeader = {
161163
[McpInvocationContext.MODE_LIMIT_HEADER]: `${input.limits.runtimeMode}/${input.limits.interactionMode}`,
164+
...(input.limits.inherit === true
165+
? { [McpInvocationContext.MODE_INHERIT_HEADER]: "1" }
166+
: {}),
162167
};
163168
const sessionKey = `${input.environmentId} ${resolved.url}`;
164169
const callOnce = (sessionId: string) =>

‎apps/server/src/peer/RemoteDelegation.test.ts‎

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -197,17 +197,14 @@ const boxProjects: ReadonlyArray<Project> = [
197197
},
198198
];
199199

200-
const serveBox = (thread: BoxThread, settings?: Parameters<typeof ServerSettings.layerTest>[0]) => {
201-
return servePeer(box, boxToolkitLayer(thread, settings));
200+
const serveBox = (thread: BoxThread) => {
201+
return servePeer(box, boxToolkitLayer(thread));
202202
};
203203

204204
const boxRunId = RunId.make("run:box");
205205
const boxLaterRunId = RunId.make("run:box-later");
206206

207-
const boxToolkitLayer = (
208-
thread: BoxThread,
209-
settings?: Parameters<typeof ServerSettings.layerTest>[0],
210-
) => {
207+
const boxToolkitLayer = (thread: BoxThread) => {
211208
const runId = boxRunId;
212209
const interrupts = new Set<string>();
213210
const shellOf = (threadId: ThreadId) =>
@@ -499,7 +496,7 @@ const boxToolkitLayer = (
499496
}),
500497
),
501498
Layer.provide(Layer.mock(SecretRequests.SecretRequests)({})),
502-
Layer.provide(ServerSettings.layerTest(settings)),
499+
Layer.provide(ServerSettings.layerTest()),
503500
Layer.provide(NodeServices.layer),
504501
);
505502
};
@@ -902,8 +899,7 @@ it.effect("a task named only by environment inherits the parent's model, within
902899
Effect.scoped(
903900
Effect.gen(function* () {
904901
const thread = yield* makeBoxThread;
905-
// New threads there default to full access, above the link, so only the link caps the task.
906-
const b = yield* serveBox(thread, { defaultRuntimeMode: "full-access" });
902+
const b = yield* serveBox(thread);
907903
const offers = yield* SubscriptionRef.make<
908904
ReadonlyArray<ProviderContinuationRequests.ProviderContinuationRequest>
909905
>([]);

‎apps/server/src/peer/RemoteDelegation.ts‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -237,9 +237,8 @@ const make = Effect.gen(function* () {
237237
? inherited.options
238238
: undefined);
239239
// Modes asked for are checked against this thread. Omitted ones are left
240-
// to the other side, which starts the task at its default for new threads
241-
// within this thread's modes and the link's access, so a narrower link
242-
// still takes the task.
240+
// to the other side, which inherits this thread's modes capped by the
241+
// link's access, so a narrower link still takes the task.
243242
const runtimeMode =
244243
input.runtimeMode === undefined || input.runtimeMode === "inherit"
245244
? undefined

‎docs/internals/remote.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,12 @@ Unlinking on the linking side only forgets the token.
9494
`T3-Mode-Limit`, which the receiving `/mcp` only ever narrows the client's
9595
approved access with. A plan-mode agent therefore cannot start full-access
9696
work through a full-access link.
97+
- **A launch that names no mode inherits a calling thread's modes**, capped by
98+
the link: the forwarder adds `T3-Mode-Inherit: 1` only for a thread, and the
99+
receiving `/mcp` honors it only from a peer link. A client outside a thread
100+
sends a ceiling, not modes, so the far side starts its launch at the project
101+
default, within that ceiling and the link, as here. If either side predates
102+
the header, every linked launch keeps that project default.
97103
- **The token goes only to an address that proves it is the linked
98104
environment**: its descriptor must report the linked environment id. A LAN
99105
address that now belongs to another machine never receives it.

0 commit comments

Comments
 (0)