[BUG] Custom subagents in .claude/agents/ not recognized by VS Code extension

Status Fixed / completed

Maintainer reply None cached

Activity 4 comments · opened Feb 9, 2026 · closed Feb 9, 2026

Preflight Checklist

[x] I have searched existing issues and this hasn't been reported yet
[x] I can reproduce this bug consistently

Bug Description

Custom subagents defined in .claude/agents/ work correctly in the CLI (claude command in terminal) but are completely unavailable in the VS Code extension. The Task tool in the VS Code extension only recognizes hardcoded built-in subagent types and rejects custom agent names.

Steps to Reproduce

Create a custom subagent at .claude/agents/tdd-planner.md with valid YAML frontmatter:

---
name: tdd-planner
description: Use this agent for planning features using TDD methodology.
tools: Read, Grep, Glob, Bash, WebFetch, WebSearch, AskUserQuestion, TodoWrite
disallowedTools: Write, Edit, NotebookEdit, Task
---

You are a TDD Planning Agent...

In the CLI (terminal): Run claude from the project directory and ask "Use the tdd-planner to plan a feature"

Result: Agent is detected, spawned, and executes correctly following the custom system prompt

In the VS Code extension: Ask the same question

Result: The Task tool attempts subagent_type: "tdd-planner" and fails with:

``Agent type 'tdd-planner' not found. Available agents: Bash, general-purpose, statusline-setup, Explore, Plan, claude-code-guide``

There is also no automatic delegation based on the agent's description field

Expected Behavior

Custom subagents in .claude/agents/ should be available in the VS Code extension with the same behavior as the CLI:

Automatic delegation based on the agent's description field
Tool restrictions from YAML frontmatter (tools, disallowedTools) enforced
Custom system prompt used for the agent's behavior

Actual Behavior

The VS Code extension's Task tool only accepts hardcoded built-in subagent types. Custom agents are completely ignored.

Workaround

Spawning a general-purpose agent and instructing it to read the .claude/agents/*.md file and follow its instructions. This does not enforce YAML frontmatter tool restrictions — the agent has full tool access regardless of disallowedTools.

Impact

Teams cannot share project-specific subagents through version control and have them work consistently across both CLI and VS Code extension, which is the documented use case for .claude/agents/ (project-scoped agents checked into the repo).

Environment

Claude Code VS Code Extension
Platform: Linux (Ubuntu 24.04)
Model: Claude Opus 4.6
Claude Code CLI: Custom agents work correctly in CLI from the same project directory

#23874 (Task tools disabled in VS Code extension due to isTTY check — possibly same root cause)
Subagents documentation

View original on GitHub ↗

4 Comments

github-actions[bot] · 8 months ago

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

hugo-bluecorn · 8 months ago

Update: Additional findings from investigation

During testing, we discovered a separate issue that was causing inconsistent behavior in the CLI: a leading space character (0x20) before the --- YAML frontmatter delimiter in the agent file. This prevented the YAML parser from recognizing the agent definition.

After fixing the frontmatter (ensuring --- starts at byte 0):

CLI: Agent now works consistently and is invoked natively as tdd-planner(...) — not through the Task tool
VS Code extension: Still fails with Agent type 'tdd-planner' not found

This confirms the VS Code extension issue is real and separate from the frontmatter parsing issue:

In the CLI, custom agents are invoked natively by the orchestrator, bypassing the Task tool entirely
In the VS Code extension, agent invocation is routed through the Task tool, which only accepts hardcoded built-in types: Bash, general-purpose, statusline-setup, Explore, Plan, claude-code-guide

Reproduction verified: Even with correctly formatted frontmatter and /agents showing the agent as registered, the VS Code extension Task tool rejects custom agent types.

Environment: Claude Code VS Code extension, Linux, Claude Opus 4.6

hugo-bluecorn · 8 months ago

Closing this issue — the root cause was a malformed YAML frontmatter in the custom agent file (a leading space character before ---), not a VS Code extension limitation.

After fixing the frontmatter and reloading the VS Code window (Developer: Reload Window), custom agents work correctly in the VS Code extension. The startup log confirms Total plugin agents loaded: 0 with the bad frontmatter, and the agent is properly recognized after the fix (SubagentStart with query: tdd-planner).

Reproducible test: clear log, reload window, new session, invoke agent — SubagentStart with query: tdd-planner fires correctly every time.

TL;DR: VS Code extension does support custom agents in .claude/agents/. The YAML frontmatter must start at byte 0 with --- — no leading whitespace.

github-actions[bot] · 7 months ago

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.