Cogtrix groups every tool into one of two safety categories, and the agent’s behaviour around side effects is gated by that classification.
Safety categories
| Category | Confirmation? | Examples |
|---|---|---|
| Safe | No prompt | read_file, calculate, web_search, http_get, git_status, git_log, parse_json |
| Sensitive | Yes, every call | execute_shell_command, execute_python, write_file, patch_file, append_file, git_commit, git_add, http_post |
Safe tools execute immediately. Sensitive tools pause the agent and ask for explicit user approval before each invocation.
The confirmation prompt
When a sensitive tool is about to run, Cogtrix prints:
⚠️ Tool 'patch_file' requires confirmation. Apply? [y/n/a/d/f/c]The responses:
| Key | Effect |
|---|---|
y | Approve this single call. |
n | Deny this call. The agent gets a tool-call error back and decides what to do next. |
a | Approve and auto-approve this tool for the rest of the session. |
d | Deny and disable this tool for the rest of the session. |
f | Forbid all further tool calls this turn. The agent must respond from memory. |
c | Cancel the current workflow entirely. |
Bypassing confirmations
In a trusted context (containerised sandbox, CI job, scripted run) you can skip prompts with -y:
uv run python cogtrix.py -y --prompt "Refactor parser.py and run the tests"-y auto-approves every sensitive tool for the entire run.
Sandboxing file access
The agent’s file tools can be confined to a directory via two repeatable flags:
uv run python cogtrix.py \
--allow-read-path /workspace \
--allow-write-path /workspace/output \
--prompt "..."read_file / list_directory will refuse reads outside --allow-read-path. Same for writes outside --allow-write-path. Combined with -y, this is the standard setup for an unattended agent run.
How the agent knows
The classification is encoded directly on the tool registration — each register_tool call sets confirmation= and safety_category=. Adding a new tool is the canonical place to declare its safety profile. See Custom tools.