Permissions Configuration Guide

This guide explains how to configure custom permission rules for Explore mode.

Overview

Explore mode is a read-only mode that blocks potentially destructive operations. Custom permission rules let you allow specific operations that would otherwise be blocked.

Permission files are located at:

• Workspace: ~/.fabric-agent/workspaces/{slug}/permissions.json
• Source: ~/.fabric-agent/workspaces/{slug}/sources/{source}/permissions.json

Auto-Scoping for Source Permissions

Important: MCP patterns in a source's permissions.json are automatically scoped to that source.

When you write:

{ "pattern": "list", "comment": "Allow list operations" }

The system converts it to mcp__<sourceSlug>__.*list internally. This means:

• Simple patterns like list only affect tools from that source
• No risk of accidentally allowing list tools from other sources
• Workspace-level patterns still apply globally (for intentional cross-source rules)

permissions.json Schema

{
  "allowedMcpPatterns": [
    { "pattern": "list", "comment": "Allow list operations" },
    { "pattern": "get", "comment": "Allow get operations" },
    { "pattern": "search", "comment": "Allow search operations" }
  ],
  "allowedApiEndpoints": [
    { "method": "GET", "path": ".*", "comment": "All GET requests" },
    { "method": "POST", "path": "^/search", "comment": "Search POST" }
  ],
  "allowedBashPatterns": [
    { "pattern": "^ls\\s", "comment": "Allow ls commands" }
  ],
  "blockedTools": [
    "dangerous_tool"
  ],
  "allowedWritePaths": [
    "/tmp/**",
    "~/.fabric-agent/**"
  ]
}

Rule Types

allowedMcpPatterns

Regex patterns for MCP tool names to allow in Explore mode.

For source-level permissions.json, use simple patterns (auto-scoped):

{
  "allowedMcpPatterns": [
    { "pattern": "list", "comment": "All list operations for this source" },
    { "pattern": "get", "comment": "All get operations for this source" },
    { "pattern": "search", "comment": "All search operations for this source" }
  ]
}

For workspace-level permissions.json (global rules), use full patterns:

{
  "allowedMcpPatterns": [
    { "pattern": "^mcp__.*__list", "comment": "List operations across all sources" }
  ]
}

allowedApiEndpoints

Fine-grained rules for API source requests.

{
  "allowedApiEndpoints": [
    { "method": "GET", "path": ".*", "comment": "All GET requests" },
    { "method": "POST", "path": "^/search", "comment": "Search POST" },
    { "method": "POST", "path": "^/v1/query$", "comment": "Query endpoint" }
  ]
}

allowedBashPatterns

Regex patterns for bash commands to allow.

{
  "allowedBashPatterns": [
    { "pattern": "^ls\\s", "comment": "ls commands" },
    { "pattern": "^git\\s+status", "comment": "git status" },
    { "pattern": "^pwd$", "comment": "pwd command" }
  ]
}

blockedTools

Additional tools to block (rarely needed).

{
  "blockedTools": ["risky_tool_name"]
}

allowedWritePaths

Glob patterns for directories where writes are allowed.

{
  "allowedWritePaths": [
    "/tmp/**",
    "~/.fabric-agent/**",
    "/path/to/project/output/**"
  ]
}

Default Behavior in Explore Mode

Blocked by default:

• Bash commands (except read-only commands listed below)
• Write, Edit, MultiEdit tools
• MCP tools with write semantics (create, update, delete)
• API POST/PUT/DELETE requests

Allowed by default:

• Read, Glob, Grep
• WebFetch, WebSearch
• TodoWrite
• MCP tools with read semantics (list, get, search)
• Plans folder writes (session plans only)

What happens when a tool is blocked

A blocked call does not end the turn. The agent is handed the reason the call was refused and keeps going, so it can tell you what it was trying to do and offer a way forward — suggest switching to a mode that permits the operation, submit a plan for you to approve, or fall back to a read-only route to the same answer. You always get a reply, never silence.

Read-Only Bash Commands

These commands are allowed in Explore mode without custom configuration:

Compound Commands

Compound commands using &&, ||, and | are allowed when all parts are safe:

Each command is validated independently. If any command is not in the allowlist, the entire compound command is blocked.

Blocked Shell Constructs

These constructs are always blocked, even if the base command is allowed:

Example: git status > file.txt is blocked because > could overwrite files.

Tightened read-only checks

• MCP tool names are matched word by word: a tool counts as read-only when a word of its own name (the part after mcp__<source>__) is a read verb (get, list, search, ...) and no word is a write verb (create, update, delete, send, run, mark, ...). So get_issue is allowed, while delete_account, send_thread_reply and get_or_create_issue are not.
• sed -n is allowed only with print-style scripts: -i, -f, and the w/W/e commands and flags are blocked.
• sort is blocked with -o/--output and --compress-program.
• gh api is allowed only for GET: -X/--method with another method is blocked, and so are -f/-F/--field/--raw-field/--input without --method GET (they switch the request to POST). gh api graphql is allowed unless the query is a mutation.

The same read-only rules — including the patterns in your workspace and source permissions.json — apply in Ask to Edit, so read-only MCP tools run there without a prompt; writes still ask.

"Always Allow" in Ask to Edit

"Always Allow" remembers, for the rest of the session, exactly what you approved:

Nothing is remembered for dangerous commands (rm, sudo, git push, git reset, terraform apply, npm publish, ...), for a destructive verb among a CLI's leading words (aws s3 rm, gh repo delete), for chains, pipes, redirects or substitutions, or for wrappers that run another command (env, xargs, ...). In those cases the button is hidden. A remembered key never auto-allows a chained command: approving git commit does not approve git commit -m x && rm -rf ~.

Cascading Rules

Rules cascade from workspace → source → agent:

1. Workspace rules apply globally
2. Source rules extend workspace rules for that source
3. Agent rules extend both for that agent's session

Rules are additive - they can only allow more operations, not restrict further.

Best Practices

1. Be specific with patterns - Use anchors (^, $) to avoid over-matching
2. Add comments - Explain why each rule exists
3. Test patterns - Verify regex matches expected tool names
4. Minimal permissions - Only allow what's needed

Examples

Read-only Linear access:

{
  "allowedMcpPatterns": [
    { "pattern": "^mcp__linear__(list|get|search)", "comment": "Read operations" }
  ]
}

Search-only API:

{
  "allowedApiEndpoints": [
    { "method": "GET", "path": ".*" },
    { "method": "POST", "path": "^/search" }
  ]
}

Safe git commands:

{
  "allowedBashPatterns": [
    { "pattern": "^git\\s+(status|log|diff|branch)", "comment": "Read-only git" }
  ]
}

Planning in Explore Mode

In Explore mode, you can create implementation plans that the user can accept to transition to execution.

When to Create Plans

Create a plan when:

• The task has multiple complex steps
• You want user approval before making changes
• You've gathered enough context and are ready to implement

Creating a Plan

1. Write your plan to a markdown file in the session's plans folder
2. Call SubmitPlan with the file path
3. The user sees a formatted plan with an "Accept Plan" button
4. Clicking "Accept Plan" exits Explore mode and begins implementation

Plan Format

# Plan Title

## Summary
Brief description of what this plan accomplishes.

## Steps
1. **Step description** - Details and approach
2. **Another step** - More details
3. ...

Explore → Implementation Workflow

The recommended workflow:

1. Explore - Read files, search code, understand the codebase
2. Plan - Write a structured plan to the plans folder
3. Submit - Call SubmitPlan to present to user
4. Accept - User clicks "Accept Plan" to exit Explore mode
5. Execute - Implement the plan with full permissions

This provides a smooth transition from exploration to implementation with user oversight.