[Bug] Subagent spawning fails with "inherit" model when using subagent_type from agent files

Bug Description
My spawned team members from existing agents (e.g. subagent_type: product-owner, uses ~/.claude/agents/product-owner.md) are throwing There's an issue with the selected model (inherit). It may not exist or you may not have access to it. Run /model to pick a different model.. If they are spawned without the subagent_type value, they are general-purpose agents and seem to work fine. See chat for details from lead agent's debugging efforts.

Chat Transcript

⏺ All three agents delivered. Shutting down and cleaning up.

⏺ They're not responding to shutdowns — just force-cleaning up.

⏺ Bash(rm -rf ~/.claude/teams/product-spec-m4n8 ~/.claude/tasks/product-spec-m4n8)
⎿  Done

⏺ Done. Stopped.

---
What we learned from this run:

The subagent_type: product-owner agents were completely broken as teammates — even after removing the tool restriction from the definition file, they never responded. Switching to general-purpose
agents with the role described in the prompt worked exactly like the comedy duo: all three delivered their full outputs via SendMessage.

The root finding: the subagent_type parameter, not just the tools list in the markdown file, is what ultimately determines tool availability for custom agent types. Removing tools: from the file may
not be sufficient — the agent type itself may have tool restrictions baked in at a deeper level. Using general-purpose (or omitting subagent_type) is the reliable path for agents that need to
participate in team communication.

❯ USER: When you launch the 3 agents that were successful was that using the TeamCreate tool?

⏺ Yes — TeamCreate was used for all three attempts, including the successful one. The difference wasn't whether TeamCreate was used, but what subagent_type was passed to the Agent tool when spawning
teammates:

• Failed runs: subagent_type: product-owner → custom agent type, broken tool access
• Successful run: subagent_type omitted → defaults to general-purpose → all tools available including SendMessage

TeamCreate itself worked fine every time. The problem was entirely in how the agents were spawned into the team.

❯ USER: do you understand what is happening behind The scenes when you set the subagent_type to product-owner ?

⏺ Partially — here's what I know and where I'm uncertain.

What I know happens:

When you pass subagent_type: product-owner to the Agent tool, Claude Code looks up ~/.claude/agents/product-owner.md, reads the frontmatter, and uses it to configure the spawned agent:

• model: sets the model (or inherits)
• color: sets the UI color
• tools: (when present) hard-restricts which tools the agent gets — this is enforced by the framework, not just advisory
• The body of the file becomes the agent's system prompt

What I'm uncertain about:

Whether the agent definition is read fresh at spawn time or cached at session start. This matters because I edited product-owner.md mid-session and then spawned new agents — and they still behaved as
if the tool restriction was in place. That suggests either:

1. The session caches agent definitions when it loads, so the file change didn't apply until a new session
2. Or something else beyond the markdown file controls tool access for named subagent types

What I observed as the real fix:

Omitting subagent_type entirely bypasses all of this — the agent gets the general-purpose type, which has no tool restrictions and gets everything including SendMessage. That's why the comedy duo and
the final successful run both worked.

The honest answer is: I don't have full visibility into the internals of how Claude Code resolves and caches custom agent definitions. The caching question is the key unknown.

Environment Info

• Platform: darwin
• Terminal: Apple_Terminal
• Version: 2.1.71
• Feedback ID: 200e153e-aac2-44f2-ae40-9c9199b17697

Errors

There's an issue with the selected model (inherit). It may not exist or you may not have access to it. Run /model to pick a different model.

Note: Content was truncated.

edited for grammar 😄