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:

  1. Create .claude/agents/issue-handler.md with isolation: worktree in the frontmatter
  2. Run claude --agent issue-handler
  3. Observe that the agent runs in the main worktree (verified with git rev-parse --git-dir returning .git directory 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 isolation parameter works correctly when used via the Agent tool (i.e., when spawning a sub-agent), but not when the agent is the top-level main agent via --agent flag

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗