Cmd Tool

Applies to: 4.0.8.1+

Cmd provides controlled shell execution with built-in safety gates.

1) Initialization

from agently.builtins.tools import Cmd

cmd = Cmd(
    allowed_cmd_prefixes=["ls", "rg", "cat", "pwd"],
    allowed_workdir_roots=["/workspace/project"],
    timeout=20,
    env=None,
)

2) Safety model

• command allowlist: only prefixes in allowed_cmd_prefixes
• working directory allowlist: workdir must be under allowed_workdir_roots

Violations return:

• need_approval=True
• reason=cmd_not_allowed or reason=workdir_not_allowed

3) Direct usage

import asyncio
from agently.builtins.tools import Cmd

cmd = Cmd(allowed_cmd_prefixes=["ls", "pwd"], allowed_workdir_roots=["/workspace/project"])

async def main():
    result = await cmd.run("ls", workdir="/workspace/project")
    print(result)

asyncio.run(main())

4) Output shape

Success fields:

• ok
• returncode
• stdout
• stderr

Rejected fields:

• ok=False
• need_approval=True
• reason

5) Agent integration tips

• expose minimum necessary commands only
• keep workdir allowlist narrow
• enforce prompt-level policy (for example read-only operations)