From ff28eb0c682f531d9f54fe7a20b8edba00c8ff8f Mon Sep 17 00:00:00 2001 From: OpeOginni Date: Tue, 27 Jan 2026 16:33:47 +0100 Subject: [PATCH 1/2] chore(docs): Better explanation on how to allow tools in external directories --- packages/web/src/content/docs/permissions.mdx | 39 ++++++++++++++++++- 1 file changed, 38 insertions(+), 1 deletion(-) diff --git a/packages/web/src/content/docs/permissions.mdx b/packages/web/src/content/docs/permissions.mdx index 229cb264e645..05b89e58a625 100644 --- a/packages/web/src/content/docs/permissions.mdx +++ b/packages/web/src/content/docs/permissions.mdx @@ -80,12 +80,49 @@ Permission patterns use simple wildcard matching: ### Home Directory Expansion -You can use `~` or `$HOME` at the start of a pattern to reference your home directory. This is particularly useful for `external_directory` rules. +You can use `~` or `$HOME` at the start of a pattern to reference your home directory. This is particularly useful for [`external_directory`](#external-directories) rules. - `~/projects/*` -> `/Users/username/projects/*` - `$HOME/projects/*` -> `/Users/username/projects/*` - `~` -> `/Users/username` +### External Directories + +Use `external_directory` to allow tool calls that touch paths outside the working directory where OpenCode was started. This applies to any tool that takes a path as input (for example `read`, `edit`, `list`, `glob`, `grep`, and many `bash` commands). + +Home expansion (like `~/...`) only affects how a pattern is written. It does not make an external path part of the current workspace, so paths outside the working directory must still be allowed via `external_directory`. + +For example, this allows access to everything under `~/projects/personal/`: + +```json title="opencode.json" +{ + "$schema": "https://opencode.ai/config.json", + "permission": { + "external_directory": { + "~/projects/personal/**": "allow" + } + } +} +``` + +Any directory allowed here inherits the same defaults as the current workspace. Since `read` defaults to `allow`, reads are also allowed for entries under `external_directory` unless overridden. Add explicit rules when a tool should be restricted in these paths, such as blocking edits while keeping reads: + +```json title="opencode.json" +{ + "$schema": "https://opencode.ai/config.json", + "permission": { + "external_directory": { + "~/projects/personal/**": "allow" + }, + "edit": { + "~/projects/personal/**": "deny" + } + } +} +``` + +Keep the list focused on trusted paths, and layer extra allow or deny rules as needed for other tools (for example `bash`). + --- ## Available Permissions From 7d29837376822d494043cf4e863e2dcdaeb6d9fa Mon Sep 17 00:00:00 2001 From: OpeOginni Date: Tue, 27 Jan 2026 16:37:35 +0100 Subject: [PATCH 2/2] chore(docs): Direct text about read defaults tot he defaults section --- packages/web/src/content/docs/permissions.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/web/src/content/docs/permissions.mdx b/packages/web/src/content/docs/permissions.mdx index 05b89e58a625..d48c2a084b44 100644 --- a/packages/web/src/content/docs/permissions.mdx +++ b/packages/web/src/content/docs/permissions.mdx @@ -105,7 +105,7 @@ For example, this allows access to everything under `~/projects/personal/`: } ``` -Any directory allowed here inherits the same defaults as the current workspace. Since `read` defaults to `allow`, reads are also allowed for entries under `external_directory` unless overridden. Add explicit rules when a tool should be restricted in these paths, such as blocking edits while keeping reads: +Any directory allowed here inherits the same defaults as the current workspace. Since [`read` defaults to `allow`](#defaults), reads are also allowed for entries under `external_directory` unless overridden. Add explicit rules when a tool should be restricted in these paths, such as blocking edits while keeping reads: ```json title="opencode.json" {