fix: rename bash tool to exec (#748) (thanks @myfunc)

2026-01-12 02:49:55 +00:00
parent b33bd6aaeb
commit 98337a14b3
51 changed files with 294 additions and 252 deletions
--- a/docs/broadcast-groups.md
+++ b/docs/broadcast-groups.md
@@ -180,7 +180,7 @@ In group `120363403215116621@g.us` with agents `["alfred", "baerbel"]`:
 Session: agent:alfred:whatsapp:group:120363403215116621@g.us
 History: [user message, alfred's previous responses]
 Workspace: /Users/pascal/clawd-alfred/
-Tools: read, write, bash
+Tools: read, write, exec
 ```

 **Bärbel's context:**
@@ -230,10 +230,10 @@ Give agents only the tools they need:
 {
  "agents": {
    "reviewer": {
-      "tools": { "allow": ["read", "bash"] }  // Read-only
+      "tools": { "allow": ["read", "exec"] }  // Read-only
    },
    "fixer": {
-      "tools": { "allow": ["read", "write", "edit", "bash"] }  // Read-write
+      "tools": { "allow": ["read", "write", "edit", "exec"] }  // Read-write
    }
  }
 }
@@ -330,8 +330,8 @@ tail -f ~/.clawdbot/logs/gateway.log | grep broadcast
  "agents": {
    "list": [
      { "id": "code-formatter", "workspace": "~/agents/formatter", "tools": { "allow": ["read", "write"] } },
-      { "id": "security-scanner", "workspace": "~/agents/security", "tools": { "allow": ["read", "bash"] } },
-      { "id": "test-coverage", "workspace": "~/agents/testing", "tools": { "allow": ["read", "bash"] } },
+      { "id": "security-scanner", "workspace": "~/agents/security", "tools": { "allow": ["read", "exec"] } },
+      { "id": "test-coverage", "workspace": "~/agents/testing", "tools": { "allow": ["read", "exec"] } },
      { "id": "docs-checker", "workspace": "~/agents/docs", "tools": { "allow": ["read"] } }
    ]
  }
--- a/docs/concepts/agent.md
+++ b/docs/concepts/agent.md
@@ -45,7 +45,7 @@ To disable bootstrap file creation entirely (for pre-seeded workspaces), set:

 ## Built-in tools

-Core tools (read/bash/edit/write and related system tools) are always available. `TOOLS.md` does **not** control which tools exist; it’s guidance for how *you* want them used.
+Core tools (read/exec/edit/write and related system tools) are always available. `TOOLS.md` does **not** control which tools exist; it’s guidance for how *you* want them used.

 ## Skills

--- a/docs/concepts/multi-agent.md
+++ b/docs/concepts/multi-agent.md
@@ -217,7 +217,7 @@ Starting with v2026.1.6, each agent can have its own sandbox and tool restrictio
        },
        tools: {
          allow: ["read"],                    // Only read tool
-          deny: ["bash", "write", "edit"],    // Deny others
+          deny: ["exec", "write", "edit"],    // Deny others
        },
      },
    ],
@@ -231,7 +231,7 @@ Starting with v2026.1.6, each agent can have its own sandbox and tool restrictio
 - **Flexible policies**: Different permissions per agent

 Note: `tools.elevated` is **global** and sender-based; it is not configurable per agent.
-If you need per-agent boundaries, use `agents.list[].tools` to deny `bash`.
+If you need per-agent boundaries, use `agents.list[].tools` to deny `exec`.
 For group targeting, use `agents.list[].groupChat.mentionPatterns` so @mentions map cleanly to the intended agent.

 See [Multi-Agent Sandbox & Tools](/multi-agent-sandbox-tools) for detailed examples.
--- a/docs/concepts/session-pruning.md
+++ b/docs/concepts/session-pruning.md
@@ -93,7 +93,7 @@ Restrict pruning to specific tools:
  agent: {
    contextPruning: {
      mode: "adaptive",
-      tools: { allow: ["bash", "read"], deny: ["*image*"] }
+      tools: { allow: ["exec", "read"], deny: ["*image*"] }
    }
  }
 }
--- a/docs/concepts/system-prompt.md
+++ b/docs/concepts/system-prompt.md
@@ -19,7 +19,7 @@ The prompt is intentionally compact and uses fixed sections:
 - **Clawdbot Self-Update**: how to run `config.apply` and `update.run`.
 - **Workspace**: working directory (`agents.defaults.workspace`).
 - **Workspace Files (injected)**: indicates bootstrap files are included below.
- **Sandbox** (when enabled): indicates sandboxed runtime, sandbox paths, and whether elevated bash is available.
+- **Sandbox** (when enabled): indicates sandboxed runtime, sandbox paths, and whether elevated exec is available.
 - **Time**: UTC default + the user’s local time (already converted).
 - **Reply Tags**: optional reply tag syntax for supported providers.
 - **Heartbeats**: heartbeat prompt and ack behavior.
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -103,7 +103,11 @@
    },
    {
      "source": "/bash",
-      "destination": "/tools/bash"
+      "destination": "/tools/exec"
+    },
+    {
+      "source": "/tools/bash",
+      "destination": "/tools/exec"
    },
    {
      "source": "/bonjour",
@@ -696,7 +700,7 @@
        "pages": [
          "tools",
          "plugin",
-          "tools/bash",
+          "tools/exec",
          "tools/elevated",
          "tools/browser",
          "tools/browser-linux-troubleshooting",
--- a/docs/gateway/background-process.md
+++ b/docs/gateway/background-process.md
@@ -1,15 +1,15 @@
 ---
-summary: "Background bash execution and process management"
+summary: "Background exec execution and process management"
 read_when:
-  - Adding or modifying background bash behavior
-  - Debugging long-running bash tasks
+  - Adding or modifying background exec behavior
+  - Debugging long-running exec tasks
 ---

-# Background Bash + Process Tool
+# Background Exec + Process Tool

-Clawdbot runs shell commands through the `bash` tool and keeps long‑running tasks in memory. The `process` tool manages those background sessions.
+Clawdbot runs shell commands through the `exec` tool and keeps long‑running tasks in memory. The `process` tool manages those background sessions.

-## bash tool
+## exec tool

 Key parameters:
 - `command` (required)
@@ -24,7 +24,7 @@ Behavior:
 - Foreground runs return output directly.
 - When backgrounded (explicit or timeout), the tool returns `status: "running"` + `sessionId` and a short tail.
 - Output is kept in memory until the session is polled or cleared.
- If the `process` tool is disallowed, `bash` runs synchronously and ignores `yieldMs`/`background`.
+- If the `process` tool is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.

 Environment overrides:
 - `PI_BASH_YIELD_MS`: default yield (ms)
@@ -32,9 +32,9 @@ Environment overrides:
 - `PI_BASH_JOB_TTL_MS`: TTL for finished sessions (ms, bounded to 1m–3h)

 Config (preferred):
- `tools.bash.backgroundMs` (default 10000)
- `tools.bash.timeoutSec` (default 1800)
- `tools.bash.cleanupMs` (default 1800000)
+- `tools.exec.backgroundMs` (default 10000)
+- `tools.exec.timeoutSec` (default 1800)
+- `tools.exec.cleanupMs` (default 1800000)

 ## process tool

@@ -59,7 +59,7 @@ Notes:

 Run a long task and poll later:
 ```json
-{"tool": "bash", "command": "sleep 5 && echo done", "yieldMs": 1000}
+{"tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000}
 ```
 ```json
 {"tool": "process", "action": "poll", "sessionId": "<id>"}
@@ -67,7 +67,7 @@ Run a long task and poll later:

 Start immediately in background:
 ```json
-{"tool": "bash", "command": "npm run build", "background": true}
+{"tool": "exec", "command": "npm run build", "background": true}
 ```

 Send stdin:
--- a/docs/gateway/configuration-examples.md
+++ b/docs/gateway/configuration-examples.md
@@ -259,9 +259,9 @@ Save to `~/.clawdbot/clawdbot.json` and you can DM the bot from that number.
  },

  tools: {
-    allow: ["bash", "process", "read", "write", "edit"],
+    allow: ["exec", "process", "read", "write", "edit"],
    deny: ["browser", "canvas"],
-    bash: {
+    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000
--- a/docs/gateway/configuration.md
+++ b/docs/gateway/configuration.md
@@ -638,7 +638,7 @@ Read-only tools + read-only workspace:
        },
        tools: {
          allow: ["read", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
-          deny: ["write", "edit", "bash", "process", "browser"]
+          deny: ["write", "edit", "exec", "process", "browser"]
        }
      }
    ]
@@ -661,7 +661,7 @@ No filesystem access (messaging/session tools enabled):
        },
        tools: {
          allow: ["sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status", "whatsapp", "telegram", "slack", "discord", "gateway"],
-          deny: ["read", "write", "edit", "bash", "process", "browser", "canvas", "nodes", "cron", "gateway", "image"]
+          deny: ["read", "write", "edit", "exec", "process", "browser", "canvas", "nodes", "cron", "gateway", "image"]
        }
      }
    ]
@@ -1274,7 +1274,7 @@ Example:
        maxConcurrent: 1,
        archiveAfterMinutes: 60
      },
-      bash: {
+      exec: {
        backgroundMs: 10000,
        timeoutSec: 1800,
        cleanupMs: 1800000
@@ -1427,10 +1427,11 @@ Z.AI models are available as `zai/<model>` (e.g. `zai/glm-4.7`) and require
 Heartbeats run full agent turns. Shorter intervals burn more tokens; be mindful
 of `every`, keep `HEARTBEAT.md` tiny, and/or choose a cheaper `model`.

-`tools.bash` configures background bash defaults:
+`tools.exec` configures background exec defaults:
 - `backgroundMs`: time before auto-background (ms, default 10000)
 - `timeoutSec`: auto-kill after this runtime (seconds, default 1800)
 - `cleanupMs`: how long to keep finished sessions in memory (ms, default 1800000)
+Legacy: `tools.bash` is still accepted as an alias.

 `agents.defaults.subagents` configures sub-agent defaults:
 - `maxConcurrent`: max concurrent sub-agent runs (default 1)
@@ -1447,7 +1448,7 @@ Example (disable browser/canvas everywhere):
 }
 ```

-`tools.elevated` controls elevated (host) bash access:
+`tools.elevated` controls elevated (host) exec access:
 - `enabled`: allow elevated mode (default true)
 - `allowFrom`: per-provider allowlists (empty = disabled)
  - `whatsapp`: E.164 numbers
@@ -1491,8 +1492,8 @@ Per-agent override (further restrict):
 Notes:
 - `tools.elevated` is the global baseline. `agents.list[].tools.elevated` can only further restrict (both must allow).
 - `/elevated on|off` stores state per session key; inline directives apply to a single message.
- Elevated `bash` runs on the host and bypasses sandboxing.
- Tool policy still applies; if `bash` is denied, elevated cannot be used.
+- Elevated `exec` runs on the host and bypasses sandboxing.
+- Tool policy still applies; if `exec` is denied, elevated cannot be used.

 `agents.defaults.maxConcurrent` sets the maximum number of embedded agent runs that can
 execute in parallel across sessions. Each session is still serialized (one run
@@ -1513,7 +1514,7 @@ Defaults (if enabled):
  - `"ro"`: keep the sandbox workspace at `/workspace`, and mount the agent workspace read-only at `/agent` (disables `write`/`edit`)
  - `"rw"`: mount the agent workspace read/write at `/workspace`
 - auto-prune: idle > 24h OR age > 7d
- tool policy: allow only `bash`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `session_status` (deny wins)
+- tool policy: allow only `exec`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `session_status` (deny wins)
  - configure via `tools.sandbox.tools`, override per-agent via `agents.list[].tools.sandbox.tools`
 - optional sandboxed browser (Chromium + CDP, noVNC observer)
 - hardening knobs: `network`, `user`, `pidsLimit`, `memory`, `cpus`, `ulimits`, `seccompProfile`, `apparmorProfile`
@@ -1584,7 +1585,7 @@ Legacy: `perSession` is still supported (`true` → `scope: "session"`,
  tools: {
    sandbox: {
      tools: {
-        allow: ["bash", "process", "read", "write", "edit", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
+        allow: ["exec", "process", "read", "write", "edit", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"]
      }
    }
--- a/docs/gateway/doctor.md
+++ b/docs/gateway/doctor.md
@@ -111,7 +111,7 @@ Current migrations:
 - `routing.agentToAgent` → `tools.agentToAgent`
 - `routing.transcribeAudio` → `tools.audio.transcription`
 - `identity` → `agents.list[].identity`
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/bash/sandbox/subagents)
+- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
 - `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks`
  → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`

--- a/docs/gateway/logging.md
+++ b/docs/gateway/logging.md
@@ -50,7 +50,7 @@ You can tune console verbosity independently via:

 ## Tool summary redaction

-Verbose tool summaries (e.g. `🛠️ bash: ...`) can mask sensitive tokens before they hit the
+Verbose tool summaries (e.g. `🛠️ exec: ...`) can mask sensitive tokens before they hit the
 console stream. This is **tools-only** and does not alter file logs.

 - `logging.redactSensitive`: `off` | `tools` (default: `tools`)
--- a/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md
+++ b/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md
@@ -1,6 +1,6 @@
 ---
 title: Sandbox vs Tool Policy vs Elevated
-summary: "Why a tool is blocked: sandbox runtime, tool allow/deny policy, and elevated bash gates"
+summary: "Why a tool is blocked: sandbox runtime, tool allow/deny policy, and elevated exec gates"
 read_when: "You hit 'sandbox jail' or see a tool/elevated refusal and want the exact config key to change."
 status: active
 ---
@@ -11,7 +11,7 @@ Clawdbot has three related (but different) controls:

 1. **Sandbox** (`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`) decides **where tools run** (Docker vs host).
 2. **Tool policy** (`tools.*`, `tools.sandbox.tools.*`, `agents.list[].tools.*`) decides **which tools are available/allowed**.
-3. **Elevated** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) is a **bash-only escape hatch** to run on the host when you’re sandboxed.
+3. **Elevated** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) is an **exec-only escape hatch** to run on the host when you’re sandboxed.

 ## Quick debug

@@ -49,10 +49,10 @@ Rules of thumb:
 - `deny` always wins.
 - If `allow` is non-empty, everything else is treated as blocked.

-## Elevated: bash-only “run on host”
+## Elevated: exec-only “run on host”

-Elevated does **not** grant extra tools; it only affects `bash`.
- If you’re sandboxed, `/elevated on` (or `bash` with `elevated: true`) runs on the host.
+Elevated does **not** grant extra tools; it only affects `exec`.
+- If you’re sandboxed, `/elevated on` (or `exec` with `elevated: true`) runs on the host.
 - If you’re already running direct, elevated is effectively a no-op (still gated).

 Gates:
@@ -74,4 +74,3 @@ Fix-it keys (pick one):
 ### “I thought this was main, why is it sandboxed?”

 In `"non-main"` mode, group/channel keys are *not* main. Use the main session key (shown by `sandbox explain`) or switch mode to `"off"`.
-
--- a/docs/gateway/sandboxing.md
+++ b/docs/gateway/sandboxing.md
@@ -17,7 +17,7 @@ This is not a perfect security boundary, but it materially limits filesystem
 and process access when the model does something dumb.

 ## What gets sandboxed
- Tool execution (`bash`, `read`, `write`, `edit`, `process`, etc.).
+- Tool execution (`exec`, `read`, `write`, `edit`, `process`, etc.).
 - Optional sandboxed browser (`agents.defaults.sandbox.browser`).
  - By default, the sandbox browser auto-starts (ensures CDP is reachable) when the browser tool needs it.
    Configure via `agents.defaults.sandbox.browser.autoStart` and `agents.defaults.sandbox.browser.autoStartTimeoutMs`.
@@ -27,7 +27,7 @@ and process access when the model does something dumb.
 Not sandboxed:
 - The Gateway process itself.
 - Any tool explicitly allowed to run on the host (e.g. `tools.elevated`).
-  - **Elevated bash runs on the host and bypasses sandboxing.**
+  - **Elevated exec runs on the host and bypasses sandboxing.**
  - If sandboxing is off, `tools.elevated` does not change execution (already on host). See [Elevated Mode](/tools/elevated).

 ## Modes
@@ -79,7 +79,7 @@ Docker installs and the containerized gateway live here:
 Tool allow/deny policies still apply before sandbox rules. If a tool is denied
 globally or per-agent, sandboxing doesn’t bring it back.

-`tools.elevated` is an explicit escape hatch that runs `bash` on the host.
+`tools.elevated` is an explicit escape hatch that runs `exec` on the host.

 Debugging:
 - Use `clawdbot sandbox explain` to inspect effective sandbox mode, tool policy, and fix-it config keys.
--- a/docs/gateway/security.md
+++ b/docs/gateway/security.md
@@ -184,7 +184,7 @@ Consider running your AI on a separate phone number from your personal one:

 You can already build a read-only profile by combining:
 - `agents.defaults.sandbox.workspaceAccess: "ro"` (or `"none"` for no workspace access)
- tool allow/deny lists that block `write`, `edit`, `bash`, `process`, etc.
+- tool allow/deny lists that block `write`, `edit`, `exec`, `process`, etc.

 We may add a single `readOnlyMode` flag later to simplify this configuration.

@@ -206,7 +206,7 @@ Also consider agent workspace access inside the sandbox:
 - `agents.defaults.sandbox.workspaceAccess: "ro"` mounts the agent workspace read-only at `/agent` (disables `write`/`edit`)
 - `agents.defaults.sandbox.workspaceAccess: "rw"` mounts the agent workspace read/write at `/workspace`

-Important: `tools.elevated` is the global baseline escape hatch that runs bash on the host. Keep `tools.elevated.allowFrom` tight and don’t enable it for strangers. You can further restrict elevated per agent via `agents.list[].tools.elevated`. See [Elevated Mode](/tools/elevated).
+Important: `tools.elevated` is the global baseline escape hatch that runs exec on the host. Keep `tools.elevated.allowFrom` tight and don’t enable it for strangers. You can further restrict elevated per agent via `agents.list[].tools.elevated`. See [Elevated Mode](/tools/elevated).

 ## Browser control risks

@@ -261,7 +261,7 @@ Common use cases:
        },
        tools: {
          allow: ["read"],
-          deny: ["write", "edit", "bash", "process", "browser"]
+          deny: ["write", "edit", "exec", "process", "browser"]
        }
      }
    ]
@@ -285,7 +285,7 @@ Common use cases:
        },
        tools: {
          allow: ["sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status", "whatsapp", "telegram", "slack", "discord", "gateway"],
-          deny: ["read", "write", "edit", "bash", "process", "browser", "canvas", "nodes", "cron", "gateway", "image"]
+          deny: ["read", "write", "edit", "exec", "process", "browser", "canvas", "nodes", "cron", "gateway", "image"]
        }
      }
    ]
--- a/docs/install/docker.md
+++ b/docs/install/docker.md
@@ -250,7 +250,7 @@ precedence, and troubleshooting.
  - `"rw"` mounts the agent workspace read/write at `/workspace`
 - Auto-prune: idle > 24h OR age > 7d
 - Network: `none` by default (explicitly opt-in if you need egress)
- Default allow: `bash`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `session_status`
+- Default allow: `exec`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `session_status`
 - Default deny: `browser`, `canvas`, `nodes`, `cron`, `discord`, `gateway`

 ### Enable sandboxing
@@ -297,7 +297,7 @@ precedence, and troubleshooting.
  tools: {
    sandbox: {
      tools: {
-        allow: ["bash", "process", "read", "write", "edit", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
+        allow: ["exec", "process", "read", "write", "edit", "sessions_list", "sessions_history", "sessions_send", "sessions_spawn", "session_status"],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"]
      }
    }
@@ -424,7 +424,7 @@ Example:

 ### Security notes

- Hard wall only applies to **tools** (bash/read/write/edit).  
+- Hard wall only applies to **tools** (exec/read/write/edit).  
 - Host-only tools like browser/camera/canvas are blocked by default.  
 - Allowing `browser` in sandbox **breaks isolation** (browser runs on host).

--- a/docs/multi-agent-sandbox-tools.md
+++ b/docs/multi-agent-sandbox-tools.md
@@ -48,7 +48,7 @@ For debugging “why is this blocked?”, see [Sandbox vs Tool Policy vs Elevate
        },
        "tools": {
          "allow": ["read"],
-          "deny": ["bash", "write", "edit", "process", "browser"]
+          "deny": ["exec", "write", "edit", "process", "browser"]
        }
      }
    ]
@@ -95,7 +95,7 @@ For debugging “why is this blocked?”, see [Sandbox vs Tool Policy vs Elevate
          "workspaceRoot": "/tmp/work-sandboxes"
        },
        "tools": {
-          "allow": ["read", "write", "bash"],
+          "allow": ["read", "write", "exec"],
          "deny": ["browser", "gateway", "discord"]
        }
      }
@@ -134,7 +134,7 @@ For debugging “why is this blocked?”, see [Sandbox vs Tool Policy vs Elevate
        },
        "tools": {
          "allow": ["read"],
-          "deny": ["bash", "write", "edit"]
+          "deny": ["exec", "write", "edit"]
        }
      }
    ]
@@ -177,7 +177,7 @@ If `agents.list[].tools.sandbox.tools` is set, it replaces `tools.sandbox.tools`
 `tools.elevated` is the global baseline (sender-based allowlist). `agents.list[].tools.elevated` can further restrict elevated for specific agents (both must allow).

 Mitigation patterns:
- Deny `bash` for untrusted agents (`agents.list[].tools.deny: ["bash"]`)
+- Deny `exec` for untrusted agents (`agents.list[].tools.deny: ["exec"]`)
 - Avoid allowlisting senders that route to restricted agents
 - Disable elevated globally (`tools.elevated.enabled: false`) if you only want sandboxed execution
 - Disable elevated per agent (`agents.list[].tools.elevated.enabled: false`) for sensitive profiles
@@ -200,7 +200,7 @@ Mitigation patterns:
  "tools": {
    "sandbox": {
      "tools": {
-        "allow": ["read", "write", "bash"],
+        "allow": ["read", "write", "exec"],
        "deny": []
      }
    }
@@ -235,7 +235,7 @@ Legacy `agent.*` configs are migrated by `clawdbot doctor`; prefer `agents.defau
 {
  "tools": {
    "allow": ["read"],
-    "deny": ["bash", "write", "edit", "process"]
+    "deny": ["exec", "write", "edit", "process"]
  }
 }
 ```
@@ -244,7 +244,7 @@ Legacy `agent.*` configs are migrated by `clawdbot doctor`; prefer `agents.defau
 ```json
 {
  "tools": {
-    "allow": ["read", "bash", "process"],
+    "allow": ["read", "exec", "process"],
    "deny": ["write", "edit", "browser", "gateway"]
  }
 }
@@ -255,7 +255,7 @@ Legacy `agent.*` configs are migrated by `clawdbot doctor`; prefer `agents.defau
 {
  "tools": {
    "allow": ["sessions_list", "sessions_send", "sessions_history", "session_status"],
-    "deny": ["bash", "write", "edit", "read", "browser"]
+    "deny": ["exec", "write", "edit", "read", "browser"]
  }
 }
 ```
@@ -276,12 +276,12 @@ sandbox, set `agents.list[].sandbox.mode: "off"`.
 After configuring multi-agent sandbox and tools:

 1. **Check agent resolution:**
-   ```bash
+   ```exec
   clawdbot agents list --bindings
   ```

 2. **Verify sandbox containers:**
-   ```bash
+   ```exec
   docker ps --filter "label=clawdbot.sandbox=1"
   ```

@@ -290,7 +290,7 @@ After configuring multi-agent sandbox and tools:
   - Verify the agent cannot use denied tools

 4. **Monitor logs:**
-   ```bash
+   ```exec
   tail -f "${CLAWDBOT_STATE_DIR:-$HOME/.clawdbot}/logs/gateway.log" | grep -E "routing|sandbox|tools"
   ```

--- a/docs/platforms/mac/menu-bar.md
+++ b/docs/platforms/mac/menu-bar.md
@@ -25,7 +25,7 @@ read_when:
 - `overridden(ActivityKind)` (debug override)

 ### ActivityKind → glyph
- `bash` → 💻
+- `exec` → 💻
 - `read` → 📄
 - `write` → ✍️
 - `edit` → 📝
@@ -40,7 +40,7 @@ read_when:

 ## Status row text (menu)
 - While work is active: `<Session role> · <activity label>`
-  - Examples: `Main · bash: pnpm test`, `Other · read: apps/macos/Sources/Clawdbot/AppState.swift`.
+  - Examples: `Main · exec: pnpm test`, `Other · read: apps/macos/Sources/Clawdbot/AppState.swift`.
 - When idle: falls back to the health summary.

 ## Event ingestion
@@ -49,7 +49,7 @@ read_when:
  - `stream: "job"` with `data.state` for start/stop.
  - `stream: "tool"` with `data.phase`, `name`, optional `meta`/`args`.
 - Labels:
-  - `bash`: first line of `args.command`.
+  - `exec`: first line of `args.command`.
  - `read`/`write`: shortened path.
  - `edit`: path plus inferred change kind from `meta`/diff counts.
  - fallback: tool name.
--- a/docs/start/faq.md
+++ b/docs/start/faq.md
@@ -836,7 +836,7 @@ exit

 These are abort triggers (not slash commands).

-For background processes (from the bash tool), you can ask the agent to run:
+For background processes (from the exec tool), you can ask the agent to run:

 ```
 process action:kill sessionId:XXX
--- a/docs/start/hubs.md
+++ b/docs/start/hubs.md
@@ -95,7 +95,7 @@ Use these hubs to discover every page, including deep dives and reference docs t

 - [Tools surface](/tools)
 - [CLI reference](/cli)
- [Bash tool](/tools/bash)
+- [Exec tool](/tools/exec)
 - [Elevated mode](/tools/elevated)
 - [Cron jobs](/automation/cron-jobs)
 - [Thinking + verbose](/tools/thinking)
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -120,11 +120,11 @@ Live tests are split into two layers so we can isolate failures:
  - Iterate models-with-keys and assert:
    - “meaningful” response (no tools)
    - a real tool invocation works (read probe)
-    - optional extra tool probes (bash+read probe)
+    - optional extra tool probes (exec+read probe)
    - OpenAI regression paths (tool-call-only → follow-up) keep working
 - Probe details (so you can explain failures quickly):
  - `read` probe: the test writes a nonce file in the workspace and asks the agent to `read` it and echo the nonce back.
-  - `bash+read` probe: the test asks the agent to `bash`-write a nonce into a temp file, then `read` it back.
+  - `exec+read` probe: the test asks the agent to `exec`-write a nonce into a temp file, then `read` it back.
  - image probe: the test attaches a generated PNG (cat + randomized code) and expects the model to return `cat <CODE>`.
  - Implementation reference: `src/gateway/gateway-models.profiles.live.test.ts` and `src/gateway/live-image-probe.ts`.
 - How to enable:
@@ -136,7 +136,7 @@ Live tests are split into two layers so we can isolate failures:
 - How to select providers (avoid “OpenRouter everything”):
  - `CLAWDBOT_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (comma allowlist)
 - Optional tool-calling stress:
-  - `CLAWDBOT_LIVE_GATEWAY_TOOL_PROBE=1` enables an extra “bash writes file → read reads it back → echo nonce” check.
+  - `CLAWDBOT_LIVE_GATEWAY_TOOL_PROBE=1` enables an extra “exec writes file → read reads it back → echo nonce” check.
  - This is specifically meant to catch tool-calling compatibility issues across providers (formatting, history replay, tool_result pairing, etc.).
 - Optional image send smoke:
  - `CLAWDBOT_LIVE_GATEWAY_IMAGE_PROBE=1` sends a real image attachment through the gateway agent pipeline (multimodal message) and asserts the model can read back a per-run code from the image.
@@ -215,7 +215,7 @@ Narrow, explicit allowlists are fastest and least flaky:
 - Single model, gateway smoke:
  - `LIVE=1 CLAWDBOT_LIVE_GATEWAY=1 CLAWDBOT_LIVE_GATEWAY_ALL_MODELS=1 CLAWDBOT_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`

- Tool calling across several providers (bash + read probe):
+- Tool calling across several providers (exec + read probe):
  - `LIVE=1 CLAWDBOT_LIVE_GATEWAY=1 CLAWDBOT_LIVE_GATEWAY_ALL_MODELS=1 CLAWDBOT_LIVE_GATEWAY_TOOL_PROBE=1 CLAWDBOT_LIVE_GATEWAY_MODELS="openai/gpt-5.2,anthropic/claude-opus-4-5,google/gemini-3-flash,zai/glm-4.7,minimax/minimax-m2.1" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`

 - Google focus (Gemini API key + Antigravity):
@@ -248,7 +248,7 @@ This is the “common models” run we expect to keep working:
 Run gateway smoke with tools + image:
 `LIVE=1 CLAWDBOT_LIVE_GATEWAY=1 CLAWDBOT_LIVE_GATEWAY_TOOL_PROBE=1 CLAWDBOT_LIVE_GATEWAY_IMAGE_PROBE=1 CLAWDBOT_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-5,google/gemini-3-pro,google/gemini-3-flash,google-antigravity/claude-opus-4-5-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/minimax-m2.1" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`

-### Baseline: tool calling (Read + optional Bash)
+### Baseline: tool calling (Read + optional Exec)

 Pick at least one per provider family:
 - OpenAI: `openai/gpt-5.2` (or `openai/gpt-5-mini`)
--- a/docs/tools/elevated.md
+++ b/docs/tools/elevated.md
@@ -1,12 +1,12 @@
 ---
-summary: "Elevated bash mode and /elevated directives"
+summary: "Elevated exec mode and /elevated directives"
 read_when:
  - Adjusting elevated mode defaults, allowlists, or slash command behavior
 ---
 # Elevated Mode (/elevated directives)

 ## What it does
- Elevated mode allows the bash tool to run with elevated privileges when the feature is available and the sender is approved.
+- Elevated mode allows the exec tool to run with elevated privileges when the feature is available and the sender is approved.
 - **Optional for sandboxed agents**: elevated only changes behavior when the agent is running in a sandbox. If the agent already runs unsandboxed, elevated is effectively a no-op.
 - Directive forms: `/elevated on`, `/elevated off`, `/elev on`, `/elev off`.
 - Only `on|off` are accepted; anything else returns a hint and does not change state.
@@ -16,16 +16,16 @@ read_when:
 - **Per-session state**: `/elevated on|off` sets the elevated level for the current session key.
 - **Inline directive**: `/elevated on` inside a message applies to that message only.
 - **Groups**: In group chats, elevated directives are only honored when the agent is mentioned. Command-only messages that bypass mention requirements are treated as mentioned.
- **Host execution**: elevated runs `bash` on the host (bypasses sandbox).
- **Unsandboxed agents**: when there is no sandbox to bypass, elevated does not change where `bash` runs.
- **Tool policy still applies**: if `bash` is denied by tool policy, elevated cannot be used.
+- **Host execution**: elevated runs `exec` on the host (bypasses sandbox).
+- **Unsandboxed agents**: when there is no sandbox to bypass, elevated does not change where `exec` runs.
+- **Tool policy still applies**: if `exec` is denied by tool policy, elevated cannot be used.

 Note:
- Sandbox on: `/elevated on` runs that `bash` command on the host.
+- Sandbox on: `/elevated on` runs that `exec` command on the host.
 - Sandbox off: `/elevated on` does not change execution (already on host).

 ## When elevated matters
- Only impacts `bash` when the agent is running sandboxed (it drops the sandbox for that command).
+- Only impacts `exec` when the agent is running sandboxed (it drops the sandbox for that command).
 - For unsandboxed agents, elevated does not change execution; it only affects gating, logging, and status.

 ## Resolution order
@@ -48,5 +48,5 @@ Note:
 - All gates must pass; otherwise elevated is treated as unavailable.

 ## Logging + status
- Elevated bash calls are logged at info level.
+- Elevated exec calls are logged at info level.
 - Session status includes elevated mode (e.g. `elevated=on`).
--- a/docs/tools/exec.md
+++ b/docs/tools/exec.md
@@ -1,14 +1,14 @@
 ---
-summary: "Bash tool usage, stdin modes, and TTY support"
+summary: "Exec tool usage, stdin modes, and TTY support"
 read_when:
-  - Using or modifying the bash tool
+  - Using or modifying the exec tool
  - Debugging stdin or TTY behavior
 ---

-# Bash tool
+# Exec tool

 Run shell commands in the workspace. Supports foreground + background execution via `process`.
-If `process` is disallowed, `bash` runs synchronously and ignores `yieldMs`/`background`.
+If `process` is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.
 Background sessions are scoped per agent; `process` only sees sessions from the same agent.

 ## Parameters
@@ -19,17 +19,17 @@ Background sessions are scoped per agent; `process` only sees sessions from the
 - `timeout` (seconds, default 1800): kill on expiry
 - `elevated` (bool): run on host if elevated mode is enabled/allowed (only changes behavior when the agent is sandboxed)
 - Need a real TTY? Use the tmux skill.
-Note: `elevated` is ignored when sandboxing is off (bash already runs on the host).
+Note: `elevated` is ignored when sandboxing is off (exec already runs on the host).

 ## Examples

 Foreground:
 ```json
-{"tool":"bash","command":"ls -la"}
+{"tool":"exec","command":"ls -la"}
 ```

 Background + poll:
 ```json
-{"tool":"bash","command":"npm run build","yieldMs":1000}
+{"tool":"exec","command":"npm run build","yieldMs":1000}
 {"tool":"process","action":"poll","sessionId":"<id>"}
 ```
--- a/docs/tools/index.md
+++ b/docs/tools/index.md
@@ -31,7 +31,7 @@ alongside tools (for example, the voice-call plugin).

 ## Tool inventory

-### `bash`
+### `exec`
 Run shell commands in the workspace.

 Core parameters:
@@ -45,12 +45,12 @@ Core parameters:
 Notes:
 - Returns `status: "running"` with a `sessionId` when backgrounded.
 - Use `process` to poll/log/write/kill/clear background sessions.
- If `process` is disallowed, `bash` runs synchronously and ignores `yieldMs`/`background`.
+- If `process` is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.
 - `elevated` is gated by `tools.elevated` plus any `agents.list[].tools.elevated` override (both must allow) and runs on the host.
 - `elevated` only changes behavior when the agent is sandboxed (otherwise it’s a no-op).

 ### `process`
-Manage background bash sessions.
+Manage background exec sessions.

 Core actions:
 - `list`, `poll`, `log`, `write`, `kill`, `clear`, `remove`
--- a/docs/tools/subagents.md
+++ b/docs/tools/subagents.md
@@ -80,7 +80,7 @@ Override via config:
        // deny wins
        deny: ["gateway", "cron"],
        // if allow is set, it becomes allow-only (deny still wins)
-        // allow: ["read", "bash", "process"]
+        // allow: ["read", "exec", "process"]
      }
    }
  }