claude-code - 💡(How to fix) Fix isolation: worktree frontmatter not respected when agent invoked via claude --agent [2 comments, 3 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#50357Fetched 2026-04-19 15:22:04
View on GitHub
Comments
2
Participants
3
Timeline
7
Reactions
0
Author
Timeline (top)
labeled ×4commented ×2cross-referenced ×1

Code Example

---
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.
RAW_BUFFERClick to expand / collapse

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

extent analysis

TL;DR

The isolation: worktree frontmatter in the agent definition file is not being respected when the agent is invoked as the main agent, suggesting a potential issue with how the --agent flag handles isolation.

Guidance

  • Verify that the isolation parameter is correctly parsed from the agent definition file by checking the code that handles the --agent flag.
  • Investigate if there's a difference in how the isolation parameter is applied when an agent is spawned as a sub-agent versus being the main agent.
  • Check the documentation for the --agent flag to see if there are any specific options or configurations that need to be set for isolation to work correctly.
  • Consider adding logging or debugging statements to the code that handles agent invocation to see how the isolation parameter is being processed.

Example

No specific code snippet can be provided without more context, but an example of how the isolation parameter might be handled in the agent invocation code could look like:

# Pseudo-code example of agent invocation
if agent_invoked_as_main:
    # Check if isolation is set to 'worktree'
    if agent_definition['isolation'] == 'worktree':
        # Create a temporary git worktree
        create_temp_worktree()
    else:
        # Run in main worktree
        run_in_main_worktree()

Notes

The issue seems to be specific to how the --agent flag handles the isolation parameter, and more investigation is needed to determine the root cause.

Recommendation

Apply a workaround by modifying the agent invocation code to correctly handle the isolation parameter when the agent is invoked as the main agent, as it seems like the current implementation has a bug or inconsistency in how isolation is applied in different scenarios.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING