isolation: worktree frontmatter not respected when agent invoked via claude --agent
Resolved 💬 3 comments Opened Apr 18, 2026 by nownabe Closed May 25, 2026
Bug Report
Version: 2.1.104
Description:
The isolation: worktree frontmatter in an agent definition file (.claude/agents/*.md) is not respected when the agent is invoked as the main agent via claude --agent <name>. The agent runs in the main worktree instead of a temporary isolated git worktree.
Agent definition file (.claude/agents/issue-handler.md):
---
name: issue-handler
description: >-
Handle a GitHub Issue end-to-end in an isolated worktree.
Use when the user specifies a GitHub Issue number or URL to work on.
isolation: worktree
skills:
- handle-issue
---
Handle the given GitHub Issue using the `/handle-issue` skill.
Pass through all arguments exactly as received.
Steps to reproduce:
- Create
.claude/agents/issue-handler.mdwithisolation: worktreein the frontmatter - Run
claude --agent issue-handler - Observe that the agent runs in the main worktree (verified with
git rev-parse --git-dirreturning.gitdirectory instead of a file pointing to the main repo)
Expected behavior:
The agent should run in a temporary git worktree, as documented for the isolation frontmatter field.
Actual behavior:
The agent runs in the main worktree. git worktree list shows the main worktree is being used.
Notes:
- YAML syntax verified with
cat -A— no hidden characters or formatting issues - The
isolationparameter works correctly when used via theAgenttool (i.e., when spawning a sub-agent), but not when the agent is the top-level main agent via--agentflag
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗