@danmoisan/drm-copilot-mcp 1.1.23 → 1.1.25

package/resources/claude-customizations/.claude/hooks/enforce-orchestration-preimplementation-gate-epic-scope.ps1

@@ -3,7 +3,7 @@
     Epic-scope legs, checkpoint read seams, and target resolution of the preimplementation gate.
 
 .DESCRIPTION
-    Dot-sourced by enforce-orchestration-preimplementation-gate.ps1. Holds four groups of
+    Dot-sourced by enforce-orchestration-preimplementation-gate.ps1. Holds five groups of
     functions:
 
     - The import guards for the worktree-resolution modules (issue #690). A failed import
@@ -15,13 +15,20 @@
       read binds to the calling process's directory. Get-CheckpointContent and
       Get-OrchestrationModeDenyReason were relocated here from the gate file by issue #690
       to keep the gate inside the 500-line cap.
+    - The target-resolution building blocks of issue #1010: the worktree-list wrapper
+      Get-OrchestrationGateWorktreeList (the only listing seam), the recording invoker
+      Invoke-OrchestrationGateWorktreeList, which records a failed or empty listing in
+      $script:OrchestrationGateWorktreeListFailed, and the command-operand parser
+      Get-OrchestrationGateCommandOperandPath for git add and git commit.
     - The target resolution of issue #690. Resolve-OrchestrationGateTarget selects the
       worktree whose checkpoint governs the call from portable identity only: the
       integration_branch: value for an epic delegation, the parallel_slug: value for a
-      parallel delegation, the file_path or git -C operand for the path and command legs,
-      and the canonical issue-number line and branch: label for a single-feature
-      delegation. Read-OrchestrationGateCheckpoint reads the checkpoint beneath the
-      resolved root, or returns the deny for an unresolved target.
+      parallel delegation, and the canonical issue-number line and branch: label for a
+      single-feature delegation. The path and command legs resolve through
+      Resolve-HookTargetWorktree (issue #1010) from the file_path or from every git add
+      and git commit selector and absolute operand. Read-OrchestrationGateCheckpoint reads
+      the checkpoint beneath the resolved root, or returns the deny for an unresolved
+      target.
     - The epic-scope decision for the command and path legs (issue #663). A staging
       command or a Write/Edit call is epic scope when the effective worktree's HEAD equals
       the integration branch of the epic checkpoint that Resolve-EpicScopeCheckpoint
@@ -30,21 +37,24 @@
 
 .NOTES
     PowerShell 7+. Depends on functions the gate defines or dot-sources before any call:
-    Split-OrchestrationCommandLine and ConvertTo-OrchestrationCommandToken (helpers file),
     Get-OrchestrationDelegationCheckpointPath (modes file), the gate's allow and block
-    decision constructors, and, through the targets file this file dot-sources (issue #738),
-    Read-CommandLineSegment, Get-CommandLineGlobalOption, and Get-CommandLineInvocation
-    (loaded by the gate's dot-source of hook-command-invocation.ps1). Imports
-    WorktreeItemResolution.psm1 and WorktreeRunResolution.psm1 before
-    EpicScopeResolution.psm1, so the nested import inside EpicScopeResolution reuses the
-    same module instance. Mirrored byte-identically under
+    decision constructors, and Read-CommandLineSegment, Get-CommandLineGlobalOption, and
+    Get-CommandLineInvocation (loaded by the gate's dot-source of
+    hook-command-invocation.ps1), which the targets file this file dot-sources (issue #738)
+    and Get-OrchestrationGateCommandOperandPath call. Imports
+    WorktreeResolution.psm1 (the reason-code accessors), then WorktreeItemResolution.psm1
+    and WorktreeRunResolution.psm1 before EpicScopeResolution.psm1, so the nested import
+    inside EpicScopeResolution reuses the same module instance, and HookTargetWorktree.psm1
+    (Resolve-HookTargetWorktree, issue #1009) last. Mirrored byte-identically under
     extensions/drm-copilot/resources/claude-customizations/.
 #>
 
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeResolution.psm1' -ErrorRecord $_ }
 try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeItemResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeItemResolution.psm1' -ErrorRecord $_ }
 try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeRunResolution.psm1' -ErrorRecord $_ }
 try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/EpicScopeResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'EpicScopeResolution.psm1' -ErrorRecord $_ }
 try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/EpicScopeReadiness.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'EpicScopeReadiness.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/HookTargetWorktree.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'HookTargetWorktree.psm1' -ErrorRecord $_ }
 # Per-segment target resolution for the epic-scope decision (issue #738).
 . (Join-Path $PSScriptRoot 'enforce-orchestration-preimplementation-gate-targets.ps1')
 
@@ -102,15 +112,137 @@ function Get-OrchestrationModeDenyReason {
         'require that checkpoint to satisfy every readiness predicate before implementation begins.')
 }
 
+function Get-OrchestrationGateWorktreeList {
+    <#
+    .SYNOPSIS
+        Returns the porcelain worktree listing for the session root (issue #1010 seam).
+    .DESCRIPTION
+        Runs the listing exactly as the default WorktreeListInvoker of
+        Resolve-HookTargetWorktree does and returns an empty string on a non-zero exit. It
+        is the only test seam for the listing.
+    .OUTPUTS
+        System.String
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory)][string] $SessionRoot)
+
+    $porcelain = & git -C $SessionRoot worktree list --porcelain 2>$null
+    if ($LASTEXITCODE -ne 0) { return '' }
+    return ($porcelain -join "`n")
+}
+
+function Invoke-OrchestrationGateWorktreeList {
+    <#
+    .SYNOPSIS
+        Recording WorktreeListInvoker: returns the listing and records a listing failure.
+    .DESCRIPTION
+        Sets $script:OrchestrationGateWorktreeListFailed when the wrapper throws (and then
+        rethrows) or when its text holds no worktree entry, so the gate denies instead of
+        accepting the resolver's session-root fallback (issue #1010, spec E1).
+    .OUTPUTS
+        System.String
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory)][string] $SessionRoot)
+
+    try {
+        $text = [string](Get-OrchestrationGateWorktreeList -SessionRoot $SessionRoot)
+    } catch {
+        $script:OrchestrationGateWorktreeListFailed = $true
+        throw
+    }
+    if (@(ConvertFrom-HookTargetWorktreePorcelain -Text $text).Count -eq 0) {
+        $script:OrchestrationGateWorktreeListFailed = $true
+    }
+    return $text
+}
+
+function Get-OrchestrationGateCommandOperandPath {
+    <#
+    .SYNOPSIS
+        Returns the worktree-selecting paths of every git add and git commit invocation.
+    .DESCRIPTION
+        Scans every Structural match of git add and git commit (every command segment and
+        wrapper payload). Each -C value in any git global-option position and each absolute
+        operand is returned, distinct and in first-seen order. Relative operands, a -C on a
+        git segment invoking neither add nor commit, and Indeterminate matches are ignored.
+        For a match whose record is not argument-injected, a subcommand-aware walk (issue
+        #1010, F2) also reads the tokens after the subcommand with a per-subcommand option
+        model, compared case-sensitively: a value option consumes the next token unless its
+        value is inline (--name=value) or attached (-mvalue); a standalone flag consumes
+        itself; '--' makes every later token an operand; a redirection and its target are
+        skipped; any other dash token, such as the cluster -am, stops the walk. Its literal
+        absolute tokens are returned, and a token the walk reads as an option value is not
+        returned as an operand.
+    .PARAMETER Command
+        The full command line.
+    .OUTPUTS
+        System.String[]
+    #>
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param([Parameter(Mandatory)][AllowEmptyString()][string] $Command)
+
+    $valueOptions = @{
+        commit = @('-m', '--message', '-F', '--file', '--author', '--date', '-C', '--reuse-message', '-c', '--reedit-message', '-t', '--template', '--fixup', '--squash', '--trailer', '--pathspec-from-file')
+        add    = @('--pathspec-from-file', '--chmod')
+    }
+    $flagOptions = @{
+        commit = @('-a', '--all', '--amend', '--no-edit', '--no-verify', '-n', '-s', '--signoff', '-q', '--quiet', '-v', '--verbose', '--allow-empty', '-o', '--only', '-i', '--include', '--pathspec-file-nul')
+        add    = @('-A', '--all', '-u', '--update', '-f', '--force', '-N', '--intent-to-add', '-n', '--dry-run', '-v', '--verbose', '--pathspec-file-nul')
+    }
+    $absolutePattern = '^([A-Za-z]:[\\/]|/)'
+    $paths = [System.Collections.Generic.List[string]]::new()
+    foreach ($subcommand in @('add', 'commit')) {
+        foreach ($match in @(Get-CommandLineInvocation -CommandText $Command -CommandWord 'git' -SubcommandPath @($subcommand))) {
+            if ($match.Status -ne 'Structural') { continue }
+            $walked = [System.Collections.Generic.List[string]]::new()
+            $optionValues = [System.Collections.Generic.List[string]]::new()
+            $tokens = if ($match.Segment.ArgumentInjected) { [string[]]@() } else { [string[]]@($match.Segment.Tokens) }
+            $afterSeparator = $false
+            for ($index = [int]$match.OperandIndex; $index -lt $tokens.Count; $index++) {
+                $token = $tokens[$index]
+                if (-not $afterSeparator -and $token -match '^(<|>|\d*>|&>)') {
+                    if ($token -match '^(\d*[<>]{1,2}&?|&>{1,2})$') { $index++ }
+                    continue
+                }
+                if ($afterSeparator -or -not $token.StartsWith('-')) { $walked.Add($token); continue }
+                if ($token -ceq '--') { $afterSeparator = $true; continue }
+                $name = if ($token.IndexOf('=') -gt 0) { $token.Substring(0, $token.IndexOf('=')) } else { $token }
+                if ($valueOptions[$subcommand] -ccontains $name) {
+                    if ($name -ceq $token -and $index + 1 -lt $tokens.Count) { $index++; $optionValues.Add($tokens[$index]) }
+                    continue
+                }
+                if ($token -match '^-[^-].' -and $valueOptions[$subcommand] -ccontains $token.Substring(0, 2)) { continue }
+                if ($flagOptions[$subcommand] -ccontains $token) { continue }
+                break
+            }
+            $candidates = @(@($match.GlobalOptions) | Where-Object { $_.Name -ceq '-C' -and $_.Value } | ForEach-Object { [string]$_.Value })
+            $candidates += @(@($match.Operands) | Where-Object { $_ -match $absolutePattern -and $optionValues -cnotcontains $_ })
+            $candidates += @($walked | Where-Object { $_ -match $absolutePattern -and (Test-CommandLineTokenLiteral -Token $_) })
+            foreach ($candidate in $candidates) {
+                if ($paths -notcontains $candidate) { $paths.Add($candidate) }
+            }
+        }
+    }
+    return [string[]]$paths.ToArray()
+}
+
 function Resolve-OrchestrationGateTarget {
     <#
     .SYNOPSIS
         Resolves the worktree whose checkpoint governs a gated call (issue #690 seam).
     .DESCRIPTION
         An epic delegation is keyed on integration_branch: (with epic_feature_folder: as a
-        cross-check), a parallel delegation on parallel_slug:, a path leg on its file_path
-        operand, a command leg on its git -C selector (none means the session root), and a
-        single-feature delegation on its canonical issue-number line and branch: label.
+        cross-check), a parallel delegation on parallel_slug:, and a single-feature
+        delegation on its canonical issue-number line and branch: label. The path and
+        command legs use Resolve-HookTargetWorktree (issue #1010): a path leg passes its
+        file_path, a command leg the Get-OrchestrationGateCommandOperandPath result, and the
+        recording invoker supplies the worktree listing. A failed or empty listing denies as
+        not derivable instead of falling back to the session root; an ambiguous result
+        denies as ambiguous; a null root denies as not derivable.
     .OUTPUTS
         System.Management.Automation.PSCustomObject (the worktree-resolution target result).
     #>
@@ -131,13 +263,29 @@ function Resolve-OrchestrationGateTarget {
         }
         return Resolve-WorktreeParallelTarget -ParallelSlug $signal.ParallelSlug -SessionRoot $sessionRoot
     }
-    if ($FilePath) {
-        return Resolve-WorktreeOperandTarget -Path $FilePath -SessionRoot $sessionRoot
+    if (-not $FilePath -and -not $Command) {
+        return Resolve-WorktreeItemTarget -Text $Prompt -SessionRoot $sessionRoot
+    }
+    $script:OrchestrationGateWorktreeListFailed = $false
+    $invoker = { param($SessionRoot) Invoke-OrchestrationGateWorktreeList -SessionRoot $SessionRoot }
+    $resolved = if ($FilePath) {
+        Resolve-HookTargetWorktree -SessionRoot $sessionRoot -FilePath @($FilePath) -WorktreeListInvoker $invoker
+    } else {
+        Resolve-HookTargetWorktree -SessionRoot $sessionRoot -CommandOperandPath @(Get-OrchestrationGateCommandOperandPath -Command $Command) -WorktreeListInvoker $invoker
+    }
+    $detail = "resolver source $($resolved.Source): $($resolved.Detail)"
+    if ($script:OrchestrationGateWorktreeListFailed) {
+        return [pscustomobject]@{ Status = 'NoTarget'; WorktreeRoot = $null; ReasonCode = (Get-WorktreeResolutionNoTargetReasonCode); Detail = "the worktree listing failed or named no worktree; $detail" }
     }
-    if ($Command) {
-        return Resolve-WorktreeOperandTarget -Path (Get-OrchestrationEpicScopeSelector -Command $Command) -SessionRoot $sessionRoot
+    if ($resolved.Ambiguous) {
+        return [pscustomobject]@{ Status = 'Ambiguous'; WorktreeRoot = $null; ReasonCode = (Get-WorktreeResolutionAmbiguityReasonCode); Detail = $detail }
     }
-    return Resolve-WorktreeItemTarget -Text $Prompt -SessionRoot $sessionRoot
+    if ([string]::IsNullOrEmpty([string]$resolved.WorktreeRoot)) {
+        return [pscustomobject]@{ Status = 'NoTarget'; WorktreeRoot = $null; ReasonCode = (Get-WorktreeResolutionNoTargetReasonCode); Detail = $detail }
+    }
+    $isSession = [string]::Equals([string]$resolved.WorktreeRoot, (ConvertTo-HookTargetWorktreeNormalizedPath -Path $sessionRoot), [System.StringComparison]::OrdinalIgnoreCase)
+    $status = if ($isSession) { 'SessionRoot' } else { 'OtherWorktree' }
+    return [pscustomobject]@{ Status = $status; WorktreeRoot = [string]$resolved.WorktreeRoot; ReasonCode = $null; Detail = $detail }
 }
 
 function Read-OrchestrationGateCheckpoint {
@@ -187,34 +335,6 @@ function Read-OrchestrationGateCheckpoint {
     }
 }
 
-function Get-OrchestrationEpicScopeSelector {
-    <#
-    .SYNOPSIS
-        Returns the value of a leading `git -C <value>` selector, or $null.
-    .DESCRIPTION
-        Pure. Reads only the first segment of the command line, split and tokenized with
-        the helpers-file parser so quoting is handled exactly as the staging exemption
-        handles it. An unbalanced command line has no decidable selector and returns $null.
-    .PARAMETER Command
-        The full command line.
-    .OUTPUTS
-        System.String
-    #>
-    [CmdletBinding()]
-    [OutputType([string])]
-    param([Parameter(Mandatory)][AllowEmptyString()][string] $Command)
-
-    $split = Split-OrchestrationCommandLine -CommandText $Command
-    if (-not $split.Balanced -or @($split.Segments).Count -eq 0) {
-        return $null
-    }
-    $token = @(ConvertTo-OrchestrationCommandToken -Segment ([string]@($split.Segments)[0]).Trim())
-    if ($token.Count -ge 3 -and $token[0] -ceq 'git' -and $token[1] -ceq '-C' -and $token[2]) {
-        return $token[2]
-    }
-    return $null
-}
-
 function Get-OrchestrationEpicScopeDecision {
     <#
     .SYNOPSIS

package/resources/claude-customizations/.claude/hooks/enforce-orchestration-preimplementation-gate.ps1

@@ -239,7 +239,7 @@ function Test-OrchestrationReady {
     }
     $lifecycleReady = $false
     if ($Payload.PSObject.Properties.Name -contains 'lifecycle_ready') {
-        $lifecycleReady = [bool]$Payload.lifecycle_ready
+        $lifecycleReady = ($Payload.lifecycle_ready -is [bool]) -and $Payload.lifecycle_ready
     }
 
     if (-not $issueNum -or -not $featureFolder -or -not $routeId -or -not $lifecycleReady) {

package/resources/claude-customizations/.claude/hooks/enforce-powershell-batch-budget.ps1

@@ -7,14 +7,28 @@
     operation. When the target file is a PowerShell source file (.ps1, .psm1, .psd1),
     it decides whether the change may proceed in direct mode.
 
-    Direct mode counts distinct production PowerShell paths per Claude Code session.
-    The running set is persisted under .claude/state/powershell-batch-budget.<session_id>.json,
-    and repeated edits to the same file are counted once. The 4th distinct production
-    path is denied with a POWERSHELL_LARGE_PATH_REQUIRED reason that instructs the
-    caller to route the change through /orchestrate.
-
-    The orchestrated large path is detected from
-    <root>/artifacts/orchestration/orchestrator-state.json. The selected route is the
+    Direct mode counts distinct production PowerShell paths per Claude Code session and
+    per resolved target worktree, and repeated edits to the same file are counted once.
+    The 4th distinct production path in one worktree is denied with a
+    POWERSHELL_LARGE_PATH_REQUIRED reason that instructs the caller to route the change
+    through /orchestrate.
+
+    The edited file is placed with Resolve-HookTargetWorktree from
+    .claude/lib/worktree-resolution/HookTargetWorktree.psm1. An absolute path resolves to
+    its nearest enclosing registered git worktree; a relative path, a path inside no
+    registered worktree, and an ambiguous result use the session root (the checkout that
+    holds this hook). The route is read from
+    artifacts/orchestration/orchestrator-state.json in the resolved target worktree.
+    The running set is kept under the session root, in
+    .claude/state/powershell-batch-budget.<session_id>.json when the resolved target worktree
+    is the session root and in
+    .claude/state/powershell-batch-budget.<session_id>.<worktree key>.json otherwise,
+    where the key comes from Get-HookTargetWorktreeKey; no state is written under another
+    worktree. A path under the root-level artifacts/ directory of the resolved target worktree
+    is gitignored scratch: it is allowed, consumes no slot, and writes no state. A
+    nested directory named artifacts elsewhere in the tree still counts.
+
+    The selected route is the
     route_id value when that key is present, otherwise the path_selected value, and it
     is usable only as a non-blank string. When the selected route is large,
     remediation, or preparation and the checkpoint is not terminal (next_step is not
@@ -38,9 +52,9 @@
     is composed into a file name, so a hostile id cannot escape the state
     directory. Resolving the id never creates the state directory.
 
-    Candidate paths are contained to the resolved root. A candidate that resolves
-    outside it is discarded: the decision is 'allow', no slot is consumed, and no
-    state is written. Persisted entries that fail the same containment test are
+    Candidate paths are contained to the resolved target worktree root. A candidate
+    that resolves outside it is discarded: the decision is 'allow', no slot is consumed,
+    and no state is written. Persisted entries that fail the same containment test are
     dropped when state is rehydrated, so a state file carried between worktrees
     cannot spend this worktree's budget.
 
@@ -48,9 +62,12 @@
     hookSpecificOutput.permissionDecision = 'deny' and exits 0. Files already counted
     are always allowed through.
 
-    Known limitation: a stale non-terminal large-path checkpoint left at the root
-    exempts a later direct-mode session at that root. Orchestrator checkpoint hygiene
-    (issue #673) moves foreign checkpoints aside before a new run.
+    Known limitations: an 8.3 short-name path, or a path reached through a junction,
+    that differs textually from the long path git reports matches no registered
+    worktree and falls back to the session root. A stale non-terminal large-path
+    checkpoint in a worktree exempts a later direct-mode session editing that worktree;
+    orchestrator checkpoint hygiene (issue #673) moves foreign checkpoints aside before
+    a new run.
 
 .NOTES
     Compatible with PowerShell 7+.
@@ -61,6 +78,7 @@ $script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot
 
 
 try { Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'HookPayload.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/HookTargetWorktree.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'HookTargetWorktree.psm1' -ErrorRecord $_ }
 $script:PowerShellBatchBudgetRouteImportFailure = $null; try { . (Join-Path $PSScriptRoot 'enforce-batch-budget-route.ps1') } catch { $script:PowerShellBatchBudgetRouteImportFailure = 'enforce-batch-budget-route.ps1' }
 
 function Test-PowerShellBatchBudgetPathInRoot {
@@ -351,7 +369,8 @@ function Invoke-PowerShellBatchBudgetHook {
         [scriptblock] $WriteState = {
             param([string] $Path, [System.Collections.IDictionary] $State)
             $State | ConvertTo-Json -Depth 5 | Set-Content -Path $Path -Encoding UTF8
-        }
+        },
+        [scriptblock] $WorktreeListInvoker
     )
 
     $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
@@ -373,6 +392,25 @@ function Invoke-PowerShellBatchBudgetHook {
     }
     if ($script:PowerShellBatchBudgetRouteImportFailure) { return Get-PowerShellBatchBudgetBlockDecision -Reason "POWERSHELL_LARGE_PATH_REQUIRED: the route helper '$($script:PowerShellBatchBudgetRouteImportFailure)' failed to load, so the batch budget for '$normalized' cannot be evaluated; the gate fails closed." }
 
+    # The file is evaluated against the registered worktree that holds it. The session root
+    # stays the fallback for a relative path, a path in no registered worktree, and an
+    # ambiguous result, which keeps today's checkpoint, containment, and state-file name.
+    $resolverArguments = @{ SessionRoot = $Root; FilePath = @($filePath) }
+    if ($PSBoundParameters.ContainsKey('WorktreeListInvoker')) { $resolverArguments['WorktreeListInvoker'] = $WorktreeListInvoker }
+    $resolution = Resolve-HookTargetWorktree @resolverArguments
+    $targetRoot = $Root
+    $isSessionRoot = $true
+    if (-not $resolution.Ambiguous -and $null -ne $resolution.WorktreeRoot -and -not [string]::Equals($resolution.WorktreeRoot, (ConvertTo-HookTargetWorktreeNormalizedPath -Path $Root), [System.StringComparison]::OrdinalIgnoreCase)) {
+        $targetRoot = $resolution.WorktreeRoot
+        $isSessionRoot = $false
+    }
+
+    # The root-level artifacts/ directory is gitignored scratch, never a production file.
+    $relativePath = if ($normalized -match '^(/|[A-Za-z]:/)') { Get-HookTargetWorktreeRelativePath -Path $normalized -WorktreeRoot $targetRoot } else { $normalized }
+    if ($null -ne $relativePath -and $relativePath.StartsWith('artifacts/', [System.StringComparison]::OrdinalIgnoreCase)) {
+        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
+    }
+
     $stateDir = Join-Path -Path $Root -ChildPath '.claude/state'
 
     # Resolved before the directory is ensured, because reading the session-id
@@ -383,11 +421,12 @@ function Invoke-PowerShellBatchBudgetHook {
         -SessionIdFilePath (Join-Path -Path $stateDir -ChildPath 'current-session-id') `
         -ReadSessionIdFile $ReadSessionIdFile
 
-    $stateFile = Join-Path -Path $stateDir -ChildPath ("powershell-batch-budget.$resolvedSessionId.json")
+    $stateLeaf = if ($isSessionRoot) { "powershell-batch-budget.$resolvedSessionId.json" } else { "powershell-batch-budget.$resolvedSessionId.$(Get-HookTargetWorktreeKey -WorktreeRoot $targetRoot).json" }
+    $stateFile = Join-Path -Path $stateDir -ChildPath $stateLeaf
 
     # The checkpoint is read before any state operation, so the large path neither
     # creates the state directory nor reads or writes the state file.
-    $checkpointPath = Join-Path -Path $Root -ChildPath 'artifacts/orchestration/orchestrator-state.json'
+    $checkpointPath = Join-Path -Path $targetRoot -ChildPath 'artifacts/orchestration/orchestrator-state.json'
     $checkpointText = ''
     try {
         $checkpointText = [string](& $ReadCheckpoint $checkpointPath)
@@ -399,7 +438,7 @@ function Invoke-PowerShellBatchBudgetHook {
     $isLargePath = Test-BatchBudgetLargePathRoute -CheckpointText $checkpointText
     $observedRoute = Get-BatchBudgetSelectedRoute -CheckpointText $checkpointText
     if ($isLargePath) {
-        return Invoke-PowerShellBatchBudgetDecision -FilePath $filePath -State (Get-PowerShellBatchBudgetState -ProdCap $ProdCap) -StateFile $stateFile -Root $Root -LargePathRoute
+        return Invoke-PowerShellBatchBudgetDecision -FilePath $filePath -State (Get-PowerShellBatchBudgetState -ProdCap $ProdCap) -StateFile $stateFile -Root $targetRoot -LargePathRoute
     }
 
     if (-not (& $TestPathExists $stateDir)) {
@@ -411,13 +450,13 @@ function Invoke-PowerShellBatchBudgetHook {
     if (& $TestPathExists $stateFile) {
         try {
             $loaded = & $ReadState $stateFile | ConvertFrom-Json -ErrorAction Stop
-            $state = ConvertTo-PowerShellBatchBudgetState -InputObject $loaded -ProdCap $ProdCap -Root $Root
+            $state = ConvertTo-PowerShellBatchBudgetState -InputObject $loaded -ProdCap $ProdCap -Root $targetRoot
         } catch {
             Write-Verbose "Ignoring unreadable PowerShell batch-budget state file '$stateFile': $($_.Exception.Message)"
         }
     }
 
-    $decision = Invoke-PowerShellBatchBudgetDecision -FilePath $filePath -State $state -StateFile $stateFile -Root $Root -ObservedRoute $observedRoute
+    $decision = Invoke-PowerShellBatchBudgetDecision -FilePath $filePath -State $state -StateFile $stateFile -Root $targetRoot -ObservedRoute $observedRoute
     if ($decision.shouldWriteState) {
         try {
             & $WriteState $stateFile $decision.state

package/resources/claude-customizations/.claude/hooks/enforce-pr-author-command-allowlist.ps1

@@ -10,9 +10,12 @@
     in one of these forms, matched by token position:
 
       - git log ...            and git rev-parse ...        (no git global option)
+      - git worktree list --porcelain                       (exactly these four tokens, issue #1011)
       - gh pr create ...       and gh pr edit ...           (no gh global option)
       - gh pr view <N> --json closingIssuesReferences,body  (exactly these six tokens, issue #989)
       - sha256sum artifacts/pr_body_<N>.md                  (only as the whole command)
+      - sha256sum <item worktree>/artifacts/pr_body_<N>.md  (only as the whole command; an absolute
+                                                             forward-slash path, issue #1011)
       - date -u [+<format>]                                 (only as the whole command)
 
     Segments may be joined only by ';', '&&', '||', '|', or a newline. A record that is
@@ -42,7 +45,38 @@ $script:PrAuthorAllowlistWrapperWords = @(
     'sh', 'bash', 'zsh', 'dash', 'ksh', 'pwsh', 'powershell', 'eval', 'xargs',
     'env', 'timeout', 'time', 'command', 'nohup'
 )
-$script:PrAuthorAllowlistFormText = 'git log, git rev-parse, gh pr create, gh pr edit, gh pr view <N> --json closingIssuesReferences,body, sha256sum artifacts/pr_body_<N>.md, date -u [+<format>]'
+$script:PrAuthorAllowlistFormText = 'git log, git rev-parse, git worktree list --porcelain, gh pr create, gh pr edit, gh pr view <N> --json closingIssuesReferences,body, sha256sum artifacts/pr_body_<N>.md, sha256sum <item worktree>/artifacts/pr_body_<N>.md, date -u [+<format>]'
+
+function Test-PrAuthorAbsoluteBodyPathToken {
+    <#
+    .SYNOPSIS
+        Report whether a token is an absolute canonical body path beneath an item worktree (issue #1011).
+    .DESCRIPTION
+        The token must be rooted at '/' or at a drive letter followed by ':/', use forward slashes
+        only, hold at least one segment before 'artifacts', hold no empty, '.', or '..' segment,
+        and end in '/artifacts/pr_body_<digits>.md' with the exact case of the relative form.
+        Pure string logic: no process, file read, or module import.
+    .PARAMETER Value
+        The sha256sum argument token, quotes already stripped.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)][AllowEmptyString()][string] $Value
+    )
+
+    if ($Value.Contains('\') -or $Value -cnotmatch '^(/|[A-Za-z]:/)(?<rest>.+)/artifacts/pr_body_\d+\.md$') {
+        return $false
+    }
+    foreach ($segment in $Matches['rest'].Split('/')) {
+        if ($segment -eq '' -or $segment -eq '.' -or $segment -eq '..') {
+            return $false
+        }
+    }
+    return $true
+}
 
 function Test-PrAuthorAllowlistForm {
     <#
@@ -67,7 +101,11 @@ function Test-PrAuthorAllowlistForm {
     }
     switch -CaseSensitive ($Token[0]) {
         'git' {
-            return ($Token.Count -ge 2 -and @('log', 'rev-parse') -ccontains $Token[1])
+            if ($Token.Count -ge 2 -and @('log', 'rev-parse') -ccontains $Token[1]) {
+                return $true
+            }
+            # The read-only worktree discovery form, matched exactly (issue #1011).
+            return ($Token.Count -eq 4 -and $Token[1] -ceq 'worktree' -and $Token[2] -ceq 'list' -and $Token[3] -ceq '--porcelain')
         }
         'gh' {
             if ($Token.Count -ge 3 -and $Token[1] -ceq 'pr' -and @('create', 'edit') -ccontains $Token[2]) {
@@ -78,7 +116,10 @@ function Test-PrAuthorAllowlistForm {
                 $Token[4] -ceq '--json' -and $Token[5] -ceq 'closingIssuesReferences,body')
         }
         'sha256sum' {
-            return ($IsWholeCommand -and $Token.Count -eq 2 -and $Token[1] -cmatch '^artifacts/pr_body_\d+\.md$')
+            if (-not $IsWholeCommand -or $Token.Count -ne 2) {
+                return $false
+            }
+            return ($Token[1] -cmatch '^artifacts/pr_body_\d+\.md$' -or (Test-PrAuthorAbsoluteBodyPathToken -Value $Token[1]))
         }
         'date' {
             if (-not $IsWholeCommand -or $Token.Count -lt 2 -or $Token[1] -cne '-u') {

package/resources/claude-customizations/.claude/hooks/enforce-pr-author-skill-helpers.ps1

@@ -50,6 +50,8 @@ Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeTarge
 # feature folder exists in every checkout branched from main, so it places a call in many at
 # once. The item is identified by its canonical issue number and its branch instead.
 Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeItemResolution.psm1') -Force -ErrorAction Stop
+# Shared target-worktree resolver (issues #1009, #1011): resolves the branch a --head names.
+Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/HookTargetWorktree.psm1') -Force -ErrorAction Stop
 # Epic scope (issue #663): the epic integration pull request is gated against the epic checkpoint.
 Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/EpicScopeResolution.psm1') -Force -ErrorAction Stop
 Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/EpicScopeReadiness.psm1') -Force -ErrorAction Stop
@@ -70,10 +72,15 @@ function Resolve-PrAuthorWorktreeTarget {
         directly would depend on the machine's live worktrees and would pass or fail
         according to what other sessions happen to have checked out, which the repository's
         determinism policy forbids. Mocking here lets a test state the resolution outcome it
-        is exercising and nothing else. A NoTarget result for a command with no signal passes
-        through Resolve-PrAuthorCurrentBranchTarget, which re-resolves the current branch (#989).
+        is exercising and nothing else. A branch the command names (--head, --branch, or
+        branch:) is resolved by the shared resolver Resolve-HookTargetWorktree, given only the
+        session root and that branch (issue #1011), unless the command also carries a canonical
+        issue number line, which Resolve-WorktreeItemTarget decides so the branch/issue agreement
+        check applies. Without a selection, Resolve-WorktreeItemTarget runs, and a NoTarget result
+        for a command with no signal passes through Resolve-PrAuthorCurrentBranchTarget, which
+        re-resolves the current branch (#989).
     .OUTPUTS
-        The target result object from Resolve-WorktreeItemTarget.
+        A target result object built by New-WorktreeResolutionTargetResult.
     #>
     [CmdletBinding()]
     param(
@@ -81,10 +88,59 @@ function Resolve-PrAuthorWorktreeTarget {
         [string] $CommandText
     )
 
-    $target = Resolve-WorktreeItemTarget -Text $CommandText -SessionRoot (Get-Location).Path
+    $sessionRoot = (Get-Location).Path
+    $branch = Find-WorktreeResolutionBranchSignal -Text $CommandText
+    $issueSignal = Find-WorktreeItemIssueSignal -Text $CommandText
+    if ($null -ne $branch -and @($issueSignal).Count -eq 0) {
+        $shared = Resolve-HookTargetWorktree -SessionRoot $sessionRoot -CommandBranch $branch
+        $mapped = ConvertFrom-PrAuthorHookTargetResult -Result $shared -CommandText $CommandText -SessionRoot $sessionRoot
+        if ($null -ne $mapped) { return $mapped }
+    }
+    $target = Resolve-WorktreeItemTarget -Text $CommandText -SessionRoot $sessionRoot
     return (Resolve-PrAuthorCurrentBranchTarget -CommandText $CommandText -Target $target)
 }
 
+function ConvertFrom-PrAuthorHookTargetResult {
+    <#
+    .SYNOPSIS
+        Map a Resolve-HookTargetWorktree result onto a pr-author target result, or $null (issue #1011).
+    .DESCRIPTION
+        Returns $null (no selection) when Result is null, when CommandText carries no branch
+        signal, when Result.Source is not CommandOperand, when Result names no root, or when that
+        root fails Test-WorktreeResolutionRootMarker (a registration whose directory is gone).
+        Only a CommandOperand result selects, being branch-derived; a FilePath, SessionRoot, or
+        DelegationIdentity result never selects the worktree (issue #673). An ambiguous result
+        maps to Ambiguous. Labelling is delegated to ConvertTo-WorktreeItemResolvedResult, which
+        maps a root equal to SessionRoot, or to the worktree enclosing it, to SessionRoot and any
+        other root to OtherWorktree.
+    .PARAMETER Result
+        The Resolve-HookTargetWorktree result.
+    .PARAMETER CommandText
+        The Bash command text under evaluation.
+    .PARAMETER SessionRoot
+        The session root the result is compared with.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [AllowNull()][object] $Result,
+        [Parameter(Mandatory)][AllowEmptyString()][string] $CommandText,
+        [Parameter(Mandatory)][string] $SessionRoot
+    )
+
+    $branch = Find-WorktreeResolutionBranchSignal -Text $CommandText
+    if ($null -eq $Result -or $null -eq $branch -or $Result.Source -cne 'CommandOperand') { return $null }
+    $detail = if ([string]::IsNullOrWhiteSpace([string]$Result.Detail)) { "branch '$branch' resolved by the shared resolver" } else { [string]$Result.Detail }
+    if ($Result.Ambiguous) {
+        return (New-WorktreeResolutionTargetResult -Status Ambiguous -SessionRoot $SessionRoot -Signal Branch -SignalValue $branch -Candidate @($Result.Candidates) -Detail $detail)
+    }
+    if ([string]::IsNullOrEmpty([string]$Result.WorktreeRoot)) { return $null }
+    if (-not (Test-WorktreeResolutionRootMarker -Path $Result.WorktreeRoot)) { return $null }
+    return (ConvertTo-WorktreeItemResolvedResult -WorktreeRoot $Result.WorktreeRoot -SessionRoot $SessionRoot -Branch $branch -Detail $detail)
+}
+
 function Get-PrAuthorTargetCheckpointResolution {
     <#
     .SYNOPSIS

package/resources/claude-customizations/.claude/hooks/enforce-pr-author-skill.epic-base-branch.ps1

@@ -59,7 +59,9 @@ function Test-EpicBaseBranchOverride {
         with reason EPIC_BASE_BRANCH_MISMATCH. When epic_mode is absent or false, when the
         checkpoint is unreadable, or when the command is not gh pr create (the base branch is
         set at create time, not edit time), this check is a no-op and standalone behavior is
-        unchanged.
+        unchanged. Only the JSON boolean true counts as epic mode: a string or number such as
+        "false", "true", or 1 is not epic mode, so the --base requirement does not apply
+        (issue #1001).
     .PARAMETER CommandText
         The Bash command text under evaluation.
     .PARAMETER CheckpointPath
@@ -116,7 +118,7 @@ function Test-EpicBaseBranchOverride {
     }
 
     $checkpointProps = @($checkpoint.PSObject.Properties.Name)
-    if ($checkpointProps -notcontains 'epic_mode' -or -not [bool]$checkpoint.epic_mode) {
+    if ($checkpointProps -notcontains 'epic_mode' -or -not (($checkpoint.epic_mode -is [bool]) -and $checkpoint.epic_mode)) {
         return $null
     }