# Permissions

> Understand what Raw tools can access, how the working directory relates to security, and how allow, ask and deny rules and approvals work.

Raw runs model-requested tools on your machine, with the permissions of your operating system account. Tool rules let you add prompts or block specific calls, but they are not a security sandbox.

> **Tools run with your full account permissions:**
>
> In terminal, headless, dashboard and ACP modes, Raw runs tool calls automatically. The `bash` tool runs any shell command your account can run. `read_file` and `write_file` can access any file your account can read or write, including files outside the project. Hooks and MCP servers you select run with the same permissions. Use Raw on code you trust, or run it in an environment you can discard, such as a container, a virtual machine, or a separate user account.

## What the working directory does

The working directory (`cwd`) is where Raw starts a session. It is used to resolve relative paths and as the directory where Bash commands start. It does not restrict what a tool can reach. An absolute path, a `..` segment, or a command such as `cd /` moves outside it.

## How tool rules work

Each agent can set an ordered list of rules in `tools.rules`. A rule matches a tool identity and applies one of three effects:

| Effect  | What happens                                                                         |
| ------- | ------------------------------------------------------------------------------------ |
| `allow` | The call runs. This is the default when no rule matches.                             |
| `ask`   | Raw stops and asks you to approve or deny this call before it runs.                  |
| `deny`  | The tool is hidden from the model, and any call to it returns a `tool_denied` error. |

Rules are checked in order, and the last matching rule wins. A rule matches tool identities such as `builtin/bash`, `local/my_tool`, `mcp/search/web_search` or `acp:name`. A pattern can use a wildcard, such as `mcp/unsafe/*`.

```json
{
  "tools": {
    "use": ["builtin/read_file", "builtin/bash", "local/my_tool"],
    "rules": [
      { "match": "local/my_tool", "effect": "deny" }
    ]
  }
}
```

### Conditional ask rules

Only an `ask` rule can add a `when` condition. The condition inspects selected string arguments with a regular expression. For Bash, `commands[*].command` contains each command in the batch. If any command matches, Raw asks once, before the batch starts.

This rule asks before commands that call `rm`:

```json
{
  "tools": {
    "use": ["builtin/read_file", "builtin/bash"],
    "rules": [{
      "match": "builtin/bash",
      "effect": "ask",
      "when": {
        "source": "arguments",
        "any": "commands[*].command",
        "regex": "(^|[;&|()\\n])\\s*(sudo\\s+)?(/usr/bin/|/bin/)?rm(\\s|$)"
      }
    }]
  }
}
```

A text pattern matches the command text, not its effect. A script, an interpreter or an alias can delete files without matching the pattern. Treat a rule as a guardrail, not a guarantee.

## Approvals

When an `ask` rule matches, the approval request shows the tool name and the complete arguments.

- **Terminal.** Raw prompts in the REPL or one-shot terminal. Answer to allow or deny this call.
- **Dashboard.** The chat shows the request inline with **Allow once** and **Deny** buttons. The answer applies only to that pending call.
- **ACP.** The client supplies the permission channel.

If you deny a call, the model receives an `approval_denied` error and can continue with another approach.

If no approval channel is available, such as a non-interactive run with no ACP client, an `ask` call does not run. The model receives an `approval_required` error.

### The `-y` flag

`-y` (or `--auto-approve`) is a compatibility alias. Tools already run automatically without it. The flag does not override an explicit `ask` rule, and it does not change a `deny` rule.

## Hooks as an extra gate

A `PreToolUse` hook runs before a tool call and can block it. Use one for checks that a rule cannot express, such as validating a path against your own list. See [Hooks](https://raw.tlelabs.com/docs/extend/hooks/).

## Practical guidance

- Start with a narrow tool list. Select `builtin/read_file` alone for read-only review, and add `builtin/bash` or `builtin/write_file` only when a task needs them.
- Add `ask` rules for commands you want to see before they run, such as deletions, network calls or installs.
- Use a separate agent with fewer tools for untrusted or exploratory work.
- Review `raw config list` after editing an agent to confirm the selected tools and rules.