> ## Documentation Index
> Fetch the complete documentation index at: https://docs.augmentcode.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool Permissions

> Control what tools the agent can execute with granular permission settings for security and compliance. Honored by the Auggie CLI and by Cosmos cloud agents; not enforced in the Augment code extension.

export const Command = ({text}) => <span className="font-bold">{text}</span>;

export const Keyboard = ({shortcut}) => <span className="inline-block border border-gray-200 bg-gray-50 dark:border-white/10 dark:bg-gray-800 rounded-md text-xs text-gray font-bold px-1 py-0.5">
    {shortcut}
  </span>;

## 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:

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. **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](#webhook-validation)). |
| `script-policy`  | Delegate the decision to a local script (see [Script Validation](#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

```json theme={null}
{
  "toolPermissions": [
    { "toolName": "terminal", "permission": { "type": "deny" } },
    { "toolName": "read", "permission": { "type": "allow" } }
  ]
}
```

<Warning>
  `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.

  ```json theme={null}
  // ✅ Correct
  { "toolName": "terminal", "permission": { "type": "deny" } }

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

### Allow List Configuration

Create an explicit allow list by only allowing specific tools:

```json theme={null}
{
  "toolPermissions": [
    { "toolName": "read", "permission": { "type": "allow" } },
    { "toolName": "web-search", "permission": { "type": "allow" } },
    { "toolName": "web-fetch", "permission": { "type": "allow" } }
  ]
}
```

<Note>This configuration explicitly allows only the listed tools. Tools not in this list will follow the CLI's implicit behavior.</Note>

### Block List Configuration

Create a block list by explicitly denying specific dangerous tools:

```json theme={null}
{
  "toolPermissions": [
    { "toolName": "write", "permission": { "type": "deny" } },
    { "toolName": "edit", "permission": { "type": "deny" } },
    { "toolName": "terminal", "shellInputRegex": "^(rm|sudo|shutdown|reboot)", "permission": { "type": "deny" } }
  ]
}
```

<Note>This configuration blocks specific dangerous operations. Tools not explicitly denied will follow the CLI's implicit behavior.</Note>

### Mix and Match Configuration

Combine allow and deny rules for fine-grained control:

```json theme={null}
{
  "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. |

<Note>
  The shell is exposed as a single tool, **`terminal`**. One `terminal` rule gates all shell commands.
</Note>

### 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:

```json theme={null}
{
  "toolPermissions": [
    { "toolName": "terminal", "shellInputRegex": "^(ls|pwd|echo|cat|grep)\\s", "permission": { "type": "allow" } },
    { "toolName": "terminal", "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

### 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`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

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

### CI/CD Pipeline

Restrictive settings for automated workflows:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:**

```json theme={null}
{
  "text": "Tool output text",
  "isError": false
}
```

**Expected response:**

```json theme={null}
{
  "allow": true,
  "output": "Optional message to include in agent response"
}
```

### Script Validation

Use local scripts for complex validation logic:

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

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

```json theme={null}
{
  "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:**

```bash theme={null}
#!/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

1. **Be Explicit**: Define clear rules for all tools you want to control
2. **Test Configurations**: Verify permissions work as expected before automation
3. **Log Decisions**: Monitor which tools are being allowed/denied for audit trails
4. **Regular Reviews**: Periodically review and update permission rules
5. **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

## Related Features

* [Authentication](/cli/setup-auggie/authentication) - Secure access to Auggie
* [Custom Rules](/cli/rules) - Project-specific guidelines
* [MCP Integrations](/cli/integrations) - External tool configuration
* [Automation](/cli/automation) - Using permissions in CI/CD