From 9355e281a08fd7d173e317a2a39778df7e7fc23d Mon Sep 17 00:00:00 2001 From: Michelle Tilley Date: Tue, 21 Apr 2026 23:00:25 -0700 Subject: fix: require all subcommands covered for shell allow rules (#3440) --- docs/docs/ai/images/tool_fs.png | Bin 0 -> 74298 bytes docs/docs/ai/images/tool_shell.png | Bin 0 -> 59603 bytes docs/docs/ai/tools-permissions.md | 100 +++++++++++++++++++++++++++++++++---- 3 files changed, 90 insertions(+), 10 deletions(-) create mode 100644 docs/docs/ai/images/tool_fs.png create mode 100644 docs/docs/ai/images/tool_shell.png (limited to 'docs') diff --git a/docs/docs/ai/images/tool_fs.png b/docs/docs/ai/images/tool_fs.png new file mode 100644 index 00000000..33b6033a Binary files /dev/null and b/docs/docs/ai/images/tool_fs.png differ diff --git a/docs/docs/ai/images/tool_shell.png b/docs/docs/ai/images/tool_shell.png new file mode 100644 index 00000000..1ccb962f Binary files /dev/null and b/docs/docs/ai/images/tool_shell.png differ diff --git a/docs/docs/ai/tools-permissions.md b/docs/docs/ai/tools-permissions.md index a8f16298..b9620b8e 100644 --- a/docs/docs/ai/tools-permissions.md +++ b/docs/docs/ai/tools-permissions.md @@ -2,12 +2,9 @@ Atuin AI has a number of tools that it can use to interact with your system, given your permission. The AI can use these tools to help answer questions and perform actions on your behalf. -!!! note "More tools coming soon" - We will be expanding the list of tools that Atuin AI can use over time. - ## Permission System -By default, Atuin AI asks your permission before using any client-side tool. You can change these defaults using a *permission file*. +By default, Atuin AI asks your permission before using any client-side tool. You can change these defaults using a _permission file_. ### Permission Files @@ -43,20 +40,17 @@ Most rules can be scoped to a particular path or other context. For example, you ### Example Config -Here's an example of a permission file that allows Atuin AI to read and write any markdown files in the current project, but denies it access to any `.env` files. Attempts to read or write any *other* files will result in Atuin AI requesting permission before proceeding. - -!!! note "Reading and writing files" - Atuin AI cannot currently read or write files; that capability is currently in development. +Here's an example of a permission file that allows Atuin AI to read and write any markdown files in the current project (because Write implies Read — see below), but denies it access to any `.env` files. Attempts to read or write any _other_ files will result in Atuin AI requesting permission before proceeding. ```toml [permissions] allow = [ - "Read(**/*.md)", "Write(**/*.md)" + "Write(**/*.md)" ] deny = [ - "Read(.env)", "Write(.env)" + "Read(.env)" ] ``` @@ -79,3 +73,89 @@ The `AtuinHistory` tool allows Atuin AI to search your Atuin history for relevan allow = ["AtuinHistory"] ``` + +### Read + +The `Read` tool allows Atuin AI to read files on your system. Atuin AI might ask to use this tool when you ask it to analyze the contents of a file, when you ask for edits to the contents of a file, or when you ask a question that is most easily answered by consulting the contents of a file. + +![Example of Atuin FS Tools](../images/tool_fs.png) + +**Permission rule and scope:** `Read()` (e.g. `Read(**/\*.md)`to allow reading all markdown files in the current directory and subdirectories). A missing glob pattern (e.g.`Read`) matches all files. + +**Config value:** `ai.capabilities.enable_fs_tools` (see [settings documentation](./settings.md#capabilities)) — this setting enables both the `Read` and `Write` tools. + +**Example permissions file:** + +```toml +[permissions] +allow = ["Read(**/*.md)"] +deny = ["Read(.secret/**)"] +``` + +!!! warning "Write Implies Read" + + To prevent accidental data loss, Atuin AI is required to read the contents of a file before writing to it. This means that any permission rule that allows the `Write` tool for a particular file or set of files will also automatically allow the `Read` tool for those same files. For example, if you have a rule that allows `Write(**/*.md)`, Atuin AI will also be able to read any markdown files in the current directory and subdirectories, even if you don't have an explicit rule allowing `Read(**/*.md)`. + +### Write + +The `Write` tool allows Atuin AI to create and edit files on your system. Atuin AI might ask to use this tool when you ask it to update configuration for a tool or help debug a problem. + +![Example of Atuin FS Tools](../images/tool_fs.png) + +**Permission rule and scope:** `Write()` (e.g. `Write(**/\*.md)`to allow reading all markdown files in the current directory and subdirectories). A missing glob pattern (e.g.`Write`) matches all files. + +**Config value:** `ai.capabilities.enable_fs_tools` (see [settings documentation](./settings.md#capabilities)) — this setting enables both the `Read` and `Write` tools. + +**Example permissions file:** + +```toml +[permissions] +allow = ["Write(**/*.md)"] +deny = ["Write(.secret/**)"] +``` + +!!! note "File Backups" + + The first time Atuin AI writes to a file in a session, it creates a backup of the original file and stores it in Atuin's data directory, under `ai/sessions/`. A manifest file in that directory maps the original file paths to the backup file paths. In the future, we'll be providing easier ways to recover from accidental data loss. + +### Shell Command Execution + +The `Shell` tool allows Atuin AI to execute shell commands on your system. Atuin AI might ask to use this tool when you ask it to perform an action that is most easily accomplished by running a shell command itself, or when you ask for help debugging a failing command, or during a multi-step workflow. + +![Example of Atuin Shell Tool](../images/tool_shell.png) + +**Permission rule and scope:** `Shell()` (e.g. `Shell(git *)` to allow any command that starts with `git`). A missing command pattern (e.g. `Shell`) matches all commands. + +**Config value:** `ai.capabilities.enable_command_execution` (see [settings documentation](./settings.md#capabilities)) + +**Example permissions file:** + +```toml +[permissions] +allow = [ + "Shell(git add *)", + "Shell(git commit *)" +] +``` + +!!! note "Command Execution Scope" + + The command pattern in a `Shell` permission rule is matched against the words in the command. The `*` wildcard has different behavior depending on where it appears: + + | Pattern | Matches | Does Not Match | + |---------|---------|----------------| + | `*` | Any command | — | + | `git commit *` | `git commit`, `git commit -m "msg"` | `git`, `git push` | + | `ls*` | `ls`, `ls -a`, `lsof` | `cat` | + | `git * --amend` | `git commit --amend`, `git rebase --amend` | `git commit` | + | `git commit` | `git commit` | `git`, `git push`, `git commit -m "msg"` | + + Note the difference between `ls *` (with a space) and `ls*` (without). The space-separated form uses **word-boundary** matching — `ls *` matches `ls` and `ls -a` but _not_ `lsof`. The attached form uses **prefix** matching — `ls*` matches all of those, including `lsof`. + + For `allow` and `ask` rules, a pattern without any wildcard (e.g. `git commit`) is an **exact match** — it only matches when the command words are identical. Use `git commit *` if you want to allow `git commit` with any arguments. + + For `deny` rules, a pattern without any wildcard (e.g. `rm`) is a **prefix match** — it matches any command that starts with that prefix. This means that a `deny` rule of `rm` would deny `rm`, `rm -rf /`, and `rm ./README.md` so be careful when writing `deny` rules without explicit wildcards. + +!!! warning "Compound Commands" + + When the AI runs a compound command (e.g. `git add . && npm test`), Atuin parses it into individual subcommands. For a command to be automatically allowed, all subcommands must be allowed. This means that `git add . && npm test` must be enabled by both `Shell(git add *)` and `Shell(npm test)` for it to be allowed, else it would fall through and ask for permission. However, our parsing is not perfect, and there may be edge cases where it fails to correctly identify the subcommands, and some shells where command parsing is sub-par. For this reason, we recommend being cautious when allowing compound commands with broad patterns. -- cgit v1.3.1