Permissions

Dropstone uses the permission config to decide whether a given action should run automatically, prompt you, or be blocked.

The legacy tools boolean config is deprecated; it has been merged into permission. The old tools config is still supported for backwards compatibility.

Actions

Each permission rule resolves to one of:

• "allow": run without approval
• "ask": prompt for approval
• "deny": block the action

Configuration

You can set permissions globally (with *), and override specific tools.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "*": "ask",
    "bash": "allow",
    "edit": "deny"
  }
}

You can also set all permissions at once:

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": "allow"
}

Granular Rules (Object Syntax)

For most permissions, you can use an object to apply different actions based on the tool input.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "npm *": "allow",
      "rm *": "deny",
      "grep *": "allow"
    },
    "edit": {
      "*": "deny",
      "packages/web/src/content/docs/*.mdx": "allow"
    }
  }
}

Rules are evaluated by pattern match, with the last matching rule winning. A common pattern is to put the catch-all "*" rule first, and more specific rules after it.

Wildcards

Permission patterns use simple wildcard matching:

• * matches zero or more of any character
• ? matches exactly one character
• All other characters match literally

Home Directory Expansion

You can use ~ or $HOME at the start of a pattern to reference your home directory. This is particularly useful for external_directory rules.

• ~/projects/* -> /Users/username/projects/*
• $HOME/projects/* -> /Users/username/projects/*
• ~ -> /Users/username

External Directories

Use external_directory to allow tool calls that touch paths outside the working directory where Dropstone was started. This applies to any tool that takes a path as input (for example read, edit, glob, grep, and many bash commands).

Home expansion (like ~/...) only affects how a pattern is written. It does not make an external path part of the current workspace, so paths outside the working directory must still be allowed via external_directory.

For example, this allows access to everything under ~/projects/personal/:

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    }
  }
}

Any directory allowed here inherits the same defaults as the current workspace. Since read defaults to allow, reads are also allowed for entries under external_directory unless overridden. Add explicit rules when a tool should be restricted in these paths, such as blocking edits while keeping reads:

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "external_directory": {
      "~/projects/personal/**": "allow"
    },
    "edit": {
      "~/projects/personal/**": "deny"
    }
  }
}

Keep the list focused on trusted paths, and layer extra allow or deny rules as needed for other tools (for example bash).

Available Permissions

Dropstone permissions are keyed by tool name, plus a couple of safety guards:

• read: reading a file (matches the file path)
• edit: all file modifications (covers edit, write, patch)
• glob: file globbing (matches the glob pattern)
• grep: content search (matches the regex pattern)
• bash: running shell commands (matches parsed commands like git status --porcelain)
• task: launching subagents (matches the subagent type)
• skill: loading a skill (matches the skill name)
• lsp: running LSP queries (currently non-granular)
• question: asking the user questions during execution
• webfetch: fetching a URL (matches the URL)
• websearch: web search (matches the query)
• external_directory: triggered when a tool touches paths outside the project working directory
• doom_loop: triggered when the same tool call repeats 3 times with identical input

Defaults

If you don't specify anything, the default build agent asks before everything. Approval is the default, not an exception:

{
  "permission": {
    "*": "ask",
    "read": {
      "*": "ask",
      "*.env": "ask",
      "*.env.*": "ask",
      "*.env.example": "ask"
    },
    "external_directory": { "*": "ask" },
    "question": "deny",
    "plan_enter": "deny",
    "plan_exit": "deny",
    "mode_switch": "deny"
  }
}

Directories you have already approved are added to external_directory as "allow" for the rest of the session.

Your config is merged on top of these defaults, and your rules win. It does not replace them: setting edit to "allow" leaves read at "ask", so name every permission you intend to change.

The accept all agent starts from "*": "allow" instead, with external_directory fully allowed. Reads of .env and .env.* still ask, on the reasoning that auto-approving a run is not the same as consenting to hand over secrets.

Headless and server mode

Interactively, "ask" is harmless: you get prompted and approve. Under dropstone serve, in CI, or anywhere else without a person at the keyboard, there is nobody to ask, so the call sits at "status": "running" and the request hangs instead of failing. There is no timeout and no error to catch.

Because the build agent asks before everything, this is the default outcome rather than an edge case. A partial config does not rescue you either: allowing edit leaves read at "ask", and the run hangs the first time the agent opens a file.

Two ways to fix it. Either run the accept all agent, which starts from "*": "allow":

curl -X POST ".../session/$SID/message" -d '{ "agent": "accept all", ... }'

Or stay on build and state the full allowlist, denying by default so a tool added in a later release cannot silently start hanging your runs:

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "*": "deny",
    "read": "allow",
    "edit": "allow",
    "glob": "allow",
    "grep": "allow",
    "bash": "allow"
  }
}

Narrow it to what the job actually needs. An agent that only reads and reports has no reason to hold edit or bash.

Note that accept all still asks before reading .env and .env.*. If an unattended run must read one, allow it explicitly and be deliberate about it.

What "Ask" does

When Dropstone prompts for approval, the UI offers three outcomes:

• once: approve just this request
• always: approve future requests matching the suggested patterns (for the rest of the current Dropstone session)
• reject: deny the request

The set of patterns that always would approve is provided by the tool (for example, bash approvals typically whitelist a safe command prefix like git status*).

Agents

You can override permissions per agent. Agent permissions are merged with the global config, and agent rules take precedence. Learn more about agent permissions.

{
  "$schema": "https://dropstone.io/schema/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "git commit *": "deny",
      "git push *": "deny",
      "grep *": "allow"
    }
  },
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git *": "allow",
          "git commit *": "ask",
          "git push *": "deny",
          "grep *": "allow"
        }
      }
    }
  }
}

You can also configure agent permissions in Markdown:

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash: ask
  webfetch: deny
---

Only analyze code and suggest changes.