修改

src/agent_tool_specs/execution.py

@@ -44,7 +44,7 @@ def build_execution_tools(handlers: Mapping[str, ToolHandler]) -> list[AgentTool
                     'timeout_seconds': {
                         'type': 'number',
                         'minimum': 1,
-                        'description': '可选超时时间，默认使用当前会话命令超时。',
+                        'description': '可选超时时间，默认 30 秒。读大 CSV/JSONL、pandas 分析、批量校验、训练评测脚本等可能 >30s 的任务必须显式传值（常规 120-300、训练/长跑 600+）。',
                     },
                     'max_output_chars': {
                         'type': 'integer',
@@ -98,16 +98,84 @@ def build_execution_tools(handlers: Mapping[str, ToolHandler]) -> list[AgentTool
                 '不要用 bash 执行 python、python3、pip 或 .venv/bin/python；结构化文件分析、'
                 'JSON/JSONL 处理、批量校验、数据抽样和快速计算必须优先使用 python_exec。'
                 'Python 包安装必须优先使用 python_package。'
+                '需要等待远端长任务（>30s 的训练、文件落盘、外部 API 回调）时，'
+                '设置 run_in_background=true 让命令在后台 detach 跑、立刻返回 task_id；'
+                '默认 wait_for_completion=true 时进程结束后会自动起新一轮把结果送回。'
+                '后台任务输出落在 <remote_workspace>/.bg_tasks/<task_id>/output。'
             ),
             parameters={
                 'type': 'object',
                 'properties': {
                     'command': {'type': 'string'},
+                    'run_in_background': {
+                        'type': 'boolean',
+                        'description': (
+                            '后台 detach 跑。立刻返回 task_id，不等命令结束。'
+                            '适合 >30s 的远端任务、需要等异步事件的场景。'
+                        ),
+                    },
+                    'wait_for_completion': {
+                        'type': 'boolean',
+                        'description': (
+                            '仅在 run_in_background=true 时生效。'
+                            'true（默认）：进程结束后由后端自动起新一轮把结果作为 system 消息送回；'
+                            'false：不自动续，agent 需自行调 bash_status 取结果。'
+                        ),
+                    },
                 },
                 'required': ['command'],
             },
             handler=resolve_handler(handlers, 'bash', 'execution'),
         ),
+        AgentTool(
+            name='bash_status',
+            description=(
+                '查询通过 bash(run_in_background=true) 启动的后台任务状态。'
+                'block=true 会阻塞到任务终止或 timeout_seconds 到期再返回；'
+                'block=false（默认）立刻返回当前快照。'
+                '返回 status (running/completed/failed/cancelled)、exit_code 和最近输出预览。'
+            ),
+            parameters={
+                'type': 'object',
+                'properties': {
+                    'task_id': {
+                        'type': 'string',
+                        'description': 'bash run_in_background 启动时返回的 task_id。',
+                    },
+                    'block': {
+                        'type': 'boolean',
+                        'description': '是否等到任务终止再返回；默认 false。',
+                    },
+                    'timeout_seconds': {
+                        'type': 'number',
+                        'minimum': 0,
+                        'maximum': 600,
+                        'description': 'block=true 时最长等待秒数，默认 30，上限 600。',
+                    },
+                },
+                'required': ['task_id'],
+            },
+            handler=resolve_handler(handlers, 'bash_status', 'execution'),
+        ),
+        AgentTool(
+            name='bash_kill',
+            description=(
+                '主动终止通过 bash(run_in_background=true) 启动的后台任务。'
+                '注意：用户在前端按 stop 取消当前 run 不会自动杀后台进程（detach 的本意），'
+                '需要明确调用本工具才能终止远端进程。'
+            ),
+            parameters={
+                'type': 'object',
+                'properties': {
+                    'task_id': {
+                        'type': 'string',
+                        'description': 'bash run_in_background 启动时返回的 task_id。',
+                    },
+                },
+                'required': ['task_id'],
+            },
+            handler=resolve_handler(handlers, 'bash_kill', 'execution'),
+        ),
         AgentTool(
             name='sleep',
             description='Pause execution briefly for bounded local wait flows.',