Skip to content

Declare explicit tool grants for the user-level subagents - #85

Open
mattmenefee wants to merge 1 commit into
mainfrom
claude-agent-tool-declarations
Open

Declare explicit tool grants for the user-level subagents#85
mattmenefee wants to merge 1 commit into
mainfrom
claude-agent-tool-declarations

Conversation

@mattmenefee

Copy link
Copy Markdown
Owner

Summary

  • Replaces the rotted tools: list on test-suite-architect, which pinned individual Serena tool names the MCP server has since renamed, plus built-ins that no longer exist (LS, NotebookRead) and one Claude Code strips from every subagent (ExitPlanMode). Unresolvable entries are dropped silently — only a list where nothing resolves raises an error — so the agent had been launching quietly under-powered.
  • Grants Write and Edit to test-suite-architect, which authors spec files but previously depended on the harness back-filling those from its preloaded skills.
  • Declares tools: on the agents that had none (documentation-expert, elasticsearch-expert, postgresql-expert, ruby-on-rails-expert, ui-ux-design-specialist). Omitting the field inherits every tool from every configured MCP server, which gave a PostgreSQL adviser reach into Linear, Harvest, Heroku and two browser-automation stacks.
  • Uses server-level wildcards (mcp__serena__*) for MCP access rather than enumerating tool names, so a renamed upstream tool can't silently vanish from the grant the way it did before.
  • Adds Skill and ToolSearch throughout — without them an agent can neither invoke a project's slash commands nor load a deferred tool schema.
  • Adds domain-scoped MCP access where the brief calls for it: Elastic for the search expert, RuboCop for the Rails expert, Chrome DevTools (for lighthouse_audit) for the accessibility remit.
  • Leaves code-best-practices-reviewer and security-reviewer on their disallowedTools denylists. An allowlist resolves after the denylist rather than alongside it, so adding one would have narrowed them to only the listed tools and stripped the file-reading and search tools they depend on.

Three grants are judgment calls rather than mechanical fixes, and are the parts worth a second opinion: mcp__elastic-agent-builder__* on the search expert, mcp__rubocop__* on the Rails expert, and mcp__chrome-devtools__* on the design specialist. The Chrome DevTools grant deliberately does not extend to mcp__playwright__*, since the alice conventions prefer driving @playwright/cli through Bash.

Test plan

  • Each edited agent launches without the Agent would be spawned with zero tools error
  • test-suite-architect can create and edit a spec file, and can invoke /lint and /test through the Skill tool
  • ruby-on-rails-expert reaches the RuboCop MCP server; elasticsearch-expert reaches the Elastic server in a project where it is configured
  • ui-ux-design-specialist can run a Lighthouse audit
  • code-best-practices-reviewer and security-reviewer still read and search files, and still cannot write or edit
  • An agent in a repo without the project-scoped servers (RuboCop, Elastic) still launches, with the unresolved entries ignored

The test-suite-architect definition pinned individual Serena tool names
that the MCP server has since renamed, alongside built-ins that no
longer exist (LS, NotebookRead) and one that Claude Code strips from
every subagent (ExitPlanMode). Unresolvable entries are dropped
silently — only a list where nothing at all resolves raises an error —
so the agent had been launching quietly under-powered. It also withheld
Write and Edit from the one agent whose job is authoring spec files,
leaving it dependent on the harness back-filling them from its
preloaded skills.

The remaining agents declared no tools whatsoever and so inherited
every tool from every configured MCP server, handing a PostgreSQL
adviser reach into Linear, Harvest, Heroku and two browser-automation
stacks. Each now declares what its brief actually calls for, using
server-level wildcards for MCP access so a renamed tool cannot
silently vanish from a grant the way it did before. Skill and
ToolSearch are granted throughout, without which an agent can neither
invoke a project's slash commands nor load a deferred tool schema.
Domain-specific additions follow the same reasoning: Elastic for the
search expert, RuboCop for the Rails expert, and Chrome DevTools for
accessibility auditing.

The two review agents keep their disallowedTools denylist untouched.
An allowlist resolves after the denylist rather than alongside it, so
adding one would have narrowed them to only the listed tools and
stripped the file-reading and search tools they depend on.
@mattmenefee mattmenefee self-assigned this Jul 29, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant