The best way to control Claude Code, Codex and more from any computer or phone
fix(acp): terminal tool fallback works from Windows PowerShell (#39949)
Julius Marminge committed
Nov 20, 2026 at 16:41 UTC
4b0dd9eb1c078db9945ed57d49a274816f9831f5
4 files changed
+102
-6
apps/server/src/mcp/AcpMcpStdioBridge.test.ts
+45
@@ -89,6 +89,51 @@ describe("AcpMcpStdioBridge", () => {
89
);
90
});
91
92
+ it("reads the arguments from stdin when given -", async () => {
93
+ const originalEnvironment = process.env;
94
+ using _environment = {
95
+ [Symbol.dispose]: () => {
96
+ process.env = originalEnvironment;
97
+ },
98
+ };
99
+ process.env = {
100
+ ...originalEnvironment,
101
+ T3_ACP_MCP_ENDPOINT: "http://127.0.0.1:1/mcp",
102
+ T3_ACP_MCP_AUTHORIZATION: "Bearer bridge-test",
103
+ };
104
+ const calls: Array<unknown> = [];
105
+ using _fetch = vi.spyOn(globalThis, "fetch").mockImplementation(async (_url, init) => {
106
+ if (init?.method === "DELETE") return new Response(null, { status: 204 });
107
+ const message = JSON.parse(String(init?.body)) as {
108
+ id?: string;
109
+ method: string;
110
+ params?: unknown;
111
+ };
112
+ if (message.method === "notifications/initialized") {
113
+ return new Response(null, { status: 202 });
114
+ }
115
+ if (message.method === "tools/call") calls.push(message.params);
116
+ return Response.json({
117
+ jsonrpc: "2.0",
118
+ id: message.id,
119
+ result:
120
+ message.method === "initialize" ? { protocolVersion: "2025-06-18" } : { content: [] },
121
+ });
122
+ });
123
+ using _output = vi.spyOn(process.stdout, "write").mockReturnValue(true);
124
+ using _stdin = vi
125
+ .spyOn(process, "stdin", "get")
126
+ .mockReturnValue(
127
+ NodeStream.Readable.from(['{"task":"say \\"hi\\"",', '"mode":"async"}\r\n']) as never,
128
+ );
129
+
130
+ await runAcpMcpCliFastPath("acp-mcp-call", ["delegate_task", "-"]);
131
+
132
+ expect(calls).toEqual([
133
+ { name: "delegate_task", arguments: { task: 'say "hi"', mode: "async" } },
134
+ ]);
135
+ });
136
+
137
it.effect("forwards requests and replays the session id and protocol version", () =>
138
Effect.gen(function* () {
139
const { input, written, requests, bridge } = makeHarness((request) => {
apps/server/src/mcp/AcpMcpStdioBridge.ts
+15
-3
@@ -342,6 +342,14 @@ export function runAcpMcpStdioBridge(options: AcpMcpStdioBridgeOptions): Effect.
342
});
343
}
344
345
+async function readStdin(): Promise<string> {
346
+ const chunks: Array<Buffer> = [];
347
+ for await (const chunk of process.stdin) {
348
+ chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
349
+ }
350
+ return Buffer.concat(chunks).toString("utf8");
351
+}
352
+
353
/** Avoid heavy imports on the ACP first-message path. */
354
export async function runAcpMcpCliFastPath(
355
command: "acp-mcp-bridge" | "acp-mcp-call",
@@ -365,12 +373,16 @@ export async function runAcpMcpCliFastPath(
373
);
374
return;
375
}
368
- const [tool, argumentsJson] = args;
369
- if (tool === undefined || argumentsJson === undefined) {
370
- process.stderr.write("acp-mcp-call requires <tool> and <arguments-json>.\n");
376
+ const [tool, argumentsArg] = args;
377
+ if (tool === undefined || argumentsArg === undefined) {
378
+ process.stderr.write(
379
+ "acp-mcp-call requires <tool> and <arguments-json>, or - to read it from stdin.\n",
380
+ );
381
process.exitCode = 2;
382
return;
383
}
384
+ // Windows PowerShell 5.1 strips the quotes from JSON passed as an argument; stdin keeps them.
385
+ const argumentsJson = argumentsArg === "-" ? await readStdin() : argumentsArg;
386
let parsed: unknown;
387
try {
388
parsed = JSON.parse(argumentsJson);
packages/provider-acp/src/server/adapter.ts
+41
-2
@@ -35,6 +35,7 @@ import {
35
type TurnTokenUsage,
36
} from "@t3tools/contracts";
37
import { AgentScope, AgentScopeThreadId } from "@t3tools/shared/AgentScope";
38
+import * as HostProcess from "@t3tools/shared/HostProcess";
39
import { HTML_RENDER_TOOL_NAME } from "@t3tools/shared/htmlRender";
40
import { modelSelectionsEqual } from "@t3tools/shared/model";
41
import { type SelfInvocation, selfInvocationArgs } from "@t3tools/shared/nodeRuntime";
@@ -996,11 +997,45 @@ interface AcpMcpContext {
997
readonly authorization?: string;
998
}
999
1000
+// A GUI-subsystem executable (packaged Windows desktop) does not hold the console, so PowerShell
1001
+// neither waits for it nor captures its output or exit code; cmd.exe running a batch file does.
1002
+// cmd.exe decodes batch files with the console code page, so paths come from the (UTF-16) environment.
1003
+const ACP_MCP_CALL_LAUNCHER = [
1004
+ "@echo off",
1005
+ "setlocal EnableExtensions DisableDelayedExpansion",
1006
+ 'set "ELECTRON_RUN_AS_NODE=1"',
1007
+ "if not defined T3_ACP_MCP_ENTRYPOINT goto packaged",
1008
+ '"%T3_ACP_MCP_NODE%" "%T3_ACP_MCP_ENTRYPOINT%" acp-mcp-call %*',
1009
+ "exit /b %errorlevel%",
1010
+ ":packaged",
1011
+ '"%T3_ACP_MCP_NODE%" acp-mcp-call %*',
1012
+ "",
1013
+].join("\r\n");
1014
+
1015
+const writeAcpMcpCallLauncher = Effect.fn("AcpAdapterV2.writeAcpMcpCallLauncher")(function* (
1016
+ stateDir: string,
1017
+) {
1018
+ if (!(yield* HostProcess.isWindows)) return undefined;
1019
+ const fileSystem = yield* FileSystem.FileSystem;
1020
+ const dir = `${stateDir}\\acp`;
1021
+ const launcherPath = `${dir}\\acp-mcp-call.cmd`;
1022
+ return yield* fileSystem.makeDirectory(dir, { recursive: true }).pipe(
1023
+ Effect.andThen(fileSystem.writeFileString(launcherPath, ACP_MCP_CALL_LAUNCHER)),
1024
+ Effect.as(launcherPath),
1025
+ Effect.catch((error) =>
1026
+ Effect.logWarning("Could not write the ACP terminal tool launcher.", error).pipe(
1027
+ Effect.as(undefined),
1028
+ ),
1029
+ ),
1030
+ );
1031
+});
1032
+
1033
function acpMcpContext(
1034
session: McpProviderSession.McpProviderSessionConfig | undefined,
1035
self: SelfInvocation,
1036
mcpOverHttp: boolean | undefined,
1037
deferMcpTools: boolean | undefined,
1038
+ callLauncher: string | undefined,
1039
): AcpMcpContext {
1040
if (session === undefined) {
1041
return { servers: [], acpServers: [], httpServers: [] };
@@ -1048,6 +1083,7 @@ function acpMcpContext(
1083
T3_ACP_MCP_AUTHORIZATION: session.authorizationHeader,
1084
T3_ACP_MCP_NODE: self.command,
1085
...(self.entrypoint === undefined ? {} : { T3_ACP_MCP_ENTRYPOINT: self.entrypoint }),
1086
+ ...(callLauncher === undefined ? {} : { T3_ACP_MCP_CALL: callLauncher }),
1087
},
1088
};
1089
}
@@ -1981,14 +2017,17 @@ export const makeAcpAdapterV2 = Effect.fn("makeAcpAdapterV2")(function* (
2017
const host = yield* ProviderHost.ProviderHost;
2018
const mcpSessions = yield* McpProviderSessions.McpProviderSessions;
2019
const { flavor, selfInvocation: self } = options;
2020
+ const callLauncher = yield* writeAcpMcpCallLauncher(host.paths.stateDir);
2021
const readMcpContext = (threadId: ThreadId | null) =>
2022
threadId === null
1986
- ? Effect.succeed(acpMcpContext(undefined, self, flavor.mcpOverHttp, flavor.deferMcpTools))
2023
+ ? Effect.succeed(
2024
+ acpMcpContext(undefined, self, flavor.mcpOverHttp, flavor.deferMcpTools, callLauncher),
2025
+ )
2026
: mcpSessions
2027
.read(threadId)
2028
.pipe(
2029
Effect.map((session) =>
1991
- acpMcpContext(session, self, flavor.mcpOverHttp, flavor.deferMcpTools),
2030
+ acpMcpContext(session, self, flavor.mcpOverHttp, flavor.deferMcpTools, callLauncher),
2031
),
2032
);
2033
const driver = flavor.driver;
packages/provider-core/src/server/orchestrationInstructions.ts
+1
-1
@@ -57,7 +57,7 @@ export const T3_CODE_DEVICE_TOOL_INSTRUCTIONS_WITH_TOOL_SEARCH = deviceToolInstr
57
58
// ACP only: some ACP agents accept the injected MCP server but never expose
59
// its tools, so they need the terminal transport other harnesses never use.
60
-const T3_CODE_ACP_MCP_FALLBACK_INSTRUCTIONS = `ACP fallback: if the T3 tools are absent and \`T3_ACP_MCP_NODE\` is present, call them through the terminal: \`ELECTRON_RUN_AS_NODE=1 "$T3_ACP_MCP_NODE" \${T3_ACP_MCP_ENTRYPOINT:+"$T3_ACP_MCP_ENTRYPOINT"} acp-mcp-call orchestrator_capabilities '{}'\` (\`T3_ACP_MCP_ENTRYPOINT\` is unset for a standalone executable). Delegate with \`acp-mcp-call delegate_task '{"task":"...","target":{"providerInstanceId":"...","model":"..."},"mode":"async","clientRequestId":"..."}'\`.`;
60
+const T3_CODE_ACP_MCP_FALLBACK_INSTRUCTIONS = `ACP fallback: if the T3 tools are absent and \`T3_ACP_MCP_NODE\` is present, call them through the terminal: \`ELECTRON_RUN_AS_NODE=1 "$T3_ACP_MCP_NODE" \${T3_ACP_MCP_ENTRYPOINT:+"$T3_ACP_MCP_ENTRYPOINT"} acp-mcp-call orchestrator_capabilities '{}'\` (\`T3_ACP_MCP_ENTRYPOINT\` is unset for a standalone executable). Delegate with \`acp-mcp-call delegate_task '{"task":"...","target":{"providerInstanceId":"...","model":"..."},"mode":"async","clientRequestId":"..."}'\`. On Windows, run \`T3_ACP_MCP_CALL\` instead and pipe the JSON to stdin, as in PowerShell \`'{}' | & $env:T3_ACP_MCP_CALL orchestrator_capabilities -\`, writing non-ASCII characters as \`\\uXXXX\` escapes.`;
61
62
const T3_CODE_ACP_DEFAULT_MODE_INSTRUCTIONS = `## T3 Code interaction mode: Default
63