​

Exec Tool — User Guide

​

Parameters

• command (required)
• workdir (defaults to cwd)
• env (key/value overrides)
• yieldMs (default 10000): auto-background after this delay
• background (bool): background immediately
• timeout (seconds, default 1800): kill on expiry
• pty (bool): run in a pseudo-terminal (use for TTY-only CLIs, coding agents, terminal UIs)
• host (sandbox | gateway | node): where to execute
• security (deny | allowlist | full): enforcement mode for gateway/node
• ask (off | on-miss | always): approval prompts for gateway/node
• node (string): node id/name for host=node
• elevated (bool): request elevated host execution when sandboxed

​

When exec asks for approval

• deny — host exec is blocked entirely.
• allowlist — approved only if the command matches an allowlisted path.
• on-miss — you get a prompt when no allowlist entry matches.
• always — you get a prompt for every command.

• Allow once — run now
• Always allow — add to allowlist and run
• Deny — block this command

​

Giving an agent full exec permission

{
  "agents": {
    "defaults": {
      "tools": {
        "exec": {
          "security": "full",
          "ask": "off"
        }
      }
    }
  }
}

{
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": {
          "exec": {
            "security": "full",
            "ask": "off"
          }
        }
      }
    ]
  }
}

​

Trusting specific commands

​

Safe bins (narrow stdin filters)

{ "tools": { "exec": { "safeBins": ["jq", "my-filter"] } } }

​

Allowlist (exec-approvals.json)

{
  "version": 1,
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [{ "pattern": "/opt/homebrew/bin/rg" }, { "pattern": "~/.local/bin/*" }]
    }
  }
}

​

Per-session overrides (/exec)

/exec host=gateway security=allowlist ask=on-miss node=mac-1

​

System events

• Exec running — emitted if the command runs longer than approvalRunningNoticeMs (default 10 s)
• Exec finished — command completed
• Exec denied — blocked by policy or explicit denial

​

Quick config reference

​

Examples

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

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