Shell 工具与进程

run_shell_command 接受必需的 command，以及可选 description、dir_path、is_background。Windows 使用 powershell.exe -NoProfile -Command，其他平台使用 bash -c，不应因用户登录 shell 是 Zsh 就假设工具也用 Zsh 语法。

输出与后台任务

返回 Command、Directory、Stdout、Stderr、Exit Code 和 Background PIDs。启动后台任务可以立即返回，PID 存在不代表任务已经成功完成；检查输出、错误及退出状态。子进程带 GEMINI_CLI=1，便于脚本识别运行来源。

交互终端

{
  "tools": {
    "shell": {
      "enableInteractiveShell": true,
      "showColor": true,
      "pager": "cat"
    }
  }
}

启用后用 node-pty，缺少 node-pty 时回退 child_process，不支持相同的实时交互。交互运行时按 Tab 将焦点交给 shell，可操作编辑器或 TUI。showColor 和 pager 仅在交互 shell 开启时适用，pager 默认 cat。

tools.shell.inactivityTimeout 表示等待输出的秒数，超过后结束进程；不要把它当作后台任务永久运行保证。

限制命令

tools.core 是所有内置工具的 allowlist，不是单纯 shell 规则。只填 run_shell_command(git) 会同时使未列出的 read_file 等工具不可用。通用 run_shell_command 项表示允许该工具的任意命令，仍受阻止策略限制。

tools.exclude 已弃用，新拒绝规则使用 Policy Engine。旧机制会拆分 &&、||、; 的子命令逐项验证，任一不允许则整体阻止；不能利用链式写法绕过限制。

策略里的 commandPrefix 和 commandRegex 是 TOML 规则简写，不是 run_shell_command 参数。官方 Shell 页末尾还有把 tools.core 简写成裸命令前缀的重复段落，与前面的全工具警告不一致；按完整工具标识与当前策略文档配置，不复制裸 git/npm test 数组当作通用配置。

连续任务与人工命令

可以要求 Agent 运行指定测试、依据失败输出修复、再运行同一组测试；每一步是否需要确认由当前策略决定。教程以逐次确认作演示，但“每条命令必然询问”和“所有沙箱都是 Docker”不适用于全部模式与平台。

输入 !git status 可直接执行人工命令；教程说明命令和输出会进入当前会话上下文，大输出可能截断。/shells 查看后台进程并处理日志或终止操作，详细交互见文件引用与 Shell 输入。