Tools & Permissions

Toporic comes with a built-in set of tools that let the agent read files, edit code, run shell commands, search the web, and more. The agent decides which tools to use on its own — you don’t need to know tool names or parameters.

What you do control is which tools and commands run automatically versus which ones ask for your approval.

Tool categories

Category	What the agent can do	Examples
Filesystem	Read, write, edit, delete files; list directories	Editing source files, creating new components
Shell	Run commands in your workspace	Tests, builds, git operations, package installs
Search	Search your codebase	Finding functions, tracing references, grep
Web	Fetch URLs, search the web	Looking up documentation, API references
LSP	Query language servers	Go-to-definition, find references, hover info
Git	Read and write git	Status, diff, commit, push, pull
Todo	Track tasks and load skills	Task planning, skill activation

Permission modes

Choose how much the agent can do without asking:

Mode	Behavior	How to enable
Auto	All tools run without confirmation	Default for --goal. In TUI, press Tab until [AUTO] shows.
Build	Mutating tools prompt for permission before each run	--goal --build "..." or /build in TUI
Plan	Agent shows a plan but executes nothing	--goal --plan "..." or /plan in TUI

In Build mode, when the agent wants to run a command or edit a file, you see a confirmation dialog:

Allow tool execution?

run_command: cargo test

[Y] Yes    [N] No

Press Y to allow it this once, or N to deny. If you trust the agent’s judgment, use Auto mode.

Fine-grained permissions

You can go beyond the basic mode toggle. In ~/.toporic/config.json, the permissions section gives you precise control:

{
  "permissions": {
    "auto_approve_reads": true,
    "enable_llm_classifier": false,
    "safe_commands": [
      "cargo test",
      "cargo build",
      "npm test",
      "npm run build",
      "npm run lint",
      "pytest",
      "go test",
      "git status",
      "git diff",
      "git log",
      "ls",
      "cat",
      "echo"
    ],
    "allowed_outside_paths": ["/tmp", "/var/log"]
  }
}

auto_approve_reads

When true (default), all read-only tools run without prompts — even in Build mode. This includes read_file, list_dir, search_files, and similar. The agent can explore your codebase freely without interrupting you, while writes and commands still need approval.

safe_commands

A list of shell command prefixes that are always safe to run without confirmation. When the agent runs a command that starts with one of these prefixes, it auto-approves regardless of the current mode.

"cargo test"      matches  cargo test --all
"npm run build"   matches  npm run build --watch
"git status"      matches  git status --short
"ls"              matches  ls -la

This is the most common way to reduce permission fatigue: add your project’s test and lint commands, and they’ll run without prompts even in Build mode.

enable_llm_classifier

When true, Toporic uses a second LLM call to classify each shell command as SAFE, RISKY, or DANGEROUS before running it. SAFE commands auto-approve; the rest prompt you.

This is a “smart” alternative to safe_commands — it handles edge cases without you having to list every variation of every command. The trade-off is an extra ~200–500ms of latency and a small API cost per command.

allowed_outside_paths

By default, all tool operations must be within your workspace root. If the agent needs to read or write files outside the workspace (e.g. /tmp, /var/log, ~/Downloads), list those paths here. The tilde ~ expands to your home directory.

Tool policies in skills

Each skill can declare its own tool policy, restricting which tools the agent can use when that skill is active:

tool_policy:
  allowed:
    - read_file
    - write_file
    - run_command
    - search_files
  denied:
    - delete_file

This is useful for limiting a skill to its intended scope — for example, a code-review skill might only allow read-only tools plus git operations.

Command allowlist

For security, run_command only permits a predefined set of programs. Unrecognized commands are rejected before execution. The built-in allowlist includes:

cargo, git, python3, python, node, npm, make, pytest,
rg, ls, cat, echo, mkdir, rm, cp, mv, touch, grep, find,
curl, wget, pwd, true, rustfmt, clippy, jq, tar, unzip, zip, wc

If you need a program not listed here, contact support or open an issue — the allowlist is maintained based on community feedback.