chore(source-control): upstream draft — worktree isolation blocked writes at a non-repo root where the docs say it skips

[kyle-sexton]

This is a DRAFT for a human to file upstream against anthropics/claude-code. It is not work for this repository. Nothing here is fixable in plugins/source-control; the rows are collected so the drafts are not lost, and so nobody re-opens the plugin-side hunt that this batch closed.

Claude Code's documented behavior at a directory that is not a git repository is: attempt isolation, and if the WorktreeCreate hook fails, skip isolation and edit the working directory in place. What was observed instead was writes blocked at a non-repo root — including a write to a temp path outside any checkout — with a refusal message that describes a checkout that does not exist. That is a divergence from documented behavior, and the changelog shows no entry that would have corrected it.

Rows

• I9 SC-F1 (deadlock half only) — plugins/source-control/hooks/hooks.json, plugins/source-control/scripts/worktree-create.sh:258-261 — the gate exits non-zero at a non-repo root (by design); the docs say the session should then skip isolation and edit in place, and it did not. Only the deadlock half is carried here — the plugin-side registration-scope half is filed separately (see cross-links).
• I9 SC-F8 — no file in this repo — the background-isolation write refusal is blanket, not path-scoped, and its message is self-contradicting. HIGH. Packet-sourced; NOT reproduced by the verifier.
• I9 SC-F9 — no file in this repo — two secondary upstream items: a docs anchor that does not exist, and no channel for a WorktreeCreate hook to signal "not applicable" inside a git repository.

Evidence

The doc sentence that settles ownership

https://code.claude.com/docs/en/agent-view, section "How file edits are isolated", fetched 2026-08-11:

"When the hook fails in a directory that isn't a git repository, the session skips isolation for that directory and edits the working directory in place. Inside a git repository, writes stay blocked until the session isolates."

Same page, the skip-bullet list, confirms the no-hook case: isolation is skipped up front when "The working directory isn't a git repository and no WorktreeCreate hook is configured". The two statements are consistent, and together they mean the documented outcome at a non-repo root is writes proceed, whether or not a hook is configured.

Path-scoping is documented separately — https://code.claude.com/docs/en/worktrees, "How Claude Code enforces isolation", fetched 2026-08-11:

"Claude Code blocks an Edit, Write, or NotebookEdit that targets a path in the main checkout"

The observation (packet-sourced, unreproduced)

Session 5559b694-…, background job (CLAUDE_CODE_CHILD_SESSION=1), cwd C:\Users\KyleSexton, win32. git -C … rev-parse --show-toplevel → fatal: not a git repository. Subagent-side refusal, verbatim:

This subagent's parent bg session hasn't isolated yet, so writes to the shared checkout are
blocked. Re-spawn this agent with isolation: "worktree", or have the parent call EnterWorktree
before spawning.

The message is self-contradicting on its own terms: it says "writes to the shared checkout are blocked" while refusing a write to a temp path outside any checkout, at a root that is not a checkout at all. That sentence should lead the upstream report. The main-thread variant refused with the same shape and named worktree.bgIsolation as the remedy. Cost of the incident: a discovery:researcher run lost ~113k tokens of completed work.

Reproduction status — read before filing upstream

The observation has not been reproduced. It is packet-sourced; the auditor states plainly they could not reproduce it, and the verification pass did not either. Reproduction is currently foreclosed on the observing machine: ~/.claude/settings.local.json gained {"worktree":{"bgIsolation":"none"}} at 22:11:48 on 2026-08-10, applied mid-session, and the packet's write-block observations straddle that edit. No duty-cycle claim is made. The setting must be reverted (or a second machine used) before the original behavior can be observed at all. Whoever files upstream should present this as an observation with a verbatim refusal message and an explicit "not yet reproduced" note, not as a confirmed repro.

Version window — the bug is live, not already fixed

https://code.claude.com/docs/en/changelog, fetched 2026-08-11. Newest version listed: 2.1.227 — the same version captured on 2026-08-10. No entry between 2.1.220 and 2.1.227 mentions non-repo isolation, WorktreeCreate fallback, or bgIsolation. The only worktree-isolation entries in that range (2.1.222, 2.1.224) widen isolation to Bash in every session type; 2.1.226 is the opaque "Bug fixes and reliability improvements" stanza. Nothing indicates the observed behavior was corrected after the audit, so this should be written as a live divergence report.

SC-F9 — the two secondary items

1. Missing docs anchor. Two pages link to settings#worktree-settings, which does not exist. Checked by the auditor on 2026-08-10; the settings page was NOT re-fetched during verification — unconfirmed at the current docs revision. Re-check before filing.
2. No "not applicable" channel — narrower than originally filed. At a non-repo root a failing hook now has a documented benign outcome (the agent-view sentence above), so a hook can effectively cede control there by failing. What remains true is the narrower claim: inside a git repository there is no documented channel for a WorktreeCreate hook to say "not applicable" — any non-zero exit fails creation, and exit-0-without-a-path is undocumented in either direction. https://code.claude.com/docs/en/hooks, fetched 2026-08-11, verbatim: "WorktreeCreate | Exit code or hookSpecificOutput.worktreePath | Any non-zero exit code fails creation."

What this settles in our own tracker

Handoff-inbox item 20260811-020411's disposition — "Not this repo — harness, recorded so nobody chases it" — is UPHELD, not reversed. Item 20260811-021645's title claims the deadlock is "probably plugin-owned"; that framing does not survive the docs above. There is no plugin-side deadlock fix, and none should be attempted.

Provenance

Severity: HIGH · Provenance: AUDITOR_VERIFIED — SC-F8 is packet-sourced and was NOT independently reproduced; the SC-F9 docs-anchor leg is auditor-only and unconfirmed at the current docs revision.
Origin: handoff-inbox item 20260811-021645-plugin-audit-four-components-and-guard-deadlock-ownership
Ledger: .work/handoff-inbox-batch-4/ledgers/I9-021645-four-components.md § "Lane D — source-control / worktree-create-gate" (and § "READ FIRST")
Verified against repo HEAD 685dd381.

[kyle-sexton]

Cross-links (handoff-inbox batch 4, lane D — source-control):

• fix(source-control): the WorktreeCreate gate registers unconditionally at user scope, and its newly-reachable opt-out asserts an unverified harness behavior #2211 carries the plugin-side half of SC-F1 (unconditional user-scope WorktreeCreate registration). Only the deadlock half is in this issue; no row was lost in the split.
• fix(source-control): the worktree-create gate's failure output reports a constant exit status, discards the helper's exit taxonomy, and names no remedy #2209 — the gate's failure messages. With the deadlock resolved upstream, that message is the only thing this plugin controls that a stuck user sees, which is why it was promoted rather than dropped.
• worktree: path-scoped rule inheritance in nested worktrees has no open upstream issue — decide whether to file one #1971 — adjacent open question on nested-worktree rule inheritance and whether to file upstream.

Filed as part of a five-issue lane covering 15 verified rows: #2208, #2209, #2211, #2212, #2213.

[kyle-sexton]

Cross-lane: handoff-inbox item 20260810-225904-discovery-dispatch-persistence-contract (I1) F5 is this same upstream defect, reached from the discovery side. Filing a second upstream-draft tracker for discovery would put two drafts against one upstream bug, so I1 F5 is recorded here rather than duplicated. Its independently re-probed conditions match this issue's exactly: cwd C:/Users/KyleSexton, git -C … rev-parse --show-toplevel → fatal: not a git repository, no .git at cwd or any ancestor, background session, no WorktreeCreate hook, and every Write refused with the same verbatim message.

One datum this draft does not currently have, and it should: the refusal was tool-keyed, not path-keyed. In the same session, the same directory tree: "name":"Write" appears 3× with "toolUseResult":"Error: This subagent…" 3× — three attempts, three refusals, zero successes — while .q2rows.json was written successfully by json.dump(...) inside a "name":"Bash" heredoc. A guard that refuses Write at a non-repo root while allowing a Bash-mediated write to the same path is a sharper report than "blanket, not path-scoped," and it narrows what upstream has to look at.

Argue that from the transcript asymmetry only. I1's verifier flagged the original derivation as rationale_falsified: the tool-keyed conclusion was derived from the worktrees page's three isolation checks (Edit/Write/NotebookEdit, command working directory, git redirects), and that section is scoped to "a session already isolated in a worktree" reaching a main checkout. The observed run was never in a worktree and had no checkout, and the guard that fired was the pre-isolation background guard. The check list shows the sibling guard is also tool-keyed — plausible by analogy, not evidence for the guard that actually fired. Do not put it in the upstream text.

One open discrepancy on the doc quote, flagged rather than resolved. This issue quotes "Inside a git repository, writes stay blocked until the session isolates" from a 2026-08-11 fetch of the agent-view page. I1's verifier fetched the same section on the same date and recorded that sentence as not appearing in its fetch — logged as not re-confirmed, explicitly not as removed, since WebFetch summarization means absence is not proof. Per the batch's standing note about WebFetch false-negatives, whoever files upstream should re-check that sentence against raw markdown rather than trusting either fetch. It is not load-bearing for the ownership conclusion either way: the non-repo skip bullet, which both passes confirmed independently, is what carries that.

Adjacent, per I1's dedup: #1971 (nested-worktree path-scoped rule inheritance — same "do we file upstream" decision class, different defect); whoever files this should consider filing both together.

Ledger: .work/handoff-inbox-batch-4/ledgers/I1-discovery-dispatch.md §§ F4, F5. Verified against origin/main 9b34a82a.

[kyle-sexton]

Batch-4 filing note — a second, independent observation of SC-F8, from a different plugin. This issue records that the write refusal was not reproduced; a separate handoff-inbox item captured the same behavior in a run that was not the one this draft is built from, which is worth carrying into the upstream report.

The other run: /claude-config:audit-instructions (not discovery), dispatching two subagents, in a repo-bearing context. Both dispatched agents had Write refused with the same message shape ("This subagent's parent bg session hasn't isolated yet…"), the PreToolUse bypass guard correctly refused the shell-write fallback, and both agents declined the offered self-lifts and returned their findings by value.

Why it matters here specifically: the discovery item's own blindspot section states that "the in-repo variant is untested and is where EnterWorktree / isolation: worktree would actually bite." This run is that untested variant, and the guard behaved the same — so the refusal is not specific to a non-repo root, which sharpens the "blanket, not path-scoped" claim rather than weakening it.

Provenance: SELF_REPORTED. This is a session observation by the run that experienced it; no independent pass reproduced it either, and the same worktree.bgIsolation: "none" setting change that forecloses reproduction on the observing machine applies to it too. It is a second data point, not a reproduction.

Ledger: .work/handoff-inbox-batch-4/ledgers/I6-report-keying-dispatch.md § RKD-10.

[kyle-sexton]

Readiness re-check for filing upstream — 2026-08-11, Claude Code 2.1.228

Re-verified every load-bearing leg against raw markdown (curl of https://code.claude.com/docs/en/<slug>.md, per the upstream-drift fetch route — not a summarizing fetch). Verdict: ready to file, with three corrections applied below. One leg must be removed before filing or the report will carry a false claim.

✅ The ownership sentence still holds verbatim

agent-view.md:484, re-fetched 2026-08-11:

"When the hook fails in a directory that isn't a git repository, the session skips isolation for that directory and edits the working directory in place. Inside a git repository, writes stay blocked until the session isolates."

The skip-bullet at :469 also still reads "The working directory isn't a git repository and no WorktreeCreate hook is configured". The path-scoping quote holds too — worktrees.md:82: "Claude Code blocks an Edit, Write, or NotebookEdit that targets a path in the main checkout." AD-4 stands.

➕ A third doc surface now states the same thing — add it, it strengthens the report

settings.md, the worktree.bgIsolation row (new since the draft was written):

""worktree" (default) blocks Edit/Write in the main checkout until EnterWorktree is called. Outside a git repository, a WorktreeCreate hook that fails releases the block so the session can edit the working directory in place; requires Claude Code v2.1.203 or later."

That is the documented behavior stated a third time, with an explicit version floor of 2.1.203 — well below the observed 2.1.220–2.1.227 window. Worth leading with, because it removes any "not supported on your version" reading.

❌ SC-F9 leg 1 — the missing docs anchor — is RESOLVED. Remove it before filing.

The draft flags settings#worktree-settings as auditor-only and "re-check before filing". Re-checked: the anchor exists. settings.md:365 is ### Worktree settings, and both pages that link to it (worktrees.md, agent-view.md) resolve. Filing this as a live docs bug would be a false claim in an upstream report.

✅ Version window extends to 2.1.228, still with no corrective entry

changelog.md re-fetched 2026-08-11. Newest listed is 2.1.228 (August 11, 2026) — one release newer than the draft's ceiling. Its 18-entry stanza names nothing touching isolation, WorktreeCreate, or bgIsolation (it covers TUI redraw, Git Bash discovery on Windows, /tui model reversion, cross-session messaging, self-hosted runners, session cleanup, plugin-cache cleanup, settings-merge, deferred-tools, skill hardening, Vertex credentials, compaction progress, terminal glyphs, Write-tool read rules, auto-mode notice). Across the whole 2.1.220→2.1.228 range the only isolation-adjacent lines remain 2.1.222/2.1.224 widening isolation to Bash in every session type, plus 2.1.226's opaque "Bug fixes and reliability improvements". Still a live divergence. Update the ceiling to 2.1.228.

➕ SC-F9 leg 2 is now MEASURED, not inferred — the strongest addition available

The draft states the narrower surviving claim: inside a git repository there is no documented channel for a WorktreeCreate hook to say "not applicable". That was reasoned from the exit-code table. It is now measured, on 2.1.228, and both failure shapes are confirmed to fail creation:

# hook: exit 0, prints nothing
$ claude -p '…' --worktree probe1 --settings <settings with that hook>
Error creating worktree: WorktreeCreate hook failed: hook succeeded but returned no worktree path
(command: echo the path to stdout; http/callback: return hookSpecificOutput.worktreePath)
$ echo $?   # 1
$ git worktree list   # nothing created

# hook: exit 3, two stderr lines
Error creating worktree: WorktreeCreate hook failed: bash "…/fail-hook.sh": FIRST-STDERR-LINE
SECOND-STDERR-LINE

# hook: prints a path it did not create
Error: worktree directory …/probe4 does not exist or is not a directory. The path came from a
WorktreeCreate hook — the hook must print the directory it created as the last line of its stdout.

Control arm (no hook) creates <repo>/.claude/worktrees/probe0 on branch worktree-probe0, locked with reason claude session probe0 (pid 29884).

So "exit-0-without-a-path is undocumented in either direction" should be restated: it is now documented and measured as failing. hooks.md carries "Hook failure or missing path fails creation" and "If the hook fails or produces no path, worktree creation fails with an error." The upstream ask survives unchanged and is now cleanly stateable: a WorktreeCreate hook has no way to decline inside a git repository — every shape it can return either creates a worktree or fails the session's isolation. That is a feature request with a measured basis rather than an inference.

The probe is runnable and now ships in-repo at plugins/source-control/skills/worktree/fixtures/worktree-create-hook-probe.sh (#2309), so the upstream filer can re-run it rather than take the transcript on trust.

⚠️ Unchanged and correct: SC-F8 is still NOT reproduced

The draft says so plainly, in its own section, and that framing must survive into the upstream issue. Reproduction remains foreclosed on the observing machine by ~/.claude/settings.local.json → worktree.bgIsolation: "none" (DQ-5, still open). I did not flip that setting — it is a machine-state change outside this lane's contract. File as an observation with a verbatim refusal message and an explicit "not yet reproduced" note, exactly as the draft instructs.

Filing checklist

Requirement	State
Reproduction	⚠️ Not reproduced — disclosed as such; DQ-5 blocks it
Verbatim observation	✅ present (subagent refusal, session 5559b694-…, win32, cwd C:\Users\KyleSexton)
Doc quote + URL + fetch date	✅ three surfaces, all re-verified 2026-08-11 at raw markdown
Version window	✅ update ceiling 2.1.227 → 2.1.228; no corrective entry in range
Secondary claims accurate	❌ drop the settings#worktree-settings anchor leg — it now exists
"No not-applicable channel"	✅ upgrade from inferred to measured (probe above)

Nothing here is fixable in plugins/source-control, and no plugin-side deadlock fix was attempted — AD-4 settled that. This issue stays open as the draft's home until a human files it; the plugin-side rows it cross-links (#2209, #2211) are handled in #2309.

_{Re-check by wave-2 lane SC, handoff-inbox batch 4. Claude Code 2.1.228, repo HEAD a0abaf81.}

[kyle-sexton]

Disposition: ready to file upstream. Labeled upstream-draft.

This was reviewed as part of the handoff-inbox batch-4 wave-2 push to drive every filed issue to
merged. It is one of two issues in that set that no local change can close — the defect lives in
anthropics/claude-code, and this repository can only observe it.

The draft was re-verified rather than assumed complete. It carries a reproduction, doc quotes with
URLs and fetch dates, a version window, and — importantly — the corrected mechanism rather than
the originally-filed one, which was falsified during validation. Filing the original attribution
would have sent a false report to another project.

What happens next is a human action, not a code change: open the report against
anthropics/claude-code, then link it here and close this tracker. Until then this stays open on
purpose, so the draft is not lost.

Leaving it open should not be read as unfinished local work. There is nothing to implement here.

[kyle-sexton]

Closing as upstream-draft / out of repo scope. Worktree isolation blocking writes at a non-repo root is a Claude Code platform behavior; the docs-vs-runtime mismatch needs an upstream issue in anthropics/claude-code (or the relevant runtime repo), not a fix in this plugin marketplace. Tracked here only as a draft for filing upstream.