Plugin agent frontmatter `isolation: worktree` not applied at runtime
Description
When a custom agent is defined in a plugin's agents/ directory with isolation: worktree in its frontmatter, the isolation is not applied at runtime. The subagent edits the main working tree directly instead of operating in an isolated git worktree.
Steps to reproduce
- Create a plugin with an agent definition at
agents/patch-worker.md:
---
name: patch-worker
description: "Implements changes in an isolated worktree."
model: sonnet
isolation: worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---
# Patch Worker
You implement a change end-to-end in an isolated worktree.
- Register the plugin (it gets cached at
~/.claude/plugins/cache/<plugin>/<plugin>/<version>/agents/patch-worker.md)
- Invoke the agent via the Agent tool with
subagent_type: "<plugin>:patch-worker"(without passingisolation: "worktree"explicitly in the tool call, since the frontmatter should handle it)
- The subagent edits files directly in the main repo working tree — no worktree is created
Expected behavior
The isolation: worktree field in the agent's frontmatter should be honored, creating a temporary git worktree for the subagent to work in, as documented in the custom subagents docs.
Actual behavior
The frontmatter isolation field is ignored for plugin agents. The subagent runs directly in the main working tree. Changes are applied to the repo immediately with no isolation.
Workaround
Pass isolation: "worktree" explicitly in the Agent tool call. This works correctly — only the frontmatter path is broken.
Environment
- Claude Code (latest as of 2025-03-15)
- macOS Darwin 25.3.0
- Agent resolved via plugin cache at
~/.claude/plugins/cache/
Notes
- The same
isolationfield in.claude/agents/(project-scoped) may or may not have the same issue — not tested. - The
modelfield from the same frontmatter IS correctly applied, so it's not a blanket "frontmatter is ignored" issue — it appears specific toisolation.
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗