diff --git a/AGENTS.md b/AGENTS.md index c8b6397..34dd41f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -50,7 +50,7 @@ The config file lives at `~/.bwai.json`. Key fields: | `home_block` | Dotfiles/paths to explicitly block | | `env_allow` | Environment variables to pass through | -`home_allow` takes precedence over `home_block`. Patterns support glob suffixes (e.g., `.bash_history*`) and nested paths (e.g., `.config/goose`). +`home_block` takes precedence over `home_allow` at the same nesting level. However, the two can be combined at different levels: a `home_block` entry hides a sub-path inside an otherwise allowed directory (e.g. `home_allow: [".cache"]` + `home_block: [".cache/sccache"]` hides `.cache/sccache`), and a `home_allow` entry re-exposes a sub-path inside an otherwise blocked directory (e.g. `home_block: [".cache"]` + `home_allow: [".cache/sccache"]` exposes only `.cache/sccache`). Patterns support glob suffixes (e.g., `.bash_history*`) and nested paths (e.g., `.config/goose`). ## Key Design Decisions diff --git a/README.md b/README.md index 0857c84..baf6849 100644 --- a/README.md +++ b/README.md @@ -108,5 +108,10 @@ The available fields are: | `bwrap_extra_args` | Extra arguments forwarded to `bwrap` (e.g. `--unshare-net`). Each element is split on whitespace, so `"--ro-bind /var /var"` and `"--ro-bind", "/var", "/var"` are equivalent | | `command` | Command (and args) to run inside the sandbox | | `home_allow` | Dotfiles/dirs in `$HOME` the agent may read and write | -| `home_block` | Dotfiles/dirs in `$HOME` that are never exposed (`home_allow` takes precedence) | +| `home_block` | Dotfiles/dirs in `$HOME` that are never exposed | | `env_allow` | Environment variables from the host passed into the sandbox | + +`home_block` takes precedence over `home_allow` at the same nesting level. However, the two can be combined at different nesting levels to achieve more granular control: + +- **Block a sub-path inside an allowed directory** — `home_allow: [".cache"]` + `home_block: [".cache/sccache"]` exposes `.cache` (read-write) but hides `.cache/sccache` inside it. +- **Re-expose a sub-path inside a blocked directory** — `home_block: [".cache"]` + `home_allow: [".cache/sccache"]` hides everything in `.cache` except `.cache/sccache`, which is available read-write.