You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit fa0b03f
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/docs/configure/agents.md
+9-6Lines changed: 9 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,7 @@ Agents define different AI personas with specific models, prompts, permissions,
12
12
| Agent | Description | Access Level |
13
13
|-------|------------|-------------|
14
14
|`builder`| Create and modify dbt models, SQL pipelines, and data transformations | Full read/write. SQL mutations prompt for approval. |
15
-
|`analyst`| Answer questions about your data — explore it, run SELECT queries, inspect schemas, generate insights | Read-only (enforced). SQL writesdenied. Safe bash commands auto-allowed. |
15
+
|`analyst`| Answer questions about your data — explore it, run SELECT queries, inspect schemas, generate insights | Read-only (enforced). SQL writes, file edits, shell, memory saves and other built-in write tools denied, even if config allows them. MCP and custom tools follow your config. Training entries and session scratch tables are still allowed. |
16
16
|`plan`| Plan before acting — restricted to planning files only | Minimal — no edits, no bash, no SQL |
17
17
18
18
### Builder
@@ -25,10 +25,11 @@ The agent for asking questions about your data. Truly read-only mode for safe da
-**Bash**: Denied. Use read, grep and glob to read files
29
29
-**Web**: Fetch and search allowed without prompts
30
30
-**Schema/warehouse/finops**: All inspection tools available
31
-
-**Workspace knowledge**: Loads workspace and project skills; reads workspace memory and views this checkout's memory audit log. Reloading memory syncs the local copy with the workspace, which can remove a local copy of a block the workspace archived. Saving memory is done with `builder`.
31
+
-**Workspace knowledge**: Loads workspace and project skills; reads workspace memory and views this checkout's memory audit log. Can read files bundled with skills, including global skills stored outside the project. Reloading memory syncs the local copy with the workspace, which can remove a local copy of a block the workspace archived. Saving memory is done with `builder`.
32
+
-**Config overrides**: A permission config such as `"*": "allow"` cannot turn file edits, SQL writes (including data diffs of arbitrary queries), shell, memory saves, warehouse connection or MCP config changes, training imports, sample project setup, feedback submission, batch tool calls or delegation beyond `data-explorer` back on. A global `"*": "allow"` does turn on MCP and custom tools for analyst, including ones that write (for example a SQL MCP server); to keep them from analyst, put the `"*": "allow"` under `agent.builder` instead of the global config, or deny those tools under `agent.analyst.permission`.
32
33
33
34
!!! tip
34
35
Use `analyst` when exploring data to ensure no accidental writes. Switch to `builder` when you're ready to create or modify models.
@@ -66,8 +67,8 @@ Define custom agents in `altimate-code.json`:
66
67
"write": "deny",
67
68
"edit": "deny",
68
69
"bash": {
69
-
"dbt docs generate": "allow",
70
-
"*": "deny"
70
+
"*": "deny",
71
+
"dbt docs generate": "allow"
71
72
}
72
73
}
73
74
}
@@ -121,7 +122,7 @@ Each agent can have its own permission overrides:
121
122
```json
122
123
{
123
124
"agent": {
124
-
"analyst": {
125
+
"builder": {
125
126
"permission": {
126
127
"write": "deny",
127
128
"edit": "deny",
@@ -137,6 +138,8 @@ Each agent can have its own permission overrides:
137
138
}
138
139
```
139
140
141
+
`analyst` already denies its shell and built-in write tools whatever its config says, so its config is mainly useful to restrict it further (for example `"webfetch": "deny"`) or to allow MCP and custom tools.
142
+
140
143
!!! warning
141
144
Agent-specific permissions override global permissions. A `"deny"` at the agent level cannot be overridden by a global `"allow"`.
Copy file name to clipboardExpand all lines: docs/docs/configure/permissions.md
+9-12Lines changed: 9 additions & 12 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -65,21 +65,25 @@ Override permissions for specific agents:
65
65
```json
66
66
{
67
67
"agent": {
68
-
"analyst": {
68
+
"builder": {
69
69
"permission": {
70
70
"write": "deny",
71
71
"edit": "deny",
72
72
"bash": {
73
+
"*": "deny",
73
74
"SELECT *": "allow",
74
-
"dbt docs *": "allow",
75
-
"*": "deny"
75
+
"dbt docs *": "allow"
76
76
}
77
77
}
78
78
}
79
79
}
80
80
}
81
81
```
82
82
83
+
The `analyst` agent's shell and built-in write tools (file edits, SQL writes, memory saves and the other built-in tools that change state) stay denied even if its permission config allows them. Training entries remain available through `training_save` and `training_remove`, and analyst can create session scratch tables. MCP and custom tools follow your config, so a global `"*": "allow"` turns them on for analyst too, including ones that write. 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.
86
+
83
87
## All Permissioned Tools
84
88
85
89
| Tool | Supports Patterns | Description |
@@ -209,15 +213,8 @@ Give each agent only the permissions it needs:
Copy file name to clipboardExpand all lines: docs/docs/configure/tools.md
+9-9Lines changed: 9 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -38,9 +38,9 @@ Control which tools agents can use via the [permission system](permissions.md):
38
38
{
39
39
"permission": {
40
40
"bash": {
41
+
"*": "ask",
41
42
"dbt *": "allow",
42
-
"rm *": "deny",
43
-
"*": "ask"
43
+
"rm *": "deny"
44
44
},
45
45
"write": "ask",
46
46
"read": "allow"
@@ -58,22 +58,22 @@ Disable a tool for a specific agent by setting its permission to `"deny"`:
58
58
```json
59
59
{
60
60
"agent": {
61
-
"analyst": {
61
+
"builder": {
62
62
"permission": {
63
63
"write": "deny",
64
64
"edit": "deny",
65
65
"bash": {
66
-
"dbt run *": "deny",
67
-
"*": "ask"
66
+
"*": "ask",
67
+
"dbt run *": "deny"
68
68
}
69
69
}
70
70
}
71
71
}
72
72
}
73
73
```
74
74
75
-
!!! example "Read-only analyst"
76
-
The configuration above creates an analyst agent that cannot modify files. It can only read and explore the codebase, and must ask before running shell commands (except`dbt run`, which is blocked entirely).
75
+
!!! example "Builder with file edit tools denied"
76
+
The configuration above denies the builder agent's `write` and `edit` tools. The builder can read and explore the codebase. It must ask before running other shell commands, and`dbt run`is blocked entirely. An approved shell command can still modify files. The `analyst` agent's shell and built-in write tools are already denied whatever its permission config says. It can still save training entries and create session scratch tables for analysis, and MCP or custom tools follow your config.
77
77
78
78
## Tool Behavior
79
79
@@ -85,11 +85,11 @@ The `bash` tool executes shell commands in the project directory. Commands run i
-**No shell.** Bash is denied. Files are read with the read, grep and glob tools
92
+
-**No memory saves.** Workspace memory blocks can be read, but not saved, extracted or deleted (use builder). Training entries can still be saved and removed
93
+
-**Config cannot lift these.** A permission config such as `"*": "allow"` does not turn file edits, SQL writes (including data diffs of arbitrary queries), shell, memory saves, warehouse connection or MCP config changes, training imports, sample project setup, feedback submission, batch tool calls or delegation beyond `data-explorer` back on for analyst. MCP and custom tools are not covered: a global `"*": "allow"` turns them on for analyst too, including ones that write.
94
+
-**Skill files readable.** Files bundled with a skill, including global skills stored outside the project, can be read
92
95
-**Full web access.** Fetch and search allowed without prompts
93
96
-**All inspection tools.** Schema, warehouse, finops, lineage, and core analysis tools available
|**Builder**| Read/Write | Create and modify SQL, dbt models, pipelines. SQL writes prompt for approval. |
153
+
|**Analyst**| Read-only | Ask questions about your data, explore production data safely, run cost analysis. Production SQL writes are denied; session scratch tables are allowed. |
154
+
|**Plan**| Minimal | Plan an approach before switching to builder to execute it |
155
155
156
156
Switch modes in the TUI:
157
157
@@ -234,12 +234,7 @@ Set tool permissions for each agent mode in `altimate-code.json`:
234
234
"agent": {
235
235
"analyst": {
236
236
"permission": {
237
-
"write": "deny",
238
-
"edit": "deny",
239
-
"bash": {
240
-
"dbt docs generate": "allow",
241
-
"*": "deny"
242
-
}
237
+
"webfetch": "deny"
243
238
}
244
239
},
245
240
"builder": {
@@ -256,6 +251,8 @@ Set tool permissions for each agent mode in `altimate-code.json`:
256
251
}
257
252
```
258
253
254
+
Analyst's shell and built-in write tools are always denied, so config cannot turn them on. It can still save training entries and create session scratch tables, and MCP or custom tools follow your config.
255
+
259
256
### Project rules with AGENTS.md
260
257
261
258
Define project-wide conventions in an `AGENTS.md` file at your project root. These rules are automatically loaded into every agent's system prompt:
@@ -271,11 +268,11 @@ Define project-wide conventions in an `AGENTS.md` file at your project root. The
Copy file name to clipboardExpand all lines: docs/docs/reference/security-faq.md
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -96,18 +96,18 @@ Yes. Use pattern-based permissions to deny destructive SQL:
96
96
}
97
97
```
98
98
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's shell and built-in write tools are already denied whatever its config says. It can still save training entries and create session scratch tables, and MCP or custom tools follow your config.
100
100
101
101
```json
102
102
{
103
103
"agent": {
104
-
"analyst": {
104
+
"builder": {
105
105
"permission": {
106
106
"write": "deny",
107
107
"edit": "deny",
108
108
"bash": {
109
-
"SELECT *": "allow",
110
-
"*": "deny"
109
+
"*": "deny",
110
+
"SELECT *": "allow"
111
111
}
112
112
}
113
113
}
@@ -300,8 +300,8 @@ For additional safety:
300
300
301
301
Altimate Code includes several layers of protection to keep the agent within your project:
302
302
303
-
-**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.
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.
303
+
-**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 a symlink inside an allowed directory cannot be used to reach a directory outside it that is not allowed.
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.
305
305
-**Path traversal blocking.** Paths containing `../` sequences that would escape the project are rejected with an "Access denied" error.
306
306
-**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.
307
307
-**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.
0 commit comments