From df03606c06dd478adffc16deadbc61c11791f632 Mon Sep 17 00:00:00 2001
From: dingyi <dingyi222666@foxmail.com>
Date: Fri, 12 Jun 2026 01:33:53 +0800
Subject: [PATCH 1/5] feat(agent): improve computer backend handling

---
 packages/core/src/llm-core/agent/sub-agent.ts | 124 ++++-----------
 .../components/computer/computer-page.vue     |  17 +--
 .../computer/config-backends/backend-e2b.vue  |   4 +-
 .../config-backends/backend-local.vue         |  49 ++----
 .../config-backends/backend-open-terminal.vue |   8 +-
 .../computer/configuration-panel.vue          | 142 ++++++++++--------
 .../components/computer/files-panel.vue       |  39 +++--
 .../components/computer/status-panel.vue      |   4 +-
 .../src/computer/backends/e2b.ts              |   7 +
 .../src/computer/backends/local/index.ts      |  32 ++--
 .../src/computer/backends/local/sandbox.ts    |  23 +--
 .../src/computer/backends/local/security.ts   |  33 ----
 .../src/computer/backends/local/store.ts      |  25 +--
 .../src/computer/backends/open_terminal.ts    |   7 +
 .../extension-agent/src/computer/types.ts     |   1 +
 .../extension-agent/src/config/defaults.ts    |   1 -
 .../extension-agent/src/service/computer.ts   |   9 +-
 packages/extension-agent/src/service/index.ts |  47 +++---
 packages/extension-agent/src/types.ts         |   3 +
 .../extension-agent/src/types/computer.ts     |   1 -
 packages/extension-agent/src/webui/index.ts   |   7 +
 21 files changed, 220 insertions(+), 363 deletions(-)

diff --git a/packages/core/src/llm-core/agent/sub-agent.ts b/packages/core/src/llm-core/agent/sub-agent.ts
index bcb65ecac..e4adc1115 100644
--- a/packages/core/src/llm-core/agent/sub-agent.ts
+++ b/packages/core/src/llm-core/agent/sub-agent.ts
@@ -250,10 +250,8 @@ export function createTaskTool(
 
                 return [
                     `task_id: ${task.id}`,
-                    `run_id: ${task.activeRunId}`,
                     'state: running',
-                    'message: queued',
-                    `status_hint: use ${toolName} with {"action":"status","id":"${task.id}"} to inspect progress.`
+                    `hint: use ${toolName} action=status id=${task.id}`
                 ].join('\n')
             }
 
@@ -408,12 +406,9 @@ export function createTaskTool(
 
 export function buildTaskToolDescription() {
     return [
-        'Delegate a focused task to a specialized agent when parallel work, deeper investigation, or a narrower prompt will help.',
-        'Use the exact agent name from the injected catalog.',
-        'If delegated work may take a while, set background=true so it can continue beyond the normal tool timeout.',
-        'Use action=list or action=status to inspect background tasks, ' +
-            'action=message to send more guidance while they run, and ' +
-            'action=run with the same id to continue the same session later.'
+        'Delegate focused work to a specialist.',
+        'Use exact agent names. Use background=true for long tasks.',
+        'Use action=list/status to monitor, message to guide, run with id to resume.'
     ].join('\n')
 }
 
@@ -424,9 +419,8 @@ export function renderAvailableAgents(
 ) {
     const lines = [
         '<available_sub_agents>',
-        'Delegate focused work to a specialist via the task tool when parallel work or a narrower prompt helps.',
-        'If delegated work may take a while or exceed the normal tool timeout, set background=true, then query it later with task action=list/status.',
-        'While a background sub-agent is running, you can send more guidance with task action=message.',
+        'Delegate to specialists via the task tool. Use background=true for long work.',
+        'Monitor with action=status; guide running tasks with action=message.',
         ''
     ]
 
@@ -449,8 +443,7 @@ export function renderAvailableAgents(
 
     lines.push(
         '',
-        'Use the exact sub-agent name. Provide a self-contained prompt with goal, context, and expected result.',
-        'Prefer background=true for long-running delegated work so it is not interrupted by the default timeout.',
+        'Use exact sub-agent names. Include goal, context, and expected result.',
         '</available_sub_agents>'
     )
 
@@ -468,28 +461,22 @@ class AgentTaskTool extends StructuredTool {
                 .enum(['run', 'status', 'list', 'message'])
                 .optional()
                 .describe(
-                    'run starts or resumes an agent task, status inspects one task, ' +
-                        'list shows recent tasks in this conversation, message sends ' +
-                        'live guidance to a running background task.'
+                    'run/resume task, status inspects one, list shows recent, message guides a running background task.'
                 ),
             agent: z
                 .string()
                 .optional()
                 .describe(
-                    'The exact agent name from the injected catalog. Required when starting a new task. Optional when resuming an existing task by id.'
+                    'Exact agent name. Required for new tasks; optional when resuming by id.'
                 ),
             id: z
                 .string()
                 .optional()
-                .describe(
-                    'Existing task id returned by an earlier task call. Reuse it to inspect, message, or continue the same agent session.'
-                ),
+                .describe('Existing task id for status, message, or resume.'),
             prompt: z
                 .string()
                 .optional()
-                .describe(
-                    'The delegated task or follow-up instruction. Required when action is run.'
-                ),
+                .describe('Task or follow-up instruction. Required for run.'),
             reason: z
                 .string()
                 .optional()
@@ -497,15 +484,11 @@ class AgentTaskTool extends StructuredTool {
             background: z
                 .boolean()
                 .optional()
-                .describe(
-                    'Run the agent in the background. Prefer this for long-running work so it can continue beyond the normal tool timeout.'
-                ),
+                .describe('Run in background for long work.'),
             message: z
                 .string()
                 .optional()
-                .describe(
-                    'Live guidance to send to a running background agent. Use with action message.'
-                )
+                .describe('Guidance for a running background task.')
         })
         .superRefine((input, ctx) => {
             const action = input.action ?? 'run'
@@ -714,7 +697,7 @@ async function runAgentTask(options: {
 
     if (options.input.background) {
         exec().catch(() => {})
-        return formatTaskStart(options.task, run, options.toolName)
+        return formatTaskStart(options.task, options.toolName)
     }
 
     return await exec()
@@ -899,32 +882,22 @@ function formatTaskResult(
     toolName: string
 ) {
     return [
+        output.trim() || '(empty)',
+        '',
         `task_id: ${task.id}`,
         `agent: ${task.agentName}`,
-        `run_id: ${run.runId}`,
         `state: ${run.state}`,
-        `resume_hint: use ${toolName} with {"action":"run","id":"${task.id}","prompt":"next instruction"} ` +
-            'to continue this session. Add "background":true when the work may take a while.',
-        '',
-        output.trim() || '(empty)'
+        `hint: use ${toolName} action=run id=${task.id} to continue`
     ].join('\n')
 }
 
-function formatTaskStart(
-    task: AgentTaskSession,
-    run: AgentTaskRun,
-    toolName: string
-) {
+function formatTaskStart(task: AgentTaskSession, toolName: string) {
     return [
         `task_id: ${task.id}`,
         `agent: ${task.agentName}`,
-        `run_id: ${run.runId}`,
         'state: running',
         'mode: background',
-        `status_hint: use ${toolName} with {"action":"status","id":"${task.id}"} to inspect progress.`,
-        `list_hint: use ${toolName} with {"action":"list"} to see recent agent tasks in this conversation.`,
-        `message_hint: use ${toolName} with {"action":"message","id":"${task.id}","message":"..."} to send more guidance while it runs.`,
-        `resume_hint: after it stops, use ${toolName} with {"action":"run","id":"${task.id}","prompt":"next instruction"} to continue this session.`
+        `hint: ${toolName} action=status id=${task.id}; action=message to guide; action=run to resume`
     ].join('\n')
 }
 
@@ -941,13 +914,11 @@ function formatTaskList(
                 task.id,
                 `[${run?.state ?? (task.activeRunId ? 'running' : 'idle')}]`,
                 task.agentName,
-                `mode=${run?.background ? 'background' : 'foreground'}`,
-                `updated=${new Date(task.updatedAt).toISOString()}`,
-                `run=${run?.runId ?? task.activeRunId ?? '-'}`
+                `mode=${run?.background ? 'background' : 'foreground'}`
             ].join(' ')
         }),
         '',
-        `Use ${toolName} with {"action":"status","id":"..."} to inspect one task.`
+        `Use ${toolName} action=status id=...`
     ].join('\n')
 }
 
@@ -956,63 +927,32 @@ function formatTaskDetail(
     run: AgentTaskRun | undefined,
     toolName: string
 ) {
-    const lines = [
+    const meta = [
         `task_id: ${task.id}`,
         `agent: ${task.agentName}`,
         `state: ${run?.state ?? (task.activeRunId ? 'running' : 'idle')}`,
-        `mode: ${run?.background ? 'background' : 'foreground'}`,
-        `run_id: ${run?.runId ?? task.activeRunId ?? '-'}`,
-        `depth: ${task.depth}`,
-        `parent_agent: ${task.parentAgent}`,
-        `started: ${new Date(task.startedAt).toISOString()}`,
-        `updated: ${new Date(task.updatedAt).toISOString()}`
+        `mode: ${run?.background ? 'background' : 'foreground'}`
     ]
 
-    if (run?.lastTool) {
-        lines.push(`last_tool: ${run.lastTool}`)
-    }
-
-    if (run) {
-        lines.push(`tool_count: ${run.toolCount}`)
-        lines.push(`turn_count: ${run.turnCount}`)
-    }
-
-    if (run?.endedAt) {
-        lines.push(`ended: ${new Date(run.endedAt).toISOString()}`)
-    }
-
     if (run?.error) {
-        lines.push(`error: ${run.error}`)
+        meta.push(`error: ${run.error}`)
     }
 
-    lines.push(
-        `status_hint: use ${toolName} with {"action":"status","id":"${task.id}"} to inspect it again.`
-    )
-
     if (run?.state === 'running' && run.background) {
-        lines.push(
-            `message_hint: use ${toolName} with {"action":"message","id":"${task.id}","message":"..."} to send more guidance while it runs.`
-        )
+        meta.push(`hint: use ${toolName} action=message id=${task.id}`)
     }
 
     if (run?.state !== 'running') {
-        lines.push(
-            `resume_hint: use ${toolName} with {"action":"run","id":"${task.id}","prompt":"next instruction"} ` +
-                'to continue this session. Add "background":true when the work may take a while.'
-        )
+        meta.push(`hint: use ${toolName} action=run id=${task.id} to continue`)
     }
 
-    lines.push('')
-
     if (run?.output?.trim()) {
-        lines.push('Output:')
-        lines.push(run.output.trim())
-        return lines.join('\n')
+        return [run.output.trim(), '', ...meta].join('\n')
     }
 
-    lines.push('History:')
-    lines.push(formatTaskHistory(task.messages))
-    return lines.join('\n')
+    return ['History:', formatTaskHistory(task.messages), '', ...meta].join(
+        '\n'
+    )
 }
 
 function formatTaskHistory(messages: BaseMessage[]) {
@@ -1025,7 +965,7 @@ function formatTaskHistory(messages: BaseMessage[]) {
                 return undefined
             }
 
-            return `${message.getType()}: ${text.length > 280 ? `${text.slice(0, 277)}...` : text}`
+            return `${message.getType()}: ${text.length > 140 ? `${text.slice(0, 137)}...` : text}`
         })
         .filter((item): item is string => item != null)
 
@@ -1033,7 +973,7 @@ function formatTaskHistory(messages: BaseMessage[]) {
         return '(no messages yet)'
     }
 
-    return lines.slice(-6).join('\n')
+    return lines.slice(-3).join('\n')
 }
 
 function formatTraceText(value: unknown) {
diff --git a/packages/extension-agent/client/components/computer/computer-page.vue b/packages/extension-agent/client/components/computer/computer-page.vue
index c4573477d..8a73167b8 100644
--- a/packages/extension-agent/client/components/computer/computer-page.vue
+++ b/packages/extension-agent/client/components/computer/computer-page.vue
@@ -54,11 +54,9 @@
             <div class="provider-row">
                 <div class="provider-item">
                     <div class="provider-copy">
-                        <div class="row-title">默认电脑能力后端</div>
+                        <div class="row-title">默认能力后端</div>
                         <div v-if="!hideDesc" class="row-description">
-                            Agent
-                            会优先使用这里选择的执行环境，建议优先启用隔离后端，
-                            Local 仅在明确知道风险时再打开。
+                            Agent 会优先使用这里选择的执行环境。推荐先用隔离后端。
                         </div>
                     </div>
                     <div class="provider-value">
@@ -67,17 +65,17 @@
                             class="provider-select"
                             @update:model-value="updateProvider"
                         >
-                            <el-option label="E2B" value="e2b" />
-                            <el-option label="open-terminal" value="open-terminal" />
-                            <el-option label="Local（高风险）" value="local" />
+                            <el-option label="E2B（云端沙箱）" value="e2b" />
+                            <el-option label="Open Terminal（远程/容器）" value="open-terminal" />
+                            <el-option label="Local（本机环境）" value="local" />
                         </el-select>
                     </div>
                 </div>
                 <div class="provider-item">
                     <div class="provider-copy">
-                        <div class="row-title">会话自动关闭</div>
+                        <div class="row-title">会话自动释放</div>
                         <div v-if="!hideDesc" class="row-description">
-                            当会话的空闲时间超过此时间后会自动关闭。
+                            会话闲置超过此时间后自动关闭。
                         </div>
                     </div>
                     <div class="provider-value">
@@ -206,7 +204,6 @@ const props = withDefaults(
                 dangerouslySkipPermissions: false,
                 preferredShell: 'auto',
                 scopePath: '',
-                writableRoots: [],
                 readOnlyRoots: [],
                 denyRoots: [],
                 ignores: [],
diff --git a/packages/extension-agent/client/components/computer/config-backends/backend-e2b.vue b/packages/extension-agent/client/components/computer/config-backends/backend-e2b.vue
index 92b73ca1b..fac437bc1 100644
--- a/packages/extension-agent/client/components/computer/config-backends/backend-e2b.vue
+++ b/packages/extension-agent/client/components/computer/config-backends/backend-e2b.vue
@@ -1,7 +1,7 @@
 <template>
     <el-form class="backend-form" label-position="top">
         <div class="section">
-            <div class="section-title">基础设置</div>
+            <div class="section-title">沙箱设置</div>
 
             <div class="form-grid">
                 <div class="form-cell form-cell-full">
@@ -64,7 +64,7 @@
         </div>
         
         <div class="info-box">
-            <div class="info-desc">推荐优先把 E2B 作为默认后端；配置会被保存，但实际可用性仍取决于状态检测结果。</div>
+            <div class="info-desc">保存后会根据 E2B 的响应更新可用状态。</div>
         </div>
     </el-form>
 </template>
diff --git a/packages/extension-agent/client/components/computer/config-backends/backend-local.vue b/packages/extension-agent/client/components/computer/config-backends/backend-local.vue
index 129c14fd9..a5076b89a 100644
--- a/packages/extension-agent/client/components/computer/config-backends/backend-local.vue
+++ b/packages/extension-agent/client/components/computer/config-backends/backend-local.vue
@@ -2,18 +2,22 @@
     <el-form class="backend-form" label-position="top">
         <div class="warning-box">
             <div class="warning-title">本地终端能力很危险</div>
-            <div class="warning-desc">它会直接在宿主机执行命令，而不是隔离沙箱。建议默认关闭，只在明确知道风险、且需要访问本地工作区时临时启用。</div>
+            <div class="warning-desc">直接访问宿主机文件系统并运行系统命令。模型会以当前用户权限操作。</div>
         </div>
 
         <div class="section">
             <div class="section-title">基础设置</div>
+            <div class="section-copy">
+                Linux 未开启“跳过沙箱与权限约束”时需要安装
+                bubblewrap (bwrap)。开启后不使用 bwrap。
+            </div>
 
             <div class="form-grid">
                 <div class="form-cell">
-                    <el-form-item label="作用域路径">
+                    <el-form-item label="初始工作目录 (CWD)">
                         <el-input
                             :model-value="config.scopePath"
-                            placeholder="留空时使用当前工作目录"
+                            placeholder="留空时使用当前进程目录"
                             @update:model-value="set('scopePath', $event)"
                         />
                     </el-form-item>
@@ -26,10 +30,10 @@
                             @update:model-value="set('sandboxMode', $event)"
                         >
                             <el-option
-                                label="工作区可写"
+                                label="沙箱：可写"
                                 value="workspace-write"
                             />
-                            <el-option label="只读" value="read-only" />
+                            <el-option label="沙箱：只读" value="read-only" />
                         </el-select>
                     </el-form-item>
                 </div>
@@ -90,10 +94,9 @@
         </div>
 
         <div class="section">
-            <div class="section-title">访问边界</div>
+            <div class="section-title">文件策略</div>
             <div class="section-copy">
-                路径和 glob
-                模式请逐条输入，按回车后会变成标签，修改时更直观，也不容易误删。
+                初始工作目录只是起点，不是访问边界。这里可以排除扫描结果，或单独禁止、只读某些路径。
             </div>
 
             <div class="form-grid">
@@ -120,31 +123,6 @@
                     </el-form-item>
                 </div>
 
-                <div class="form-cell form-cell-full">
-                    <el-form-item label="可写根目录">
-                        <el-select
-                            :model-value="config.writableRoots"
-                            multiple
-                            filterable
-                            allow-create
-                            clearable
-                            default-first-option
-                            :reserve-keyword="false"
-                            placeholder="输入绝对路径后按回车添加"
-                            @update:model-value="
-                                setList('writableRoots', $event)
-                            "
-                        >
-                            <el-option
-                                v-for="item in config.writableRoots"
-                                :key="item"
-                                :label="item"
-                                :value="item"
-                            />
-                        </el-select>
-                    </el-form-item>
-                </div>
-
                 <div class="form-cell form-cell-full">
                     <el-form-item label="只读根目录">
                         <el-select
@@ -256,10 +234,10 @@
                 :model-value="config.dangerouslySkipPermissions"
                 @update:model-value="set('dangerouslySkipPermissions', $event)"
             >
-                <span class="danger-title">跳过权限检查（危险）</span>
+                <span class="danger-title">跳过沙箱与权限约束（危险）</span>
             </el-checkbox>
             <div class="danger-copy">
-                启用后将跳过作用域、白名单和高危操作确认。仅在完全信任当前模型时使用。
+                开启后不使用 bwrap，也不做路径保护、命令白名单和高危确认。模型会直接以当前用户权限运行。
             </div>
         </div>
     </el-form>
@@ -269,7 +247,6 @@
 import type { LocalBackendConfig } from '../../../../src/types'
 
 type LocalListKey =
-    | 'writableRoots'
     | 'readOnlyRoots'
     | 'denyRoots'
     | 'ignores'
diff --git a/packages/extension-agent/client/components/computer/config-backends/backend-open-terminal.vue b/packages/extension-agent/client/components/computer/config-backends/backend-open-terminal.vue
index aae319ebd..0a02af10a 100644
--- a/packages/extension-agent/client/components/computer/config-backends/backend-open-terminal.vue
+++ b/packages/extension-agent/client/components/computer/config-backends/backend-open-terminal.vue
@@ -1,7 +1,7 @@
 <template>
     <el-form class="backend-form" label-position="top">
         <div class="section">
-            <div class="section-title">连接设置</div>
+            <div class="section-title">接口设置</div>
 
             <div class="form-grid">
                 <div class="form-cell form-cell-full">
@@ -72,14 +72,14 @@ const emit = defineEmits<{
 
 const warning = computed(() => {
     if (props.config.deploymentMode === 'docker') {
-        return 'Docker 模式的隔离效果取决于容器配置，建议限制网络访问和挂载目录；如果容器隔离做得不好，风险会逐渐接近 Local。'
+        return 'Docker 模式的安全性取决于容器配置。请限制挂载目录和网络权限。'
     }
 
     if (props.config.deploymentMode === 'bare-metal') {
-        return '裸机模式没有宿主机隔离，命令会直接在远端主机上执行。虽然不是本机 Local，但仍属于高风险配置。'
+        return '裸机模式会直接在远端主机执行命令，请只用于受控服务器。'
     }
 
-    return '无法确认部署模式，请按最小权限原则配置；隔离边界不明确时，不建议把它当成高信任后端。'
+    return '无法确认部署模式。请按最低权限配置。'
 })
 
 function set<K extends keyof OpenTerminalBackendConfig>(
diff --git a/packages/extension-agent/client/components/computer/configuration-panel.vue b/packages/extension-agent/client/components/computer/configuration-panel.vue
index b990d41c7..623c78c75 100644
--- a/packages/extension-agent/client/components/computer/configuration-panel.vue
+++ b/packages/extension-agent/client/components/computer/configuration-panel.vue
@@ -25,7 +25,7 @@
                         </el-tag>
                     </div>
                     <div v-if="!props.hideDesc" class="backend-copy">
-                        云端隔离沙箱，支持桌面和 GUI，适合需要完整隔离的任务。
+                        云端隔离环境，适合默认执行后端。需要时可开启桌面能力。
                     </div>
                     <div
                         v-if="props.status.backends.e2b.error"
@@ -37,7 +37,7 @@
 
                 <div class="backend-actions">
                     <el-button text @click="openGuide('e2b')">
-                        如何配置
+                        配置指南
                     </el-button>
                     <el-button
                         class="test-link"
@@ -99,7 +99,7 @@
                         </el-tag>
                     </div>
                     <div v-if="!props.hideDesc" class="backend-copy">
-                        接入已部署的远程执行服务，适合复用现有的执行节点。
+                        连接已部署的 Open Terminal 服务，用远程机器或容器执行任务。
                     </div>
                     <div
                         v-if="props.status.backends['open-terminal'].error"
@@ -111,7 +111,7 @@
 
                 <div class="backend-actions">
                     <el-button text @click="openGuide('open-terminal')">
-                        如何配置
+                        配置指南
                     </el-button>
                     <el-button
                         class="test-link"
@@ -176,7 +176,7 @@
                         </el-tag>
                     </div>
                     <div v-if="!props.hideDesc" class="backend-copy">
-                        直接在宿主机执行，终端能力风险很高，只建议在完全信任当前模型和工作目录时启用。
+                        直接访问宿主机文件系统并运行系统命令。模型会以当前用户权限操作。
                     </div>
                     <div
                         v-if="props.status.backends.local.error"
@@ -188,7 +188,7 @@
 
                 <div class="backend-actions">
                     <el-button text @click="openGuide('local')">
-                        如何配置
+                        配置指南
                     </el-button>
                     <el-button
                         class="test-link"
@@ -225,7 +225,7 @@
 
         <el-dialog
             v-model="guideOpen"
-            :title="`${guide.title} 如何配置`"
+            :title="`${guide.title} 配置指南`"
             width="min(860px, calc(100vw - 32px))"
             destroy-on-close
         >
@@ -341,38 +341,38 @@ const guide = computed<GuideContent>(() => {
     if (guideType.value === 'local') {
         return {
             title: 'Local 本地环境',
-            intro: 'Local 会直接在宿主机上读写文件并执行终端命令，适合你明确知道工作目录、命令边界和风险的时候使用。',
-            warn: '建议保持默认关闭。优先把 scopePath 收紧到单个项目目录，并保留按需审批。',
+            intro: 'Local 使用这台机器的文件系统和终端。适合需要直接操作本机项目时使用。',
+            warn: '开启“跳过沙箱与权限约束”后，不再使用 bwrap，也不会做路径保护、命令白名单和高危确认。',
             sections: [
                 {
-                    title: '推荐配置顺序',
+                    title: '配置顺序',
                     steps: [
-                        '先把“作用域路径”设置为单个项目的绝对路径，只给 Agent 它必须访问的目录。',
-                        '把“沙箱模式”设为“只读”，只有在确实需要改文件时再切到“工作区可写”。',
-                        '把“审批模式”保留为“按需审批”，这样高风险命令还需要人工确认。',
-                        '把“网络策略”设为“阻止”，只有明确需要联网下载或调用外部服务时再放开。',
-                        '如果只允许一小部分命令，就填写“允许的命令”；如果只是排除危险命令，就填写“禁止的命令”。',
-                        '设置完成后先点“测试连接”，确认没问题再启用。'
+                        'Linux 先安装 bubblewrap (bwrap)。如果准备开启“跳过沙箱与权限约束”，可以不装。',
+                        '把“初始工作目录”设为常用项目目录。它只是起点，不限制访问范围。',
+                        '默认用“沙箱：只读”。需要改文件时再切到“沙箱：可写”。',
+                        '保留“按需审批”，高风险命令会先问你。',
+                        '不需要联网时，把网络策略设为“阻止”。',
+                        '保存后点“测试连接”，确认本机环境可用。'
                     ]
                 },
                 {
-                    title: '字段怎么填',
+                    title: '字段说明',
                     items: [
-                        '作用域路径：必填绝对路径，建议直接指向你的仓库根目录。',
-                        '可写根目录：仅当需要写 scopePath 之外的路径时再加。',
-                        '只读根目录 / 禁止访问目录：用来进一步收紧访问边界。',
-                        '首选终端：一般保持“自动检测”即可。',
-                        '命令超时：保守值可以先用 0.5 分钟。',
-                        '忽略模式：把 node_modules、dist、缓存目录排除掉，能减少误读和误改。'
+                        '初始工作目录：终端和文件面板的起始路径，不是访问边界。',
+                        '只读根目录：这些路径可以读，不能写。',
+                        '禁止访问目录：这些路径不允许读写。',
+                        '忽略模式：减少搜索和文件列表里的噪音，比如 node_modules、dist。',
+                        '跳过沙箱与权限约束：直接运行，不使用 bwrap，也不拦高危命令。'
                     ],
                     code: [
-                        '推荐起步配置',
-                        '作用域路径: /path/to/project 或 C:\\repo\\project',
+                        '# Ubuntu / Debian',
+                        'sudo apt install bubblewrap',
+                        '',
+                        '# 建议起步',
+                        '初始工作目录: /path/to/project 或 C:\\repo\\project',
                         '沙箱模式: read-only',
                         '审批模式: on-request',
-                        '首选终端: auto',
-                        '命令超时: 0.5',
-                        '网络策略: block'
+                        '跳过沙箱与权限约束: false'
                     ].join('\n')
                 }
             ],
@@ -383,19 +383,15 @@ const guide = computed<GuideContent>(() => {
     if (guideType.value === 'open-terminal') {
         return {
             title: 'open-terminal 远程终端',
-            intro: 'open-terminal 更适合把执行环境放到远端机器或容器里，ChatLuna 只需要连接它暴露出的 HTTP API。',
-            warn: '官方文档推荐优先使用 Docker。裸机模式会直接在远端宿主机上执行命令，风险明显更高。',
+            intro: 'ChatLuna 通过 HTTP API 连接 Open Terminal。服务可以跑在容器里，也可以跑在远端主机上。',
+            warn: '优先用 Docker。裸机模式会直接在远端主机执行命令。',
             sections: [
                 {
-                    title: '最快启动方式',
+                    title: 'Docker 快速启动',
                     steps: [
-                        '用 Docker 启动 open-terminal，并显式设置 API Key。',
-                        '建议同时设置 `HOME=/home/user`，让 `~` 和相对路径都稳定落在挂载卷里。',
-                        '如果你需要让图片、音频、视频、PDF、压缩包等二进制文件在 Agent 场景里正常读写或传递，记得保留 `OPEN_TERMINAL_BINARY_MIME_PREFIXES`。',
-                        '启动后把“基础 URL”填成你的服务地址，例如 http://localhost:8000。',
-                        '把“API 密钥”填成 env:OPEN_TERMINAL_API_KEY 或直接填密钥。',
-                        '如果服务跑在 Docker 里，把“部署模式”设为 Docker；如果是 pip/uvx 裸机启动，就选裸机。',
-                        '配置完成后先点“测试连接”，确认通了再启用。'
+                        '推荐先用 Docker 跑起来。',
+                        'ChatLuna 里基础 URL 填 http://host:8000。',
+                        'API 密钥填 env:OPEN_TERMINAL_API_KEY 或直接填密钥。'
                     ],
                     code: [
                         'docker run -d --name open-terminal --restart unless-stopped \\',
@@ -409,32 +405,48 @@ const guide = computed<GuideContent>(() => {
                     ].join('\n')
                 },
                 {
-                    title: '表单字段建议',
+                    title: 'Docker Compose 示例',
+                    code: [
+                        'services:',
+                        '  open-terminal:',
+                        '    image: ghcr.io/open-webui/open-terminal',
+                        '    restart: unless-stopped',
+                        '    ports:',
+                        '      - "8000:8000"',
+                        '    working_dir: /home/user',
+                        '    environment:',
+                        '      HOME: /home/user',
+                        '      OPEN_TERMINAL_API_KEY: your-secret-key',
+                        '      OPEN_TERMINAL_BINARY_MIME_PREFIXES: image,audio,video,application/pdf,application/zip,application/vnd.openxmlformats-officedocument.,application/octet-stream',
+                        '    volumes:',
+                        '      - open-terminal:/home/user',
+                        '',
+                        'volumes:',
+                        '  open-terminal:'
+                    ].join('\n')
+                },
+                {
+                    title: '字段说明',
                     items: [
-                        '基础 URL：填写 open-terminal 对外地址，通常是 http://host:8000。',
-                        'API 密钥：推荐使用 env:OPEN_TERMINAL_API_KEY，便于统一管理。',
-                        '`OPEN_TERMINAL_BINARY_MIME_PREFIXES`：用于声明哪些二进制 MIME 类型允许按文件处理；推荐至少保留 image、audio、video、application/pdf、application/zip。',
-                        '部署模式：按真实部署情况选 Docker / 裸机 / 未知。',
-                        '如果你用 Docker，建议把 HOME 和工作目录都固定到 /home/user；其中 HOME 会影响 `~` 的展开位置，工作目录会影响部分相对路径和会话 cwd 的初始位置。',
-                        '这样可以避免新版本 open-terminal 按会话 cwd 解析相对路径时落到 /app 之类的镜像目录。',
-                        '用户隔离：只有你明确启用了 open-terminal 的 multi-user 模式时再打开；这个开关主要是配置标记，不会替代底层隔离。',
-                        '如果你需要每个用户更强隔离，官方 README 也建议考虑每用户单独容器的方案。'
+                        '基础 URL：Open Terminal 对外地址。',
+                        'API 密钥：推荐使用 env: 前缀读取环境变量。',
+                        '部署模式：用于提示风险，不会改变远端隔离方式。',
+                        '用户隔离：只有服务端启用了 multi-user 模式时再打开。',
+                        'Docker 建议固定 HOME 和工作目录，避免相对路径落到镜像目录。'
                     ],
                     code: [
                         '基础 URL: http://localhost:8000',
                         'API 密钥: env:OPEN_TERMINAL_API_KEY',
-                        '二进制类型: image,audio,video,application/pdf,application/zip,...',
                         '部署模式: docker',
-                        'Docker 环境变量: HOME=/home/user（影响 ~ 的展开位置）',
-                        'Docker 工作目录: /home/user',
                         '用户隔离: false'
                     ].join('\n')
                 },
                 {
                     title: '裸机启动示例',
                     steps: [
-                        '如果不用 Docker，可以用 uvx 或 pip 安装后直接启动。',
-                        '这种模式下命令会直接以当前用户权限运行，请只在可信机器上使用。'
+                        '不用 Docker 时，可以用 uvx 或 pip 启动。',
+                        '裸机会直接在远端主机执行命令，只放在受控机器上。',
+                        '启动后把部署模式选为“裸机”。'
                     ],
                     code: [
                         'uvx open-terminal run --host 0.0.0.0 --port 8000 --api-key your-secret-key',
@@ -459,22 +471,21 @@ const guide = computed<GuideContent>(() => {
 
     return {
         title: 'E2B 沙箱',
-        intro: 'E2B 适合做默认电脑后端：隔离好、开箱即用，还能在需要时扩展到桌面流和 GUI 自动化。',
-        warn: '没有桌面需求时，把“桌面模板”留空即可；只有要用桌面流和截图时，才需要单独准备 desktop template。',
+        intro: 'E2B 提供云端沙箱。普通文件、终端和代码任务直接使用 base 模板即可。',
+        warn: '不需要桌面功能时，“桌面模板”留空。',
         sections: [
             {
-                title: '基础配置步骤',
+                title: '配置步骤',
                 steps: [
-                    '先在 E2B 创建账号，并从 Dashboard 的 Keys 页面生成 API Key。',
-                    '把“API 密钥”填成 env:E2B_API_KEY，或直接填入你的密钥。',
-                    '普通文件和终端任务直接把“模板”保持为 base 即可。',
-                    '如果你需要桌面能力，再去构建一个 desktop template，并把模板名填到“桌面模板”。',
-                    '“超时时间”建议先保留 5 分钟；“保持连接”适合连续任务复用同一个沙箱。',
-                    '配置完先点“测试连接”，通过后再启用。'
+                    '在 E2B 控制台创建 API Key。',
+                    'API 密钥推荐填 env:E2B_API_KEY。',
+                    '普通任务保持模板为 base。',
+                    '需要桌面时再填写桌面模板。',
+                    '保存后点“测试连接”。'
                 ]
             },
             {
-                title: '没有桌面需求时的推荐值',
+                title: '推荐值',
                 code: [
                     'API 密钥: env:E2B_API_KEY',
                     '模板: base',
@@ -484,11 +495,10 @@ const guide = computed<GuideContent>(() => {
                 ].join('\n')
             },
             {
-                title: '需要桌面时怎么填',
+                title: '桌面能力',
                 items: [
-                    'E2B Desktop 文档给了完整的 desktop template 示例，构建完成后可以直接用模板名，例如 desktop。',
-                    '填了“桌面模板”后，这个后端才会暴露桌面流、截图和桌面操作能力。',
-                    '如果你只是让 Agent 跑 bash、读写文件、搜索代码，不需要额外开启桌面模板。'
+                    '填了“桌面模板”后，才会开启桌面流、截图和桌面操作。',
+                    '只跑 bash、读写文件、搜索代码时不需要桌面模板。'
                 ],
                 code: [
                     'API 密钥: env:E2B_API_KEY',
diff --git a/packages/extension-agent/client/components/computer/files-panel.vue b/packages/extension-agent/client/components/computer/files-panel.vue
index 6d62e78f0..c0b01e627 100644
--- a/packages/extension-agent/client/components/computer/files-panel.vue
+++ b/packages/extension-agent/client/components/computer/files-panel.vue
@@ -54,7 +54,7 @@
                         v-model="search"
                         clearable
                         class="search-input"
-                        placeholder="搜索当前目录，支持 * 通配符"
+                        placeholder="搜索文件，支持 * 通配符"
                         @clear="clearSearch"
                         @keyup.enter="searchFiles"
                     >
@@ -82,7 +82,7 @@
                     <div class="panel-head">
                         <div>
                             <div class="panel-title">
-                                {{ keyword ? '搜索结果' : '当前目录' }}
+                                {{ keyword ? '匹配文件' : '目录列表' }}
                             </div>
                             <div class="panel-copy">
                                 {{ backendLabel }} · {{ currentDir }} ·
@@ -157,15 +157,15 @@
                             <div class="empty-title">
                                 {{
                                     keyword
-                                        ? '没有找到匹配文件'
-                                        : '当前目录为空'
+                                        ? '未找到匹配文件'
+                                        : '暂无内容'
                                 }}
                             </div>
                             <div class="empty-copy">
                                 {{
                                     keyword
-                                        ? '试试更短的关键字，或输入 *.ts 这样的通配符。'
-                                        : '点击文件夹进入下一层，或直接在顶部输入路径。'
+                                        ? '换个关键字，或使用 *.ts 这样的通配符。'
+                                        : '点击文件夹开始浏览，或在顶部输入路径。'
                                 }}
                             </div>
                         </div>
@@ -276,9 +276,9 @@
                                 class="image-preview"
                             />
                             <div v-else class="empty-state viewer-empty">
-                                <div class="empty-title">图片暂时无法显示</div>
+                                <div class="empty-title">图片无法显示</div>
                                 <div class="empty-copy">
-                                    可以刷新标签重试，或者切换到其他文件继续浏览。
+                                    刷新标签重试，或查看其他文件。
                                 </div>
                             </div>
                         </div>
@@ -291,9 +291,9 @@
                             placeholder="当前文件为空。"
                         />
                         <div v-else class="empty-state viewer-empty">
-                            <div class="empty-title">打开文件开始预览</div>
+                            <div class="empty-title">选择文件进行预览</div>
                             <div class="empty-copy">
-                                左侧列表高度已限制，可独立滚动；中间拖拽条可以调节左右区域宽度。
+                                支持代码和图片预览。拖动中间分割线可调整宽度。
                             </div>
                         </div>
                     </div>
@@ -511,7 +511,7 @@ const browserSize = ref(38)
 const history = ref<string[]>([])
 const historyIndex = ref(-1)
 
-const rootPath = computed(() => clean(props.config.local.scopePath || '/'))
+const rootPath = ref('/')
 const rootLabel = computed(() => {
     const parts = rootPath.value.split('/').filter(Boolean)
     return parts[parts.length - 1] || rootPath.value
@@ -535,7 +535,7 @@ const canGoForward = computed(
     () =>
         historyIndex.value > -1 && historyIndex.value < history.value.length - 1
 )
-const canGoUp = computed(() => currentDir.value !== rootPath.value)
+const canGoUp = computed(() => upOf(currentDir.value) !== currentDir.value)
 const bodyStyle = computed(() => ({
     '--browser-size': `${browserSize.value}%`
 }))
@@ -571,8 +571,13 @@ const crumbs = computed(() => {
 })
 
 watch(
-    [() => props.config.defaultProvider, rootPath],
+    () => props.config.defaultProvider,
     async () => {
+        rootPath.value = clean(
+            await send('chatluna-agent/getComputerHome', {
+                backend: props.config.defaultProvider
+            })
+        )
         currentDir.value = rootPath.value
         pathInput.value = rootPath.value
         search.value = ''
@@ -702,13 +707,7 @@ async function goUp() {
     }
 
     search.value = ''
-    const path = upOf(currentDir.value)
-    await loadDir(
-        path.startsWith(rootPath.value) || rootPath.value === '/'
-            ? path
-            : rootPath.value,
-        'push'
-    )
+    await loadDir(upOf(currentDir.value), 'push')
 }
 
 async function refreshFolder() {
diff --git a/packages/extension-agent/client/components/computer/status-panel.vue b/packages/extension-agent/client/components/computer/status-panel.vue
index 1611f5799..a02301b5f 100644
--- a/packages/extension-agent/client/components/computer/status-panel.vue
+++ b/packages/extension-agent/client/components/computer/status-panel.vue
@@ -2,9 +2,9 @@
     <div class="panel" :class="{ compact: props.compactMode }">
         <div class="panel-header">
             <div>
-                <div class="panel-title">后端状态</div>
+                <div class="panel-title">后端可用性</div>
                 <div v-if="!props.hideDesc" class="panel-description">
-                    查看可用性和会话数量。
+                    查看各执行环境的连接状态和活跃会话。
                 </div>
             </div>
         </div>
diff --git a/packages/extension-agent/src/computer/backends/e2b.ts b/packages/extension-agent/src/computer/backends/e2b.ts
index d8fb750d6..d1ac0d366 100644
--- a/packages/extension-agent/src/computer/backends/e2b.ts
+++ b/packages/extension-agent/src/computer/backends/e2b.ts
@@ -424,6 +424,13 @@ export class E2BComputerSession implements ComputerSessionApi {
         }
     }
 
+    async getTempDir() {
+        const result = await this.execute(
+            "printf %s '$" + '{TMPDIR:-$' + '{TMP:-$' + "{TEMP:-/tmp}}}'"
+        )
+        return result.stdout.trim() || '/tmp'
+    }
+
     async createTerminal(options: TerminalOptions = {}) {
         try {
             const sandbox = await this.ensureSandbox()
diff --git a/packages/extension-agent/src/computer/backends/local/index.ts b/packages/extension-agent/src/computer/backends/local/index.ts
index 827b3c916..d811dcd97 100644
--- a/packages/extension-agent/src/computer/backends/local/index.ts
+++ b/packages/extension-agent/src/computer/backends/local/index.ts
@@ -3,6 +3,7 @@
 import { spawn } from 'node:child_process'
 import { createReadStream } from 'node:fs'
 import fs from 'node:fs/promises'
+import os from 'node:os'
 import path from 'path'
 import { randomUUID } from 'crypto'
 import mimeTypes from 'mime-types'
@@ -21,12 +22,7 @@ import {
     resolveInteractiveShellCommand,
     resolveShellCommand
 } from './shell'
-import {
-    confirmHighRiskCommand,
-    ensureCommandAllowed,
-    ensureCommandPathsInScope,
-    ensureWorkdirInScope
-} from './security'
+import { confirmHighRiskCommand, ensureCommandAllowed } from './security'
 import {
     ensureLocalCommandAccess,
     ensureLocalPathAccess,
@@ -65,10 +61,7 @@ export class LocalComputerSession implements ComputerSessionApi {
     }
 
     async connect() {
-        await fs.mkdir(
-            path.join(this._cfg.scopePath || process.cwd(), '.tmp'),
-            { recursive: true }
-        )
+        await fs.mkdir(os.tmpdir(), { recursive: true })
         this._connected = true
     }
 
@@ -122,13 +115,9 @@ export class LocalComputerSession implements ComputerSessionApi {
     async execute(command: string, options: ExecuteOptions = {}) {
         ensureCommandAllowed(command, this._cfg)
 
-        const tmp = path.join(this._cfg.scopePath || process.cwd(), '.tmp')
+        const tmp = os.tmpdir()
         const workdir = options.workdir || this._cfg.scopePath || process.cwd()
 
-        ensureWorkdirInScope(workdir, this._cfg)
-        ensureCommandPathsInScope(command, this._cfg, (filePath) =>
-            this.isInScope(filePath)
-        )
         ensureLocalCommandAccess(command, workdir, this._cfg)
         await confirmHighRiskCommand(command, this._cfg, options.session)
 
@@ -155,13 +144,9 @@ export class LocalComputerSession implements ComputerSessionApi {
     ) {
         ensureCommandAllowed(command, this._cfg)
 
-        const tmp = path.join(this._cfg.scopePath || process.cwd(), '.tmp')
+        const tmp = os.tmpdir()
         const workdir = options.workdir || this._cfg.scopePath || process.cwd()
 
-        ensureWorkdirInScope(workdir, this._cfg)
-        ensureCommandPathsInScope(command, this._cfg, (filePath) =>
-            this.isInScope(filePath)
-        )
         ensureLocalCommandAccess(command, workdir, this._cfg)
         await confirmHighRiskCommand(command, this._cfg, options.session)
 
@@ -217,6 +202,10 @@ export class LocalComputerSession implements ComputerSessionApi {
         }
     }
 
+    async getTempDir() {
+        return os.tmpdir()
+    }
+
     isInScope(filePath: string) {
         return this._store.isInScope(filePath)
     }
@@ -228,9 +217,8 @@ export class LocalComputerSession implements ComputerSessionApi {
     async createTerminal(
         options: { cwd?: string; cols?: number; rows?: number } = {}
     ) {
-        const tmp = path.join(this._cfg.scopePath || process.cwd(), '.tmp')
+        const tmp = os.tmpdir()
         const cwd = options.cwd || this._cwd
-        ensureWorkdirInScope(cwd, this._cfg)
         const shell = await resolveInteractiveShellCommand(this._cfg)
         this._cwd = path.resolve(cwd)
         return createLocalTerminal(shell, cwd, {
diff --git a/packages/extension-agent/src/computer/backends/local/sandbox.ts b/packages/extension-agent/src/computer/backends/local/sandbox.ts
index b55e9720c..da2d18543 100644
--- a/packages/extension-agent/src/computer/backends/local/sandbox.ts
+++ b/packages/extension-agent/src/computer/backends/local/sandbox.ts
@@ -64,15 +64,6 @@ export function ensureLocalPathAccess(
     ) {
         throw new Error(`Path "${filePath}" is read-only by configuration.`)
     }
-
-    if (
-        mode === 'write' &&
-        cfg.scopePath &&
-        !isInsideRoot(resolved, cfg.scopePath) &&
-        !cfg.writableRoots.some((root) => isInsideRoot(resolved, root))
-    ) {
-        throw new Error(`Path "${filePath}" is outside the writable workspace.`)
-    }
 }
 
 export function ensureLocalCommandAccess(
@@ -113,7 +104,7 @@ export function wrapCommandWithSandbox(
     cfg: LocalBackendConfig,
     tmp: string
 ) {
-    if (process.platform === 'win32') {
+    if (process.platform === 'win32' || cfg.dangerouslySkipPermissions) {
         return command
     }
 
@@ -158,16 +149,12 @@ export function wrapCommandWithSandbox(
         }
     }
 
-    const ro = cfg.sandboxMode === 'read-only'
-    const scope = cfg.scopePath || workdir || process.cwd()
-
     return [
         quote(bwrap),
-        '--ro-bind / /',
-        ro
-            ? `--ro-bind ${quote(scope)} ${quote(scope)}`
-            : `--bind ${quote(scope)} ${quote(scope)}`,
-        ro ? `--ro-bind ${quote(tmp)} /tmp` : `--bind ${quote(tmp)} /tmp`,
+        cfg.sandboxMode === 'read-only' ? '--ro-bind / /' : '--bind / /',
+        cfg.sandboxMode === 'read-only'
+            ? `--ro-bind ${quote(tmp)} /tmp`
+            : `--bind ${quote(tmp)} /tmp`,
         '--dev /dev',
         '--proc /proc',
         '--die-with-parent',
diff --git a/packages/extension-agent/src/computer/backends/local/security.ts b/packages/extension-agent/src/computer/backends/local/security.ts
index 17a163335..c812611e3 100644
--- a/packages/extension-agent/src/computer/backends/local/security.ts
+++ b/packages/extension-agent/src/computer/backends/local/security.ts
@@ -1,6 +1,4 @@
 import { randomBytes } from 'crypto'
-import path from 'path'
-
 import { Session } from 'koishi'
 import { LocalBackendConfig } from '../../../types'
 
@@ -52,37 +50,6 @@ export function ensureCommandAllowed(cmd: string, cfg: LocalBackendConfig) {
     }
 }
 
-export function ensureWorkdirInScope(workdir: string, cfg: LocalBackendConfig) {
-    if (cfg.dangerouslySkipPermissions || !cfg.scopePath) return
-
-    const resolved = path.resolve(workdir)
-    const scope = path.resolve(cfg.scopePath)
-    if (resolved !== scope && !resolved.startsWith(scope + path.sep)) {
-        throw new Error(
-            `Working directory "${workdir}" is outside the configured scope path "${cfg.scopePath}".`
-        )
-    }
-}
-
-export function ensureCommandPathsInScope(
-    command: string,
-    cfg: LocalBackendConfig,
-    isInScope: (filePath: string) => boolean
-) {
-    if (cfg.dangerouslySkipPermissions || !cfg.scopePath) return
-
-    for (const match of command.matchAll(
-        /(?:^|[\s="'`:(\[{;<>@,])((?:\/|[A-Za-z]:)[^\s"'`)\]}<>;,@]*)/g
-    )) {
-        const fp = match[1]
-        if (!isInScope(path.resolve(fp))) {
-            throw new Error(
-                `Command references path "${fp}" which is outside the scope path "${cfg.scopePath}".`
-            )
-        }
-    }
-}
-
 export async function confirmHighRiskCommand(
     command: string,
     cfg: LocalBackendConfig,
diff --git a/packages/extension-agent/src/computer/backends/local/store.ts b/packages/extension-agent/src/computer/backends/local/store.ts
index 48720c067..aa38a2158 100644
--- a/packages/extension-agent/src/computer/backends/local/store.ts
+++ b/packages/extension-agent/src/computer/backends/local/store.ts
@@ -37,18 +37,10 @@ export class FileStore implements BaseFileStore {
     }
 
     isInScope(filePath: string) {
-        if (!this._cfg.scopePath) {
-            return true
-        }
-
-        const target = path.resolve(filePath)
-        const scope = path.resolve(this._cfg.scopePath)
-        return target === scope || target.startsWith(scope + path.sep)
+        return true
     }
 
     async readFile(filePath: string, offset?: number, limit?: number) {
-        this.assertInScope(filePath)
-
         const stat = await fs.stat(filePath)
         if (stat.isDirectory()) {
             return (await fs.readdir(filePath, { withFileTypes: true }))
@@ -83,8 +75,6 @@ export class FileStore implements BaseFileStore {
     }
 
     async writeFile(writePath: string, contents: FileContent) {
-        this.assertInScope(writePath)
-
         await fs.mkdir(path.dirname(writePath), { recursive: true })
         await fs.writeFile(writePath, contents)
     }
@@ -95,7 +85,6 @@ export class FileStore implements BaseFileStore {
         newString: string,
         replaceCount?: number
     ) {
-        this.assertInScope(filePath)
         const next = replaceSubstring(
             await fs.readFile(filePath, 'utf-8'),
             oldString,
@@ -118,7 +107,6 @@ export class FileStore implements BaseFileStore {
 
     async grep(pattern: string, searchPath?: string, include?: string) {
         const dir = searchPath || this._cfg.scopePath || process.cwd()
-        this.assertInScope(dir)
 
         const stat = await fs.stat(dir).catch(() => null)
         if (!stat) {
@@ -246,7 +234,6 @@ export class FileStore implements BaseFileStore {
 
     async glob(pattern: string, searchPath?: string) {
         const dir = searchPath || this._cfg.scopePath || process.cwd()
-        this.assertInScope(dir)
 
         const stat = await fs.stat(dir).catch(() => null)
         if (!stat) {
@@ -386,16 +373,6 @@ export class FileStore implements BaseFileStore {
             { dot: true }
         )
     }
-
-    private assertInScope(filePath: string) {
-        if (this.isInScope(filePath)) {
-            return
-        }
-
-        throw new Error(
-            `path "${filePath}" is not in scope "${this._cfg.scopePath}"`
-        )
-    }
 }
 
 function runProcess(file: string, args: string[], cwd: string) {
diff --git a/packages/extension-agent/src/computer/backends/open_terminal.ts b/packages/extension-agent/src/computer/backends/open_terminal.ts
index a7eaca66e..a885cab82 100644
--- a/packages/extension-agent/src/computer/backends/open_terminal.ts
+++ b/packages/extension-agent/src/computer/backends/open_terminal.ts
@@ -634,6 +634,13 @@ exit
 `
     }
 
+    async getTempDir() {
+        const result = await this.execute(
+            "printf %s '$" + '{TMPDIR:-$' + '{TMP:-$' + "{TEMP:-/tmp}}}'"
+        )
+        return result.stdout.trim() || '/tmp'
+    }
+
     async getDesktopInfo() {
         return undefined
     }
diff --git a/packages/extension-agent/src/computer/types.ts b/packages/extension-agent/src/computer/types.ts
index 5bf286103..6d22eb0b5 100644
--- a/packages/extension-agent/src/computer/types.ts
+++ b/packages/extension-agent/src/computer/types.ts
@@ -31,6 +31,7 @@ export interface ComputerSessionApi {
     execute(command: string, options?: ExecuteOptions): Promise<ExecuteResult>
     readAsset?(path: string): Promise<string>
     openAsset(path: string): Promise<OpenAssetResult>
+    getTempDir(): Promise<string>
 
     createTerminal?(options?: TerminalOptions): Promise<TerminalHandle>
     prepareBackgroundCommand?(
diff --git a/packages/extension-agent/src/config/defaults.ts b/packages/extension-agent/src/config/defaults.ts
index d1e3855fd..a8cc02b7e 100644
--- a/packages/extension-agent/src/config/defaults.ts
+++ b/packages/extension-agent/src/config/defaults.ts
@@ -309,7 +309,6 @@ export function createDefaultComputerConfig(): ComputerConfig {
             dangerouslySkipPermissions: false,
             preferredShell: 'auto',
             scopePath: '',
-            writableRoots: [],
             readOnlyRoots: [],
             denyRoots: [],
             ignores: [
diff --git a/packages/extension-agent/src/service/computer.ts b/packages/extension-agent/src/service/computer.ts
index f2b30385e..aff070adc 100644
--- a/packages/extension-agent/src/service/computer.ts
+++ b/packages/extension-agent/src/service/computer.ts
@@ -648,6 +648,11 @@ export class ChatLunaAgentComputerService {
         return await session.glob(input.pattern, input.path)
     }
 
+    async getHomeForUi(clientId: string, backend?: ComputerBackendType) {
+        const session = await this.getOrCreateUiSession(clientId, backend)
+        return session.cwd || session.getScopePath()
+    }
+
     async removeRemoteSkill(dir: string) {
         await this.removeRemoteEntry(dir)
     }
@@ -759,10 +764,6 @@ export class ChatLunaAgentComputerService {
         const session = await this.getToolSession(runConfig)
         return await Promise.all(
             filePaths.map(async (filePath) => {
-                if (!session.isInScope(filePath)) {
-                    throw new Error(`Path is outside scope: ${filePath}`)
-                }
-
                 const fileName = path.posix.basename(
                     filePath.replaceAll('\\', '/')
                 )
diff --git a/packages/extension-agent/src/service/index.ts b/packages/extension-agent/src/service/index.ts
index a9dad4296..00d6eb4df 100644
--- a/packages/extension-agent/src/service/index.ts
+++ b/packages/extension-agent/src/service/index.ts
@@ -2,6 +2,7 @@
 
 import { randomUUID } from 'crypto'
 import { mkdir, rm, stat, writeFile } from 'fs/promises'
+import os from 'node:os'
 import { dirname, join, resolve } from 'path'
 import { Context, Service } from 'koishi'
 import { ChatLunaPlugin } from 'koishi-plugin-chatluna/services/chat'
@@ -623,38 +624,29 @@ export class ChatLunaAgentService extends Service {
         if (input.text.length <= limit) return input.text
 
         if (input.session) {
-            const base =
-                input.session.cwd ||
-                input.session.getScopePath() ||
-                process.cwd()
-            const root = /^[A-Za-z]:[\\/]?$/.test(base)
-                ? `${base[0]}:/`
-                : base === '/'
-                  ? '/'
-                  : base.replace(/[\\/]+$/, '')
-            const filePath =
-                `${root}${root.endsWith('/') ? '' : '/'}` +
-                `.tmp-chatluna-${input.name}-${Date.now()}-${randomUUID()}.txt`
+            const dir = (await input.session.getTempDir()).replace(
+                /[\\/]+$/,
+                ''
+            )
+            const filePath = `${dir}/${input.name}-${Date.now()}-${randomUUID()}.txt`
 
             try {
                 await input.session.writeFile(filePath, input.text)
-                return `Output too large (${input.text.length} chars). Truncated preview below.
-Full output saved to: ${filePath}
-Use file_read with this path plus offset/limit to inspect more.
+                return `${truncateOutput(input.text, limit)}
 
-${truncateOutput(input.text, limit)}`
+Output too large (${input.text.length} chars). Full output saved to: ${filePath}
+Use file_read with this path plus offset/limit to inspect more.
+`
             } catch (err) {
                 this.ctx.logger.warn(err)
-                return `Output too large (${input.text.length} chars). Truncated preview below.
-Failed to save full output: ${getErrorMessage(err)}
+                return `${truncateOutput(input.text, limit)}
 
-${truncateOutput(input.text, limit)}`
+Output too large (${input.text.length} chars). Failed to save full output: ${getErrorMessage(err)}`
             }
         }
 
         const dir =
-            input.outputDir ??
-            resolve(this.ctx.baseDir, 'data/chatluna/truncation')
+            input.outputDir ?? resolve(os.tmpdir(), 'chatluna', 'truncation')
         const filePath = join(
             dir,
             `${input.name}-${Date.now()}-${randomUUID()}.txt`
@@ -663,17 +655,16 @@ ${truncateOutput(input.text, limit)}`
         try {
             await mkdir(dir, { recursive: true })
             await writeFile(filePath, input.text, 'utf-8')
-            return `Output too large (${input.text.length} chars). Truncated preview below.
-Full output saved to: ${filePath}
-Use file_read with this path plus offset/limit to inspect more.
+            return `${truncateOutput(input.text, limit)}
 
-${truncateOutput(input.text, limit)}`
+Output too large (${input.text.length} chars). Full output saved to: ${filePath}
+Use file_read with this path plus offset/limit to inspect more.
+`
         } catch (err) {
             this.ctx.logger.warn(err)
-            return `Output too large (${input.text.length} chars). Truncated preview below.
-Failed to save full output: ${getErrorMessage(err)}
+            return `${truncateOutput(input.text, limit)}
 
-${truncateOutput(input.text, limit)}`
+Output too large (${input.text.length} chars). Failed to save full output: ${getErrorMessage(err)}`
         }
     }
 
diff --git a/packages/extension-agent/src/types.ts b/packages/extension-agent/src/types.ts
index 3234ab45e..207fcea7a 100644
--- a/packages/extension-agent/src/types.ts
+++ b/packages/extension-agent/src/types.ts
@@ -142,6 +142,9 @@ declare module '@koishijs/plugin-console' {
             path?: string
             backend?: ComputerBackendType
         }) => Promise<string[]>
+        'chatluna-agent/getComputerHome': (input?: {
+            backend?: ComputerBackendType
+        }) => Promise<string>
         'chatluna-agent/getComputerDesktop': (input?: {
             backend?: ComputerBackendType
         }) => Promise<ComputerDesktopState>
diff --git a/packages/extension-agent/src/types/computer.ts b/packages/extension-agent/src/types/computer.ts
index cb45e1264..18d67ed16 100644
--- a/packages/extension-agent/src/types/computer.ts
+++ b/packages/extension-agent/src/types/computer.ts
@@ -17,7 +17,6 @@ export interface LocalBackendConfig {
     dangerouslySkipPermissions: boolean
     preferredShell: 'git-bash' | 'powershell' | 'cmd' | 'auto'
     scopePath: string
-    writableRoots: string[]
     readOnlyRoots: string[]
     denyRoots: string[]
     ignores: string[]
diff --git a/packages/extension-agent/src/webui/index.ts b/packages/extension-agent/src/webui/index.ts
index 399072f3b..651080b77 100644
--- a/packages/extension-agent/src/webui/index.ts
+++ b/packages/extension-agent/src/webui/index.ts
@@ -212,6 +212,13 @@ function registerComputerListeners(ctx: Context, agent: AgentRef) {
         }
     )
 
+    ctx.console.addListener(
+        'chatluna-agent/getComputerHome',
+        async function (input) {
+            return await agent().computer.getHomeForUi(this.id, input?.backend)
+        }
+    )
+
     ctx.console.addListener(
         'chatluna-agent/getComputerDesktop',
         async function (input) {

From 70a9f67421ce6b02e273d82f2b861fad074a0946 Mon Sep 17 00:00:00 2001
From: dingyi <dingyi222666@foxmail.com>
Date: Fri, 12 Jun 2026 21:31:53 +0800
Subject: [PATCH 2/5] feat(agent): auto wake background task results

---
 .gitignore                                    |   3 +-
 packages/core/package.json                    |   5 +
 packages/core/src/config.ts                   |   2 +
 packages/core/src/index.ts                    |   2 +
 packages/core/src/llm-core/agent/sub-agent.ts | 388 ++++++++++++------
 packages/core/src/llm-core/agent/wakeup.ts    | 101 +++++
 packages/core/src/locales/en-US.schema.yml    |   1 +
 packages/core/src/locales/zh-CN.schema.yml    |   1 +
 .../conversation/request_conversation.ts      |  10 +-
 packages/core/src/utils/virtual_session.ts    |  47 +++
 .../extension-agent/src/service/sub_agent.ts  |   4 +
 .../extension-agent/src/sub-agent/session.ts  | 237 +----------
 .../extension-agent/src/trigger/session.ts    |  36 +-
 13 files changed, 434 insertions(+), 403 deletions(-)
 create mode 100644 packages/core/src/llm-core/agent/wakeup.ts
 create mode 100644 packages/core/src/utils/virtual_session.ts

diff --git a/.gitignore b/.gitignore
index 40381bd88..5f3c00fde 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,6 +13,7 @@ tsconfig.temp.json
 .DS_Store
 .idea
 .vscode
+.chatluna
 *.suo
 *.ntvs*
 *.njsproj
@@ -23,4 +24,4 @@ packages/*/dist
 packages/*/lib
 
 .VSCodeCounter
-.yarn/install-state.gz
\ No newline at end of file
+.yarn/install-state.gz
diff --git a/packages/core/package.json b/packages/core/package.json
index 68979e3b9..120c80cc1 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -142,6 +142,11 @@
             "import": "./lib/utils/koishi.mjs",
             "require": "./lib/utils/koishi.cjs"
         },
+        "./utils/virtual_session": {
+            "types": "./lib/utils/virtual_session.d.ts",
+            "import": "./lib/utils/virtual_session.mjs",
+            "require": "./lib/utils/virtual_session.cjs"
+        },
         "./utils/langchain": {
             "types": "./lib/utils/langchain.d.ts",
             "import": "./lib/utils/langchain.mjs",
diff --git a/packages/core/src/config.ts b/packages/core/src/config.ts
index 62317a3c8..0ea86f1af 100644
--- a/packages/core/src/config.ts
+++ b/packages/core/src/config.ts
@@ -31,6 +31,7 @@ export interface Config {
     autoPurgeArchiveTimeout: number
     messageQueue: boolean
     messageQueueDelay: number
+    agentTaskAutoWakeup: boolean
     infiniteContext: boolean
     infiniteContextThreshold: number
     rawOnCensor: boolean
@@ -117,6 +118,7 @@ export const Config: Schema<Config> = Schema.intersect([
             .min(0)
             .max(60 * 30)
             .default(0),
+        agentTaskAutoWakeup: Schema.boolean().default(true),
         showThoughtMessage: Schema.boolean().default(false)
     }),
 
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index edbfeb708..d9a107939 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -11,6 +11,7 @@ import * as request from 'koishi-plugin-chatluna/utils/request'
 import { PromiseLikeDisposable } from 'koishi-plugin-chatluna/utils/types'
 import { command } from './command'
 import { Config } from './config'
+import { applyAgentTaskWakeup } from './llm-core/agent/wakeup'
 import { defaultFactory } from './llm-core/chat/default'
 import { apply as loreBook } from './llm-core/memory/lore_book'
 import { apply as authorsNote } from './llm-core/memory/authors_note'
@@ -108,6 +109,7 @@ async function initializeComponents(ctx: Context, config: Config) {
     await ctx.chatluna.preset.init()
     await setupAutoArchive(ctx, config)
     await setupAutoPurgeArchive(ctx, config)
+    applyAgentTaskWakeup(ctx, config)
     loreBook(ctx, config)
     authorsNote(ctx, config)
 }
diff --git a/packages/core/src/llm-core/agent/sub-agent.ts b/packages/core/src/llm-core/agent/sub-agent.ts
index e4adc1115..76a13a574 100644
--- a/packages/core/src/llm-core/agent/sub-agent.ts
+++ b/packages/core/src/llm-core/agent/sub-agent.ts
@@ -16,126 +16,13 @@ import { observationToMessageContent } from './legacy-executor'
 import { MessageQueue } from './types'
 import type { AgentEvent, AgentStep, SubagentContext, ToolMask } from './types'
 
-export interface AgentTaskDescriptor {
-    id: string
-    name: string
-    description: string
-}
-
-export interface AgentTaskTarget {
-    agent: ChatLunaAgent
-    toolMask?: ToolMask
-}
-
-export interface AgentTaskSession {
-    id: string
-    agentId: string
-    agentName: string
-    conversationId: string
-    parentConversationId: string
-    depth: number
-    maxDepth: number
-    parentAgent: string
-    activeRunId?: string
-    messages: BaseMessage[]
-    startedAt: number
-    updatedAt: number
-}
-
-export interface AgentTaskRunTraceEntry {
-    id: string
-    type:
-        | 'prompt'
-        | 'message'
-        | 'thought'
-        | 'tool-call'
-        | 'tool-result'
-        | 'output'
-        | 'error'
-    at: number
-    text: string
-    tool?: string
-    title?: string
-    callId?: string
-}
-
-export interface AgentTaskRun {
-    runId: string
-    taskId: string
-    agentId: string
-    agentName: string
-    conversationId: string
-    parentConversationId: string
-    depth: number
-    state: 'running' | 'completed' | 'failed' | 'aborted'
-    background?: boolean
-    startedAt: number
-    endedAt?: number
-    lastTool?: string
-    toolCount: number
-    turnCount: number
-    error?: string
-    output?: string
-    trace: AgentTaskRunTraceEntry[]
-}
-
-export interface AgentTaskInput {
-    action?: 'run' | 'status' | 'list' | 'message'
-    agent?: string
-    id?: string
-    prompt?: string
-    reason?: string
-    background?: boolean
-    message?: string
-}
-
-export interface AgentTaskQueryContext {
-    session?: Session
-    source?: 'chatluna' | 'character'
-}
-
-export interface AgentTaskResolveContext extends AgentTaskQueryContext {
-    conversationId?: string
-    parent?: SubagentContext
-    runConfig?: ChatLunaToolRunnable
-}
-
-export interface CreateTaskToolOptions {
-    list: (ctx: AgentTaskQueryContext) => Awaitable<AgentTaskDescriptor[]>
-    get: (
-        name: string,
-        ctx: AgentTaskResolveContext
-    ) => Awaitable<AgentTaskTarget | undefined>
-    refresh?: () => Awaitable<void>
-    maxDepth?: number
-    taskTtl?: number
-    runTtl?: number
-    name?: string
-}
-
-export interface AgentTaskToolRuntime {
-    buildToolDescription(): string
-    createTool(): StructuredTool
-    dispose(): Promise<void>
-    getRuns(): AgentTaskRun[]
-    getTasks(): AgentTaskSession[]
-    runTask(
-        input: AgentTaskInput,
-        runConfig?: ChatLunaToolRunnable
-    ): Promise<string>
-}
-
-interface ActiveAgentTaskRun {
-    abort: AbortController
-    queue: MessageQueue
-}
-
 export function createTaskTool(
     options: CreateTaskToolOptions
 ): AgentTaskToolRuntime {
     const tasks = new Map<string, AgentTaskSession>()
     const runs = new Map<string, AgentTaskRun>()
     const active = new Map<string, ActiveAgentTaskRun>()
+    const snapshots = new Map<string, AgentTaskSessionSnapshot>()
     const runDispose = new Map<string, () => void>()
     const taskDispose = new Map<string, () => void>()
     const toolName = options.name ?? 'task'
@@ -159,6 +46,7 @@ export function createTaskTool(
             clearDisposers(taskDispose)
             tasks.clear()
             runs.clear()
+            snapshots.clear()
         },
         getRuns() {
             return [...runs.values()].sort((a, b) => b.startedAt - a.startedAt)
@@ -251,7 +139,7 @@ export function createTaskTool(
                 return [
                     `task_id: ${task.id}`,
                     'state: running',
-                    `hint: use ${toolName} action=status id=${task.id}`
+                    'hint: guidance delivered; result will arrive automatically. Do not poll status.'
                 ].join('\n')
             }
 
@@ -297,7 +185,7 @@ export function createTaskTool(
             }
 
             if (next.activeRunId) {
-                return `Task '${next.id}' is already running. Use action=status to inspect it or action=message to guide it while it runs in background.`
+                return `Task '${next.id}' is already running; result will arrive automatically. Use action=message to guide it.`
             }
 
             const raw = input.prompt?.trim()
@@ -317,8 +205,10 @@ export function createTaskTool(
                     input,
                     toolName,
                     runtime: options,
+                    tasks,
                     runs,
                     active,
+                    snapshots,
                     scheduleRunCleanup,
                     scheduleTaskCleanup,
                     task: next,
@@ -366,6 +256,7 @@ export function createTaskTool(
             createTimeout(async () => {
                 runDispose.delete(runId)
                 runs.delete(runId)
+                snapshots.delete(runId)
                 await options.refresh?.()
             }, runTtl)
         )
@@ -396,6 +287,7 @@ export function createTaskTool(
 
                     cancelRunCleanup(run.runId)
                     runs.delete(run.runId)
+                    snapshots.delete(run.runId)
                 }
 
                 await options.refresh?.()
@@ -406,9 +298,9 @@ export function createTaskTool(
 
 export function buildTaskToolDescription() {
     return [
-        'Delegate focused work to a specialist.',
-        'Use exact agent names. Use background=true for long tasks.',
-        'Use action=list/status to monitor, message to guide, run with id to resume.'
+        'Delegate focused work to a specialist agent (exact name required).',
+        'Set background=true for long tasks; results are delivered to you automatically - never poll status.',
+        'Actions: run (new task, or resume with id), status, list, message (guide a running background task).'
     ].join('\n')
 }
 
@@ -419,8 +311,7 @@ export function renderAvailableAgents(
 ) {
     const lines = [
         '<available_sub_agents>',
-        'Delegate to specialists via the task tool. Use background=true for long work.',
-        'Monitor with action=status; guide running tasks with action=message.',
+        'Delegate via the task tool. background=true for long work; results arrive automatically - do not poll status.',
         ''
     ]
 
@@ -434,16 +325,13 @@ export function renderAvailableAgents(
 
     for (const item of agents) {
         lines.push(
-            '  <sub_agent>',
-            `    <name>${escapeXml(item.name)}</name>`,
-            `    <description>${escapeXml(item.description)}</description>`,
-            '  </sub_agent>'
+            `<sub_agent name="${escapeXml(item.name)}">${escapeXml(item.description)}</sub_agent>`
         )
     }
 
     lines.push(
         '',
-        'Use exact sub-agent names. Include goal, context, and expected result.',
+        'Use exact names. Include goal, context, and expected result in the prompt.',
         '</available_sub_agents>'
     )
 
@@ -543,8 +431,10 @@ async function runAgentTask(options: {
     input: AgentTaskInput
     toolName: string
     runtime: CreateTaskToolOptions
+    tasks: Map<string, AgentTaskSession>
     runs: Map<string, AgentTaskRun>
     active: Map<string, ActiveAgentTaskRun>
+    snapshots: Map<string, AgentTaskSessionSnapshot>
     scheduleRunCleanup: (runId: string) => void
     scheduleTaskCleanup: (taskId: string) => void
     task: AgentTaskSession
@@ -601,9 +491,27 @@ async function runAgentTask(options: {
     const queue = options.input.background ? new MessageQueue() : undefined
     const signal = abort?.signal ?? options.signal
     const promptMessage = new HumanMessage(options.prompt)
+    const snapshot: AgentTaskSessionSnapshot | undefined = options.input
+        .background
+        ? {
+              session: options.session,
+              routing: {
+                  platform: options.session.platform,
+                  selfId: options.session.selfId,
+                  userId: options.session.userId,
+                  username: options.session.username ?? undefined,
+                  guildId: options.session.guildId ?? undefined,
+                  channelId: options.session.channelId ?? undefined,
+                  isDirect: options.session.isDirect ?? false
+              }
+          }
+        : undefined
 
     options.task.activeRunId = runId
     options.runs.set(runId, run)
+    if (snapshot) {
+        options.snapshots.set(runId, snapshot)
+    }
     if (abort && queue) {
         options.active.set(runId, { abort, queue })
     }
@@ -667,6 +575,7 @@ async function runAgentTask(options: {
             options.scheduleRunCleanup(runId)
             options.scheduleTaskCleanup(options.task.id)
             await options.runtime.refresh?.()
+            await notifyFinished(options, run, snapshot)
             return formatTaskResult(
                 options.task,
                 run,
@@ -689,6 +598,7 @@ async function runAgentTask(options: {
             options.scheduleRunCleanup(runId)
             options.scheduleTaskCleanup(options.task.id)
             await options.runtime.refresh?.()
+            await notifyFinished(options, run, snapshot)
             throw err
         } finally {
             options.active.delete(runId)
@@ -703,6 +613,57 @@ async function runAgentTask(options: {
     return await exec()
 }
 
+async function notifyFinished(
+    options: {
+        input: AgentTaskInput
+        runtime: CreateTaskToolOptions
+        tasks: Map<string, AgentTaskSession>
+        active: Map<string, ActiveAgentTaskRun>
+        task: AgentTaskSession
+        target: AgentTaskTarget
+        source: 'chatluna' | 'character'
+    },
+    run: AgentTaskRun,
+    snapshot?: AgentTaskSessionSnapshot
+) {
+    if (!options.input.background || run.state === 'aborted') {
+        return
+    }
+
+    if (options.task.parentConversationId.startsWith('subagent:')) {
+        const task = [...options.tasks.values()].find(
+            (item) => item.conversationId === options.task.parentConversationId
+        )
+        const active = task?.activeRunId
+            ? options.active.get(task.activeRunId)
+            : undefined
+        if (active) {
+            active.queue.push(
+                new HumanMessage(
+                    formatAgentTaskWakeup(
+                        options.task.id,
+                        options.task.agentName,
+                        run
+                    )
+                )
+            )
+        }
+        return
+    }
+
+    try {
+        await options.runtime.onRunFinished?.({
+            run,
+            taskId: options.task.id,
+            agentId: options.target.agent.id,
+            agentName: options.target.agent.name,
+            parentConversationId: options.task.parentConversationId,
+            source: options.source,
+            snapshot
+        })
+    } catch {}
+}
+
 async function onTaskEvent(
     task: AgentTaskSession,
     run: AgentTaskRun,
@@ -895,9 +856,31 @@ function formatTaskStart(task: AgentTaskSession, toolName: string) {
     return [
         `task_id: ${task.id}`,
         `agent: ${task.agentName}`,
-        'state: running',
-        'mode: background',
-        `hint: ${toolName} action=status id=${task.id}; action=message to guide; action=run to resume`
+        'state: running (background)',
+        'hint: result will be delivered automatically - do NOT poll status. ' +
+            'Continue other work or end your reply; use ' +
+            `${toolName} action=message id=${task.id} to send guidance.`
+    ].join('\n')
+}
+
+export function formatAgentTaskWakeup(
+    taskId: string,
+    agentName: string,
+    run: Pick<AgentTaskRun, 'state' | 'output' | 'error'>
+) {
+    return [
+        `<agent_task_result task_id="${escapeXml(taskId)}" agent="${escapeXml(agentName)}" state="${run.state}">`,
+        escapeXml(
+            run.state === 'failed' ? (run.error ?? '') : (run.output ?? '')
+        ),
+        '</agent_task_result>',
+        '',
+        run.state === 'failed'
+            ? 'Automatic notice: a background task you started failed. ' +
+              `Report the failure or retry with task action=run id=${taskId}.`
+            : 'Automatic notice: a background task you started finished. ' +
+              'Use the result to respond to the user; continue it with ' +
+              `task action=run id=${taskId} if needed.`
     ].join('\n')
 }
 
@@ -1035,3 +1018,150 @@ function escapeXml(value: string) {
         .replace(/"/g, '&quot;')
         .replace(/'/g, '&apos;')
 }
+
+export interface AgentTaskDescriptor {
+    id: string
+    name: string
+    description: string
+}
+
+export interface AgentTaskTarget {
+    agent: ChatLunaAgent
+    toolMask?: ToolMask
+}
+
+export interface AgentTaskSession {
+    id: string
+    agentId: string
+    agentName: string
+    conversationId: string
+    parentConversationId: string
+    depth: number
+    maxDepth: number
+    parentAgent: string
+    activeRunId?: string
+    messages: BaseMessage[]
+    startedAt: number
+    updatedAt: number
+}
+
+export interface AgentTaskRunTraceEntry {
+    id: string
+    type:
+        | 'prompt'
+        | 'message'
+        | 'thought'
+        | 'tool-call'
+        | 'tool-result'
+        | 'output'
+        | 'error'
+    at: number
+    text: string
+    tool?: string
+    title?: string
+    callId?: string
+}
+
+export interface AgentTaskRun {
+    runId: string
+    taskId: string
+    agentId: string
+    agentName: string
+    conversationId: string
+    parentConversationId: string
+    depth: number
+    state: 'running' | 'completed' | 'failed' | 'aborted'
+    background?: boolean
+    startedAt: number
+    endedAt?: number
+    lastTool?: string
+    toolCount: number
+    turnCount: number
+    error?: string
+    output?: string
+    trace: AgentTaskRunTraceEntry[]
+}
+
+export interface AgentTaskSessionSnapshot {
+    session?: Session
+    routing?: {
+        platform: string
+        selfId: string
+        userId: string
+        username?: string
+        guildId?: string
+        channelId?: string
+        isDirect: boolean
+    }
+    bindingKey?: string
+}
+
+export interface AgentTaskFinishedPayload {
+    run: AgentTaskRun
+    taskId: string
+    agentId: string
+    agentName: string
+    parentConversationId: string
+    source: 'chatluna' | 'character'
+    snapshot?: AgentTaskSessionSnapshot
+}
+
+export interface AgentTaskInput {
+    action?: 'run' | 'status' | 'list' | 'message'
+    agent?: string
+    id?: string
+    prompt?: string
+    reason?: string
+    background?: boolean
+    message?: string
+}
+
+export interface AgentTaskQueryContext {
+    session?: Session
+    source?: 'chatluna' | 'character'
+}
+
+export interface AgentTaskResolveContext extends AgentTaskQueryContext {
+    conversationId?: string
+    parent?: SubagentContext
+    runConfig?: ChatLunaToolRunnable
+}
+
+export interface CreateTaskToolOptions {
+    list: (ctx: AgentTaskQueryContext) => Awaitable<AgentTaskDescriptor[]>
+    get: (
+        name: string,
+        ctx: AgentTaskResolveContext
+    ) => Awaitable<AgentTaskTarget | undefined>
+    refresh?: () => Awaitable<void>
+    maxDepth?: number
+    taskTtl?: number
+    runTtl?: number
+    name?: string
+    onRunFinished?: (payload: AgentTaskFinishedPayload) => Awaitable<void>
+}
+
+declare module 'koishi' {
+    interface Events {
+        'chatluna/agent-task-finished': (
+            payload: AgentTaskFinishedPayload
+        ) => Promise<void>
+    }
+}
+
+export interface AgentTaskToolRuntime {
+    buildToolDescription(): string
+    createTool(): StructuredTool
+    dispose(): Promise<void>
+    getRuns(): AgentTaskRun[]
+    getTasks(): AgentTaskSession[]
+    runTask(
+        input: AgentTaskInput,
+        runConfig?: ChatLunaToolRunnable
+    ): Promise<string>
+}
+
+interface ActiveAgentTaskRun {
+    abort: AbortController
+    queue: MessageQueue
+}
diff --git a/packages/core/src/llm-core/agent/wakeup.ts b/packages/core/src/llm-core/agent/wakeup.ts
new file mode 100644
index 000000000..3c48eb146
--- /dev/null
+++ b/packages/core/src/llm-core/agent/wakeup.ts
@@ -0,0 +1,101 @@
+import { randomUUID } from 'crypto'
+
+import { HumanMessage } from '@langchain/core/messages'
+import { Context, h, Universal } from 'koishi'
+import { buildVirtualSession } from 'koishi-plugin-chatluna/utils/virtual_session'
+import type { Config } from '../../config'
+import {
+    type AgentTaskFinishedPayload,
+    formatAgentTaskWakeup
+} from './sub-agent'
+
+export function applyAgentTaskWakeup(ctx: Context, config: Config) {
+    ctx.on('chatluna/agent-task-finished', async (payload) => {
+        if (!config.agentTaskAutoWakeup) return
+        if (payload.run.background !== true) return
+        if (payload.run.state === 'aborted') return
+        if (payload.source !== 'chatluna') return
+        if (payload.parentConversationId.startsWith('subagent:')) return
+
+        const conversation = await ctx.chatluna.conversation.getConversation(
+            payload.parentConversationId
+        )
+        if (conversation == null) return
+
+        const content = formatAgentTaskWakeup(
+            payload.taskId,
+            payload.agentName,
+            payload.run
+        )
+        const msg = new HumanMessage({ content, name: 'task' })
+
+        if (
+            conversation.chatMode === 'plugin' &&
+            (await ctx.chatluna.conversationRuntime.appendPendingMessage(
+                payload.parentConversationId,
+                msg,
+                conversation.chatMode
+            ))
+        ) {
+            return
+        }
+
+        const session = restoreSession(ctx, payload)
+        if (session == null) {
+            ctx.logger.warn(
+                'agent task %s finished but bot %s:%s is offline; result kept until TTL.',
+                payload.taskId,
+                payload.snapshot?.routing?.platform,
+                payload.snapshot?.routing?.selfId
+            )
+            return
+        }
+
+        const resolved = await ctx.chatluna.conversation.resolveConversation(
+            session,
+            {
+                mode: 'active',
+                bindingKey:
+                    payload.snapshot?.bindingKey ?? conversation.bindingKey,
+                conversationId: conversation.id
+            }
+        )
+        if (resolved.conversation == null) return
+
+        await ctx.chatluna.chatChain.receiveCommand(session, 'chat', {
+            message: [h.text(content)],
+            messageId: randomUUID(),
+            conversation: resolved,
+            triggerWakeup: {
+                requestId: randomUUID(),
+                source: {
+                    kind: 'agent-task',
+                    detail: {
+                        taskId: payload.taskId,
+                        runId: payload.run.runId,
+                        agent: payload.agentName,
+                        state: payload.run.state
+                    }
+                }
+            },
+            inputMessage: { content, name: 'task' }
+        })
+    })
+}
+
+function restoreSession(ctx: Context, payload: AgentTaskFinishedPayload) {
+    const live = payload.snapshot?.session
+    if (live?.bot?.status === Universal.Status.ONLINE) return live
+
+    const routing = payload.snapshot?.routing
+    if (routing == null) return undefined
+
+    const bot = ctx.bots[`${routing.platform}:${routing.selfId}`]
+    if (bot == null || bot.status !== Universal.Status.ONLINE) return undefined
+
+    return buildVirtualSession(
+        bot,
+        { ...routing, username: 'task' },
+        { message: '', messageName: 'task' }
+    )
+}
diff --git a/packages/core/src/locales/en-US.schema.yml b/packages/core/src/locales/en-US.schema.yml
index 39009be36..249afa4d4 100644
--- a/packages/core/src/locales/en-US.schema.yml
+++ b/packages/core/src/locales/en-US.schema.yml
@@ -27,6 +27,7 @@ $inner:
       msgCooldown: Set global message cooldown (seconds) to limit adapter calls.
       messageQueue: Enable message queue. When enabled, if multiple messages are sent and the model has not responded to the initial message, the messages will be cached and merged into one message, and will be sent after waiting for the model response.
       messageQueueDelay: Set message queue delay time (seconds). Set to 0 to disable delay. When delay is enabled, the system will wait for the specified time before sending messages to the model. If there are unprocessed messages during this period, they will be cached and merged into multiple messages to send to the model.
+      agentTaskAutoWakeup: Automatically wake up the conversation when a background agent task finishes. Disable to return to manual status checks.
       showThoughtMessage: Display thinking message in plugin mode or reasoner model.
 
     - $desc: Message Rendering
diff --git a/packages/core/src/locales/zh-CN.schema.yml b/packages/core/src/locales/zh-CN.schema.yml
index adfdbde4e..3a89ddd06 100644
--- a/packages/core/src/locales/zh-CN.schema.yml
+++ b/packages/core/src/locales/zh-CN.schema.yml
@@ -27,6 +27,7 @@ $inner:
       msgCooldown: 设置全局消息冷却时间（单位：秒），用于防止适配器被过于频繁地调用。
       messageQueue: 设置是否启用消息队列。启用后当发送了多条消息，并且模型未响应初始消息时，会将将消息缓存合并成一条消息，并等待模型响应后再发送。
       messageQueueDelay: 设置消息队列的延迟时间（单位：秒）。为 0 则不启用延迟。开启延迟后，会等待指定时间后才发送消息给模型，如果在此期间内存在未处理的消息，则将消息缓存合并成多条消息发送给模型。
+      agentTaskAutoWakeup: 后台代理任务完成后自动唤醒所在对话。关闭后回到手动 status 查询模式。
       showThoughtMessage: 在使用插件模式或思考模型时，是否显示思考过程。
 
     - $desc: 消息渲染选项
diff --git a/packages/core/src/middlewares/conversation/request_conversation.ts b/packages/core/src/middlewares/conversation/request_conversation.ts
index 168731425..0a1dfa987 100644
--- a/packages/core/src/middlewares/conversation/request_conversation.ts
+++ b/packages/core/src/middlewares/conversation/request_conversation.ts
@@ -135,8 +135,14 @@ export function apply(ctx: Context, config: Config, chain: ChatChain) {
             let responseMessage: Message
 
             inputMessage.conversationId = conversation.id
-            inputMessage.name =
-                session.author?.name ?? session.author?.id ?? session.username
+            if (wakeup?.source.kind === 'agent-task') {
+                inputMessage.name = 'task'
+            } else {
+                inputMessage.name =
+                    session.author?.name ??
+                    session.author?.id ??
+                    session.username
+            }
 
             const requestId = context.options.messageId
 
diff --git a/packages/core/src/utils/virtual_session.ts b/packages/core/src/utils/virtual_session.ts
new file mode 100644
index 000000000..0e7e6494a
--- /dev/null
+++ b/packages/core/src/utils/virtual_session.ts
@@ -0,0 +1,47 @@
+import { h, type Session, type Universal } from 'koishi'
+import { transformMessageContentToElements } from 'koishi-plugin-chatluna/utils/koishi'
+import { getMessageContent } from 'koishi-plugin-chatluna/utils/string'
+
+export interface VirtualSessionRouting {
+    platform: string
+    selfId: string
+    userId: string
+    username?: string
+    guildId?: string
+    channelId?: string
+    isDirect: boolean
+}
+
+export function buildVirtualSession(
+    bot: Session['bot'],
+    routing: VirtualSessionRouting,
+    action: {
+        message: Parameters<typeof getMessageContent>[0]
+        messageName?: string
+    }
+) {
+    const event: Partial<Universal.Event> = {
+        type: 'message',
+        platform: routing.platform,
+        selfId: routing.selfId,
+        timestamp: Date.now(),
+        channel: {
+            id: routing.channelId ?? routing.guildId ?? routing.userId,
+            type: routing.isDirect ? 1 : 0
+        },
+        guild: routing.guildId == null ? undefined : { id: routing.guildId },
+        user: {
+            id: routing.userId,
+            name: routing.username ?? action.messageName ?? 'trigger'
+        },
+        message: {
+            content: getMessageContent(action.message),
+            elements:
+                typeof action.message === 'string'
+                    ? [h.text(action.message)]
+                    : transformMessageContentToElements(action.message)
+        }
+    }
+
+    return bot.session(event)
+}
diff --git a/packages/extension-agent/src/service/sub_agent.ts b/packages/extension-agent/src/service/sub_agent.ts
index 691db2faa..ad9538d92 100644
--- a/packages/extension-agent/src/service/sub_agent.ts
+++ b/packages/extension-agent/src/service/sub_agent.ts
@@ -203,6 +203,10 @@ export class ChatLunaAgentSubAgentService {
             },
             refresh: async () => {
                 await this.ctx.chatluna_agent?.refreshConsoleData()
+            },
+            onRunFinished: async (payload) => {
+                await this.ctx.parallel('chatluna/agent-task-finished', payload)
+                await this.ctx.chatluna_agent?.refreshConsoleData()
             }
         })
     }
diff --git a/packages/extension-agent/src/sub-agent/session.ts b/packages/extension-agent/src/sub-agent/session.ts
index d735f28b8..5ef6206d4 100644
--- a/packages/extension-agent/src/sub-agent/session.ts
+++ b/packages/extension-agent/src/sub-agent/session.ts
@@ -1,17 +1,6 @@
 /** @module sub-agent/session */
 
-import {
-    AIMessage,
-    BaseMessage,
-    HumanMessage,
-    ToolMessage
-} from '@langchain/core/messages'
-import {
-    type AgentStep,
-    observationToMessageContent
-} from 'koishi-plugin-chatluna/llm-core/agent'
-import { getMessageContent } from 'koishi-plugin-chatluna/utils/string'
-import type { SubAgentInfo, SubAgentRunInfo } from '../types'
+import type { BaseMessage } from '@langchain/core/messages'
 
 export interface SubAgentTaskSession {
     id: string
@@ -27,227 +16,3 @@ export interface SubAgentTaskSession {
     startedAt: number
     updatedAt: number
 }
-
-export function createTaskSession(input: {
-    id: string
-    info: SubAgentInfo
-    parentConversationId: string
-    depth: number
-    maxDepth: number
-    parentAgent: string
-}): SubAgentTaskSession {
-    const now = Date.now()
-    return {
-        id: input.id,
-        agentId: input.info.id,
-        agentName: input.info.name,
-        conversationId: `subagent:${input.id}`,
-        parentConversationId: input.parentConversationId,
-        depth: input.depth,
-        maxDepth: input.maxDepth,
-        parentAgent: input.parentAgent,
-        messages: [],
-        startedAt: now,
-        updatedAt: now
-    }
-}
-
-export function touchTaskSession(task: SubAgentTaskSession) {
-    task.updatedAt = Date.now()
-}
-
-export function appendTaskMessage(
-    task: SubAgentTaskSession,
-    message: BaseMessage
-) {
-    task.messages.push(message)
-    task.updatedAt = Date.now()
-}
-
-export function appendTaskMessages(
-    task: SubAgentTaskSession,
-    messages: BaseMessage[]
-) {
-    if (messages.length < 1) return
-    task.messages.push(...messages)
-    task.updatedAt = Date.now()
-}
-
-export function appendTaskToolBatch(
-    task: SubAgentTaskSession,
-    steps: AgentStep[]
-) {
-    if (steps.length < 1) return
-    appendTaskMessages(task, createAgentToolMessages(steps))
-}
-
-export function formatTaskResult(
-    task: SubAgentTaskSession,
-    run: SubAgentRunInfo,
-    output: string
-) {
-    return [
-        `task_id: ${task.id}`,
-        `agent: ${task.agentName}`,
-        `run_id: ${run.runId}`,
-        `state: ${run.state}`,
-        `resume_hint: use task with {"action":"run","id":"${task.id}","prompt":"next instruction"} ` +
-            'to continue this session. Add "background":true when the work may take a while.',
-        '',
-        output.trim() || '(empty)'
-    ].join('\n')
-}
-
-export function formatTaskStart(
-    task: SubAgentTaskSession,
-    run: SubAgentRunInfo
-) {
-    return [
-        `task_id: ${task.id}`,
-        `agent: ${task.agentName}`,
-        `run_id: ${run.runId}`,
-        'state: running',
-        'mode: background',
-        `status_hint: use task with {"action":"status","id":"${task.id}"} to inspect progress.`,
-        'list_hint: use task with {"action":"list"} to see recent sub-agent tasks in this conversation.',
-        `message_hint: use task with {"action":"message","id":"${task.id}","message":"..."} to send more guidance while it runs.`,
-        `resume_hint: after it stops, use task with {"action":"run","id":"${task.id}","prompt":"next instruction"} to continue this session.`
-    ].join('\n')
-}
-
-export function formatTaskList(
-    tasks: SubAgentTaskSession[],
-    getRun: (taskId: string) => SubAgentRunInfo | undefined
-) {
-    return [
-        'Sub-agent tasks:',
-        ...tasks.map((task) => {
-            const run = getRun(task.id)
-            return [
-                task.id,
-                `[${run?.state ?? (task.activeRunId ? 'running' : 'idle')}]`,
-                task.agentName,
-                `mode=${run?.background ? 'background' : 'foreground'}`,
-                `updated=${new Date(task.updatedAt).toISOString()}`,
-                `run=${run?.runId ?? task.activeRunId ?? '-'}`
-            ].join(' ')
-        }),
-        '',
-        'Use task with {"action":"status","id":"..."} to inspect one task.'
-    ].join('\n')
-}
-
-export function formatTaskDetail(
-    task: SubAgentTaskSession,
-    run?: SubAgentRunInfo
-) {
-    const lines = [
-        `task_id: ${task.id}`,
-        `agent: ${task.agentName}`,
-        `state: ${run?.state ?? (task.activeRunId ? 'running' : 'idle')}`,
-        `mode: ${run?.background ? 'background' : 'foreground'}`,
-        `run_id: ${run?.runId ?? task.activeRunId ?? '-'}`,
-        `depth: ${task.depth}`,
-        `parent_agent: ${task.parentAgent}`,
-        `started: ${new Date(task.startedAt).toISOString()}`,
-        `updated: ${new Date(task.updatedAt).toISOString()}`
-    ]
-
-    if (run?.lastTool) {
-        lines.push(`last_tool: ${run.lastTool}`)
-    }
-
-    if (run) {
-        lines.push(`tool_count: ${run.toolCount}`)
-        lines.push(`turn_count: ${run.turnCount}`)
-    }
-
-    if (run?.endedAt) {
-        lines.push(`ended: ${new Date(run.endedAt).toISOString()}`)
-    }
-
-    if (run?.error) {
-        lines.push(`error: ${run.error}`)
-    }
-
-    lines.push(
-        `status_hint: use task with {"action":"status","id":"${task.id}"} to inspect it again.`
-    )
-
-    if (run?.state === 'running' && run.background) {
-        lines.push(
-            `message_hint: use task with {"action":"message","id":"${task.id}","message":"..."} to send more guidance while it runs.`
-        )
-    }
-
-    if (run?.state !== 'running') {
-        lines.push(
-            `resume_hint: use task with {"action":"run","id":"${task.id}","prompt":"next instruction"} ` +
-                'to continue this session. Add "background":true when the work may take a while.'
-        )
-    }
-
-    lines.push('')
-
-    if (run?.output?.trim()) {
-        lines.push('Output:')
-        lines.push(run.output.trim())
-        return lines.join('\n')
-    }
-
-    lines.push('History:')
-    lines.push(formatTaskHistory(task.messages))
-    return lines.join('\n')
-}
-
-function createAgentToolMessages(steps: AgentStep[]): BaseMessage[] {
-    const reasoning = steps[0]?.action.reasoningContent
-    const message = steps[0]?.action.messageLog?.[0]
-
-    return [
-        new AIMessage({
-            content: '',
-            additional_kwargs: {
-                ...(message?.additional_kwargs ?? {}),
-                ...(reasoning != null ? { reasoning_content: reasoning } : {})
-            },
-            tool_calls: steps.map((step) => ({
-                id: step.action.toolCallId,
-                name: step.action.tool,
-                args:
-                    typeof step.action.toolInput !== 'string'
-                        ? step.action.toolInput
-                        : { input: step.action.toolInput }
-            }))
-        }),
-        ...steps.map(
-            (step) =>
-                new ToolMessage({
-                    content: observationToMessageContent(step.observation),
-                    tool_call_id: step.action.toolCallId,
-                    name: step.action.tool
-                })
-        )
-    ]
-}
-
-function formatTaskHistory(messages: BaseMessage[]) {
-    const lines = messages
-        .map((msg) => {
-            const text = getMessageContent(msg.content)
-                .replace(/\s+/g, ' ')
-                .trim()
-            if (!text) return undefined
-            return `${msg.getType()}: ${text.length > 280 ? `${text.slice(0, 277)}...` : text}`
-        })
-        .filter((item): item is string => item != null)
-
-    if (lines.length < 1) return '(no messages yet)'
-    return lines.slice(-6).join('\n')
-}
-
-export function isHumanMessages(
-    messages: BaseMessage[]
-): messages is HumanMessage[] {
-    return messages.every((msg) => msg.getType() === 'human')
-}
diff --git a/packages/extension-agent/src/trigger/session.ts b/packages/extension-agent/src/trigger/session.ts
index 5697a3c6b..827e07e5f 100644
--- a/packages/extension-agent/src/trigger/session.ts
+++ b/packages/extension-agent/src/trigger/session.ts
@@ -1,35 +1 @@
-import { h, type Session, type Universal } from 'koishi'
-import { transformMessageContentToElements } from 'koishi-plugin-chatluna/utils/koishi'
-import { getMessageContent } from 'koishi-plugin-chatluna/utils/string'
-import type { WakeupAction, WakeupRouting } from '../types'
-
-export function buildVirtualSession(
-    bot: Session['bot'],
-    routing: WakeupRouting,
-    action: Pick<WakeupAction, 'message' | 'messageName'>
-) {
-    const event: Partial<Universal.Event> = {
-        type: 'message',
-        platform: routing.platform,
-        selfId: routing.selfId,
-        timestamp: Date.now(),
-        channel: {
-            id: routing.channelId ?? routing.guildId ?? routing.userId,
-            type: routing.isDirect ? 1 : 0
-        },
-        guild: routing.guildId == null ? undefined : { id: routing.guildId },
-        user: {
-            id: routing.userId,
-            name: routing.username ?? action.messageName ?? 'trigger'
-        },
-        message: {
-            content: getMessageContent(action.message),
-            elements:
-                typeof action.message === 'string'
-                    ? [h.text(action.message)]
-                    : transformMessageContentToElements(action.message)
-        }
-    }
-
-    return bot.session(event)
-}
+export { buildVirtualSession } from 'koishi-plugin-chatluna/utils/virtual_session'

From 13f6dfb210213c025b68db37288edd949439db6f Mon Sep 17 00:00:00 2001
From: dingyi <dingyi222666@foxmail.com>
Date: Sat, 13 Jun 2026 03:08:55 +0800
Subject: [PATCH 3/5] feat(agent): add sub-agent task controls

---
 packages/core/src/llm-core/agent/agent.ts     |   2 +
 .../src/llm-core/agent/legacy-executor.ts     |   2 +
 packages/core/src/llm-core/agent/sub-agent.ts |   4 +-
 packages/core/src/llm-core/agent/types.ts     |   1 +
 .../core/src/middlewares/chat/stop_chat.ts    |   4 +
 packages/core/src/services/types.ts           |   4 +
 .../extension-agent/src/commands/agent.ts     |   2 +-
 packages/extension-agent/src/commands/task.ts | 211 ++++++++++++++++++
 .../src/computer/backends/local/sandbox.ts    |  19 +-
 packages/extension-agent/src/index.ts         |   2 +
 .../extension-agent/src/service/sub_agent.ts  |  90 ++++++++
 .../src/sub-agent/task_attach.ts              | 143 ++++++++++++
 12 files changed, 478 insertions(+), 6 deletions(-)
 create mode 100644 packages/extension-agent/src/commands/task.ts
 create mode 100644 packages/extension-agent/src/sub-agent/task_attach.ts

diff --git a/packages/core/src/llm-core/agent/agent.ts b/packages/core/src/llm-core/agent/agent.ts
index 81008e45e..64a05ad15 100644
--- a/packages/core/src/llm-core/agent/agent.ts
+++ b/packages/core/src/llm-core/agent/agent.ts
@@ -58,6 +58,7 @@ export interface AgentGenerateOptions {
     signal?: AbortSignal
     maxToken?: number
     messageQueue?: MessageQueue
+    pauseGate?: (signal?: AbortSignal) => Promise<void>
     toolMask?: ToolMask
     subagentContext?: SubagentContext
     source?: 'chatluna' | 'character'
@@ -161,6 +162,7 @@ export function createAgent(options: CreateAgentOptions): ChatLunaAgent {
             const bound = runner.value.withConfig({
                 configurable: {
                     messageQueue: input.messageQueue,
+                    pauseGate: input.pauseGate,
                     onAgentEvent: input.onStep,
                     agentContext: ctx
                 }
diff --git a/packages/core/src/llm-core/agent/legacy-executor.ts b/packages/core/src/llm-core/agent/legacy-executor.ts
index d42b47718..b57f52792 100644
--- a/packages/core/src/llm-core/agent/legacy-executor.ts
+++ b/packages/core/src/llm-core/agent/legacy-executor.ts
@@ -215,6 +215,8 @@ export async function* runAgent(
 
     while (iterations < maxIterations) {
         checkAborted(signal)
+        await runtime.pauseGate?.(signal)
+        checkAborted(signal)
 
         const pending = queue?.drain() ?? []
         if (pending.length > 0) {
diff --git a/packages/core/src/llm-core/agent/sub-agent.ts b/packages/core/src/llm-core/agent/sub-agent.ts
index 76a13a574..ad5b5b6f8 100644
--- a/packages/core/src/llm-core/agent/sub-agent.ts
+++ b/packages/core/src/llm-core/agent/sub-agent.ts
@@ -858,8 +858,8 @@ function formatTaskStart(task: AgentTaskSession, toolName: string) {
         `agent: ${task.agentName}`,
         'state: running (background)',
         'hint: result will be delivered automatically - do NOT poll status. ' +
-            'Continue other work or end your reply; use ' +
-            `${toolName} action=message id=${task.id} to send guidance.`
+            `Continue other work or end your reply; use ${toolName} ` +
+            `action=message id=${task.id} to send guidance.`
     ].join('\n')
 }
 
diff --git a/packages/core/src/llm-core/agent/types.ts b/packages/core/src/llm-core/agent/types.ts
index 28175cb6e..a0ddb2b78 100644
--- a/packages/core/src/llm-core/agent/types.ts
+++ b/packages/core/src/llm-core/agent/types.ts
@@ -291,6 +291,7 @@ export interface AgentCallbackEvent {
 
 export interface AgentRuntimeConfigurable {
     messageQueue?: MessageQueue
+    pauseGate?: (signal?: AbortSignal) => Promise<void>
     onAgentEvent?: (event: AgentEvent) => Promise<void> | void
     agentContext?: AgentRunContext
 }
diff --git a/packages/core/src/middlewares/chat/stop_chat.ts b/packages/core/src/middlewares/chat/stop_chat.ts
index 1dd2c335e..9141ea8bc 100644
--- a/packages/core/src/middlewares/chat/stop_chat.ts
+++ b/packages/core/src/middlewares/chat/stop_chat.ts
@@ -61,6 +61,10 @@ export function apply(ctx: Context, config: Config, chain: ChatChain) {
                 ctx.chatluna.conversationRuntime.stopConversationRequest(
                     conversation.id
                 )
+            await ctx.parallel('chatluna/chat-stopped', {
+                conversationId: conversation.id,
+                session
+            })
 
             if (!status) {
                 context.message = session.text('.no_active_chat')
diff --git a/packages/core/src/services/types.ts b/packages/core/src/services/types.ts
index 6ce1e61fe..faca6fa1e 100644
--- a/packages/core/src/services/types.ts
+++ b/packages/core/src/services/types.ts
@@ -186,6 +186,10 @@ declare module 'koishi' {
     }
 
     interface Events {
+        'chatluna/chat-stopped'(payload: {
+            conversationId: string
+            session: Session
+        }): Promise<void>
         'chatluna/before-check-sender'(session: Session): Promise<boolean>
         'chatluna/check-passive-trigger'(
             session: Session,
diff --git a/packages/extension-agent/src/commands/agent.ts b/packages/extension-agent/src/commands/agent.ts
index 9fd312a30..647306f4b 100644
--- a/packages/extension-agent/src/commands/agent.ts
+++ b/packages/extension-agent/src/commands/agent.ts
@@ -5,7 +5,7 @@ import { getErrorMessage } from '../utils/shell'
 
 export function apply(ctx: Context) {
     ctx.command('chatluna.agent', 'ChatLuna agent admin commands', {
-        authority: 3
+        authority: 1
     })
 
     ctx.command(
diff --git a/packages/extension-agent/src/commands/task.ts b/packages/extension-agent/src/commands/task.ts
new file mode 100644
index 000000000..1a5b60485
--- /dev/null
+++ b/packages/extension-agent/src/commands/task.ts
@@ -0,0 +1,211 @@
+/** @module commands/task */
+
+import { Context, Session } from 'koishi'
+import type {
+    AgentTaskRun,
+    AgentTaskSession
+} from 'koishi-plugin-chatluna/llm-core/agent'
+import { checkAdmin } from 'koishi-plugin-chatluna/utils/koishi'
+
+export function apply(ctx: Context) {
+    ctx.command('chatluna.agent.list', 'List sub-agent tasks', {
+        authority: 1
+    })
+        .option('all', '--all')
+        .action(async ({ session, options }) => {
+            const service = ctx.chatluna_agent
+            if (!service) return 'ChatLuna agent service is not ready.'
+
+            if (options.all && !(await checkAdmin(session))) {
+                return 'Admin permission is required for --all.'
+            }
+
+            const resolved = options.all
+                ? undefined
+                : await ctx.chatluna.conversation.resolveConversation(session, {
+                      permission: 'manage',
+                      mode: 'target'
+                  })
+            const id = resolved?.conversation?.id
+            if (!options.all && !id) return 'No active conversation.'
+
+            const runs = service.subAgent.getRuns()
+            const tasks = service.subAgent
+                .getTasks()
+                .filter(
+                    (task) => options.all || task.parentConversationId === id
+                )
+            if (tasks.length < 1) return 'No sub-agent tasks.'
+
+            return [
+                'Sub-agent tasks:',
+                ...tasks.map((task) => {
+                    const run = latest(runs, task.id)
+                    return [
+                        task.id.slice(0, 8),
+                        task.agentName,
+                        state(task, run),
+                        run?.background ? 'background' : 'foreground',
+                        `depth=${task.depth}`,
+                        `started=${new Date(task.startedAt).toLocaleString()}`
+                    ].join(' | ')
+                })
+            ].join('\n')
+        })
+
+    ctx.command('chatluna.agent.stop [id:string]', 'Stop sub-agent task', {
+        authority: 1
+    })
+        .option('all', '--all')
+        .action(async ({ session, options }, id) => {
+            const service = ctx.chatluna_agent
+            if (!service) return 'ChatLuna agent service is not ready.'
+
+            const resolved =
+                await ctx.chatluna.conversation.resolveConversation(session, {
+                    permission: 'manage',
+                    mode: 'target'
+                })
+            const conversationId = resolved.conversation?.id
+            if (!conversationId) return 'No active conversation.'
+
+            if (options.all) {
+                const count =
+                    service.subAgent.abortByParentConversation(conversationId)
+                return `Stopped ${count} background sub-agent task(s).`
+            }
+
+            const task = await findTask(ctx, session, id, conversationId)
+            if (typeof task === 'string') return task
+
+            const run = latest(service.subAgent.getRuns(), task.id)
+            if (!run?.background)
+                return 'Foreground tasks stop with chatluna.stop.'
+
+            if (!service.subAgent.stopTask(task.id)) {
+                return 'Task is not running or not stoppable.'
+            }
+
+            service.subAgent.detachAttachedTask(task.id)
+            return `Stopped sub-agent task ${task.id.slice(0, 8)}.`
+        })
+
+    ctx.command('chatluna.agent.pause <id:string>', 'Pause sub-agent task', {
+        authority: 1
+    }).action(async ({ session }, id) => {
+        const service = ctx.chatluna_agent
+        if (!service) return 'ChatLuna agent service is not ready.'
+
+        const resolved = await ctx.chatluna.conversation.resolveConversation(
+            session,
+            { permission: 'manage', mode: 'target' }
+        )
+        const conversationId = resolved.conversation?.id
+        if (!conversationId) return 'No active conversation.'
+
+        const task = await findTask(ctx, session, id, conversationId)
+        if (typeof task === 'string') return task
+
+        const run = latest(service.subAgent.getRuns(), task.id)
+        if (!run?.background) return 'Only background tasks can be paused.'
+
+        return service.subAgent.pauseTask(task.id)
+            ? `Pause requested for ${task.id.slice(0, 8)}.`
+            : 'Task is not running or already unavailable.'
+    })
+
+    ctx.command('chatluna.agent.resume <id:string>', 'Resume sub-agent task', {
+        authority: 1
+    }).action(async ({ session }, id) => {
+        const service = ctx.chatluna_agent
+        if (!service) return 'ChatLuna agent service is not ready.'
+
+        const resolved = await ctx.chatluna.conversation.resolveConversation(
+            session,
+            { permission: 'manage', mode: 'target' }
+        )
+        const conversationId = resolved.conversation?.id
+        if (!conversationId) return 'No active conversation.'
+
+        const task = await findTask(ctx, session, id, conversationId)
+        if (typeof task === 'string') return task
+
+        return service.subAgent.resumeTask(task.id)
+            ? `Resumed ${task.id.slice(0, 8)}.`
+            : 'Task is not paused or already unavailable.'
+    })
+
+    ctx.command('chatluna.agent.chat <id:string>', 'Attach to sub-agent task', {
+        authority: 1
+    }).action(async ({ session }, id) => {
+        const service = ctx.chatluna_agent
+        if (!service) return 'ChatLuna agent service is not ready.'
+
+        const resolved = await ctx.chatluna.conversation.resolveConversation(
+            session,
+            { permission: 'manage', mode: 'target' }
+        )
+        const conversationId = resolved.conversation?.id
+        if (!conversationId) return 'No active conversation.'
+
+        const task = await findTask(ctx, session, id, conversationId)
+        if (typeof task === 'string') return task
+
+        const run = latest(service.subAgent.getRuns(), task.id)
+        service.subAgent.attachTask(session, task.id, conversationId)
+        return [
+            `Attached to ${task.agentName} (${task.id.slice(0, 8)}).`,
+            `State: ${state(task, run)}. Send messages here; use chatluna.agent.task.exit to leave.`,
+            'Recent history:',
+            service.subAgent.getTaskHistory(task)
+        ].join('\n')
+    })
+
+    ctx.command('chatluna.agent.exit', 'Exit sub-agent attach', {
+        authority: 1
+    }).action(({ session }) => {
+        const service = ctx.chatluna_agent
+        if (!service) return 'ChatLuna agent service is not ready.'
+        return service.subAgent.detachTaskAttach(session)
+            ? 'Exited sub-agent attach mode.'
+            : 'No sub-agent attach is active.'
+    })
+}
+
+async function findTask(
+    ctx: Context,
+    session: Session,
+    id: string | undefined,
+    conversationId: string
+) {
+    if (!id?.trim()) return 'Task id is required.'
+
+    const service = ctx.chatluna_agent
+    const all = await checkAdmin(session)
+    const tasks = service.subAgent
+        .getTasks()
+        .filter((task) =>
+            all ? true : task.parentConversationId === conversationId
+        )
+    const matches = tasks.filter((task) => task.id.startsWith(id.trim()))
+    if (matches.length < 1) return `Task '${id}' was not found.`
+    if (matches.length > 1) {
+        return [
+            `Task prefix '${id}' is ambiguous:`,
+            ...matches.map((task) => `${task.id.slice(0, 8)} ${task.agentName}`)
+        ].join('\n')
+    }
+
+    return matches[0]
+}
+
+function latest(runs: AgentTaskRun[], taskId: string) {
+    return runs.filter((run) => run.taskId === taskId).at(-1)
+}
+
+function state(task: AgentTaskSession, run?: AgentTaskRun) {
+    if (run?.paused) return 'running (paused)'
+    return run?.state ?? (task.activeRunId ? 'running' : 'idle')
+}
+
+export const inject = ['chatluna_agent']
diff --git a/packages/extension-agent/src/computer/backends/local/sandbox.ts b/packages/extension-agent/src/computer/backends/local/sandbox.ts
index da2d18543..3b6e5d051 100644
--- a/packages/extension-agent/src/computer/backends/local/sandbox.ts
+++ b/packages/extension-agent/src/computer/backends/local/sandbox.ts
@@ -149,19 +149,32 @@ export function wrapCommandWithSandbox(
         }
     }
 
-    return [
+    const args = [
         quote(bwrap),
-        cfg.sandboxMode === 'read-only' ? '--ro-bind / /' : '--bind / /',
+        '--ro-bind / /',
+        cfg.sandboxMode === 'workspace-write'
+            ? `--bind ${quote(cfg.scopePath || workdir)} ${quote(cfg.scopePath || workdir)}`
+            : undefined,
+        cfg.sandboxMode === 'workspace-write' &&
+        path.resolve(workdir) !== path.resolve(cfg.scopePath || workdir)
+            ? `--bind ${quote(workdir)} ${quote(workdir)}`
+            : undefined,
         cfg.sandboxMode === 'read-only'
             ? `--ro-bind ${quote(tmp)} /tmp`
             : `--bind ${quote(tmp)} /tmp`,
+        ...cfg.readOnlyRoots.map(
+            (root) => `--ro-bind ${quote(root)} ${quote(root)}`
+        ),
+        ...cfg.denyRoots.map((root) => `--tmpfs ${quote(root)}`),
         '--dev /dev',
         '--proc /proc',
         '--die-with-parent',
         ...(cfg.networkPolicy === 'block' ? ['--unshare-net'] : []),
         'sh -lc',
         quote(command)
-    ].join(' ')
+    ].filter((arg): arg is string => arg != null)
+
+    return args.join(' ')
 }
 
 function isInsideRoot(target: string, root: string) {
diff --git a/packages/extension-agent/src/index.ts b/packages/extension-agent/src/index.ts
index bc09c82b7..edcc4fdd0 100644
--- a/packages/extension-agent/src/index.ts
+++ b/packages/extension-agent/src/index.ts
@@ -9,6 +9,7 @@ import { readConfig } from './config/read'
 import * as webui from './webui'
 import * as mcpCommands from './commands/mcp'
 import * as agentCommands from './commands/agent'
+import * as taskCommands from './commands/task'
 
 export * from './types'
 
@@ -29,6 +30,7 @@ export async function apply(ctx: Context, config: Config) {
     ctx.plugin(webui)
     ctx.plugin(mcpCommands)
     ctx.plugin(agentCommands)
+    ctx.plugin(taskCommands)
 }
 
 export const Config: Schema<Config> = Schema.intersect([ChatLunaPlugin.Config])
diff --git a/packages/extension-agent/src/service/sub_agent.ts b/packages/extension-agent/src/service/sub_agent.ts
index ad9538d92..614c792b6 100644
--- a/packages/extension-agent/src/service/sub_agent.ts
+++ b/packages/extension-agent/src/service/sub_agent.ts
@@ -2,6 +2,8 @@
 
 import { Context } from 'koishi'
 import {
+    type AgentTaskResolveContext,
+    type AgentTaskSession,
     type AgentTaskToolRuntime,
     createTaskTool,
     renderAvailableAgents
@@ -11,11 +13,13 @@ import {
     countMessageTokens,
     PromptContextRuntime
 } from 'koishi-plugin-chatluna/llm-core/prompt'
+import { getMessageContent } from 'koishi-plugin-chatluna/utils/string'
 import { getSubAgentsRootPath } from '../config/path'
 import { buildSubAgentCatalog } from '../sub-agent/catalog'
 import { createManualAgent } from '../sub-agent/manual'
 import { createSubAgent } from '../sub-agent/run'
 import { ensureSubAgentsRoot, REMOTE_SUBAGENTS_ROOT } from '../sub-agent/scan'
+import { ChatLunaAgentTaskAttachService } from '../sub-agent/task_attach'
 import {
     AgentConfig,
     ManualSubAgentInput,
@@ -31,6 +35,7 @@ export class ChatLunaAgentSubAgentService {
     private _manual = new Map<string, ManualSubAgentInput>()
     private _toolDispose?: () => void
     private _promptDispose?: () => void
+    private _attach: ChatLunaAgentTaskAttachService
     private _task: AgentTaskToolRuntime
 
     constructor(
@@ -39,6 +44,20 @@ export class ChatLunaAgentSubAgentService {
         private permission: ChatLunaAgentPermissionService
     ) {
         this._task = this._createTaskRuntime()
+        this._attach = new ChatLunaAgentTaskAttachService(this.ctx)
+        this.ctx.on('chatluna/chat-stopped', async ({ conversationId }) => {
+            if (this._task.abortByParentConversation(conversationId) > 0) {
+                await this.ctx.chatluna_agent?.refreshConsoleData()
+            }
+        })
+        this.ctx.on(
+            'chatluna/before-conversation-clear-history',
+            async ({ conversation }) => {
+                if (this._task.abortByParentConversation(conversation.id) > 0) {
+                    await this.ctx.chatluna_agent?.refreshConsoleData()
+                }
+            }
+        )
     }
 
     async start() {
@@ -81,6 +100,77 @@ export class ChatLunaAgentSubAgentService {
         return this._task.getRuns() as SubAgentRunInfo[]
     }
 
+    getTasks() {
+        return this._task.getTasks()
+    }
+
+    getTask(id: string) {
+        return this._task.getTask(id)
+    }
+
+    stopTask(id: string) {
+        const result = this._task.stopTask(id)
+        if (result) this.ctx.chatluna_agent?.refreshConsoleData()
+        return result
+    }
+
+    pauseTask(id: string) {
+        const result = this._task.pauseTask(id)
+        if (result) this.ctx.chatluna_agent?.refreshConsoleData()
+        return result
+    }
+
+    resumeTask(id: string) {
+        const result = this._task.resumeTask(id)
+        if (result) this.ctx.chatluna_agent?.refreshConsoleData()
+        return result
+    }
+
+    abortByParentConversation(id: string) {
+        const result = this._task.abortByParentConversation(id)
+        if (result > 0) this.ctx.chatluna_agent?.refreshConsoleData()
+        return result
+    }
+
+    async chatTask(id: string, prompt: string, ctx: AgentTaskResolveContext) {
+        return await this._task.chatTask(id, prompt, ctx)
+    }
+
+    attachTask(
+        session: Parameters<ChatLunaAgentTaskAttachService['attach']>[0],
+        id: string,
+        conversationId: string
+    ) {
+        this._attach.attach(session, id, conversationId)
+    }
+
+    detachTaskAttach(
+        session: Parameters<ChatLunaAgentTaskAttachService['detach']>[0]
+    ) {
+        return this._attach.detach(session)
+    }
+
+    detachAttachedTask(id: string) {
+        this._attach.detachTask(id)
+    }
+
+    getTaskHistory(task: AgentTaskSession) {
+        const lines = task.messages
+            .map((msg) => {
+                const text = getMessageContent(msg.content)
+                    .replace(/\s+/g, ' ')
+                    .trim()
+                if (!text) return undefined
+
+                return `${msg.getType()}: ${text.length > 140 ? `${text.slice(0, 137)}...` : text}`
+            })
+            .filter((item): item is string => item != null)
+
+        return lines.length < 1
+            ? '(no messages yet)'
+            : lines.slice(-3).join('\n')
+    }
+
     listRunnableAgents(
         session?: Parameters<
             ChatLunaAgentPermissionService['canUseSubAgent']
diff --git a/packages/extension-agent/src/sub-agent/task_attach.ts b/packages/extension-agent/src/sub-agent/task_attach.ts
new file mode 100644
index 000000000..f3b5108bd
--- /dev/null
+++ b/packages/extension-agent/src/sub-agent/task_attach.ts
@@ -0,0 +1,143 @@
+/** @module sub-agent/task_attach */
+
+import { Context, Session } from 'koishi'
+import type { ConversationRecord } from 'koishi-plugin-chatluna/services/chat'
+import type { ChatLunaToolRunnable } from 'koishi-plugin-chatluna/llm-core/platform/types'
+
+interface TaskAttachState {
+    taskId: string
+    parentConversationId: string
+    lastActiveAt: number
+}
+
+export class ChatLunaAgentTaskAttachService {
+    private _items = new Map<string, TaskAttachState>()
+
+    constructor(public ctx: Context) {
+        ctx.middleware(async (session, next) => {
+            const key = this.key(session)
+            const item = this._items.get(key)
+            if (!item) return next()
+
+            if (Date.now() - item.lastActiveAt > 10 * 60 * 1000) {
+                this._items.delete(key)
+                await session.send('Sub-agent attach expired.')
+                return next()
+            }
+
+            if (session.argv?.command) return next()
+
+            const task = this.ctx.chatluna_agent?.subAgent.getTask(item.taskId)
+            if (!task) {
+                this._items.delete(key)
+                await session.send('Sub-agent task was not found or expired.')
+                return
+            }
+
+            item.lastActiveAt = Date.now()
+            const conversation =
+                await this.ctx.chatluna.conversation.getConversation(
+                    item.parentConversationId
+                )
+            if (!conversation) {
+                this._items.delete(key)
+                await session.send(
+                    'Parent conversation is no longer available.'
+                )
+                return
+            }
+
+            const result = await this.ctx.chatluna_agent.subAgent.chatTask(
+                item.taskId,
+                session.content,
+                {
+                    session,
+                    conversationId: item.parentConversationId,
+                    source: 'chatluna',
+                    runConfig: await this.runConfig(session, conversation)
+                }
+            )
+
+            if (result.state === 'queued') {
+                await session.send(
+                    `Delivered to running sub-agent ${task.agentName} (${task.id.slice(0, 8)}).`
+                )
+                return
+            }
+
+            await session.send(result.output?.trim() || '(empty)')
+        }, true)
+
+        ctx.on('chatluna/chat-stopped', async ({ conversationId }) => {
+            this.detachConversation(conversationId)
+        })
+        ctx.on(
+            'chatluna/before-conversation-clear-history',
+            async ({ conversation }) => {
+                this.detachConversation(conversation.id)
+            }
+        )
+        ctx.setInterval(() => {
+            const now = Date.now()
+            for (const [key, item] of this._items.entries()) {
+                if (now - item.lastActiveAt > 10 * 60 * 1000) {
+                    this._items.delete(key)
+                }
+            }
+        }, 60 * 1000)
+    }
+
+    attach(session: Session, taskId: string, parentConversationId: string) {
+        this._items.set(this.key(session), {
+            taskId,
+            parentConversationId,
+            lastActiveAt: Date.now()
+        })
+    }
+
+    detach(session: Session) {
+        return this._items.delete(this.key(session))
+    }
+
+    detachTask(taskId: string) {
+        for (const [key, item] of this._items.entries()) {
+            if (item.taskId === taskId) this._items.delete(key)
+        }
+    }
+
+    detachConversation(conversationId: string) {
+        for (const [key, item] of this._items.entries()) {
+            if (item.parentConversationId === conversationId) {
+                this._items.delete(key)
+            }
+        }
+    }
+
+    private key(session: Session) {
+        return [
+            session.platform,
+            session.selfId,
+            session.channelId ?? session.userId,
+            session.userId
+        ].join(':')
+    }
+
+    private async runConfig(
+        session: Session,
+        conversation: ConversationRecord
+    ) {
+        const model = await this.ctx.chatluna.createChatModel(
+            conversation.model
+        )
+        return {
+            configurable: {
+                model: model.value,
+                session,
+                conversationId: conversation.id,
+                preset: conversation.preset,
+                userId: session.userId,
+                source: 'chatluna'
+            }
+        } as ChatLunaToolRunnable
+    }
+}

From be7f07e7398c7ca0a06c7bf3ee1ca15053e8576b Mon Sep 17 00:00:00 2001
From: dingyi <dingyi222666@foxmail.com>
Date: Sun, 14 Jun 2026 02:08:22 +0800
Subject: [PATCH 4/5] fix(agent): address task control review feedback

---
 packages/core/src/llm-core/agent/sub-agent.ts | 139 +++++++++++++++++-
 .../core/src/middlewares/chat/stop_chat.ts    |  10 +-
 packages/extension-agent/src/commands/task.ts |   2 +-
 .../src/sub-agent/task_attach.ts              |  41 +++---
 4 files changed, 168 insertions(+), 24 deletions(-)

diff --git a/packages/core/src/llm-core/agent/sub-agent.ts b/packages/core/src/llm-core/agent/sub-agent.ts
index ad5b5b6f8..f153215e6 100644
--- a/packages/core/src/llm-core/agent/sub-agent.ts
+++ b/packages/core/src/llm-core/agent/sub-agent.ts
@@ -54,6 +54,107 @@ export function createTaskTool(
         getTasks() {
             return [...tasks.values()].sort((a, b) => b.updatedAt - a.updatedAt)
         },
+        getTask(id) {
+            return tasks.get(id)
+        },
+        stopTask(id) {
+            const task = tasks.get(id)
+            const runId = task?.activeRunId
+            const item = runId ? active.get(runId) : undefined
+            if (!runId || !item) return false
+
+            const run = runs.get(runId)
+            if (run) run.paused = false
+            item.paused = false
+            item.resume?.()
+            item.abort.abort()
+            options.refresh?.()
+            return true
+        },
+        pauseTask(id) {
+            const runId = tasks.get(id)?.activeRunId
+            const item = runId ? active.get(runId) : undefined
+            if (!runId || !item || item.paused) return false
+
+            item.paused = true
+            const run = runs.get(runId)
+            if (run) run.paused = true
+            options.refresh?.()
+            return true
+        },
+        resumeTask(id) {
+            const runId = tasks.get(id)?.activeRunId
+            const item = runId ? active.get(runId) : undefined
+            if (!runId || !item?.paused) return false
+
+            item.paused = false
+            const run = runs.get(runId)
+            if (run) run.paused = false
+            item.resume?.()
+            options.refresh?.()
+            return true
+        },
+        abortByParentConversation(id) {
+            let count = 0
+            for (const task of tasks.values()) {
+                if (task.parentConversationId !== id || !task.activeRunId) {
+                    continue
+                }
+
+                const item = active.get(task.activeRunId)
+                if (!item) continue
+
+                const run = runs.get(task.activeRunId)
+                if (run) run.paused = false
+                item.paused = false
+                item.resume?.()
+                item.abort.abort()
+                count += 1
+            }
+
+            if (count > 0) options.refresh?.()
+            return count
+        },
+        async chatTask(id, prompt, ctx) {
+            const task = tasks.get(id)
+            if (!task) {
+                return {
+                    state: 'failed',
+                    output: `Task '${id}' was not found or expired.`
+                }
+            }
+
+            const runId = task.activeRunId
+            const item = runId ? active.get(runId) : undefined
+            if (runId && item) {
+                item.queue.push(new HumanMessage(prompt))
+                touchTaskSession(task)
+                scheduleTaskCleanup(task.id)
+                await options.refresh?.()
+                return { state: 'queued' }
+            }
+
+            if (runId) {
+                return {
+                    state: 'failed',
+                    output: `Task '${task.id}' is not accepting live messages because it was not started in background.`
+                }
+            }
+
+            const output = await runtime.runTask(
+                {
+                    action: 'run',
+                    id,
+                    prompt
+                },
+                ctx.runConfig
+            )
+            const run = getLatestTaskRun(runs, id)
+            return {
+                state: run?.state ?? 'completed',
+                output
+            }
+        },
         async runTask(input, runConfig) {
             const action = input.action ?? 'run'
             const parent =
@@ -489,6 +590,8 @@ async function runAgentTask(options: {
 
     const abort = options.input.background ? new AbortController() : undefined
     const queue = options.input.background ? new MessageQueue() : undefined
+    const activeRun: ActiveAgentTaskRun | undefined =
+        abort && queue ? { abort, queue } : undefined
     const signal = abort?.signal ?? options.signal
     const promptMessage = new HumanMessage(options.prompt)
     const snapshot: AgentTaskSessionSnapshot | undefined = options.input
@@ -512,8 +615,8 @@ async function runAgentTask(options: {
     if (snapshot) {
         options.snapshots.set(runId, snapshot)
     }
-    if (abort && queue) {
-        options.active.set(runId, { abort, queue })
+    if (activeRun) {
+        options.active.set(runId, activeRun)
     }
     options.scheduleTaskCleanup(options.task.id)
     run.trace.push({
@@ -549,6 +652,25 @@ async function runAgentTask(options: {
                 history: [...options.task.messages],
                 signal,
                 messageQueue: queue,
+                pauseGate: activeRun
+                    ? async (signal) => {
+                          while (activeRun.paused) {
+                              if (signal?.aborted) return
+
+                              await new Promise<void>((resolve) => {
+                                  const done = () => {
+                                      signal?.removeEventListener('abort', done)
+                                      activeRun.resume = undefined
+                                      resolve()
+                                  }
+                                  activeRun.resume = done
+                                  signal?.addEventListener('abort', done, {
+                                      once: true
+                                  })
+                              })
+                          }
+                      }
+                    : undefined,
                 toolMask,
                 subagentContext: subCtx,
                 source: options.source,
@@ -1072,6 +1194,7 @@ export interface AgentTaskRun {
     depth: number
     state: 'running' | 'completed' | 'failed' | 'aborted'
     background?: boolean
+    paused?: boolean
     startedAt: number
     endedAt?: number
     lastTool?: string
@@ -1155,6 +1278,16 @@ export interface AgentTaskToolRuntime {
     dispose(): Promise<void>
     getRuns(): AgentTaskRun[]
     getTasks(): AgentTaskSession[]
+    getTask(id: string): AgentTaskSession | undefined
+    stopTask(id: string): boolean
+    pauseTask(id: string): boolean
+    resumeTask(id: string): boolean
+    abortByParentConversation(id: string): number
+    chatTask(
+        id: string,
+        prompt: string,
+        ctx: AgentTaskResolveContext
+    ): Promise<{ state: 'queued' | AgentTaskRun['state']; output?: string }>
     runTask(
         input: AgentTaskInput,
         runConfig?: ChatLunaToolRunnable
@@ -1164,4 +1297,6 @@ export interface AgentTaskToolRuntime {
 interface ActiveAgentTaskRun {
     abort: AbortController
     queue: MessageQueue
+    paused?: boolean
+    resume?: () => void
 }
diff --git a/packages/core/src/middlewares/chat/stop_chat.ts b/packages/core/src/middlewares/chat/stop_chat.ts
index 9141ea8bc..fab1428db 100644
--- a/packages/core/src/middlewares/chat/stop_chat.ts
+++ b/packages/core/src/middlewares/chat/stop_chat.ts
@@ -61,15 +61,17 @@ export function apply(ctx: Context, config: Config, chain: ChatChain) {
                 ctx.chatluna.conversationRuntime.stopConversationRequest(
                     conversation.id
                 )
-            await ctx.parallel('chatluna/chat-stopped', {
-                conversationId: conversation.id,
-                session
-            })
 
             if (!status) {
                 context.message = session.text('.no_active_chat')
+                return ChainMiddlewareRunStatus.STOP
             }
 
+            await ctx.parallel('chatluna/chat-stopped', {
+                conversationId: conversation.id,
+                session
+            })
+
             return ChainMiddlewareRunStatus.STOP
         })
         .after('lifecycle-handle_command')
diff --git a/packages/extension-agent/src/commands/task.ts b/packages/extension-agent/src/commands/task.ts
index 1a5b60485..1f4cd3e73 100644
--- a/packages/extension-agent/src/commands/task.ts
+++ b/packages/extension-agent/src/commands/task.ts
@@ -155,7 +155,7 @@ export function apply(ctx: Context) {
         service.subAgent.attachTask(session, task.id, conversationId)
         return [
             `Attached to ${task.agentName} (${task.id.slice(0, 8)}).`,
-            `State: ${state(task, run)}. Send messages here; use chatluna.agent.task.exit to leave.`,
+            `State: ${state(task, run)}. Send messages here; use chatluna.agent.exit to leave.`,
             'Recent history:',
             service.subAgent.getTaskHistory(task)
         ].join('\n')
diff --git a/packages/extension-agent/src/sub-agent/task_attach.ts b/packages/extension-agent/src/sub-agent/task_attach.ts
index f3b5108bd..96d288b8a 100644
--- a/packages/extension-agent/src/sub-agent/task_attach.ts
+++ b/packages/extension-agent/src/sub-agent/task_attach.ts
@@ -47,26 +47,33 @@ export class ChatLunaAgentTaskAttachService {
                 return
             }
 
-            const result = await this.ctx.chatluna_agent.subAgent.chatTask(
-                item.taskId,
-                session.content,
-                {
-                    session,
-                    conversationId: item.parentConversationId,
-                    source: 'chatluna',
-                    runConfig: await this.runConfig(session, conversation)
+            try {
+                const result = await this.ctx.chatluna_agent.subAgent.chatTask(
+                    item.taskId,
+                    session.content,
+                    {
+                        session,
+                        conversationId: item.parentConversationId,
+                        source: 'chatluna',
+                        runConfig: await this.runConfig(session, conversation)
+                    }
+                )
+
+                if (result.state === 'queued') {
+                    await session.send(
+                        `Delivered to running sub-agent ${task.agentName} (${task.id.slice(0, 8)}).`
+                    )
+                    return
                 }
-            )
 
-            if (result.state === 'queued') {
-                await session.send(
-                    `Delivered to running sub-agent ${task.agentName} (${task.id.slice(0, 8)}).`
-                )
-                return
+                await session.send(result.output?.trim() || '(empty)')
+            } catch (err) {
+                this._items.delete(key)
+                this.ctx.logger.error(err)
+                await session.send('Sub-agent task failed, please retry.')
+                return next()
             }
-
-            await session.send(result.output?.trim() || '(empty)')
-        }, true)
+        })
 
         ctx.on('chatluna/chat-stopped', async ({ conversationId }) => {
             this.detachConversation(conversationId)

From b00753fb236c3bcef744d4768027601fc446de6a Mon Sep 17 00:00:00 2001
From: dingyi <dingyi222666@foxmail.com>
Date: Mon, 15 Jun 2026 00:25:36 +0800
Subject: [PATCH 5/5] fix(agent): await task control refreshes

---
 packages/core/src/llm-core/agent/sub-agent.ts | 90 ++++++++++++-------
 packages/extension-agent/src/commands/task.ts | 10 ++-
 .../extension-agent/src/service/sub_agent.ts  | 26 +++---
 3 files changed, 81 insertions(+), 45 deletions(-)

diff --git a/packages/core/src/llm-core/agent/sub-agent.ts b/packages/core/src/llm-core/agent/sub-agent.ts
index f153215e6..64cc3fcf5 100644
--- a/packages/core/src/llm-core/agent/sub-agent.ts
+++ b/packages/core/src/llm-core/agent/sub-agent.ts
@@ -8,6 +8,7 @@ import {
 import { StructuredTool } from '@langchain/core/tools'
 import { randomUUID } from 'crypto'
 import type { Awaitable, Session } from 'koishi'
+import { logger } from 'koishi-plugin-chatluna'
 import { z } from 'zod'
 import type { ChatLunaToolRunnable } from '../platform/types'
 import { getMessageContent } from 'koishi-plugin-chatluna/utils/string'
@@ -57,7 +58,7 @@ export function createTaskTool(
         getTask(id) {
             return tasks.get(id)
         },
-        stopTask(id) {
+        async stopTask(id) {
             const task = tasks.get(id)
             const runId = task?.activeRunId
             const item = runId ? active.get(runId) : undefined
@@ -68,10 +69,14 @@ export function createTaskTool(
             item.paused = false
             item.resume?.()
             item.abort.abort()
-            options.refresh?.()
+            try {
+                await options.refresh?.()
+            } catch (err) {
+                logger.error(err)
+            }
             return true
         },
-        pauseTask(id) {
+        async pauseTask(id) {
             const runId = tasks.get(id)?.activeRunId
             const item = runId ? active.get(runId) : undefined
             if (!runId || !item || item.paused) return false
@@ -79,10 +84,14 @@ export function createTaskTool(
             item.paused = true
             const run = runs.get(runId)
             if (run) run.paused = true
-            options.refresh?.()
+            try {
+                await options.refresh?.()
+            } catch (err) {
+                logger.error(err)
+            }
             return true
         },
-        resumeTask(id) {
+        async resumeTask(id) {
             const runId = tasks.get(id)?.activeRunId
             const item = runId ? active.get(runId) : undefined
             if (!runId || !item?.paused) return false
@@ -91,10 +100,14 @@ export function createTaskTool(
             const run = runs.get(runId)
             if (run) run.paused = false
             item.resume?.()
-            options.refresh?.()
+            try {
+                await options.refresh?.()
+            } catch (err) {
+                logger.error(err)
+            }
             return true
         },
-        abortByParentConversation(id) {
+        async abortByParentConversation(id) {
             let count = 0
             for (const task of tasks.values()) {
                 if (task.parentConversationId !== id || !task.activeRunId) {
@@ -112,7 +125,13 @@ export function createTaskTool(
                 count += 1
             }
 
-            if (count > 0) options.refresh?.()
+            if (count > 0) {
+                try {
+                    await options.refresh?.()
+                } catch (err) {
+                    logger.error(err)
+                }
+            }
             return count
         },
         async chatTask(id, prompt, ctx) {
@@ -696,8 +715,12 @@ async function runAgentTask(options: {
             touchTaskSession(options.task)
             options.scheduleRunCleanup(runId)
             options.scheduleTaskCleanup(options.task.id)
-            await options.runtime.refresh?.()
             await notifyFinished(options, run, snapshot)
+            try {
+                await options.runtime.refresh?.()
+            } catch (err) {
+                logger.error(err)
+            }
             return formatTaskResult(
                 options.task,
                 run,
@@ -719,8 +742,12 @@ async function runAgentTask(options: {
             touchTaskSession(options.task)
             options.scheduleRunCleanup(runId)
             options.scheduleTaskCleanup(options.task.id)
-            await options.runtime.refresh?.()
             await notifyFinished(options, run, snapshot)
+            try {
+                await options.runtime.refresh?.()
+            } catch (err) {
+                logger.error(err)
+            }
             throw err
         } finally {
             options.active.delete(runId)
@@ -752,25 +779,26 @@ async function notifyFinished(
         return
     }
 
-    if (options.task.parentConversationId.startsWith('subagent:')) {
-        const task = [...options.tasks.values()].find(
-            (item) => item.conversationId === options.task.parentConversationId
-        )
-        const active = task?.activeRunId
+    let parentId = options.task.parentConversationId
+    const message = new HumanMessage(
+        formatAgentTaskWakeup(options.task.id, options.task.agentName, run)
+    )
+
+    while (parentId.startsWith('subagent:')) {
+        const task = options.tasks.get(parentId.slice('subagent:'.length))
+        const item = task?.activeRunId
             ? options.active.get(task.activeRunId)
             : undefined
-        if (active) {
-            active.queue.push(
-                new HumanMessage(
-                    formatAgentTaskWakeup(
-                        options.task.id,
-                        options.task.agentName,
-                        run
-                    )
-                )
-            )
+        if (item) {
+            item.queue.push(message)
+            return
         }
-        return
+
+        if (!task) {
+            return
+        }
+
+        parentId = task.parentConversationId
     }
 
     try {
@@ -779,7 +807,7 @@ async function notifyFinished(
             taskId: options.task.id,
             agentId: options.target.agent.id,
             agentName: options.target.agent.name,
-            parentConversationId: options.task.parentConversationId,
+            parentConversationId: parentId,
             source: options.source,
             snapshot
         })
@@ -1279,10 +1307,10 @@ export interface AgentTaskToolRuntime {
     getRuns(): AgentTaskRun[]
     getTasks(): AgentTaskSession[]
     getTask(id: string): AgentTaskSession | undefined
-    stopTask(id: string): boolean
-    pauseTask(id: string): boolean
-    resumeTask(id: string): boolean
-    abortByParentConversation(id: string): number
+    stopTask(id: string): Promise<boolean>
+    pauseTask(id: string): Promise<boolean>
+    resumeTask(id: string): Promise<boolean>
+    abortByParentConversation(id: string): Promise<number>
     chatTask(
         id: string,
         prompt: string,
diff --git a/packages/extension-agent/src/commands/task.ts b/packages/extension-agent/src/commands/task.ts
index 1f4cd3e73..5a1af7241 100644
--- a/packages/extension-agent/src/commands/task.ts
+++ b/packages/extension-agent/src/commands/task.ts
@@ -71,7 +71,9 @@ export function apply(ctx: Context) {
 
             if (options.all) {
                 const count =
-                    service.subAgent.abortByParentConversation(conversationId)
+                    await service.subAgent.abortByParentConversation(
+                        conversationId
+                    )
                 return `Stopped ${count} background sub-agent task(s).`
             }
 
@@ -82,7 +84,7 @@ export function apply(ctx: Context) {
             if (!run?.background)
                 return 'Foreground tasks stop with chatluna.stop.'
 
-            if (!service.subAgent.stopTask(task.id)) {
+            if (!(await service.subAgent.stopTask(task.id))) {
                 return 'Task is not running or not stoppable.'
             }
 
@@ -109,7 +111,7 @@ export function apply(ctx: Context) {
         const run = latest(service.subAgent.getRuns(), task.id)
         if (!run?.background) return 'Only background tasks can be paused.'
 
-        return service.subAgent.pauseTask(task.id)
+        return (await service.subAgent.pauseTask(task.id))
             ? `Pause requested for ${task.id.slice(0, 8)}.`
             : 'Task is not running or already unavailable.'
     })
@@ -130,7 +132,7 @@ export function apply(ctx: Context) {
         const task = await findTask(ctx, session, id, conversationId)
         if (typeof task === 'string') return task
 
-        return service.subAgent.resumeTask(task.id)
+        return (await service.subAgent.resumeTask(task.id))
             ? `Resumed ${task.id.slice(0, 8)}.`
             : 'Task is not paused or already unavailable.'
     })
diff --git a/packages/extension-agent/src/service/sub_agent.ts b/packages/extension-agent/src/service/sub_agent.ts
index 614c792b6..ce7a84238 100644
--- a/packages/extension-agent/src/service/sub_agent.ts
+++ b/packages/extension-agent/src/service/sub_agent.ts
@@ -46,14 +46,20 @@ export class ChatLunaAgentSubAgentService {
         this._task = this._createTaskRuntime()
         this._attach = new ChatLunaAgentTaskAttachService(this.ctx)
         this.ctx.on('chatluna/chat-stopped', async ({ conversationId }) => {
-            if (this._task.abortByParentConversation(conversationId) > 0) {
+            if (
+                (await this._task.abortByParentConversation(conversationId)) > 0
+            ) {
                 await this.ctx.chatluna_agent?.refreshConsoleData()
             }
         })
         this.ctx.on(
             'chatluna/before-conversation-clear-history',
             async ({ conversation }) => {
-                if (this._task.abortByParentConversation(conversation.id) > 0) {
+                if (
+                    (await this._task.abortByParentConversation(
+                        conversation.id
+                    )) > 0
+                ) {
                     await this.ctx.chatluna_agent?.refreshConsoleData()
                 }
             }
@@ -108,26 +114,26 @@ export class ChatLunaAgentSubAgentService {
         return this._task.getTask(id)
     }
 
-    stopTask(id: string) {
-        const result = this._task.stopTask(id)
+    async stopTask(id: string) {
+        const result = await this._task.stopTask(id)
         if (result) this.ctx.chatluna_agent?.refreshConsoleData()
         return result
     }
 
-    pauseTask(id: string) {
-        const result = this._task.pauseTask(id)
+    async pauseTask(id: string) {
+        const result = await this._task.pauseTask(id)
         if (result) this.ctx.chatluna_agent?.refreshConsoleData()
         return result
     }
 
-    resumeTask(id: string) {
-        const result = this._task.resumeTask(id)
+    async resumeTask(id: string) {
+        const result = await this._task.resumeTask(id)
         if (result) this.ctx.chatluna_agent?.refreshConsoleData()
         return result
     }
 
-    abortByParentConversation(id: string) {
-        const result = this._task.abortByParentConversation(id)
+    async abortByParentConversation(id: string) {
+        const result = await this._task.abortByParentConversation(id)
         if (result > 0) this.ctx.chatluna_agent?.refreshConsoleData()
         return result
     }