Skip to content

Commit e5beb92

Browse files
hkaltaiclaude
andcommitted
docs(permission): put wildcard rules first in examples and describe outside symlinks accurately
Permission rules are last-match-wins and config keeps key order, so a "*" rule listed after a specific pattern overrode it: "dbt run *": "deny" followed by "*": "ask" still let dbt run through after approval. Every example now lists "*" first, and the permissions page says so. The security FAQ example restricting analyst's shell now uses builder, since analyst's shell is always denied, and the symlink bullet says outside symlinks go through the external_directory check rather than being blocked. The permissions page names the training tools analyst keeps. The analyst registry test now checks tools through LLM.removedTools, the helper that removes tools from each model request. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 6cbc8c4 commit e5beb92

5 files changed

Lines changed: 25 additions & 17 deletions

File tree

‎docs/docs/configure/agents.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -67,8 +67,8 @@ Define custom agents in `altimate-code.json`:
6767
"write": "deny",
6868
"edit": "deny",
6969
"bash": {
70-
"dbt docs generate": "allow",
71-
"*": "deny"
70+
"*": "deny",
71+
"dbt docs generate": "allow"
7272
}
7373
}
7474
}

‎docs/docs/configure/permissions.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -70,17 +70,19 @@ Override permissions for specific agents:
7070
"write": "deny",
7171
"edit": "deny",
7272
"bash": {
73+
"*": "deny",
7374
"SELECT *": "allow",
74-
"dbt docs *": "allow",
75-
"*": "deny"
75+
"dbt docs *": "allow"
7676
}
7777
}
7878
}
7979
}
8080
}
8181
```
8282

83-
The `analyst` agent is read-only regardless of config: its shell and write tools (file edits, SQL writes, memory saves and other built-in write tools) stay denied even if its permission config allows them. Config can still restrict analyst further.
83+
The `analyst` agent is read-only regardless of config: its shell and write tools (file edits, SQL writes, memory saves and other built-in write tools) stay denied even if its permission config allows them. Training entries remain available through `training_save` and `training_remove`. Config can still restrict analyst further.
84+
85+
Rules are evaluated in order and the last matching rule wins, so put a `"*"` rule before the more specific patterns it should not override.
8486

8587
## All Permissioned Tools
8688

‎docs/docs/configure/tools.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,9 @@ Control which tools agents can use via the [permission system](permissions.md):
3838
{
3939
"permission": {
4040
"bash": {
41+
"*": "ask",
4142
"dbt *": "allow",
42-
"rm *": "deny",
43-
"*": "ask"
43+
"rm *": "deny"
4444
},
4545
"write": "ask",
4646
"read": "allow"
@@ -63,8 +63,8 @@ Disable a tool for a specific agent by setting its permission to `"deny"`:
6363
"write": "deny",
6464
"edit": "deny",
6565
"bash": {
66-
"dbt run *": "deny",
67-
"*": "ask"
66+
"*": "ask",
67+
"dbt run *": "deny"
6868
}
6969
}
7070
}
@@ -85,11 +85,11 @@ The `bash` tool executes shell commands in the project directory. Commands run i
8585
{
8686
"permission": {
8787
"bash": {
88+
"*": "ask",
8889
"dbt *": "allow",
8990
"git *": "allow",
9091
"python *": "allow",
91-
"rm -rf *": "deny",
92-
"*": "ask"
92+
"rm -rf *": "deny"
9393
}
9494
}
9595
}

‎docs/docs/reference/security-faq.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -96,18 +96,18 @@ Yes. Use pattern-based permissions to deny destructive SQL:
9696
}
9797
```
9898

99-
You can also configure per-agent permissions. For example, restrict the `analyst` agent to read-only:
99+
You can also configure per-agent permissions. For example, keep the `builder` agent from editing files and allow only `SELECT` shell commands. The `analyst` agent is already read-only: its shell and write tools stay denied whatever its config says.
100100

101101
```json
102102
{
103103
"agent": {
104-
"analyst": {
104+
"builder": {
105105
"permission": {
106106
"write": "deny",
107107
"edit": "deny",
108108
"bash": {
109-
"SELECT *": "allow",
110-
"*": "deny"
109+
"*": "deny",
110+
"SELECT *": "allow"
111111
}
112112
}
113113
}
@@ -301,7 +301,7 @@ For additional safety:
301301
Altimate Code includes several layers of protection to keep the agent within your project:
302302

303303
- **Project boundary enforcement.** File operations check that paths stay within your project directory (or git worktree for monorepos). Attempts to read or write outside the project trigger an `external_directory` permission prompt. A path that goes through a symlink is also checked against the directory it resolves to, so an allowed directory cannot be used to reach a denied one.
304-
- **Symlink-aware path resolution.** Symlinks inside the project that point outside are detected and blocked. This prevents an agent from reading or writing outside your project through symlinks.
304+
- **Symlink-aware path resolution.** Symlinks inside the project that point outside are resolved, so following one triggers the same `external_directory` permission check as any other path outside the project. Whether it is allowed depends on that permission.
305305
- **Path traversal blocking.** Paths containing `../` sequences that would escape the project are rejected with an "Access denied" error.
306306
- **Sensitive file protection.** Writing to credential files (`.env`, `.ssh/`, `.aws/`, private keys) triggers a confirmation prompt, even inside the project. See [below](#why-am-i-being-prompted-to-edit-env-files) for details.
307307
- **Bash command analysis.** The bash tool parses commands with tree-sitter to detect file operations (`rm`, `cp`, `mv`, etc.) targeting paths outside your project, and prompts for permission.

‎packages/opencode/test/agent/analyst-data-explorer.test.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ import { deriveSubagentSessionPermission } from "../../src/agent/subagent-permis
99
import { Permission } from "../../src/permission"
1010
import { RuntimeFlags } from "../../src/effect/runtime-flags"
1111
import { ToolRegistry } from "../../src/tool/registry"
12+
import { LLM } from "../../src/session/llm"
13+
import type { MessageV2 } from "../../src/session/message-v2"
1214
import { assertExternalDirectoryEffect } from "../../src/tool/external-directory"
1315
import { MessageID, SessionID } from "../../src/session/schema"
1416
import type { Tool } from "../../src/tool/tool"
@@ -479,7 +481,11 @@ withRegistry.instance(
479481
const ids = yield* (yield* ToolRegistry.Service).ids()
480482
const analyst = (yield* Agent.Service.use((svc) => svc.get("analyst")))!
481483
expect(ids).toContain("batch")
482-
const disabled = Permission.disabled(ids, analyst.permission)
484+
// The same helper that removes tools from each model request.
485+
const disabled = LLM.removedTools(ids, {
486+
agent: analyst,
487+
user: { tools: undefined } as unknown as MessageV2.User,
488+
})
483489
expect(ids.filter((id) => !disabled.has(id) && !analystConfigEnabled.has(id))).toEqual([])
484490
for (const tool of analystWrites.filter((tool) => ids.includes(tool))) expect(disabled.has(tool), tool).toBe(true)
485491
}),

0 commit comments

Comments
 (0)