Controlling Tools, Permissions, and Isolation per Agent

Why Per-Agent Control Matters

A well-designed multi-agent system gives each worker exactly the access it needs — no more. A research agent should be able to read files but not write them. A test runner should execute shell commands but not edit source code. A documentation writer should write files but never run arbitrary commands.

This is not just about safety. Narrow tool access also makes agents faster and more predictable. An agent with forty tools available has to reason about which tools to use. An agent with five tools that match its task has fewer decisions to make and makes them more reliably.

The tools Allowlist

The tools frontmatter field restricts which tools the agent can use. If you specify tools, the agent can only use the tools you list — all others are unavailable.

---
name: research-agent
description: Reads files and searches the codebase to answer questions. Does not modify anything.
tools: Read, Glob, Grep
---

This agent can read, search by filename pattern, and search file contents. It cannot write, edit, run commands, or spawn other agents. For a research task, this is all it needs.

If you omit tools, the agent inherits all tools available to the parent session.

The disallowedTools Denylist

The disallowedTools field works as a denylist. It removes specific tools from an agent that would otherwise have full access. The denylist is applied before the allowlist.

---
name: safe-coder
description: Writes and edits code. Cannot run shell commands.
disallowedTools: Bash
---

This agent can use all tools except Bash. Use the denylist when you want to grant broad access but block specific dangerous capabilities.

You can also restrict which subagents an agent can spawn:

disallowedTools: Agent(Explore), Agent(general-purpose)

This blocks the agent from delegating to Explore or general-purpose subagents. Useful when you want an agent to do its own work rather than further delegating.

Permission Modes

The permissionMode field controls how the agent handles permission prompts — the dialogs that appear when Claude wants to run a potentially sensitive action.

• default: Standard permission checking. Prompts appear when needed.
• acceptEdits: Auto-accepts file edits within the working directory. No prompt for file writes.
• auto: A background classifier evaluates each action. Safe actions proceed automatically; risky ones are blocked.
• dontAsk: Auto-denies permission prompts. The agent can only use pre-allowed tools without any prompting.
• bypassPermissions: Skips all permission checks entirely. Use only in fully trusted, controlled environments.
• plan: Read-only exploration mode. The agent cannot modify anything.

For automated pipelines where you want agents to run unattended, acceptEdits or auto are common choices. For agents doing sensitive work you want to review, keep the default or use plan mode for an initial pass.

Worktree Isolation

The isolation: worktree field gives a subagent its own temporary git worktree — a separate checkout of the repository in a different directory. The agent works there independently, so its changes do not affect the main working directory or any other agent's work.

---
name: feature-implementer
description: Implements a feature in an isolated git worktree. Safe to run in parallel with other implementers.
isolation: worktree
tools: Read, Write, Edit, Bash
permissionMode: acceptEdits
---

Worktree isolation is particularly valuable when multiple agents are editing code in parallel. Without isolation, two agents writing to the same file at the same time will overwrite each other's work. With worktrees, each agent works in its own branch and directory — no conflicts.

After the agent finishes, you can merge its worktree branch into the main branch, discard it, or inspect it before deciding.