Docs

Permissions

Every tool call that an agent makes outside a pre-approved list goes through the Agenties permission system. A persistent card appears in the corner of the UI asking you to approve, deny, or always-allow the action. This keeps you in control of what agents can do — especially for destructive operations like shell commands and file writes.

How it works

When an agent calls the request_permissionMCP tool (or when Claude Code's built-in permission check fires), the Agenties main process intercepts the request and:

1.Pauses the agent — the tool call is held pending.
2.Creates a permission card in the UI with the agent name, tool name, and input preview.
3.Waits for your decision (up to 5 minutes before auto-denying).
4.Sends the decision back to the agent via the MCP response.
5.If "Always allow" — adds the tool+pattern to the auto-allowed list in config.json.

Permission card UI

Permission cards appear in the bottom-right corner of the Agenties window. Each card shows:

Permission request
Alex (builder)
Tool
Bash
Input preview
rm -rf ./dist

Options

OptionEffect
DenyRejects the tool call. The agent receives an error and must decide how to proceed.
Allow oncePermits this specific call. The next identical call from any agent will prompt again.
Always allowAdds this tool (with optional input pattern) to the project's auto-allowed list. Future matching calls are never blocked.

Overflow and batch approval

The permission card stack shows a maximum of 4 cards at once. If more than 4 permission requests arrive simultaneously (common when multiple agents are running), a "+N more" indicator appears. Clicking it opens an overflow modal with all pending requests listed in a table, allowing batch approval or denial.

Tip:In the overflow modal, you can select multiple requests and approve or deny them all at once. This is useful for the initial setup of a new project where many tools need to be permitted.

Auto-allowed tools

The auto-allowed list in config.json specifies tools that are always permitted without showing a card. You can manage this list in Settings → Permissions.

config.json (toolPermissions section)
{
  "toolPermissions": {
    "autoAllowed": [
      { "tool": "Read",        "pattern": "*" },
      { "tool": "Glob",        "pattern": "*" },
      { "tool": "Grep",        "pattern": "*" },
      { "tool": "Write",       "pattern": "src/**" },
      { "tool": "Edit",        "pattern": "src/**" },
      { "tool": "Bash",        "pattern": "npm test*" },
      { "tool": "Bash",        "pattern": "npm run lint*" },
      { "tool": "spawn_agent", "pattern": "*" },
      { "tool": "send_message","pattern": "*" }
    ]
  }
}

Each entry has a tool (the MCP tool or Claude Code built-in tool name) and apattern (glob matched against the tool's input string). Use * to match any input for a tool.

Permissions history

Navigate to Settings → Permissions to see the full history of all permission decisions. You can:

•Filter by tool name, agent, decision (approved/denied/always-allowed), or date range.
•Revoke any "always allow" entry — future calls will prompt again.
•Export the history as JSON for auditing.
•See token costs for approved vs. denied agent runs.

The request_permission MCP tool

Agents can proactively request permission before attempting a sensitive operation:

TypeScript
request_permission({
  tool: "Bash",
  input: "rm -rf ./node_modules && npm install",
  reason: "Need to do a clean reinstall to fix the lockfile conflict."
})

The tool returns a boolean granted. If denied, the agent should find an alternative approach or report the blocker to the orchestrator.

Warning:Do not configure * as a pattern for Bash in production projects. Shell commands can be destructive — always use specific patterns like npm run * orgit status* to limit auto-approval to safe operations.