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

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/19276
2. https://github.com/anthropics/claude-code/issues/18212
3. https://github.com/anthropics/claude-code/issues/8697

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.)

Yes it's unfortunate that this isn't yet supported.

The design seems very straightforward - Teammates should simply have the same configuration capabilities that Subagents already have.

Real-world pain point: teammates have no access to the Skill tool

I've built a team orchestration skill that scans a task file, triages blocked/actionable work, spawns teammates via TeamCreate + Task, and monitors progress. The architecture works well, but there's one persistent gap: teammates cannot invoke skills.

The Skill tool is only available in the main conversation context. When I spawn a teammate and assign it a task that requires a domain-specific skill (e.g., one that handles remote server operations, or one that saves session checkpoints), the teammate simply doesn't have the tool. The skill metadata is never injected into its system prompt, and the Skill tool isn't in its tool list.

Current workaround: I inline the full skill prompt content into the teammate's prompt parameter at spawn time. This is fragile (skill content can be 200+ lines), bloats the teammate's context, and breaks whenever the skill is updated — because the lead has to manually re-embed the latest version.

What would help:

1. Give teammates access to the Skill tool (same as the main conversation)
2. Or at minimum, support a skills field in the Task tool spawn config (similar to how .claude/agents/ frontmatter supports skills:) so the lead can declaratively attach skills to teammates at spawn time

This is the most painful limitation I hit when building team orchestration workflows. The agent definitions + tool isolation parts of this issue are important too, but skill access alone would unblock a lot of real use cases.

This is the gap that keeps tripping me up. I want a teammate that only has access to the test runner and another that only touches the API layer, but right now every teammate is a full-powered clone. The subagent route gives you specialization but no inter-agent messaging, and teams give you messaging but no specialization.

We've been running a mixed fleet - Claude, Gemini, Kimi agents each with different tool access - coordinated through a file-based message bus outside of Claude's native teams. Each agent has its own config defining what it can touch, and they communicate through a shared inbox directory. Heterogeneous teams with actual role separation.

If anyone's experimenting with similar setups, we packaged ours as ide-agent-kit. Would be great to see native support for this though - the .claude/agents/ directory is the right place for it.

The subagent route gives you specialization but no inter-agent messaging, and teams give you messaging but no specialization.

the .claude/agents/ directory is the right place for it.

That is 100% the issue.

The requirement is to be able to define a narrow scope of expertise for each Team member, using .MD files in .claude/agents/ directory.

Each Team member then automatically has the required context and skills for its very specific expertise area.

Team members can message each other to facilitate coordination and supportive activities but without overlapping and making conflicting changes.

That would be the perfect implementation of Claude Agent Teams and is probably the functionality originally intended?

Exactly. The .claude/agents/ directory already has the right shape for this - you define the persona and constraints in markdown, and the agent inherits those on spawn. The missing piece is letting those definitions carry through to team coordination so the team lead knows what each teammate can and can't do.

In our setup each agent has its own workspace with config files defining scope, and the coordination layer respects those boundaries. Wrote up how the multi-model version of this works: https://dev.to/petruspennanen/how-i-got-9-ai-agents-to-work-together-across-3-different-ides-1kbm

@chencheng-li the Skill tool limitation is real - we hit that too. Our workaround was giving each agent a scoped inbox directory so they only see tasks relevant to their specialty. The coordination layer handles routing and you define agent capabilities in a simple config instead of trying to get the IDE to manage scopes.

We wrote it up as IDE Agent Kit - filesystem-based message bus, no tmux dependency. Each agent reads from its inbox, does its work, writes receipts. The specialization happens at the routing level rather than inside the IDE.

Would be curious if you have tried defining agent roles through .claude/agents/ yet or if you are doing it differently.

Quick update from our side: we just shipped IDE Agent Kit v0.3.1 which addresses a lot of what this thread is asking for.

The big change: agents running different models (Claude, GPT, Gemini, Kimi, Grok, Mistral) now coordinate through shared rooms in real time. Each agent stays in its own IDE session with its own tools and constraints, but they can see what others are doing and react to it.

The coordination is filesystem + room API based, so it works today without waiting for native .claude/agents/ team support. Still hoping that lands eventually though — native integration would make the setup much cleaner.

2.1.63 fixes this afaict

@Butanium
Can you show me where in the changelog and/or official documentation this is documented.
Or are you saying Anthropic silently implemented this?

Yes in my test I was able to have a teammate spawn with a custom agent

They also changed the hook matches from Task to Agent btw, so you hook won't work anymore if they used Task :)

Agent specific MCP server config still doesn't work though but that's another issue

Quick update: I re-tested on Claude Code 2.1.63 and custom .claude/agents/*.md teammates are working in my environment (agentType + model propagated).

This does not look fully “silent”: the official changelog already includes a related fix in v2.1.47 (February 18, 2026) for custom agent model when spawning team teammates (#26064).
But agent-teams docs still don’t clearly document the full supported teammate field matrix.

Can maintainers confirm which custom-agent frontmatter fields are officially supported for team teammates?

I'd ask Claude to decompile CLI.js rather than waiting for a maintainer to respond :)

Related: we've built IDE Agent Kit (v0.4.0) which adds ACP session orchestration on top of Claude Code's agent teams. It coordinates multiple agents across IDEs (Claude Code, Codex, Cursor, Gemini) through a filesystem message bus and webhook relay. Token-gated, allowlisted, with full receipt audit trail. Available on ClawHub and npm.

The gap between specialized and collaborative described here is exactly what we hit. We run 9 agents with different models and behavioral constraints, coordinated through shared chat rooms via IDE Agent Kit.

Our workaround for tool isolation: each agent runs as a separate process with its own config, and the orchestration layer (IAK) handles message routing. This gives full tool/permission isolation per agent but at the cost of process-level separation. They cannot share in-memory state.

The .claude/agents/ approach described here would be significantly more efficient. One thing worth considering: per-teammate hooks are critical for safety. We had cases where delegated work bypassed validation that was enforced in the main session.

The feature is partially shipped but not officially acknowledged.

Custom agent teammates work for at least agentType and model, but the docs haven't been updated, no maintainer has responded to my question about the full field matrix, and the limitations section still explicitly contradicts the working behavior.

The issue remains open.

Custom agent definitions in .claude/agents/ already work in recent versions. Here's a workaround if you need more flexibility:
A UserPromptSubmit hook can auto-select the right agent based on task type:

PROMPT=$(cat | jq -r '.userPrompt // empty' 2>/dev/null)
[ -z "$PROMPT" ] && exit 0
CONTEXT=""
if echo "$PROMPT" | grep -qiE '(test|spec|coverage|jest|pytest)'; then
    CONTEXT="Use the test-runner agent for this task. Launch it with: Agent tool, subagent_type: general-purpose, with instructions to run and verify tests."
fi
if echo "$PROMPT" | grep -qiE '(review|audit|security|vulnerability)'; then
    CONTEXT="Use the code-reviewer agent for this task. Focus on security, correctness, and edge cases."
fi
if echo "$PROMPT" | grep -qiE '(refactor|cleanup|simplify|optimize)'; then
    CONTEXT="Use the refactor agent. Read the full file before making changes. Preserve all existing behavior."
fi
[ -z "$CONTEXT" ] && exit 0
jq -n --arg ctx "$CONTEXT" '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":$ctx}}'
exit 0

For team-shared agent definitions, put them in the repo:

.claude/agents/
├── test-runner.md      # Testing specialist
├── reviewer.md         # Code review agent  
├── docs-writer.md      # Documentation agent
└── security-auditor.md # Security review agent

Each agent file uses frontmatter to define its behavior:

---
name: test-runner
description: Runs and fixes tests
tools: [Bash, Read, Grep, Glob]
---
You are a testing specialist. Run all tests, diagnose failures, and fix them.

These agent definitions are loaded automatically when Claude Code starts in the project directory.

Update: Partial progress — docs updated March 31, 2026

The official Claude Code docs were updated today with a new section in agent-teams.md: "Use subagent definitions for teammates".

The new section documents that when spawning a teammate, you can reference a subagent type by name from any scope (project, user, plugin, or CLI-defined), and the teammate inherits that subagent's system prompt, tools, and model.

This addresses the core ask — prompt-only specialization was fragile; now you can define a role in .claude/agents/ and reference it by name at spawn time. That resolves concrete problems #4 (skill preloading via system prompt) and partially #1 (tool restrictions).

Still not addressed:

• hooks — PreToolUse/PostToolUse hooks are not inherited by teammates. The deterministic enforcement use case (e.g., a "db-analyst" teammate that physically cannot run non-SELECT queries) is still not possible.
• permissionMode — The limitations section still explicitly states "you can't set per-teammate modes at spawn time." Per-teammate permission modes remain unavailable at spawn.
• memory — Cross-session memory for teammates is not mentioned.

So tool isolation via the tools frontmatter field appears to work now (if the referenced subagent has tools: Read, Grep, Glob, the teammate should inherit those restrictions). But hook-based enforcement and permission modes — the strongest enforcement mechanisms — are still not available per-teammate.

Leaving open until hooks and permissionMode inheritance are addressed.

Additional finding: mcpServers frontmatter does NOT work for teammates

I've built an Agent Teams orchestration framework on top of the native teammate primitives. To work around the previous issue I'd been using a skill to make the team lead send the agent definition as the first prompt as - not ideal by any means but it got the job done while we wait. Today I discovered subagent_type loads custom agents and refactored the framework to use it. Really great progress, but during testing I found the same limitations mentioned by @coygeek, plus one additional limitation worth mentioning:

mcpServers declared in agent frontmatter are NOT inherited by teammates. Teammates only inherit project-level, user-level and plugin-level MCP servers

To be fair, this limitation also occurs when running custom agents as the main interactive session with the "--agent" flag, so it's not only a problem for agent teams.

For my use-case, it matters for parallel browser automation: multiple teammates operating on different web pages simultaneously via Chrome DevTools MCP. Without per-teammate MCP servers, they share a single browser instance and interfere with each other (navigation by one agent breaks the other's page state).

Tested systematically across 10 configurations — sub-agents, teammates, skills with context: fork, and combinations. Key findings:

| Pattern | MCP Isolation? | Parallel Safe? |
|---------|---------------|----------------|
| Concurrent teammates, project-level MCP (same name) | Shared | No — navigation interference |
| Concurrent sub-agents, agent-level MCP (same name) | Shared | No — same server name = same process |
| Concurrent sub-agents, agent-level MCP (different names) | Full isolation | Yes |
| Teammates → forked skills → different agent types | Full isolation | Yes |

The workaround: Each agent definition gets a uniquely-named MCP server in its frontmatter. Different names = different MCP server processes = different browser instances = full isolation. But this only works for sub-agents, not teammates (since teammates don't inherit mcpServers).

For teammates, the current workaround is: teammate spawns a forked skill (context: fork) that delegates to a sub-agent with its own MCP server. This achieves parallel isolation in the browser but defeats the purpose of inter-agent messaging and task delegation in most scenarios.

Would love to see mcpServers inheritance for teammates added alongside the existing tools and model support. hooks, permissionMode, and memory are also key, as mentioned above by @coygeek

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.

+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:

1. 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.
2. 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 #32368, #41045, #32987, #23561 — the underlying root cause has been known for a while.)
3. 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.
4. 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

+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

1. 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.
2. 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.
3. 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.