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
• 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 (exec already runs on the host).

Examples

Foreground:

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

Background + poll:

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