Allow custom agent definitions with specific tools, permissions, and system prompts for team recruitment #32357

Feature Request

Problem

Currently, Claude Code has two separate agent systems with complementary but non-overlapping capabilities:

• Agent Teams (TeamCreate): Spawn independent Claude Code sessions that work in parallel and can communicate with each other. However, all teammates inherit the project's CLAUDE.md, the lead's permission settings, and have access to all tools — with no way to customize per-teammate at spawn time.

• Sub-agents (Agent tool): Support custom system prompts, per-agent tool whitelists/denylists, per-agent permission modes, and per-agent models. However, sub-agents cannot communicate with each other — they only report back to the caller.

There is no way to get a team member (with inter-agent communication) that also has a fully custom system prompt and restricted tool set (like a sub-agent).

Proposed Solution

Allow developers to define custom agent profiles that can be recruited as teammates. Each agent definition would specify:

• Custom system prompt — independent of project/user CLAUDE.md, tailored to the agent's role (e.g., a "Security Reviewer" agent with security-focused instructions)
• Tool whitelist/denylist — restrict which tools the agent can use (e.g., a "Read-Only Analyst" that can only use Read, Grep, Glob)
• Permission mode — set per-agent permissions at spawn time
• Skills — assign specific skills to the agent
• Model — optionally specify a different model for cost/speed optimization

These could be defined in a project-level config file (e.g., .claude/agents/security-reviewer.md or a section in CLAUDE.md) and then referenced when the team lead recruits teammates.

Example Usage

# .claude/agents/security-reviewer.yaml
name: security-reviewer
system_prompt: |
  You are a security reviewer. Focus exclusively on identifying
  vulnerabilities, insecure patterns, and OWASP top 10 issues.
  Do not modify code — only report findings.
tools:
  allow: [Read, Grep, Glob, Agent]
  deny: [Edit, Write, Bash]
permissions: plan
model: claude-sonnet-4-6
skills: [web-design-guidelines]

The team lead could then recruit this agent:

TeamCreate: Recruit "security-reviewer" to audit the authentication module

Benefits

• Separation of concerns: Each agent has a focused role with appropriate access
• Security: Restrict destructive tools for agents that should only analyze, not modify
• Cost optimization: Use cheaper/faster models for simpler agent roles
• Reusability: Define agent profiles once, recruit them across tasks
• Team composition: Build teams with specialized agents (reviewer, coder, tester, architect) that can collaborate while staying within their defined boundaries

Current Workaround

Today, the closest workaround is using sub-agents with custom prompts and tool restrictions, orchestrated by the main agent — but these lack inter-agent communication. Alternatively, teams can be used with spawn prompts to guide behavior, but teammates still see CLAUDE.md and have access to all tools with no enforcement.

🤖 Generated with Claude Code