Tool Permissions

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

Where Permissions Are Enforced

toolPermissions is honored by the Auggie CLI and by Cosmos cloud agents. Rules are loaded at agent startup from the settings files below and applied to every tool call, so the same configuration behaves identically in either place.

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
Executes or denies the tool call based on the matched rule

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

Permission Types and Precedence

There are four permission types:

Type	Effect
`allow`	Permit the tool call.
`deny`	Block the tool call.
`webhook-policy`	Delegate the decision to an external HTTP endpoint (see Webhook Validation).
`script-policy`	Delegate the decision to a local script (see Script Validation).

Precedence

Rules can come from more than one source — the settings files and the --permission CLI flag each form a policy:

Within a single policy, the first matching rule wins (top-down).
Across policies, the most restrictive matching permission wins, in this order (most to least restrictive): deny > webhook-policy > script-policy > allow

So if the settings file allows a tool but a --permission rule denies it, the tool is denied. This most-restrictive-wins resolution means a stricter policy can never be overridden by a more permissive one.

The `--permission` CLI Flag

The --permission flag lets you supply rules on the command line. These rules form a separate policy that is combined with the settings-file rules using the most-restrictive-wins resolution above, so a --permission deny always takes effect even if the settings files would allow the tool.

Configuration Files

Tool permissions are configured in settings.json. Both the Auggie CLI and Cosmos cloud agents read from two locations:

File	Scope
`~/.augment/settings.json`	Personal settings that apply to all your projects (user/home).
`.augment/settings.json`	Repo-level settings committed to the project, applied to any agent running in that repo.

Cosmos cloud agents read both files at agent startup. Committing a .augment/settings.json to your repository is the recommended way to enforce an organizational policy (for example, blocking git merge) on every cloud agent that runs there.

Basic Configuration

Creating Rules

Rules define permissions for specific tools. Each rule can specify:

Tool name - The specific tool to control
Permission type - allow or deny
Optional patterns - For shell commands, use regex matching

Basic Rule Structure

{
  "toolPermissions": [
    { "toolName": "terminal", "permission": { "type": "deny" } },
    { "toolName": "read", "permission": { "type": "allow" } }
  ]
}

permission must be an object with a type field — { "type": "deny" }, not the bare string "deny". A rule with a bare-string permission is malformed and is dropped. As of the latest version, a dropped rule also emits a warning at startup so the misconfiguration is visible instead of failing silently.

// ✅ Correct
{ "toolName": "terminal", "permission": { "type": "deny" } }

// ❌ Wrong — dropped (and warned) at load time
{ "toolName": "terminal", "permission": "deny" }

Allow List Configuration

Create an explicit allow list by only allowing specific tools:

{
  "toolPermissions": [
    { "toolName": "read", "permission": { "type": "allow" } },
    { "toolName": "web-search", "permission": { "type": "allow" } },
    { "toolName": "web-fetch", "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:

{
  "toolPermissions": [
    { "toolName": "write", "permission": { "type": "deny" } },
    { "toolName": "edit", "permission": { "type": "deny" } },
    { "toolName": "terminal", "shellInputRegex": "^(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 and deny rules for fine-grained control:

{
  "toolPermissions": [
    { "toolName": "read", "permission": { "type": "allow" } },

    { "toolName": "edit", "permission": { "type": "allow" } },
    { "toolName": "write", "permission": { "type": "deny" } },

    { "toolName": "terminal", "shellInputRegex": "^(npm test|npm run lint|git status|git diff)", "permission": { "type": "allow" } },
    { "toolName": "terminal", "shellInputRegex": "^(rm -rf|sudo|chmod 777)", "permission": { "type": "deny" } },
    { "toolName": "terminal", "permission": { "type": "deny" } }
  ]
}

This configuration provides fine-grained control with different permission levels based on tool risk and usage patterns.

Available Tools

Shell

Tool	Description
`terminal`	Execute shell commands in a re-entrant session. Takes a `command` input and is matched by `shellInputRegex` against that command.

The shell is exposed as a single tool, terminal. One terminal rule gates all shell commands.

File Operations

Tool	Description
`read`	Read file contents
`edit`	Edit files with find/replace
`write`	Create or overwrite files

Web

Tool	Description
`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

Migrating from legacy tool names

Older configurations may use legacy tool names. They still work — the legacy names are aliased to their current equivalents — but use the current names below.

Legacy name	Current name	Description
`launch-process`	`terminal`	Execute shell commands
`view`	`read`	Read file contents
`str-replace-editor`	`edit`	Edit files with find/replace
`save-file`	`write`	Create or overwrite files

Advanced Rules

Shell Command Filtering

Control which shell commands can be executed using regex patterns:

{
  "toolPermissions": [
    { "toolName": "terminal", "shellInputRegex": "^(ls|pwd|echo|cat|grep)\\s", "permission": { "type": "allow" } },
    { "toolName": "terminal", "permission": { "type": "deny" } }
  ]
}

This configuration:

Allows only safe commands (ls, pwd, echo, cat, grep)
Denies all other shell commands
Rules are evaluated in order - first match wins

Blocking a Specific Command (e.g. `git merge`)

To hard-block a single command such as git merge — a common enterprise policy for Cosmos cloud agents — deny it on the terminal tool with a shellInputRegex:

{
  "toolPermissions": [
    { "toolName": "terminal", "shellInputRegex": "\\bgit\\s+merge(\\s|$)", "permission": { "type": "deny" } }
  ]
}

Commit this to .augment/settings.json in the repository to enforce it on every Cosmos cloud agent that runs there. The trailing (\s|$) ensures only the git merge subcommand is matched and not related subcommands like git merge-base: a plain \bgit\s+merge\b would still match git merge-base, because - is a non-word character and \b is satisfied at the merge/- boundary. Requiring whitespace or end-of-input after merge blocks git merge and git merge main while leaving git merge-base allowed.

Event-Based Permissions

Control when permission checks occur:

{
  "toolPermissions": [
    { "toolName": "web-fetch", "eventType": "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

Common Configurations

Read-Only Mode

Allow only read operations, perfect for code review and analysis:

{
  "toolPermissions": [
    { "toolName": "read", "permission": { "type": "allow" } },
    { "toolName": "web-search", "permission": { "type": "allow" } },
    { "toolName": "web-fetch", "permission": { "type": "allow" } },
    { "toolName": "edit", "permission": { "type": "deny" } },
    { "toolName": "write", "permission": { "type": "deny" } },
    { "toolName": "terminal", "permission": { "type": "deny" } }
  ]
}

Development Mode

Deny potentially dangerous operations while allowing the rest:

{
  "toolPermissions": [
    {
      "toolName": "terminal",
      "shellInputRegex": "^(rm|sudo|chmod)\\s",
      "permission": { "type": "deny" }
    }
  ]
}

CI/CD Pipeline

Restrictive settings for automated workflows:

{
  "toolPermissions": [
    { "toolName": "read", "permission": { "type": "allow" } },
    { "toolName": "edit", "permission": { "type": "allow" } },
    { "toolName": "write", "permission": { "type": "allow" } },
    {
      "toolName": "terminal",
      "shellInputRegex": "^(npm test|npm run lint|jest)\\s",
      "permission": { "type": "allow" }
    },
    { "toolName": "terminal", "permission": { "type": "deny" } }
  ]
}

Custom Policies

Webhook Validation

Use external services to validate tool requests:

{
  "toolPermissions": [
    { "toolName": "terminal", "permission": { "type": "webhook-policy", "webhookUrl": "https://api.company.com/validate-tool" } }
  ]
}

The webhook receives a POST request with the following JSON payload:

{
  "tool-name": "terminal",
  "event-type": "tool-call",
  "details": { /* tool-specific data, see below */ },
  "timestamp": "2025-01-01T02:41:40.580Z"
}

Payload fields:

tool-name: The name of the tool being invoked
event-type: Either "tool-call" (before execution) or "tool-response" (after execution)
details: Tool-specific data (for tool-call) or response data (for tool-response)
timestamp: ISO 8601 timestamp of the request

Details for tool-call event type (varies by tool):

Tool	Details Fields
`terminal`	`cwd`, `command`
`read`	`path`
`edit`	`path`, `command`
`write`	`path`
`web-fetch`	`url`

Details for tool-response event type:

{
  "text": "Tool output text",
  "isError": false
}

Expected response:

{
  "allow": true,
  "output": "Optional message to include in agent response"
}

Script Validation

Use local scripts for complex validation logic:

{
  "toolPermissions": [
    { "toolName": "terminal", "permission": { "type": "script-policy", "script": "/path/to/validate-command.sh" } }
  ]
}

The script receives the same JSON payload as webhooks via stdin:

{
  "tool-name": "terminal",
  "event-type": "tool-call",
  "details": {
    "cwd": "/path/to/workspace",
    "command": "npm install express"
  },
  "timestamp": "2025-01-01T02:41:40.580Z"
}

Script behavior:

Exit code 0: Allow the tool execution
Non-zero exit code: Deny the tool execution
stdout/stderr: Optional message included in the agent response

Example script:

#!/bin/bash
# Read JSON payload from stdin
payload=$(cat)

# Extract command using jq
command=$(echo "$payload" | jq -r '.details.command // empty')

# Deny dangerous commands
if [[ "$command" == *"rm -rf"* ]] || [[ "$command" == *"sudo"* ]]; then
  echo "Dangerous command blocked: $command"
  exit 1
fi

# Allow all other commands
exit 0

Best Practices

Be Explicit: Define clear rules for all tools you want to control
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

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

Authentication - Secure access to Auggie
Custom Rules - Project-specific guidelines
MCP Integrations - External tool configuration
Automation - Using permissions in CI/CD

​About Tool Permissions

​Where Permissions Are Enforced

​How Permissions Work

​Permission Flow

​Notes on Unmatched Tools

​Permission Types and Precedence

​Precedence

​The --permission CLI Flag

​Configuration Files

​Basic Configuration

​Creating Rules

​Basic Rule Structure

​Allow List Configuration

​Block List Configuration

​Mix and Match Configuration

​Available Tools

​Shell

​File Operations

​Web

​MCP Server Tools

​Migrating from legacy tool names

​Advanced Rules

​Shell Command Filtering

​Blocking a Specific Command (e.g. git merge)

​Event-Based Permissions

​Common Configurations

​Read-Only Mode

​Development Mode

​CI/CD Pipeline

​Custom Policies

​Webhook Validation

​Script Validation

​Best Practices

​Troubleshooting

​Security Considerations

​Related Features

About Tool Permissions

Where Permissions Are Enforced

How Permissions Work

Permission Flow

Notes on Unmatched Tools

Permission Types and Precedence

Precedence

The `--permission` CLI Flag

Configuration Files

Basic Configuration

Creating Rules

Basic Rule Structure

Allow List Configuration

Block List Configuration

Mix and Match Configuration

Available Tools

Shell

File Operations

Web

MCP Server Tools

Migrating from legacy tool names

Advanced Rules

Shell Command Filtering

Blocking a Specific Command (e.g. `git merge`)

Event-Based Permissions

Common Configurations

Read-Only Mode

Development Mode

CI/CD Pipeline

Custom Policies

Webhook Validation

Script Validation

Best Practices

Troubleshooting

Security Considerations

Related Features