Tools & Permissions

Agents interact with your repository and data warehouse through tools—functions that read files, run queries, execute commands, and perform git operations. By default, agents have access to a curated set of tools appropriate for most workflows. You can customize tool access and apply restrictions to ensure agents operate safely within defined boundaries. This guide covers tool presets, individual tool configuration, permission restrictions, and security best practices.

Tool Presets

The fastest way to configure tools is using presets—predefined tool bundles optimized for common agent patterns.

Standard (Default)

preset

"standard"

Balanced tool access suitable for most automation workflows. Includes read/write file operations, SQL queries, bash commands, and git operations.

tools:
  preset: standard

Includes:

File operations: read, write, edit, search
SQL execution with read-only default
Bash commands (restricted to safe list)
Git operations: commit, push, PR creation
Metadata retrieval for profiling

This preset works for 80% of agents. Start here unless you have specific security requirements.

Safe

preset

"safe"

Read-only access for agents that analyze and report but shouldn’t modify anything.

tools:
  preset: safe

Includes:

File reading only (no writes)
SQL queries (strictly read-only)
Metadata retrieval
PR commenting (no commits or file changes)
Directory listing and search

Use for:

Code review agents
Audit and compliance checks
Monitoring and alerting
Report generation

Unrestricted

preset

"unrestricted"

Full tool access including potentially destructive operations. Use with caution.

tools:
  preset: unrestricted

Includes:

Everything in standard
File deletion capabilities
Destructive git operations (force push, branch deletion)
Unrestricted bash command execution
Database write operations

Only use this preset for agents that explicitly need destructive capabilities. Apply additional restrictions to limit scope.

Reference

File Operation Tools

read_file

tool

Read contents of files in the repository.

tools:
  include:
    - read_file

Capabilities:

Read any file within allowed paths
Supports binary and text files
Can read multiple files in parallel

Restrictions:

Subject to files.allow and files.deny paths
Cannot read files outside repository

write_file

tool

Create new files in the repository.

tools:
  include:
    - write_file

Capabilities:

Create files in allowed paths
Set file permissions
Create parent directories as needed

Requires:

files.can_create_files: true in restrictions
File path must match files.allow patterns

edit_file

tool

Modify existing files using search-and-replace operations.

tools:
  include:
    - edit_file

Capabilities:

Find and replace text patterns
Multi-line edits
Preserve file formatting

Restrictions:

Cannot edit files in files.deny paths
Cannot edit files marked as critical_files without approval

multi_edit_file

tool

Perform multiple edits across several files in a single operation.

tools:
  include:
    - multi_edit_file

Use for:

Batch refactoring operations
Consistent changes across many files
Performance optimization (fewer tool calls)

delete_file

tool

Remove files from the repository. Only available with unrestricted preset or explicit inclusion.

tools:
  include:
    - delete_file

Requires files.can_delete_files: true in restrictions. Deletion is permanent in the agent’s working tree.

Data Access Tools

run_sql

tool

Execute SQL queries against connected data warehouses.

tools:
  include:
    - run_sql

Capabilities:

Run SELECT queries for analysis
Join across schemas (within allowed schemas)
Aggregate and transform data

Default restrictions:

Read-only (SELECT, WITH, SHOW only)
Row limit enforced (default: 10,000)
Timeout limit (default: 120 seconds)
Schema restrictions if configured

Enable write operations carefully. Most agents should stay read-only.

retrieve_metadata

tool

Get table and column statistics without running queries.

tools:
  include:
    - retrieve_metadata

Returns:

Table row counts
Column names and types
Null percentages
Distinct value counts
Min/max for numeric columns

Advantages:

Faster than SQL queries
Lower warehouse cost
No query timeout issues

Code Search Tools

grep

tool

Search file contents using regular expressions.

tools:
  include:
    - grep

Use for:

Finding specific code patterns
Locating model references
Searching documentation

glob

tool

Find files matching path patterns.

tools:
  include:
    - glob

Examples:

models/**/*.sql - All SQL files in models
models/marts/**/dim_*.sql - All dimension models
**/*.yml - All YAML files

tool

List directory contents.

tools:
  include:
    - ls

Capabilities:

List files and subdirectories
Get file metadata (size, modified time)
Recursive directory traversal

Command Execution Tools

bash

tool

Execute shell commands in the repository environment.

tools:
  include:
    - bash

Default allowed commands:

git - Git operations
dbt - dbt commands
python - Python scripts
node - Node.js scripts
curl - HTTP requests
jq - JSON processing

Blocked by default:

rm - File deletion
sudo - Privilege escalation
dd - Disk operations
mkfs - Filesystem operations

See Bash Configuration for customization.

git_operations

tool

Perform git operations: commit, push, create branches, open PRs.

tools:
  include:
    - git_operations

Capabilities:

Create branches
Commit changes with messages
Push to remote
Create pull requests via GitHub API
Add reviewers and labels

Subject to:

git_operations restrictions
Branch naming requirements
Approval gates if configured

Task Delegation Tools

task

tool

Spawn sub-agents to work on subtasks in parallel.

tools:
  include:
    - task

Use cases:

Complex agents that need research phases
Parallel analysis of multiple files
Delegating specialized sub-workflows

Sub-agents inherit parent tool restrictions but can have their own prompts and context.

Restrictions

Apply fine-grained controls beyond preset defaults.

File System Restrictions

restrictions.files

object

Control which files and directories agents can access.

Show File Restrictions

allow

array

Glob patterns for paths the agent can access. If specified, agent can only access matching paths.

restrictions:
  files:
    allow:
      - "models/**"
      - "tests/**"
      - "macros/**"

deny

array

Glob patterns for paths the agent cannot access. Takes precedence over allow.

restrictions:
  files:
    deny:
      - ".env"
      - "**/*.env"
      - ".git/**"
      - "**/secrets/**"

Always deny environment files and secrets directories.

can_create_files

boolean

Whether agent can create new files. Defaults to true for standard and unrestricted, false for safe.

can_delete_files

boolean

Whether agent can delete files. Defaults to false for standard and safe, true for unrestricted.

read_only

array

Paths the agent can read but not modify.

restrictions:
  files:
    allow: ["models/**", "dbt_project.yml"]
    read_only: ["dbt_project.yml"]

Git Operation Restrictions

restrictions.git_operations

object

Control git capabilities and requirements.

Show Git Restrictions

can_commit

boolean

Whether agent can create commits. Defaults to true.

can_push

boolean

Whether agent can push commits to remote. Defaults to true.

# Agent can commit locally but not push
restrictions:
  git_operations:
    can_commit: true
    can_push: false
    can_create_pr: true  # Can still create PR from local commits

can_create_pr

boolean

Whether agent can create pull requests. Defaults to true.

branch_prefix

string

Required prefix for any branches the agent creates.

restrictions:
  git_operations:
    branch_prefix: "agent/"

Results in branches like: agent/schema-update, agent/docs-sync

require_signed_commits

boolean

Whether commits must be GPG signed. Defaults to false.

SQL Restrictions

restrictions.sql

object

Control database access and query capabilities.

Show SQL Restrictions

read_only

boolean

Restrict to SELECT, SHOW, DESCRIBE queries only. Defaults to true.

restrictions:
  sql:
    read_only: true

Only set to false if your agent explicitly needs to create or modify tables.

allowed_schemas

array

Limit which schemas the agent can query.

restrictions:
  sql:
    allowed_schemas:
      - raw
      - staging
      - analytics

denied_schemas

array

Schemas the agent cannot access. Takes precedence over allowed_schemas.

restrictions:
  sql:
    denied_schemas:
      - pii
      - financial_sensitive

max_rows_returned

integer

Maximum number of rows a query can return. Defaults to 10000.

timeout_seconds

integer

Maximum query execution time. Defaults to 120.

max_queries_per_run

integer

Limit total queries agent can execute in one run. Prevents runaway query loops.

Bash Configuration

tools.configurations.bash

object

Customize bash tool restrictions and allowed commands.

Show Bash Configuration

allowed_commands

array

Whitelist of commands the agent can execute.

tools:
  configurations:
    bash:
      allowed_commands:
        - git
        - dbt
        - python
        - curl
        - jq
        - yq

blocked_commands

array

Commands explicitly blocked even if in allowed list.

tools:
  configurations:
    bash:
      blocked_commands:
        - rm
        - sudo
        - dd
        - chmod

timeout_seconds

integer

Maximum execution time for bash commands. Defaults to 300.

allow_pipes

boolean

Whether commands can use pipes and redirection. Defaults to true.

Critical Files Protection

restrictions.critical_files

array

List of files requiring approval before modification.

restrictions:
  critical_files:
    - dbt_project.yml
    - profiles.yml
    - packages.yml
    - .github/workflows/**

Agents can read these files but must request approval to modify them.

Approval Gates

restrictions.approval

object

Require human approval for sensitive operations.

Show Approval Configuration

require_approval_for

array

Operations requiring approval before execution.Values:

pr_creation - Creating pull requests
file_deletion - Deleting files
critical_file_modification - Editing files in critical_files list
sql_write - Non-SELECT queries
bash_execution - Running bash commands

restrictions:
  approval:
    require_approval_for:
      - pr_creation
      - file_deletion

approvers

object

Who can approve agent actions.

Show Approvers

users

array

GitHub usernames who can approve.Example: ["alice", "bob"]

teams

array

GitHub teams who can approve.Example: ["data-platform-team", "engineering-leads"]

approval_timeout_hours

integer

Hours to wait for approval before timing out. Defaults to 24.

notification_channel

string

Slack channel to notify when approval needed.Example: "#agent-approvals"

Examples

Review-Only Agent
Restricted Staging Agent
Audit Agent with Approvals
Documentation Generator
Advanced Bash Configuration

review-only.yaml

name: code-reviewer
description: Reviews code without making changes

tools:
  preset: safe

restrictions:
  files:
    allow:
      - "models/**"
      - "tests/**"
      - "macros/**"
  sql:
    read_only: true
    allowed_schemas: [raw, staging, marts]

prompt: |
  Review this PR for dbt best practices.
  Leave comments on any issues found.
  Do not make any file changes.

Best Practices

Start Restrictive, Expand as Needed

Begin with the safe preset and grant additional tools only when agents demonstrate the need.

Start with safe preset

Deploy agents initially with read-only access:

tools:
  preset: safe

Monitor agent behavior

Check run logs to see what operations the agent attempts but can’t perform.

Grant specific tools

Add only the tools needed:

tools:
  preset: safe
  include:
    - edit_file  # Now can edit after proving read-only works

Apply restrictions

Even with additional tools, restrict scope:

tools:
  preset: safe
  include:
    - edit_file
restrictions:
  files:
    allow: ["models/staging/**"]  # Limit scope

Layer Multiple Restrictions

Combine different restriction types for defense in depth:

restrictions:
  files:
    allow: ["models/**"]
    deny: ["models/sensitive/**"]
    critical_files: ["models/marts/**/fct_*.sql"]
  sql:
    read_only: true
    allowed_schemas: [staging, marts]
  git_operations:
    branch_prefix: "agent/"
  approval:
    require_approval_for: [pr_creation]

Protect Sensitive Data

Always deny access to credentials, secrets, and PII-containing files.

restrictions:
  files:
    deny:
      - "**/*.env"
      - "**/.env*"
      - "**/secrets/**"
      - ".aws/**"
      - ".gcp/**"
  sql:
    denied_schemas:
      - pii
      - raw_sensitive
      - customer_data

Use Approval Gates for High-Risk Operations

Require human review before agents perform sensitive actions:

restrictions:
  approval:
    require_approval_for:
      - pr_creation  # Review before opening PRs
      - file_deletion  # Confirm before deleting
      - critical_file_modification  # Check important file changes
    approvers:
      teams: ["data-platform-leads"]
    approval_timeout_hours: 24
    notification_channel: "#agent-approvals"

Scope SQL Access Appropriately

Read-only for most agents

Keep sql.read_only: true unless agent explicitly needs to write:

restrictions:
  sql:
    read_only: true
    max_rows_returned: 10000

Limit schemas accessed

Grant access only to schemas the agent needs:

restrictions:
  sql:
    allowed_schemas: [staging, marts]

Set query limits

Prevent expensive queries and runaway loops:

restrictions:
  sql:
    max_rows_returned: 10000
    timeout_seconds: 120
    max_queries_per_run: 50

Document Tool Requirements

Add comments explaining why agents need specific tools:

tools:
  preset: standard
  include:
    - delete_file  # Needed to clean up temp files in .buster/temp/

restrictions:
  files:
    allow:
      - "models/**"
      - ".buster/temp/**"  # Temp files only
    can_delete_files: true
  # Only allow deletion in temp directory
  critical_files:
    - "models/**"  # Protect models from deletion

Introduction

Guides

Examples

Resources

Tools & Permissions

Tool Presets

Standard (Default)

Safe

Unrestricted

Reference

File Operation Tools

Data Access Tools

Code Search Tools

Command Execution Tools

Task Delegation Tools

Restrictions

File System Restrictions

Git Operation Restrictions

SQL Restrictions

Bash Configuration

Critical Files Protection

Approval Gates

Examples

Best Practices

Start Restrictive, Expand as Needed

Layer Multiple Restrictions

Protect Sensitive Data

Use Approval Gates for High-Risk Operations

Scope SQL Access Appropriately

Document Tool Requirements

Introduction

Guides

Examples

Resources

​Tool Presets

​Standard (Default)

​Safe

​Unrestricted

​Reference

​File Operation Tools

​Data Access Tools

​Code Search Tools

​Command Execution Tools

​Task Delegation Tools

​Restrictions

​File System Restrictions

​Git Operation Restrictions

​SQL Restrictions

​Bash Configuration

​Critical Files Protection

​Approval Gates

​Examples

​Best Practices

​Start Restrictive, Expand as Needed

​Layer Multiple Restrictions

​Protect Sensitive Data

​Use Approval Gates for High-Risk Operations

​Scope SQL Access Appropriately

​Document Tool Requirements

Tool Presets

Standard (Default)

Safe

Unrestricted

Reference

File Operation Tools

Data Access Tools

Code Search Tools

Command Execution Tools

Task Delegation Tools

Restrictions

File System Restrictions

Git Operation Restrictions

SQL Restrictions

Bash Configuration

Critical Files Protection

Approval Gates

Examples

Best Practices

Start Restrictive, Expand as Needed

Layer Multiple Restrictions

Protect Sensitive Data

Use Approval Gates for High-Risk Operations

Scope SQL Access Appropriately

Document Tool Requirements