Safe Commands Protocol

This skill defines all commands that are SAFE TO AUTO-RUN without user approval.

[!IMPORTANT] This is the single source of truth for Safe Commands. All other skills and prompts should reference this skill instead of duplicating the list.

Auto-Run Command Categories

[!IMPORTANT] artifact-formalizer/evals/run_authoring.py is deliberately NOT on this list. The other two eval scripts read files and spawn nothing. run_authoring.py spawns claude -p once per arm per case and spends tokens, so it requires approval on every invocation.

Pattern Matching Rules

Commands are safe if they match these patterns:

• From the project root only. The framework-script patterns name paths relative to the project root. Run from another directory, the same text names another file, such as a nested checkout's script of the same path.
• In the project's own work tree only. The test-runner patterns run the code of the directory they start in: a nested checkout's conftest.py or package.json scripts.
• Enforcement. No hook enforces these two conditions yet: an allow list cannot see the working directory, so the agent runs these commands from the project root. A PreToolUse hook to make a relative-path command ask inside a nested checkout is deferred to WI-34.
• find is not on this list. -exec, -execdir, -ok and -delete run a command or delete files, and a pattern cannot tell them apart; find asks for approval.
• Options that run a program. rg --pre and rg --hostname-bin run a program, and so do fd -x, fd -X, --exec and --exec-batch. The rg and fd patterns exclude these options wherever they stand. ripgrep 14.1.1 rejects an abbreviated long option; the fd pattern excludes every long option that starts with --exe, and x or X anywhere in a short-option cluster, digits included (fd -1x).
• Archiving runs through a script. archive_move.py accepts docs/TASK.md with docs/tasks/task-<ID>-<slug>.md and docs/PLAN.md with docs/plans/plan-<ID>-<slug>.md, and refuses every other operand, a link and an existing file. The pattern admits any operand because the script is the guard (TASK 112 R1).
• No file. file is off this list: -C, and its abbreviation --co, write a compiled magic file (TASK 112 D2).
• An allow rule names its command whole. X * matches X with arguments; X* also matches every command whose name starts with X, such as git difftool for git diff*. Each pattern ends at its command or its script's name for the same reason.
• Read forms only. --output makes git log, git diff and git show write a file. With an argument, git branch, git tag and git remote create or delete a ref or change a remote. tree -o writes a file, so tree is off this list. Claude Code's built-in check approves the read forms of git with no rule, and the committed settings name only the bare forms of these commands (TASK 111 D13).
• Test runners with no argument. An option of pytest, npm test, jest or cargo test can run a program, delete a directory or overwrite a file. The patterns match the bare commands only. npx jest is off this list: it downloads jest when the project has none (TASK 111 D14).
• Each simple command, after quote removal. A pattern applies to each simple command of a compound command, after the shell removes its quotes. A simple command with an output redirection to a file other than /dev/null, a command substitution or a process substitution is not safe. Neither is a command with a line continuation, $'…' or $"…" quoting, a parameter or brace expansion, or, for rg, fd and git, an unquoted glob: the shell can turn each into an option the patterns never see. Neither is a command the agent cannot reduce that way.

# Read-only filesystem
^(ls|cat|head|tail|grep|wc|stat|du|df|echo)(?:\s|$)

# Symlink-aware listing — framework dirs (.agent/, .agents/, System/, .agentic-development/) may be symlinks
^ls\s+-[a-zA-Z]*L

# rg and fd, except the options that run a program; -L and --follow follow symlinks
^rg(?![\s\S]*\s--(?:pre|hostname-bin)(?:[=\s]|$))(?:\s|$)
^fd(?![\s\S]*\s(?:-[^-\s]*[xX]|--exe))(?:\s|$)

# Git read operations (the boundary keeps `git difftool -x <program>` out; `--output` writes a file)
^git\s+(status|log|diff|show)(?![\s\S]*\s--output)(\s|$)
^git\s+(branch|remote|tag)$

# Archiving: the script refuses every operand but the two archive pairs
^python3\s+\.agent/tools/archive_move\.py(\s|$)

# Directory creation (three fixed directories)
^mkdir\s+-p\s+docs/(tasks|plans|architectures)$

# Python testing (bare forms only)
^(python|python3)\s+-m\s+pytest$

# Node and Rust testing (bare forms only)
^npm\s+test$
^cargo\s+test$

# Framework scripts (each pattern ends at the script's name)
^python3\s+\.agent/skills/skill-session-state/scripts/update_state\.py(\s|$)
^python3\s+\.agent/tools/task_id_tool\.py(\s|$)
^python3\s+\.agent/tools/rebase_links\.py(\s|$)
^python3\s+\.agent/skills/skill-creator/scripts/(validate_skill|init_skill)\.py(\s|$)
^python3\s+\.agent/skills/artifact-formalizer/scripts/(scan_register|selftest_scan)\.py(\s|$)
^python3\s+\.agent/skills/artifact-formalizer/evals/(selftest_evals|grade_run)\.py(\s|$)
^python3\s+System/scripts/doctor\.py(\s|$)

Implementation Guidelines

For Agents (Runtime Behavior)

When calling run_command in ANY environment:

1. Check whether the command matches a pattern above. The table names the same commands; it approves no command that no pattern matches.
2. If match found → Set SafeToAutoRun: true.
3. If no match → Set SafeToAutoRun: false (require approval).

[!IMPORTANT] Symlink-following is the default for framework paths. When listing or searching .agent/, .agents/, .cursor/skills/, System/, or .agentic-development/, prefer the symlink-aware variants (ls -L, rg --follow, fd -L) — a plain ls/rg/fd silently skips symlinked directories. If a read-only probe returns nothing under a known framework directory, retry it once with symlink-following enabled before treating the path as empty or missing.

For Users (Configuration)

Note for Agents: Do NOT create configuration files (like .cursorrules or AGENTS.md) automatically. These are user-managed files.

Cursor Users:

• Add the patterns above to your .cursorrules or AGENTS.md file to enable auto-approval.

Antigravity Users:

• Add the command list below to "Allow List Terminal Commands" setting in IDE options: ls,cat,head,tail,grep,wc,stat,du,df,git status,python3 .agent/tools/archive_move.py
• Antigravity matches an entry as an exact word or token prefix, so ls does not admit lsof (antigravity.google/docs/permissions, read 2026-10-06). A chain or a pipeline of listed commands still matches, and so does a simple file redirect, which writes. A command or process substitution turns prefix matching off for the whole line.
• An entry cannot exclude an option, so the list names only commands with no option that writes or runs a program. rg, fd, mkdir and the test runners ask; from git, only git status is listed. The agent's SafeToAutoRun still rejects a redirect (Troubleshooting item 1). python3 .agent/tools/archive_move.py admits any operand as a prefix entry; the script refuses every operand but the two archive pairs. Its path is relative, like every framework-script pattern, so the agent runs it from the project root (WI-34).

Troubleshooting

If the IDE still requests approval for commands listed here:

1. Agent Behavior: Ensure the Agent is actually setting SafeToAutoRun: true in the tool call. If the Agent sets it to false, the IDE must ask for approval regardless of the Allow List.
2. Prefix Matching: Antigravity matches a word or token prefix. If git status runs unasked but a longer command asks, check whether the command carries a construct that turns prefix matching off, such as a command substitution. Do not shorten an entry to a bare command such as mv or git: it then admits every form of that command.

Integration

How Other Skills Should Reference This

Instead of duplicating Safe Commands lists, use:

## Safe Commands
See `skill-safe-commands` for the authoritative list of commands safe for auto-execution.

Required by

• skill-archive-task — archiving commands
• artifact-management — file operations
• developer-guidelines — test commands
• All agent prompts — general command execution