Skip to main content
Loom’s permission system ensures the AI can’t perform destructive operations without your approval. Configure auto-approve lists, session-based grants, and per-tool policies.

Overview

The permission manager categorizes tools and enforces access control:

Read

Safe, read-only operations always allowed by default

Write

File modifications require permission

Execute

Shell commands require explicit approval

Tool Categories

Read Tools (Auto-Approved)

These tools are typically safe and auto-approved:
  • file_read
  • file_search
  • content_search
  • directory_list
No permission prompts for read operations

Write Tools (Require Permission)

These tools modify files:
  • file_write
  • file_edit
User approval required unless explicitly granted

Execute Tools (Require Permission)

These tools run commands:
  • shell
  • git
Potentially dangerous - always requires approval unless granted

Permission Checks

When a tool is invoked, Loom checks:
1

Auto-Approve List

Is the tool in the auto_approve list from config?If yes → Allow immediately
2

Existing Grant

Has the user granted permission for this tool in this session?If yes → Allow immediately
3

Ask User

Neither auto-approved nor granted?Show permission prompt

Configuration

Auto-Approve List

Set tools to auto-approve in .loom.toml:
[permissions]
auto_approve = [
  "file_read",
  "file_search",
  "content_search",
  "directory_list"
]
These tools will never prompt for permission.

Default Configuration

If no config is provided, read tools are auto-approved:
default_auto_approve = [
  "file_read",
  "file_search",
  "content_search",
  "directory_list"
]

Permission Prompts

CLI Prompt

In the terminal, you’ll see:
[file_edit] wants to: write to src/user.ex

[y]es / [n]o / [a]lways for this session:
y (yes)
Allow this one operation
n (no)
Deny this operation - Loom will continue without it
a (always)
Grant permission for all invocations of this tool in this session

Web UI Modal

In the browser, a modal dialog appears:
Permission Required

Allow file_edit on src/user.ex?

[Deny] [Allow Once] [Allow Always]
Deny
Reject this operation
Allow Once
Approve this single operation
Allow Always
Auto-approve all operations of this tool type for the session

Session Grants

When you choose “Always” or “Allow Always”, a grant is stored:
%PermissionGrant{
  tool: "file_edit",
  scope: "*",  # or specific path
  session_id: "abc123...",
  granted_at: ~U[2026-02-28 10:30:00Z]
}

Grant Scope

Grants can be:
  • Tool-wide (scope: "*"): Applies to all uses of this tool
  • Path-specific (scope: "lib/core/user.ex"): Only for specific file
Currently, grants are tool-wide. Path-specific grants are planned for future releases.

Grant Duration

Grants last for:
  • Session lifetime: While the session is active
  • Not persisted: Grants are cleared when session ends
For fully automated workflows, use --yes flag or add tools to auto_approve list.

Auto-Approve Mode

CLI: --yes Flag

Skip all permission prompts:
loom --yes "refactor the authentication module"
All tools will be auto-approved for this session.
Use with caution! Loom will be able to:
  • Write and modify files
  • Execute shell commands
  • Run git operations
Only use in trusted environments or for non-critical tasks.

Web UI: Auto-Approve Session

Once you click “Allow Always” for a tool, it’s auto-approved for the rest of the session. To reset:
  • Start a new session
  • Refresh the page

Permission Manager API

Check Permission

Loom.Permissions.Manager.check("file_edit", "lib/user.ex", session_id)
# Returns: :allowed | :denied | :ask

Grant Permission

Loom.Permissions.Manager.grant("shell", "*", session_id)
# Stores grant in database

Check If Auto-Approved

Loom.Permissions.Manager.is_auto_approved?("file_read")
# Returns: true | false

Get Tool Category

Loom.Permissions.Manager.tool_category("file_edit")
# Returns: :write

Loom.Permissions.Manager.tool_category("shell")
# Returns: :execute

Security Best Practices

Start Restrictive: Only auto-approve read tools initially. Grant write/execute permissions as needed.
Review Prompts: Read what Loom wants to do before approving. Check file paths and command arguments.
Use Sessions: Grants are session-scoped. Start fresh sessions for different tasks to limit scope.
Avoid --yes in Production: Never use auto-approve mode on production codebases or critical projects.

Permission Workflow Example

1

User Request

You ask Loom: “Add error handling to user_controller.ex”
2

Loom Plans

AI decides it needs to:
  1. Read user_controller.ex (auto-approved ✓)
  2. Edit user_controller.ex (requires permission)
3

Permission Prompt

Loom shows:
[file_edit] wants to: write to lib/user_controller.ex

[y]es / [n]o / [a]lways:
4

User Approves

You type: yLoom proceeds with the edit.
5

Follow-up Edit

AI wants to edit the same file again.If you chose a (always), no new prompt. If you chose y (yes), another prompt appears.

Handling Denials

When you deny a permission:
  1. Loom receives denial: Tool returns error
  2. AI adjusts: May:
    • Explain what it wanted to do
    • Ask for clarification
    • Suggest manual steps
    • Continue with read-only analysis
Denying permissions doesn’t end the session. Loom will work within the constraints you set.

Database Schema

Permission grants are stored in the database:
CREATE TABLE permission_grants (
  id UUID PRIMARY KEY,
  tool VARCHAR NOT NULL,
  scope VARCHAR NOT NULL,
  session_id UUID NOT NULL,
  granted_at TIMESTAMP NOT NULL
);
Query grants:
import Ecto.Query

from g in PermissionGrant,
  where: g.session_id == ^session_id,
  where: g.tool == ^tool_name

Custom Permission Policies

You can extend the permission system:
defmodule MyApp.CustomPermissions do
  def check_custom_policy(tool_name, path, session_id) do
    case tool_name do
      "shell" ->
        # Only allow safe commands
        if safe_command?(path), do: :allowed, else: :ask
        
      "file_write" ->
        # Only allow writes to specific directories
        if writable_dir?(path), do: :allowed, else: :denied
        
      _ ->
        # Delegate to default policy
        Loom.Permissions.Manager.check(tool_name, path, session_id)
    end
  end
end

Future Enhancements

Planned Features

  • Path-specific grants: “Allow file_edit only in lib/core/”
  • Time-limited grants: “Auto-approve for 1 hour”
  • Audit log: Track all permission requests and grants
  • Team policies: Shared permission rules across team
  • Dry-run mode: See what Loom would do without executing

Troubleshooting

Too Many Prompts

Solution: Add tools to auto_approve list or use “Always” in prompts.

Accidentally Granted Permission

Solution: Start a new session to reset all grants.

Config Not Loading

Solution: Ensure .loom.toml is in project root and formatted correctly:
[permissions]
auto_approve = ["file_read", "content_search"]

Next Steps

Tools

Learn about all available tools and their categories

Configuration

Configure Loom’s behavior and policies

CLI

Use permission flags in command-line mode

Web UI

Manage permissions in the visual interface

Build docs developers (and LLMs) love