wenshao · Aug 5, 2026 · Aug 6, 2026 · Aug 6, 2026 · Aug 6, 2026 · Aug 6, 2026
diff --git a/docs/design/assets/web-shell-tmux-terminal/webshell-session.png b/docs/design/assets/web-shell-tmux-terminal/webshell-session.png
diff --git a/docs/design/web-shell-tmux-terminal.md b/docs/design/web-shell-tmux-terminal.md
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/acp-bridge/src/status.ts b/packages/acp-bridge/src/status.ts
@@ -690,6 +690,19 @@ export interface ServeSessionShellTaskStatus {
   pid?: number;
   exitCode?: number;
   error?: string;
+  /**
+   * Present when the shell task is backed by an interactive tmux session
+   * (created by the tmux tool). The daemon terminal endpoint uses this to
+   * locate the attachable tmux session.
+   */
+  terminal?: {
+    /** tmux server socket name (`tmux -L <socket>`). */
+    socket: string;
+    /** tmux session name on that socket. */
+    tmuxSession: string;
+    /** Pane the terminal's command runs in. */
+    paneId?: string;
+  };
 }
 
 export interface ServeSessionMonitorTaskStatus {

diff --git a/packages/cli/src/acp-integration/session/Session.ts b/packages/cli/src/acp-integration/session/Session.ts
@@ -9154,7 +9154,8 @@ export class Session implements SessionContext {
           const isPlanShellCall =
             isPlanMode &&
             (policyToolName === ToolNames.SHELL ||
-              policyToolName === ToolNames.MONITOR);
+              policyToolName === ToolNames.MONITOR ||
+              policyToolName === ToolNames.TMUX);
 
           if (finalPermission === 'deny') {
             return earlyErrorResponse(
@@ -9170,14 +9171,19 @@ export class Session implements SessionContext {
 
           let planShellAmbientWorkingDirectory: string | undefined;
           if (isPlanShellCall) {
-            const directory = toolParams['directory'];
+            // tmux carries its working directory under `cwd`, not
+            // `directory`; inject the ambient value under the key the
+            // tool actually reads.
+            const directoryKey =
+              policyToolName === ToolNames.TMUX ? 'cwd' : 'directory';
+            const directory = toolParams[directoryKey];
             planShellAmbientWorkingDirectory =
               typeof directory === 'string' && directory.length > 0
                 ? undefined
                 : this.config.getTargetDir();
             invocation.params = {
               ...structuredClone(invocation.params),
-              directory:
+              [directoryKey]:
                 typeof directory === 'string' && directory.length > 0
                   ? directory
                   : planShellAmbientWorkingDirectory,

diff --git a/packages/cli/src/acp-integration/session/tasksSnapshot.test.ts b/packages/cli/src/acp-integration/session/tasksSnapshot.test.ts
@@ -5,9 +5,17 @@
  */
 
 import { describe, expect, it } from 'vitest';
-import type { AgentTask, Config, MonitorTask } from '@qwen-code/qwen-code-core';
+import type {
+  AgentTask,
+  Config,
+  MonitorTask,
+  ShellTask,
+} from '@qwen-code/qwen-code-core';
 import { buildSessionTasksStatus } from './tasksSnapshot.js';
-import type { ServeSessionAgentTaskStatus } from '@qwen-code/acp-bridge/status';
+import type {
+  ServeSessionAgentTaskStatus,
+  ServeSessionShellTaskStatus,
+} from '@qwen-code/acp-bridge/status';
 
 function agentTask(overrides: Partial<AgentTask> = {}): AgentTask {
   return {
@@ -107,6 +115,57 @@ describe('buildSessionTasksStatus agent lineage', () => {
   });
 });
 
+function shellTask(overrides: Partial<ShellTask> = {}): ShellTask {
+  return {
+    kind: 'shell',
+    id: 'bg_0123456789abcdef',
+    shellId: 'bg_0123456789abcdef',
+    command: 'python3 app.py',
+    description: 'python3 app.py',
+    status: 'running',
+    startTime: 1_000,
+    outputFile: '/tmp/shell-bg.output',
+    cwd: '/work',
+    abortController: new AbortController(),
+    ...overrides,
+  } as unknown as ShellTask;
+}
+
+function serializedShell(shell: ShellTask): ServeSessionShellTaskStatus {
+  const config = {
+    getBackgroundTaskRegistry: () => ({ getAll: () => [] }),
+    getBackgroundShellRegistry: () => ({ getAll: () => [shell] }),
+    getMonitorRegistry: () => ({ getAll: () => [] }),
+  } as unknown as Config;
+  return buildSessionTasksStatus('session-1', config, 2_000).tasks.find(
+    (task) => task.kind === 'shell',
+  ) as ServeSessionShellTaskStatus;
+}
+
+describe('buildSessionTasksStatus shell tasks', () => {
+  it('passes terminal metadata through for tmux-backed tasks', () => {
+    const task = serializedShell(
+      shellTask({
+        terminal: {
+          socket: 'qwen-serve',
+          tmuxSession: 'qsh-bg_x',
+          paneId: '%1',
+        },
+      }),
+    );
+    expect(task.terminal).toEqual({
+      socket: 'qwen-serve',
+      tmuxSession: 'qsh-bg_x',
+      paneId: '%1',
+    });
+  });
+
+  it('omits terminal for plain shell tasks', () => {
+    const task = serializedShell(shellTask());
+    expect('terminal' in task).toBe(false);
+  });
+});
+
 describe('buildSessionTasksStatus monitor correlation', () => {
   it('exposes the tool call that launched a monitor', () => {
     const task = serializedMonitor({

diff --git a/packages/cli/src/acp-integration/session/tasksSnapshot.ts b/packages/cli/src/acp-integration/session/tasksSnapshot.ts
@@ -94,6 +94,7 @@ function serializeShellTask(
     ...optionalField('pid', entry.pid),
     ...optionalField('exitCode', entry.exitCode),
     ...optionalField('error', entry.error),
+    ...optionalField('terminal', entry.terminal),
   };
 }
 

diff --git a/packages/cli/src/config/config.test.ts b/packages/cli/src/config/config.test.ts
@@ -2494,6 +2494,7 @@ describe('mergeExcludeTools', () => {
   const defaultExcludes = [
     ToolNames.SHELL,
     ToolNames.MONITOR,
+    ToolNames.TMUX,
     ToolNames.EDIT,
     ToolNames.WRITE_FILE,
   ];
@@ -2655,6 +2656,7 @@ describe('Approval mode tool exclusion logic', () => {
     const excludedTools = config.getPermissionsDeny();
     expect(excludedTools).toContain(ToolNames.SHELL);
     expect(excludedTools).toContain(ToolNames.MONITOR);
+    expect(excludedTools).toContain(ToolNames.TMUX);
     expect(excludedTools).toContain(ToolNames.EDIT);
     expect(excludedTools).toContain(ToolNames.WRITE_FILE);
   });
@@ -2675,6 +2677,7 @@ describe('Approval mode tool exclusion logic', () => {
     const excludedTools = config.getPermissionsDeny();
     expect(excludedTools).toContain(ToolNames.SHELL);
     expect(excludedTools).toContain(ToolNames.MONITOR);
+    expect(excludedTools).toContain(ToolNames.TMUX);
     expect(excludedTools).toContain(ToolNames.EDIT);
     expect(excludedTools).toContain(ToolNames.WRITE_FILE);
   });
@@ -2696,6 +2699,26 @@ describe('Approval mode tool exclusion logic', () => {
     const excludedTools = config.getPermissionsDeny();
     expect(excludedTools).toContain(ToolNames.SHELL);
     expect(excludedTools).toContain(ToolNames.MONITOR);
+    expect(excludedTools).toContain(ToolNames.TMUX);
+    expect(excludedTools).toContain(ToolNames.EDIT);
+    expect(excludedTools).toContain(ToolNames.WRITE_FILE);
+  });
+
+  it('should not exclude tmux when explicitly allowed in tools.allowed', async () => {
+    process.argv = ['node', 'script.js', '-p', 'test'];
+    const argv = await parseArguments();
+    const settings: Settings = {
+      tools: {
+        allowed: [ToolNames.TMUX],
+      },
+    };
+
+    const config = await loadCliConfig(settings, argv, undefined, []);
+
+    const excludedTools = config.getPermissionsDeny();
+    expect(excludedTools).toContain(ToolNames.SHELL);
+    expect(excludedTools).toContain(ToolNames.MONITOR);
+    expect(excludedTools).not.toContain(ToolNames.TMUX);
     expect(excludedTools).toContain(ToolNames.EDIT);
     expect(excludedTools).toContain(ToolNames.WRITE_FILE);
   });

diff --git a/packages/cli/src/config/config.ts b/packages/cli/src/config/config.ts
@@ -1869,6 +1869,7 @@ export async function loadCliConfig(
         // Deny all write/execute tools unless explicitly allowed.
         denyUnlessAllowed(ToolNames.SHELL as ToolName);
         denyUnlessAllowed(ToolNames.MONITOR as ToolName);
+        denyUnlessAllowed(ToolNames.TMUX as ToolName);
         denyUnlessAllowed(ToolNames.EDIT as ToolName);
         denyUnlessAllowed(ToolNames.WRITE_FILE as ToolName);
         break;
@@ -1880,13 +1881,15 @@ export async function loadCliConfig(
         // toward YOLO behavior).
         denyUnlessAllowed(ToolNames.SHELL as ToolName);
         denyUnlessAllowed(ToolNames.MONITOR as ToolName);
+        denyUnlessAllowed(ToolNames.TMUX as ToolName);
         denyUnlessAllowed(ToolNames.EDIT as ToolName);
         denyUnlessAllowed(ToolNames.WRITE_FILE as ToolName);
         break;
       case ApprovalMode.AUTO_EDIT:
         // Shell-like execute tools still require a prompt in auto-edit mode.
         denyUnlessAllowed(ToolNames.SHELL as ToolName);
         denyUnlessAllowed(ToolNames.MONITOR as ToolName);
+        denyUnlessAllowed(ToolNames.TMUX as ToolName);
         break;
       case ApprovalMode.YOLO:
         // No extra denials for YOLO mode.

diff --git a/packages/cli/src/i18n/index.test.ts b/packages/cli/src/i18n/index.test.ts
@@ -208,4 +208,19 @@ describe('localizeToolDisplayName', () => {
     );
     expect(untranslated).toEqual([]);
   });
+
+  it('has a zh-TW translation for every core tool display name', async () => {
+    const { setLanguageAsync, localizeToolDisplayName } = await import(
+      './index.js'
+    );
+    const { ToolDisplayNames } = await import('@qwen-code/qwen-code-core');
+    await setLanguageAsync('zh-TW');
+
+    const KEEP_ENGLISH = new Set(['Agent', 'Grep', 'Glob']);
+    const untranslated = Object.values(ToolDisplayNames).filter(
+      (name) =>
+        !KEEP_ENGLISH.has(name) && localizeToolDisplayName(name) === name,
+    );
+    expect(untranslated).toEqual([]);
+  });
 });
diff --git a/packages/cli/src/i18n/locales/en.js b/packages/cli/src/i18n/locales/en.js
@@ -217,6 +217,7 @@ export default {
   'toolDisplayName.SendMessage': 'toolDisplayName.SendMessage',
   'toolDisplayName.StructuredOutput': 'toolDisplayName.StructuredOutput',
   'toolDisplayName.Monitor': 'toolDisplayName.Monitor',
+  'toolDisplayName.Tmux': 'toolDisplayName.Tmux',
   'toolDisplayName.NotebookEdit': 'toolDisplayName.NotebookEdit',
   'toolDisplayName.ToolSearch': 'toolDisplayName.ToolSearch',
   'toolDisplayName.EnterWorktree': 'toolDisplayName.EnterWorktree',

diff --git a/packages/cli/src/i18n/locales/zh-TW.js b/packages/cli/src/i18n/locales/zh-TW.js
@@ -208,6 +208,7 @@ export default {
   'toolDisplayName.SendMessage': '傳送訊息',
   'toolDisplayName.StructuredOutput': '結構化輸出',
   'toolDisplayName.Monitor': '監控',
+  'toolDisplayName.Tmux': '終端',
   'toolDisplayName.NotebookEdit': '編輯 Notebook',
   'toolDisplayName.ToolSearch': '工具搜尋',
   'toolDisplayName.EnterWorktree': '進入 Worktree',

diff --git a/packages/cli/src/i18n/locales/zh.js b/packages/cli/src/i18n/locales/zh.js
@@ -209,6 +209,7 @@ export default {
   'toolDisplayName.SendMessage': '发送消息',
   'toolDisplayName.StructuredOutput': '结构化输出',
   'toolDisplayName.Monitor': '监控',
+  'toolDisplayName.Tmux': '终端',
   'toolDisplayName.NotebookEdit': '编辑 Notebook',
   'toolDisplayName.ToolSearch': '工具搜索',
   'toolDisplayName.EnterWorktree': '进入 Worktree',

diff --git a/packages/cli/src/serve/acp-http/index.ts b/packages/cli/src/serve/acp-http/index.ts
@@ -476,6 +476,13 @@ export interface MountAcpHttpOptions {
 export interface ExtraWsRoute {
   path: string;
   onConnection: (ws: WebSocket, req: IncomingMessage) => void;
+  /**
+   * Dispatch before the ACP-mount drain gate. For routes that own their own
+   * protocol and resolve their own scope (the handler validates the target
+   * itself) — otherwise a primary-runtime drain 503s connections that the
+   * handler would have resolved to a healthy runtime.
+   */
+  bypassMountDrainGate?: boolean;
 }
 
 /**
@@ -1761,6 +1768,17 @@ export function mountAcpHttp(
         activeMount = resolvedMount;
       }
 
+      if (extraRoute?.bypassMountDrainGate) {
+        wss!.handleUpgrade(req, socket, head, (ws: WebSocket) => {
+          if (disposed) {
+            ws.close(1012, 'Server shutting down');
+            return;
+          }
+          extraRoute.onConnection(ws, req);
+        });
+        return;
+      }
+
       if (activeMount.draining) {
         logReject(`workspace-draining ${activeMount.routeLabel}`);
         socket.write(

diff --git a/packages/cli/src/serve/process-env-guard.test.ts b/packages/cli/src/serve/process-env-guard.test.ts
@@ -206,6 +206,14 @@ const allowedProcessEnvAccesses = normalizeAllowances([
       },
     },
   ],
+  [
+    'packages/cli/src/serve/terminal/terminal-ws.ts',
+    {
+      reason:
+        'The terminal attach pty uses the daemon environment as its base so `tmux` resolves on PATH and the tmux socket location is reachable.',
+      accesses: { whole: 1 },
+    },
+  ],
 ]);
 
 function listTypeScriptFiles(dir: string): string[] {

diff --git a/packages/cli/src/serve/server.ts b/packages/cli/src/serve/server.ts
@@ -51,6 +51,7 @@ import {
   type ExtraWsRoute,
 } from './acp-http/index.js';
 import { createVoiceWsConnectionHandler } from './voice/voice-ws.js';
+import { createTerminalWsConnectionHandler } from './terminal/terminal-ws.js';
 import {
   ClientMcpSenderRegistry,
   createClientMcpServerProvider,
@@ -2729,6 +2730,21 @@ export function createServeApp(
           acquireVoiceLease: acquirePrimaryVoiceLease,
         }),
       },
+      // Browser live-terminal attach for tmux-backed shell tasks (the core
+      // tmux tool). Shares the upgrade listener's loopback/CSRF/bearer
+      // checks; the handler validates the task against the live registry
+      // before attaching. It resolves the owning runtime per session, so a
+      // primary-runtime drain must not gate it (healthy secondary workspaces
+      // stay attachable); hence bypassMountDrainGate.
+      {
+        path: '/terminal',
+        bypassMountDrainGate: true,
+        onConnection: createTerminalWsConnectionHandler({
+          workspaceRegistry,
+          daemonLog,
+          resolveAttachEnv: (runtime) => getRuntimeEffectiveEnv(runtime.env),
+        }),
+      },
     ],
     workspaceVoiceConnection: (runtime, ws, req) =>
       createVoiceWsConnectionHandler(runtime.workspaceCwd, {