About Tool Permissions
Auggie CLIs tool permission system provides fine-grained control over what actions the agent can perform in your environment. This security layer ensures that Auggie only executes approved operations, protecting your codebase and system from unintended changes. Tool permissions are especially important when:- Running Auggie in production environments
- Working with sensitive codebases
- Enforcing organizational security policies
- Using Auggie in automated workflows
How Permissions Work
When Auggie attempts to use a tool, the permission system:- Checks for matching rules in your configuration
- Applies the first matching rule based on tool name and optional patterns
- Rules are evaluated top-down - first match wins
- Prompts for approval when set to ask-user mode (interactive only)
Permission Flow
Notes on Unmatched Tools
- Rules are evaluated in order from top to bottom
- The first matching rule determines the permission
- If no rules match, the CLI follows its implicit runtime behavior
- Configure explicit rules for all tools you want to control
Configuration Files
Tool permissions are configured throughsettings.json
files with clear precedence:
File Locations
-
User settings:
~/.augment/settings.json
- Personal preferences that apply to all your projects
- Ideal for your default security stance
-
Project settings:
<workspace>/.augment/settings.json
- Repository-specific rules shared with your team
- Perfect for project-specific security requirements
Settings are merged with later files taking precedence. Project settings override user settings.
Basic Configuration
Creating Rules
Rules define permissions for specific tools. Each rule can specify:- Tool name - The specific tool to control
- Permission type -
allow
,deny
, orask-user
- Optional patterns - For shell commands, use regex matching
Basic Rule Structure
Allow List Configuration
Create an explicit allow list by only allowing specific tools:This configuration explicitly allows only the listed tools. Tools not in this list will follow the CLI’s implicit behavior.
Block List Configuration
Create a block list by explicitly denying specific dangerous tools:This configuration blocks specific dangerous operations. Tools not explicitly denied will follow the CLI’s implicit behavior.
Mix and Match Configuration
Combine allow, deny, and ask-user rules for fine-grained control:Available Tools
Process Management
Tool | Description |
---|---|
launch-process | Execute shell commands and scripts |
read-process | Read output from running processes |
write-process | Send input to running processes |
list-processes | List all active processes |
kill-process | Terminate running processes |
File Operations
Tool | Description |
---|---|
view | Read file contents |
str-replace-editor | Edit files with find/replace |
save-file | Create or overwrite files |
remove-files | Delete files from the filesystem |
codebase-retrieval | Search codebase with context engine |
grep-search | Search files with regex patterns |
External Services
Tool | Description |
---|---|
github-api | GitHub API operations |
linear | Linear issue tracking |
notion | Notion workspace access |
supabase | Supabase database operations |
web-search | Web search queries |
web-fetch | Fetch web page content |
MCP Server Tools
MCP tools follow the pattern{tool-name}_{server-name}
:
- Example:
query_database-mcp
- Truncated to 64 characters if longer
- Treated like any other tool for permissions
Advanced Rules
Shell Command Filtering
Control which shell commands can be executed using regex patterns:- Allows only safe commands (ls, pwd, echo, cat, grep)
- Denies all other shell commands
- Rules are evaluated in order - first match wins
Event-Based Permissions
Control when permission checks occur:tool-call
(default) - Check before tool executiontool-response
- Check after execution but before returning results to agent
Interactive Approval
When usingask-user
mode in interactive sessions, Auggie displays approval prompts:
Keyboard Shortcuts
Key | Action |
---|---|
A | Allow this specific request |
D | Deny this specific request |
Y | Always allow this tool |
N | Never allow this tool |
Esc | Cancel and deny request |
In non-interactive mode (—print), ask-user permissions default to deny for security.
Common Configurations
Read-Only Mode
Allow only read operations, perfect for code review and analysis:Development Mode
Add safety guards for potentially dangerous operations:CI/CD Pipeline
Restrictive settings for automated workflows:Custom Policies
Webhook Validation
Use external services to validate tool requests:Script Validation
Use local scripts for complex validation logic:Best Practices
- Be Explicit: Define clear rules for all tools you want to control
- Layer Settings: Use user settings for defaults, project settings for team rules
- Test Configurations: Verify permissions work as expected before automation
- Log Decisions: Monitor which tools are being allowed/denied for audit trails
- Regular Reviews: Periodically review and update permission rules
- Order Matters: Remember that rules are evaluated top-down, first match wins
Troubleshooting
Ask-User Mode in Automation:- Ask-user permissions automatically deny in non-interactive mode
- Use explicit allow/deny rules for automation scenarios
- Consider webhook or script policies for dynamic decisions
- Ensure MCP server name follows
{tool}_{server}
pattern - Check for 64-character truncation on long names
- Verify MCP server is properly configured and running
Security Considerations
- Never commit sensitive webhook URLs to version control
- Use
.augment/settings.local.json
for personal security overrides - Regularly audit tool usage in production environments
- Implement defense in depth with multiple permission layers
- Test permission changes in isolated environments first
Related Features
- Authentication - Secure access to Auggie
- Custom Rules - Project-specific guidelines
- MCP Integrations - External tool configuration
- Automation - Using permissions in CI/CD