Feature Request: Add `disallowed-tools` to sub-agent frontmatter for more flexible permissions

Resolved 💬 3 comments Opened Aug 18, 2025 by coygeek Closed Jan 6, 2026

Title: Feature Request: Add disallowed-tools to sub-agent frontmatter for more flexible permissions

Body:

Is your feature request related to a problem? Please describe.

Currently, sub-agent permissions are managed via a tools key in the frontmatter, which acts as an explicit allowlist. This is great for sub-agents that only need a few specific tools.

However, for sub-agents that should have broad capabilities except for a few dangerous ones (e.g., a "code-reviewer" that can read files and run diagnostics but should never write files or execute destructive commands), the current system is cumbersome. The user must manually list every single safe tool (Read, Grep, Glob, LS, etc.).

This approach has two main drawbacks:

  1. Maintenance Burden: It's verbose and difficult to maintain a long list of allowed tools.
  2. Not Future-Proof: If a new, safe tool is added to Claude Code in a future update, every sub-agent definition must be manually updated to include it.
Describe the solution you'd like

I propose adding a disallowed-tools key to the sub-agent's markdown frontmatter. This would function as a denylist, providing a more flexible "deny by exception" permission model.

The permission logic would work as follows:

  1. If the tools (allowlist) key is present in the frontmatter, it is used exclusively, and the disallowed-tools key is ignored. This maintains existing behavior.
  2. If the tools key is not present, the sub-agent inherits all available tools from the parent session except for those explicitly listed in the disallowed-tools key.
Example Use Case

Creating a safe code-reviewer sub-agent that has access to all current and future read-only and diagnostic tools, but is explicitly prevented from making changes.

Before (Current Method - brittle and verbose):

---
name: code-reviewer
description: Reviews code for quality, style, and potential bugs.
tools: Read, Grep, Glob, LS, Bash(git diff:*), Bash(npm run lint) # Must list every single allowed tool...
---

You are an expert code reviewer. Analyze the recent changes...

After (Proposed Solution - flexible and secure):

---
name: code-reviewer
description: Reviews code for quality, style, and potential bugs.
disallowed-tools: Write, Edit, MultiEdit, NotebookEdit, Bash(rm*), Bash(git commit:*)
---

You are an expert code reviewer. Analyze the recent changes...

This new version would automatically inherit all other tools (like Read, Grep, WebSearch, etc.) while remaining secure against destructive actions.

Describe alternatives you've considered

The only alternative is to continue using the explicit tools allowlist, which suffers from the maintenance and future-proofing issues described above.

This feature would significantly improve the usability and security of custom sub-agents. Thank you for considering it

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗