clawdbot/docs/tools/exec.md

summary, read_when

summary	read_when
Exec tool usage, stdin modes, and TTY support	Using or modifying the exec tool Debugging stdin or TTY behavior

Exec tool

Run shell commands in the workspace. Supports foreground + background execution via process. 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

• command (required)
• yieldMs (default 10000): auto-background after delay
• background (bool): background immediately
• timeout (seconds, default 1800): kill on expiry
• pty (bool): run in a pseudo-terminal when available (TTY-only CLIs, coding agents, terminal UIs)
• elevated (bool): run on host if elevated mode is enabled/allowed (only changes behavior when the agent is sandboxed)
• Need a fully interactive session? Use pty: true and the process tool for stdin/output. Note: elevated is ignored when sandboxing is off (exec already runs on the host).

Config

• tools.exec.notifyOnExit (default: true): when true, backgrounded exec sessions enqueue a system event and request a heartbeat on exit.

Examples

Foreground:

{"tool":"exec","command":"ls -la"}

Background + poll:

{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}

apply_patch (experimental)

apply_patch is a subtool of exec for structured multi-file edits. Enable it explicitly:

{
  tools: {
    exec: {
      applyPatch: { enabled: true, allowModels: ["gpt-5.2"] }
    }
  }
}

Notes:

• Only available for OpenAI/OpenAI Codex models.
• Tool policy still applies; allow: ["exec"] implicitly allows apply_patch.
• Config lives under tools.exec.applyPatch.