holocron/plugins/kyberforge/docs/research/docs/claude-code-plugins/troubleshooting.md at 4f73f54b4409b7e9d851dff085925bc443ba93de

Files

Defame1297 4f73f54b44 docs(kyberforge): add Claude Code plugins and subagents research

Research from official docs (code.claude.com) and Context7, covering
plugin manifest schema, agent definition frontmatter spec, scope
priority, marketplace distribution, and plugin subagent restrictions.
Foundation for writing an agent-author skill.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-06-27 10:39:41 +00:00

3.2 KiB

Raw Blame History

topic, source_keys

topic

source_keys

troubleshooting

claude-code-subagents-docs

claude-code-plugins-docs

Agent Files Not Loading

Files added manually to agents/ directories require a full session restart to load. Files created or edited via the /agents UI take effect immediately. Use /reload-plugins inside a session to pick up plugin file changes without restarting.

Duplicate Agent Names

When two agent definitions share the same name within the same scope level, Claude Code silently keeps one and discards the other without warning. Use unique names or rely on scope priority (project .claude/agents/ overrides plugin agents).

Plugin Frontmatter Fields Silently Ignored

Plugin subagents (files in a plugin's agents/ directory) silently ignore hooks, mcpServers, and permissionMode. To use these features, copy the agent file to .claude/agents/ (project scope) or ~/.claude/agents/ (user scope).

permissionMode Overrides

Parent session mode overrides child subagent mode in two cases:

Parent uses bypassPermissions or acceptEdits → child cannot override
Parent uses auto mode → child permissionMode is ignored entirely

bypassPermissions still prompts for root/home directory removals and explicit ask rules.

Model Falls Back Silently

If the model resolved from CLAUDE_CODE_SUBAGENT_MODEL, per-invocation parameter, or frontmatter model is excluded by an availableModels policy, the subagent silently falls back to the inherited model with no warning.

Nesting Depth Limit

Nested subagents are supported up to depth 5 (fixed, not configurable). At depth 5 the Agent tool is withheld from the subagent. A fork cannot spawn another fork. Background subagent depth is fixed at spawn time — resuming from a shallower context does not grant additional depth.

Explore and Plan Cannot Be Resumed

Explore and Plan are one-shot agents and return no agent ID. They cannot be resumed. For work that needs resumption, use the general-purpose subagent.

CLAUDE.md Not Passed to Explore / Plan

The built-in Explore and Plan agents skip CLAUDE.md and git status to keep their context lean. To pass a project rule to these agents, restate it explicitly in the delegation prompt.

MCP Restrictions Apply to Subagent Servers

Enterprise MCP policies (--strict-mcp-config, allowedMcpServers/deniedMcpServers) apply to servers declared in subagent frontmatter mcpServers. Blocked servers generate a warning. Exception: --strict-mcp-config does not filter inline servers passed via --agents or the Agent SDK agents option.

Context Consumption from Parallel Subagents

Running many parallel subagents that each return large result summaries can rapidly consume main conversation context. Scope subagent instructions to return concise summaries, not full verbatim output.

Fork Mode Caveats

Fork mode (/fork, CLAUDE_CODE_FORK_SUBAGENT=1) is experimental. Enabling it forces all subagent spawns to run in the background, not just forks.

Tools Unavailable to All Subagents

These tools are never available to any subagent regardless of the tools frontmatter field:

AskUserQuestion
EnterPlanMode
ExitPlanMode (unless permissionMode: plan)
ScheduleWakeup
WaitForMcpServers

3.2 KiB Raw Blame History