[FEATURE] Allow custom .claude/agents/ definitions as agent team teammates

Preflight Checklist

I have searched existing requests and this feature hasn't been requested yet
This is a single feature request (not multiple features)

Problem Statement

Agent teams currently spawn all teammates as undifferentiated general-purpose agents. The only way to specialize a teammate is through the natural language prompt the team lead writes at spawn time. Meanwhile, the subagent system (.claude/agents/ files) supports rich customization — tool restrictions, permission modes, scoped hooks, persistent memory, preloaded skills, and custom models — but subagents can only report back to a parent and cannot communicate with each other.

This creates a gap: if you need agents that are both specialized (different tool access, different constraints) and collaborative (messaging each other, sharing a task list), neither system works.

Concrete problems this causes:

No tool isolation between teammates. You can't spawn a "researcher" teammate restricted to read-only tools alongside an "implementer" teammate with full write access. Every teammate gets the lead's full permission set, violating least-privilege.
No per-teammate hooks. Subagents support PreToolUse hooks (e.g., validating Bash commands are read-only SQL). Teammates cannot. You can't enforce that a "db-analyst" teammate only runs SELECT queries while a "code-writer" teammate has unrestricted Bash.
No persistent memory for teammates. Subagents support memory: user|project|local for cross-session learning. Teammates start fresh every time. A "code-reviewer" teammate can't build institutional knowledge across team sessions.
No skill preloading for teammates. Subagents can preload domain-specific skills into their context. Teammates rely entirely on whatever the lead puts in the spawn prompt.
Prompt-only specialization is fragile. Natural language prompts can be ignored, misinterpreted, or overridden by the model. Tool restrictions and hooks are deterministic enforcement mechanisms — a teammate with tools: Read, Grep, Glob physically cannot write files, regardless of what it's asked to do.

Proposed Solution

Allow agent team teammates to be spawned from .claude/agents/ definitions, inheriting all customization that subagents currently support.

User experience:

Create a team to refactor the authentication module. Spawn these teammates:
- A "researcher" using my code-reviewer agent (read-only, Haiku)
- An "implementer" using my debugger agent (full tools, inherits model)
- A "validator" using my db-reader agent (Bash with SQL validation hooks)

Or more explicitly:

Spawn a teammate from the code-reviewer agent definition to review PR #142

The team lead would reference agent definitions by name, and the teammate would inherit that agent's:

tools / disallowedTools — tool restrictions
model — model selection
permissionMode — permission behavior
hooks — lifecycle hooks (PreToolUse, PostToolUse, Stop)
skills — preloaded domain knowledge
memory — persistent cross-session memory
System prompt (the markdown body of the agent file)

The spawn prompt from the lead would be appended as additional context, not replace the agent's system prompt.

Config representation — the team config would reflect the agent type:

{
  "name": "researcher",
  "agentType": "code-reviewer",
  "model": "haiku",
  "prompt": "Review the authentication module at src/auth/ for vulnerabilities..."
}

Instead of every teammate being "agentType": "general-purpose".

Alternative Solutions

Current workaround: subagents instead of teams. For specialized agents, I use the Task tool with custom subagent types. This gives me full customization but loses inter-agent communication — subagents report back to the parent and can't message each other. For tasks requiring both specialization and collaboration, there is no workaround.

Possible lighter alternative: per-teammate overrides at spawn time. Instead of requiring full .claude/agents/ files, allow the team lead to specify tool restrictions and other properties inline when spawning:

Spawn a read-only researcher teammate with tools: Read, Grep, Glob and model: haiku

This would be simpler to implement but less reusable than referencing agent definitions.

Another alternative: let subagents message each other. Instead of bringing customization to teams, bring collaboration to subagents. This would be a larger architectural change but would close the gap from the other direction.

Priority

High - Significant impact on productivity

Agent teams are powerful for parallel work, but the lack of per-teammate customization makes them unsuitable for workflows where different agents need different capabilities. This forces a choice between specialization (subagents) and collaboration (teams) when many real-world tasks need both.

Feature Category

Developer tools/SDK

Use Case Example

Scenario: Multi-agent codebase refactoring with safety constraints

I'm refactoring an authentication system that touches the database, API layer, and frontend
I want a team where:
- A researcher (read-only, Haiku) explores the codebase and identifies all auth-related code paths
- An architect (read-only, plan mode required) designs the migration strategy and gets my approval before anyone writes code
- A backend implementer (full tools, has PreToolUse hook preventing direct DB mutations — must use migration files) implements the API changes
- A frontend implementer (tools restricted to src/frontend/** via hooks) implements the UI changes
- A test writer (full tools, persistent memory to remember test patterns across sessions) writes and runs tests
Currently, all five teammates get identical capabilities. The researcher could accidentally write files. The frontend implementer could modify backend code. The backend implementer could run raw SQL. Safety depends entirely on prompt compliance.
With this feature, each teammate would have deterministic capability boundaries enforced by tool restrictions and hooks, while still being able to message each other, share a task list, and coordinate through the team lead.

Additional Context

The building blocks already exist. The subagent system already parses .claude/agents/ files, applies tool restrictions, configures hooks, manages memory directories, and preloads skills. The agent team system already spawns independent sessions, manages messaging, and coordinates task lists. This feature request is about connecting the two — letting the team spawner use agent definitions instead of always defaulting to general-purpose.

Relevant documentation:

Agent teams — current team capabilities and limitations
Custom subagents — the customization system that teammates should be able to use

Current limitation explicitly documented:

"Teammates start with the lead's permission settings. [...] you can't set per-teammate modes at spawn time." — agent-teams.md

This limitation should be lifted by allowing teammates to inherit permissions from their agent definition.

Found 3 possible duplicate issues:

This issue will be automatically closed as a duplicate in 3 days.

If your issue is a duplicate, please close it and 👍 the existing issue instead
To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

Would love this to be implemented asap ❤️ Amazing idea!

Agreed this would be very helpful!

This would be a killer feature, especially us who have invested a lot of time and energy defining and tuning our own custom agents. To be able to define a "team" - create a team-manifest - would be game-changing.

Related: #24505 proposes the hook-system counterpart - teammate metadata in hook input, per-teammate hook configuration, and a TeammateSpawn event for validating team composition at spawn time.
In this scenario we have capability boundaries (#24316) and behavioral validation (#24505).

Agreed, this feature request is the natural next step to take for the Claude Code team and I'd be very surprised if it's not implemented soon.

Users can already begin interactive sessions with the command "claude --agent {agent_name}"

Giving the Team Lead the ability to do this would unlock much better determinism and customization when designing workflows for agent teams - and it builds on the existing primitives.

The next step after this would be to add a "teams" feature alongside commands, skills, agents, etc. This would allow users to create predefined agent teams, composed of their existing custom agents. Users could optionally add additional front matter fields per agent in the team file for things such as hooks and skills.

I have been looking for exactly this. Context focus is huge. Having separation of context with agents in agent teams is absolutely critical.

Hope this to be implemented ASAP ❤️

Been hitting this exact limitation in my project. I have custom backend and frontend agents defined in .claude/agents/ with specific tool restrictions and workflows for my repo. When I try to use Agent Teams to orchestrate them, I can't actually load those agent definitions as teammates.

What I really need: let me define which agents the orchestrator spawns, and how it calls them. I want to customize both the orchestrator and the agent composition, while still using Agent Teams' built-in dispatch and observation flow. Would love to see this land soon.

"Specialized agents + collaborative messaging" - The lack of per-teammate customization is a real gap in Claude Code's agent teams.

Your pain points:

No tool isolation between teammates
No per-teammate hooks
Prompt-only specialization is fragile
Can't enforce "researcher is read-only while implementer has write access"

On the "prompt-only specialization is fragile" point:
You're absolutely right. Natural language prompts can be overridden by the model when it thinks it knows better. You need deterministic enforcement mechanisms, not just instructions in CLAUDE.md.

The mobile approval angle:
While ForkOff doesn't solve multi-agent orchestration (we focus on mobile approval for individual Claude Code sessions), the broader issue here is lack of control. When you're running 5 specialized agents and one tries to bypass restrictions:

Terminal-only workflow: You need to be at your desk watching terminal output to catch it
Mobile approval workflow: You get push notification, see exactly what the agent wants to do, deny before damage is done

For your use case (auth refactoring with 5 specialized agents):
The frustration you're describing - agents not respecting their assigned constraints - is why mobile approval gates matter. Even if prompts fail, you have a human checkpoint before execution.

The real solution needs to come from Anthropic (proper per-teammate tool restrictions in agent teams). Until then, explicit mobile approvals at least give you visibility and control.

Just launched mobile approval for Claude Code this week. Waitlist at https://forkoff.app

(Disclosure: I work on ForkOff. We don't solve the multi-agent orchestration problem you're describing, but we do solve the "I need to oversee agents without being desk-bound" part.)

I've built a multi-agent orchestrator (Bernstein) that does exactly this -- role-based agent definitions with per-role constraints, model selection, and completion verification. Sharing what works in practice after running this against our own codebase for months.

Here's the format we settled on:

# .claude/agents/backend.yaml
name: backend
description: Backend engineer specializing in API and data layer
model_policy:
  high_complexity: opus
  medium_complexity: sonnet
  low_complexity: haiku
allowed_paths: ["src/api/", "src/models/", "src/services/", "tests/"]
denied_paths: [".github/*", "src/frontend/", "templates/roles/*"]
completion_signals:
  - type: test_passes
    command: "pytest src/api/ -x -q"
  - type: test_passes
    command: "pyright src/api/"
max_tasks_per_session: 3

Two things matter more than the format itself:

Path constraints are not optional. Without denied_paths, agents step on each other. A backend agent will "helpfully" fix a frontend bug it notices. Worse: we found that giving QA agents write access to source code led to them "fixing" bugs instead of writing tests. Explicit allowed_paths / denied_paths per role eliminated entire categories of wasted work and merge conflicts.

Model-per-complexity saves real money. Low-complexity tasks (rename a variable, add a docstring) do not need Opus. Our orchestrator routes low to Haiku, medium to Sonnet, high to Opus based on task metadata. This cut our API spend roughly in half without measurable quality loss on simple tasks.

Completion signals make verification deterministic. Instead of trusting the agent's claim that it's done, the janitor runs test_passes, path_exists, and file_contains checks. If signals fail, the task gets sent back or a fix task is auto-created. No human in the loop for routine verification.

One request: please make whatever format you choose tool-agnostic. We run Claude Code, but also Codex and Gemini CLI through the same role definitions via adapter layers. If .claude/agents/ only works with Claude Code, every orchestrator has to maintain parallel formats. A shared spec under .agents/ or a documented schema that other tools can adopt would be far more useful to the ecosystem.

Issue #24316 Verification

Title: [FEATURE] Allow custom .claude/agents/ definitions as agent team teammates
Issue Date: 2026-02-09
Verification Date: 2026-04-06
Status: PARTIALLY RESOLVED

Issue Summary

This issue requests that agent-team teammates be able to use custom .claude/agents/ definitions, with the same specialization surface available to subagents rather than relying only on prompt wording. The requested behavior includes inheriting configuration such as tool restrictions, model, permission mode, hooks, skills, and persistent memory.

Verification Results

Claim 1: The docs now show that teammates can be spawned from subagent definitions

Status: RESOLVED

At https://code.claude.com/docs/en/agent-teams, lines 236-246, the docs now state that when spawning a teammate, you can reference a subagent type from any subagent scope, and that the teammate honors that definition's tools allowlist and model, with the definition body appended to the teammate's system prompt.

At https://code.claude.com/docs/en/sub-agents, line 199, the subagents page also states that subagent definitions are available to agent teams and that a teammate uses the definition's tools and model.

At https://code.claude.com/docs/en/changelog, line 993, the changelog documents a teammate-specific fix: "Fixed custom agent model field in .claude/agents/*.md being ignored when spawning team teammates."

Verdict: The official docs now document a partial version of the requested feature. Teammates can use named subagent definitions, and the docs explicitly cover inherited tools, model, and prompt-body behavior.

Claim 2: The requested per-teammate permission behavior is now documented as inherited from agent definitions

Status: UNRESOLVED

At https://code.claude.com/docs/en/agent-teams, lines 252-255, the current docs say: "Teammates start with the lead's permission settings... After spawning, you can change individual teammate modes, but you can't set per-teammate modes at spawn time."

The limitations section repeats this at https://code.claude.com/docs/en/agent-teams, line 415: "Permissions set at spawn: all teammates start with the lead's permission mode."

Verdict: The documentation explicitly states the opposite of the requested permissionMode inheritance behavior. Per-teammate permission settings at spawn are still not documented as supported.

Claim 3: The docs now show teammates inheriting the full subagent customization surface requested in the issue

Status: UNRESOLVED

The subagent frontmatter reference at https://code.claude.com/docs/en/sub-agents, lines 230-239, lists permissionMode, skills, mcpServers, hooks, and memory among the supported subagent fields.

But the teammate-specific section at https://code.claude.com/docs/en/agent-teams, lines 246-249, only says that teammates honor tools and model, append the definition body as instructions, and explicitly notes that the skills and mcpServers frontmatter fields are not applied when that definition runs as a teammate.

The same teammate section does not document hooks or memory from subagent definitions as carrying over to teammates.

Verdict: The current docs describe partial teammate inheritance, not the full .claude/agents/ customization model requested in the issue. Some requested capabilities remain explicitly excluded, and others are still not documented as teammate features.

Current State

Claim	Status
Teammates can use subagent definitions	RESOLVED
Per-teammate permission mode at spawn	UNRESOLVED
Full inheritance of subagent features (`skills`, `mcpServers`, `hooks`, `memory`, etc.)	UNRESOLVED

Suggested Fix

If Anthropic intends this issue to remain open, the remaining work is not just a documentation tweak. The product/docs gap is that agent teams currently document only partial subagent-definition support. To fully satisfy the request, teammates would need to inherit the remaining requested configuration surface, especially permissionMode, and the docs should include an explicit compatibility table showing which subagent frontmatter fields do and do not apply when the definition is used for a teammate.

References

URL: https://code.claude.com/docs/en/agent-teams
Lines 236-249: Documents using subagent definitions for teammates, honoring tools and model, and explicitly excluding skills and mcpServers
Lines 252-255: States teammates start with the lead's permission settings and cannot set per-teammate modes at spawn time
Line 415: Repeats that all teammates start with the lead's permission mode
URL: https://code.claude.com/docs/en/sub-agents
Line 199: States subagent definitions are available to agent teams and teammates use tools and model
Lines 230-239: Lists subagent frontmatter fields including permissionMode, skills, mcpServers, hooks, and memory
URL: https://code.claude.com/docs/en/changelog
Line 993: Documents the fix for custom agent model when spawning team teammates

Conclusion & Recommendation

Primary Concern: Whether agent teams now support custom .claude/agents/ teammate definitions with the full subagent customization surface requested in the issue.

Resolution Status: PARTIALLY RESOLVED

Recommendation: KEEP OPEN

The docs now clearly document that teammates can be spawned from subagent definitions and inherit tools, model, and prompt-body instructions. But the issue asked for much broader inheritance, and the current docs still explicitly exclude some requested fields and retain the lead-owned permission model at spawn.

@imports

+1 from a production use case. We just spent a day building exactly the team this FR describes and ran straight into the limitation. Posting the evidence in case it's useful for prioritization.

Setup

A persistent 5-agent team for a media/finance business:

1 lead (orchestrator role) at ~/.claude/agents/lead.md, model opus
4 specialists at ~/.claude/agents/{a,b,c,d}.md, each with:
- distinct model (mix of opus and sonnet)
- distinct tools: allowlist (some need mcp__qmd__* from a custom MCP server, others don't)
- a substantial body (200+ lines) defining role, principles, and operating rules
- their own workspace at ~/agent-workspaces/<name>/ with a workspace CLAUDE.md chain
- their own memory at ~/.claude/agent-memory/<name>/

The intent: spawn the lead, then TeamCreate to bring the four specialists in as in-process teammates so they can communicate via SendMessage while each retaining their definition, workspace, MCP access, and memory.

What we observed (Claude Code v2.1.89, in-process backend, macOS)

After TeamCreate + spawning all 4 specialists, three of the four independently reported a variant of:

"I am the lead. My cwd is the lead's workspace. The qmd MCP server is not available. I cannot find my own SOUL/role definition."

The fourth got stuck in its boot prompt and never produced a turn (separate issue, see #34476 comment).

Inspecting ~/.claude/teams/<team>/config.json after spawn confirmed the inheritance breakage at the config layer:

{
  "members": [
    { "name": "lead", "agentType": "lead", "model": "claude-opus-4-6", "cwd": "/Users/.../agent-workspaces/lead", ... },
    { "name": "a",    "agentType": "a",    "model": "claude-opus-4-6", "cwd": "/Users/.../agent-workspaces/lead", ... },
    { "name": "b",    "agentType": "b",    "model": "claude-opus-4-6", "cwd": "/Users/.../agent-workspaces/lead", ... },
    { "name": "c",    "agentType": "c",    "model": "claude-opus-4-6", "cwd": "/Users/.../agent-workspaces/lead", ... },
    { "name": "d",    "agentType": "d",    "model": "claude-opus-4-6", "cwd": "/Users/.../agent-workspaces/lead", ... }
  ]
}

Four distinct things broke at once:

cwd is set to the lead's cwd for every teammate, even though each specialist's workspace is at ~/agent-workspaces/<name>/. Consequence: the workspace CLAUDE.md chain that loads operational rules, paths, and integration credentials never loads. The teammate boots in the wrong directory.
model is forced to the lead's model regardless of what each specialist's frontmatter declares. Three specialists are configured as sonnet for cost reasons; all four ran as opus. (This is also tracked in Agent Teams: Spawned teammates don't inherit model configuration from team lead #32368, Agent teams (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS) ignore modelOverrides when spawning subagents #41045, Agent Teams teammates ignore model/auth environment variables (incomplete fix from #23561) #32987, [BUG][Bedrock] Agent Teams teammates spawned with non-Bedrock model ID via --model flag, causing 400 errors #23561 — the underlying root cause has been known for a while.)
The body of ~/.claude/agents/<name>.md is not appended to the teammate's system prompt. The 200+ line role definition (the agent's "SOUL") is silently dropped. This is the most user-visible symptom — the teammate has no identity at all and answers as a generic Claude or as the lead.
tools: allowlist is not honored, MCP servers from the teammate's workspace are not loaded. Specialists that depend on custom MCP servers (in our case qmd for cross-corpus search) report the tool as unavailable. The teammate ends up with the lead's tool surface, not its own.

The doc quote in this FR's body —

"Teammates start with the lead's permission settings. [...] you can't set per-teammate modes at spawn time."

— understates it in practice. It's not just permission modes; it's cwd, model, the agent body, and the entire MCP/tool surface. From a user perspective, in-process teammates spawned via TeamCreate are effectively clones of the lead with a different name field.

Comparison: same definitions via headless CLI work perfectly

The same four definition files, dispatched via:

cd ~/agent-workspaces/<name> && claude -p --agent <name> "task..."

…load everything correctly:

✅ correct cwd (verified with pwd)
✅ correct model (verified by asking the agent its model ID)
✅ full body / SOUL loaded (each specialist self-identifies with phrases from its own definition)
✅ workspace CLAUDE.md chain loaded (workspace-specific paths, integrations, MEMORY_PROTOCOL @imports all present)
✅ workspace MCP servers loaded (mcp__qmd__* available)
✅ episodic memory written automatically on Stop hook to ~/.claude/agent-memory/<name>/YYYY-MM-DD.md (no extra config needed; the existing user-scope hook fires from the subprocess)

So the definition-loading code path exists and is correct. The gap is exactly what this FR describes: the TeamCreate in-process spawn pipeline does not run that pipeline for teammates — it spawns them as bare general-purpose agents and stamps the agentType field after the fact.

Workaround we adopted

We abandoned TeamCreate for our team and built a thin dispatch helper around claude -p --agent <name>:

# dispatch.sh — validates that the task file contains a quality checklist
# (role, absolute paths, success criteria, error handling, file hygiene, context),
# then cd's to the agent's workspace and invokes claude -p --agent <name>.
# Same script is used by our cron tasks. Stop hook handles memory persistence.

This works for us today, and it preserves identity / cwd / model / tools / MCP / memory correctly. What it loses is exactly the value proposition of agent teams: persistent in-process teammates that can SendMessage each other directly without going through the lead. For our orchestration pattern (lead routes work to specialists, specialists report back) the headless pattern is actually fine. For workflows that genuinely need direct teammate-to-teammate messaging, there's currently no viable path because of this FR.

Why this matters for prioritization

The four breakages above are the same issue (definition not loaded for teammates), just observed at four different layers. Fixing the underlying gap — running the same definition-loading pipeline for teammates that claude -p --agent <name> already runs — would close all four at once and unblock real production use cases like ours.

Happy to provide more reproduction artifacts, anonymized configs, or test against a patch.

This has been a big problem for me! I spent a lot of time on my own custom agent team assuming that it worked with custom agent, until I realized it was general agents :(

The whole value of an agent teams for me is being able to use my own, in particular being able to ensure there's no violations in terms of read-write access and passing structural checks.

Seems like it's a bug based on #30703 though, probably will be addressed at some poit

@ilkerbbb

+1, confirming still broken on v2.1.101 (macOS Darwin 24.6, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1), 12 versions after @ilkerbbb's v2.1.89 report. Adding one data point that isn't yet in the thread.

`memory:` frontmatter is silently dropped for teammates

@coygeek's verification table left memory in the UNRESOLVED row without explicit testing. I can confirm the result: declaring memory: project in a teammate's .claude/agents/*.md definition has no effect. The .claude/agent-memory/<agent-name>/MEMORY.md file that would normally be loaded into the agent's system prompt is simply not loaded when that definition runs as a teammate. For pure subagents on the same machine, the same file loads correctly. No error, no warning, no debug output — just an empty memory section.

This is the single most painful omission for any team that wants teammates to accumulate knowledge across sessions. The whole reason to use memory: project instead of reading a file manually is that it arrives at system-prompt authority and is automatically kept in scope. Prompt-only workarounds don't have that property.

Workaround (same shape as @Koriit in #30703, independently)

Same pattern as the #30703 thread: a global SubagentStart hook registered in .claude/settings.local.json (since frontmatter hooks are also dropped for teammates) that reads the per-teammate brain file and emits it as additionalContext:

{"hookSpecificOutput": {"hookEventName": "SubagentStart", "additionalContext": "<brain content>"}}

I can independently confirm @Koriit's finding that hook-injected additionalContext does not persist across turns for teammates. The content arrives on the first turn, then quietly falls out of context on turn 2. We only noticed because our injected content would disappear mysteriously mid-session. We patched it with a Stop hook that re-reads and re-injects the brain file on every turn — same re-injection strategy as @Koriit, arrived at from an independent starting point. That this workaround converges across two separate implementations is a strong signal it's real behavior, not an artifact.

Why this matters for the feature request

For a persistent multi-agent team (in our case, 12 standing teammates with per-agent knowledge bases), the memory: frontmatter is not a nice-to-have — it's the backbone of cross-session compounding. Without it, every teammate starts from zero every session, which defeats the purpose of having a standing team rather than one-shot subagents. The current state forces every team to either (a) build the SubagentStart-hook + Stop-hook + symlink workaround stack from scratch, or (b) manually delegate brain content in the spawn prompt every single time.

Ranked ask

Include memory: in the teammate frontmatter pipeline alongside tools and model. Even if hooks, skills, and mcpServers remain excluded, fixing memory: alone would close the largest gap for persistent-team use cases.
Emit a warning when frontmatter fields are dropped on teammate spawn — even just team teammate 'X': dropped frontmatter fields [memory, skills, hooks, mcpServers] at --debug level. The silent failure is what costs real time; once you know the frontmatter is being dropped, the workaround is obvious.
Document the persistence-across-turns behavior of hook-injected additionalContext for teammates. Whether the answer is "intentional, re-inject on every turn" or "bug, will fix" — either is actionable. The current undocumented silent eviction is the worst case.

Happy to share reproduction detail or test against a patch. Thanks for the excellent platform.

Concrete +1. The current split — Agent Teams teammates are generic and can message each other, but rich customization lives in .claude/agents/ subagents which can't message each other — is exactly the kind of primitive mismatch that accumulates tech debt fast.

What I'd push for specifically: let a .claude/agents/X.md teammate carry its skills, tools, hooks, AND its messaging identity into the team context. In TokenRip (https://tokenrip.com) we treat an agent's capability description as a first-class thing — the agent's profile describes what it can do, what tools it has, what it can accept/reject — and any other agent in the thread can read it before deciding to propose.

Would love to pair on a proof-of-concept bridging .claude/agents/ subagents into Agent Teams via TokenRip's messaging layer as an external substrate. Would give us a working reference even if Anthropic ships their own.

Agree +1 that this is causing agent teams to not function properly.

I've particularly run into issues with the isolation: worktree not being honored when the team members are spawned so they all end up clobbering each other as they try to work in git.

@ofekron

@ofekron agree, and reporting from running this shape in production: identity and capability have to be one durable object. Our version: every teammate is a named handle minted server-side with its own scoped API key (name-driven mint, deduped on owner+name), and the role's constraints hang off that handle rather than prompt text. What that bought us: audit trails that survive session restarts (the handle stays stable when the underlying model or machine changes), revocation that actually revokes (kill the key and the role is gone everywhere), and no read-only reviewer quietly inheriting write tools, because tools attach to the handle rather than to whichever session is playing the role today. Your predicted failure mode is real: before this, our agents were collaborative but stateless and handoffs were prose. Typed handoffs only became enforceable once both ends had durable identities to verify against.

This shipped in a recent release: when spawning a teammate you can name a subagent definition from .claude/agents/ (project, user, plugin, or CLI-defined), e.g. "Spawn a teammate using the security-reviewer agent type". The teammate honors that definition's tools allowlist and model, and its body is added to the teammate's system prompt. Note that skills and mcpServers frontmatter aren't applied to teammates.

Docs: https://code.claude.com/docs/en/agent-teams#use-subagent-definitions-for-teammates · Changelog: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md

🤖 Generated with Claude Code

I ran into this exact problem while building a multi-agent workflow around Claude Code.

I wanted each agent to have a persistent role definition, model, permissions, and skills, while still being able to compose them into a larger workflow. Instead of relying entirely on .claude/agents/ inheritance, I ended up moving the team definition one layer above Claude Code.

The project is open source if anyone wants to see the approach:

hacker room

The basic idea is:

Planner → Coder → Reviewer → Tester → Auditor

Each role runs as its own real Claude Code session, with its own configuration and capabilities, and the orchestrator controls when each member runs.

I'm curious whether something like this belongs natively in Claude Code's agent definitions, or whether keeping the orchestration layer external gives more flexibility.

@SinghAbhinav04

@SinghAbhinav04 we landed in the same place, and the split is the useful part.

Native teammate definitions are the right layer for in-session teams that share a repo and a runtime: role, model, tool allowlist. Boris shipping that (with the caveat that skills and mcpServers still do not travel) covers that shape.

The layer above Claude Code is what you need once the teammates are different products or different machines. We run Claude Code, Codex, Grok and many others as separate processes, each with a named handle and a scoped API key. Identity and capability hang off the handle, not the prompt, so a reviewer cannot quietly inherit write tools and a crashed session cannot keep the role. Orchestration is a shared room: agents @mention each other, a relay delivers, each process replies in its own IDE.

So: keep native definitions for Claude-to-Claude teammates. Keep the external orchestrator when the team is mixed-model or cross-machine. Your Planner → Coder → Reviewer pipeline as real sessions is that second shape. We would not pull it back into .claude/agents/.

Open source for the room/relay half: https://github.com/ThinkOffApp/ide-agent-kit

@ThinkOffApp

@ThinkOffApp Agreed on the split, with one correction to where you put me.

Hackeroom isn't the cross-machine layer. Every member is the same product — Claude Code CLI on one host — differing only by model. No handles, no scoped keys, no relay. It's a third shape: one product, separate processes, enforced boundaries.

Which is why your caveat is the interesting part. Skills and mcpServers not travelling with native teammate definitions is the gap I actually fill: each member's skills are packaged as a plugin loaded with --plugin-dir for that session only, so attaching a long document to one member costs about fifteen tokens of context until it's needed and nobody else can see it. That sits below your layer rather than beside it.

And "identity and capability hang off the handle, not the prompt" is the same claim I'd make about the manifest — written at run start, outside every member's write scope, enforced by a PreToolUse hook rather than requested in a role prompt. A reviewer can't inherit write tools because the hook resolves capability from the member ID, not from anything the session says about itself.

Where I'd want your layer: the moment one seat should be Codex or a different machine. That's a relay problem and I haven't built one. Reading ide-agent-kit now — the append-only receipts are the bit I'm most curious about, since my equivalent is a state file rewritten whole on every event with no locking, which is exactly why only one member runs at a time.

Fixed the isolation fallback, by the way: 5ee0428.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.

Navigation Menu

Repository navigation

[FEATURE] Allow custom .claude/agents/ definitions as agent team teammates #24316

Preflight Checklist

Problem Statement

Proposed Solution

Alternative Solutions

Priority

Feature Category

Use Case Example

Additional Context

21 remaining items

Issue #24316 Verification

Issue Summary

Verification Results

Claim 1: The docs now show that teammates can be spawned from subagent definitions

Claim 2: The requested per-teammate permission behavior is now documented as inherited from agent definitions

Claim 3: The docs now show teammates inheriting the full subagent customization surface requested in the issue

Current State

Suggested Fix

References

Conclusion & Recommendation

Setup

What we observed (Claude Code v2.1.89, in-process backend, macOS)

Comparison: same definitions via headless CLI work perfectly

Workaround we adopted

Why this matters for prioritization

`memory:` frontmatter is silently dropped for teammates

Workaround (same shape as @Koriit in #30703, independently)

Why this matters for the feature request

Ranked ask

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

[FEATURE] Allow custom .claude/agents/ definitions as agent team teammates #24316

Description

Preflight Checklist

Problem Statement

Proposed Solution

Alternative Solutions

Priority

Feature Category

Use Case Example

Additional Context

Activity

github-actions commented on Feb 9, 2026

jatidevelopments commented on Feb 9, 2026

YusufSherif commented on Feb 9, 2026

twistingmercury commented on Feb 9, 2026

frmoretto commented on Feb 11, 2026

Pumpdnz commented on Feb 11, 2026

mikeburb commented on Feb 13, 2026

AlbumenJ commented on Feb 14, 2026

xrliAnnie commented on Feb 15, 2026

ForkyTheBot commented on Feb 15, 2026

21 remaining items

chernistry commented on Apr 6, 2026

coygeek commented on Apr 6, 2026

Issue #24316 Verification

Issue Summary

Verification Results

Claim 1: The docs now show that teammates can be spawned from subagent definitions

Claim 2: The requested per-teammate permission behavior is now documented as inherited from agent definitions

Claim 3: The docs now show teammates inheriting the full subagent customization surface requested in the issue

Current State

Suggested Fix

References

Conclusion & Recommendation

ilkerbbb commented on Apr 6, 2026

Setup

What we observed (Claude Code v2.1.89, in-process backend, macOS)

Comparison: same definitions via headless CLI work perfectly

Workaround we adopted

Why this matters for prioritization

jajanet commented on Apr 10, 2026

Leu-s commented on Apr 10, 2026

memory: frontmatter is silently dropped for teammates

Workaround (same shape as @Koriit in #30703, independently)

Why this matters for the feature request

Ranked ask

aleksandarperak33-hub commented on Apr 21, 2026

mark4code commented on Jun 14, 2026

ThinkOffApp commented on Jul 21, 2026

bcherny commented on Aug 17, 2026

SinghAbhinav04 commented on Aug 23, 2026

ThinkOffApp commented on Aug 23, 2026

SinghAbhinav04 commented on Aug 23, 2026

github-actions commented on Oct 14, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

`memory:` frontmatter is silently dropped for teammates