​
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:
  1. Checks for matching rules in your configuration
  2. Applies the first matching rule based on tool name and optional patterns
  3. Rules are evaluated top-down - first match wins
  4. Prompts for approval when set to ask-user mode (interactive only)

​
Permission Flow

Tool Request → Check Rules → Apply Permission → Execute/Deny → Log Decision

​
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 through settings.json files with clear precedence:

​
File Locations

  1. User settings: ~/.augment/settings.json
    • Personal preferences that apply to all your projects
    • Ideal for your default security stance
  2. 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, or ask-user
  • Optional patterns - For shell commands, use regex matching

​
Basic Rule Structure

{
  "tool-permissions": {
    "rules": [
      {
        "tool-name": "launch-process",
        "permission": {
          "type": "deny"
        }
      },
      {
        "tool-name": "view",
        "permission": {
          "type": "allow"
        }
      }
    ]
  }
}

​
Allow List Configuration

Create an explicit allow list by only allowing specific tools: 
{
  "tool-permissions": {
    "rules": [
      {
        "tool-name": "view",
        "permission": { "type": "allow" }
      },
      {
        "tool-name": "codebase-retrieval",
        "permission": { "type": "allow" }
      },
      {
        "tool-name": "grep-search",
        "permission": { "type": "allow" }
      },
      {
        "tool-name": "github-api",
        "permission": { "type": "allow" }
      }
    ]
  }
}
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: 
{
  "tool-permissions": {
    "rules": [
      {
        "tool-name": "remove-files",
        "permission": { "type": "deny" }
      },
      {
        "tool-name": "kill-process",
        "permission": { "type": "deny" }
      },
      {
        "tool-name": "launch-process",
        "shell-input-regex": "^(rm|sudo|shutdown|reboot)",
        "permission": { "type": "deny" }
      }
    ]
  }
}
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: 
{
  "tool-permissions": {
    "rules": [
      // Always allow safe read operations
      {
        "tool-name": "view",
        "permission": { "type": "allow" }
      },
      {
        "tool-name": "codebase-retrieval",
        "permission": { "type": "allow" }
      },
      {
        "tool-name": "grep-search",
        "permission": { "type": "allow" }
      },

      // Require user approval for file modifications
      {
        "tool-name": "str-replace-editor",
        "permission": { "type": "ask-user" }
      },
      {
        "tool-name": "save-file",
        "permission": { "type": "ask-user" }
      },

      // Allow safe shell commands
      {
        "tool-name": "launch-process",
        "shell-input-regex": "^(npm test|npm run lint|git status|git diff)",
        "permission": { "type": "allow" }
      },

      // Deny dangerous shell commands
      {
        "tool-name": "launch-process",
        "shell-input-regex": "^(rm -rf|sudo|chmod 777)",
        "permission": { "type": "deny" }
      },

      // User approval for other shell commands
      {
        "tool-name": "launch-process",
        "permission": { "type": "ask-user" }
      },

      // Always deny file deletion
      {
        "tool-name": "remove-files",
        "permission": { "type": "deny" }
      }
    ]
  }
}
This configuration provides fine-grained control with different permission levels based on tool risk and usage patterns.

​
Available Tools

​
Process Management

ToolDescription
launch-processExecute shell commands and scripts
read-processRead output from running processes
write-processSend input to running processes
list-processesList all active processes
kill-processTerminate running processes

​
File Operations

ToolDescription
viewRead file contents
str-replace-editorEdit files with find/replace
save-fileCreate or overwrite files
remove-filesDelete files from the filesystem
codebase-retrievalSearch codebase with context engine
grep-searchSearch files with regex patterns

​
External Services

ToolDescription
github-apiGitHub API operations
linearLinear issue tracking
notionNotion workspace access
supabaseSupabase database operations
web-searchWeb search queries
web-fetchFetch 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: 
{
  "tool-permissions": {
    "rules": [
      {
        "tool-name": "launch-process",
        "shell-input-regex": "^(ls|pwd|echo|cat|grep)\\s",
        "permission": {
          "type": "allow"
        }
      },
      {
        "tool-name": "launch-process",
        "permission": {
          "type": "deny"
        }
      }
    ]
  }
}
This configuration:
  1. Allows only safe commands (ls, pwd, echo, cat, grep)
  2. Denies all other shell commands
  3. Rules are evaluated in order - first match wins

​
Event-Based Permissions

Control when permission checks occur: 
{
  "tool-permissions": {
    "rules": [
      {
        "tool-name": "github-api",
        "event-type": "tool-response",
        "permission": {
          "type": "allow"
        }
      }
    ]
  }
}
Event types:
  • tool-call (default) - Check before tool execution
  • tool-response - Check after execution but before returning results to agent

​
Interactive Approval

When using ask-user mode in interactive sessions, Auggie displays approval prompts: 
🔒 Tool Approval Required
─────────────────────────
Tool: launch-process
Command: npm install express

[A]llow once  [D]eny  [Always allow]  [Never allow]

​
Keyboard Shortcuts

KeyAction
AAllow this specific request
DDeny this specific request
YAlways allow this tool
NNever allow this tool
EscCancel 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: 
{
  "tool-permissions": {
    "rules": [
      { "tool-name": "view", "permission": { "type": "allow" } },
      { "tool-name": "codebase-retrieval", "permission": { "type": "allow" } },
      { "tool-name": "grep-search", "permission": { "type": "allow" } },
      { "tool-name": "web-search", "permission": { "type": "allow" } },
      { "tool-name": "web-fetch", "permission": { "type": "allow" } },
      { "tool-name": "str-replace-editor", "permission": { "type": "deny" } },
      { "tool-name": "save-file", "permission": { "type": "deny" } },
      { "tool-name": "remove-files", "permission": { "type": "deny" } },
      { "tool-name": "launch-process", "permission": { "type": "deny" } }
    ]
  }
}

​
Development Mode

Add safety guards for potentially dangerous operations: 
{
  "tool-permissions": {
    "rules": [
      { "tool-name": "remove-files", "permission": { "type": "ask-user" } },
      {
        "tool-name": "launch-process",
        "shell-input-regex": "^(rm|sudo|chmod)\\s",
        "permission": { "type": "ask-user" }
      }
    ]
  }
}

​
CI/CD Pipeline

Restrictive settings for automated workflows: 
{
  "tool-permissions": {
    "rules": [
      { "tool-name": "view", "permission": { "type": "allow" } },
      { "tool-name": "str-replace-editor", "permission": { "type": "allow" } },
      { "tool-name": "save-file", "permission": { "type": "allow" } },
      {
        "tool-name": "launch-process",
        "shell-input-regex": "^(npm test|npm run lint|jest)\\s",
        "permission": { "type": "allow" }
      },
      { "tool-name": "remove-files", "permission": { "type": "deny" } },
      { "tool-name": "launch-process", "permission": { "type": "deny" } }
    ]
  }
}

​
Custom Policies

​
Webhook Validation

Use external services to validate tool requests: 
{
  "tool-permissions": {
    "rules": [
      {
        "tool-name": "github-api",
        "permission": {
          "type": "webhook-policy",
          "webhook-url": "https://api.company.com/validate-tool"
        }
      }
    ]
  }
}
The webhook receives: 
{
  "tool-name": "github-api",
  "event-type": "tool-call",
  "details": { /* tool-specific data */ },
  "timestamp": "2025-01-01T02:41:40.580Z"
}
Expected response: 
{
  "allow": true,
  "output": "Optional message to include in agent response"
}

​
Script Validation

Use local scripts for complex validation logic: 
{
  "tool-permissions": {
    "rules": [
      {
        "tool-name": "launch-process",
        "permission": {
          "type": "script-policy",
          "script": "/path/to/validate-command.sh"
        }
      }
    ]
  }
}

​
Best Practices

  1. Be Explicit: Define clear rules for all tools you want to control
  2. Layer Settings: Use user settings for defaults, project settings for team rules
  3. Test Configurations: Verify permissions work as expected before automation
  4. Log Decisions: Monitor which tools are being allowed/denied for audit trails
  5. Regular Reviews: Periodically review and update permission rules
  6. Order Matters: Remember that rules are evaluated top-down, first match wins

​
Troubleshooting

Permissions Not Working:
  • Check file locations and ensure settings.json is valid JSON
  • Verify rule order - first matching rule wins
  • Use --augment-cache-dir to specify custom settings directory
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
MCP Tools Not Recognized:
  • 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