@danmoisan/drm-copilot-mcp 1.1.23 → 1.1.25

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-discovery-planning-gate.ps1

@@ -0,0 +1,149 @@
+<#
+.SYNOPSIS
+    Codex PreToolUse hook that gates planner and orchestrator launches on current configured discovery authority.
+
+.DESCRIPTION
+    Invoked by the Codex PreToolUse hook. The hook reads the Codex envelope from
+    stdin, recognizes an atomic-planner or orchestrator launch, and takes its
+    decision from the shared DiscoveryPlanning module (published under
+    .codex/lib/discovery-validation, or read from .claude/lib when this repository
+    hosts itself):
+
+    - a call that is not a planner or orchestrator launch, and a workspace without
+      a protected discovery activation, allow silently (no stdout) so the existing
+      Codex gates keep their behavior;
+    - an active workspace must still hold the activated locator and domain profile
+      and the protected session must hold a current, passing, gateway-written
+      planning-mode receipt for this host and session; otherwise the launch is
+      denied with a PreToolUse deny decision at exit 0.
+
+    An envelope the hook cannot read is a hard failure: the reason goes to stderr
+    and the hook exits 2. Dependency failures deny with the
+    DISCOVERY_PLANNING_GATE_BLOCKED: prefix. The hook never runs Python (issue #980).
+
+.NOTES
+    Requires PowerShell 7+. Invokes NO external process.
+#>
+[CmdletBinding()]
+param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
+
+function Get-DiscoveryPlanningHelperModulePath {
+    <#
+    .SYNOPSIS
+        Returns the published (.codex/lib) or self-hosting (.claude/lib) path of one helper module.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)][string]$ModuleName,
+        [Parameter(Mandatory = $false)][string]$ScriptRoot = $PSScriptRoot
+    )
+
+    $published = Join-Path $ScriptRoot "../lib/discovery-validation/$ModuleName"
+    $selfHosted = Join-Path $ScriptRoot "../../.claude/lib/discovery-validation/$ModuleName"
+    foreach ($candidate in @($published, $selfHosted)) {
+        if (Test-Path -LiteralPath $candidate -PathType Leaf) { return $candidate }
+    }
+    return $published
+}
+
+function Import-DiscoveryPlanningSelfHostedModule {
+    <#
+    .SYNOPSIS
+        Imports the shared helpers from this repository's .claude/lib layout when no published .codex/lib exists (exemption D4).
+    #>
+    [CmdletBinding()]
+    param()
+
+    $ScriptRoot = $PSScriptRoot
+    try { Import-Module (Join-Path $ScriptRoot '../../.claude/lib/discovery-validation/DiscoveryEncoding.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryEncoding.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $ScriptRoot '../../.claude/lib/discovery-validation/DiscoveryAuthority.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryAuthority.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $ScriptRoot '../../.claude/lib/discovery-validation/DiscoveryManifest.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryManifest.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $ScriptRoot '../../.claude/lib/discovery-validation/DiscoveryPayload.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryPayload.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $ScriptRoot '../../.claude/lib/discovery-validation/DiscoveryToolRouting.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryToolRouting.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $ScriptRoot '../../.claude/lib/discovery-validation/DiscoveryAuthorization.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryAuthorization.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $ScriptRoot '../../.claude/lib/discovery-validation/DiscoveryStartRecord.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryStartRecord.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $ScriptRoot '../../.claude/lib/discovery-validation/DiscoveryPlanning.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryPlanning.psm1' -ErrorRecord $_ }
+}
+
+# The published destination keeps the helpers beside .codex/hooks; this repository hosts them under .claude/lib.
+if (Test-Path -LiteralPath (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryEncoding.psm1') -PathType Leaf) {
+    try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryEncoding.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryEncoding.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryAuthority.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryAuthority.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryManifest.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryManifest.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryPayload.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryPayload.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryToolRouting.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryToolRouting.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryAuthorization.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryAuthorization.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryStartRecord.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryStartRecord.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryPlanning.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryPlanning.psm1' -ErrorRecord $_ }
+} else {
+    Import-DiscoveryPlanningSelfHostedModule
+}
+
+$script:DiscoveryPlanningReasonPrefix = 'DISCOVERY_PLANNING_GATE_BLOCKED:'
+
+function Invoke-DiscoveryPlanningGateDecision {
+    <#
+    .SYNOPSIS
+        Parses the Codex PreToolUse envelope and returns the planning outcome.
+    .DESCRIPTION
+        Returns the shared outcome object (Decision, Code, Reason, Receipt,
+        Prerequisite). Every seam defaults to the real host and is injectable. A
+        recorded dependency failure returns a deny outcome before the envelope is read.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory = $false)][AllowNull()][AllowEmptyString()][string]$ToolInputRaw,
+        [Parameter(Mandatory = $false)][AllowNull()][hashtable]$HostEnvironment = $null,
+        [Parameter(Mandatory = $false)][AllowNull()][hashtable]$Store = $null,
+        [Parameter(Mandatory = $false)][AllowNull()][scriptblock]$ReadBytes = $null
+    )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix $script:DiscoveryPlanningReasonPrefix
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
+
+    if ($null -eq $HostEnvironment) { $HostEnvironment = Get-DiscoveryTrustedHostEnvironment }
+    if ($null -eq $Store) { $Store = Get-DiscoveryStartStore }
+
+    $normalized = ConvertFrom-DiscoveryHostPayloadText -HostName 'codex' -Text $ToolInputRaw
+    $parameters = @{ Normalized = $normalized; HostEnvironment = $HostEnvironment; Store = $Store }
+    if ($null -ne $ReadBytes) { $parameters['ReadBytes'] = $ReadBytes }
+    return Get-DiscoveryPlanningDecision @parameters
+}
+
+function Invoke-DiscoveryPlanningGateEntryPoint {
+    <#
+    .SYNOPSIS
+        Reads one Codex PreToolUse payload, writes the decision and returns the process exit code.
+    .DESCRIPTION
+        An unreadable envelope writes its reason to stderr and returns 2. A deny
+        writes the PreToolUse decision JSON to stdout and returns 0. An allow writes
+        nothing and returns 0, as the Codex gates do.
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param([Parameter(Mandatory = $false)][AllowNull()][AllowEmptyString()][string]$PayloadRaw)
+
+    $outcome = Invoke-DiscoveryPlanningGateDecision -ToolInputRaw $PayloadRaw
+    # A dependency failure is already the PreToolUse deny decision.
+    if ($outcome -is [System.Collections.IDictionary]) { [Console]::Out.WriteLine(($outcome | ConvertTo-Json -Compress -Depth 5)); return 0 }
+    if ($outcome.Decision -eq 'allow') { return 0 }
+    if ($outcome.Code -eq 'ENVELOPE') {
+        [Console]::Error.WriteLine("$($script:DiscoveryPlanningReasonPrefix) $($outcome.Reason)")
+        return 2
+    }
+    $decision = ConvertTo-DiscoveryPlanningHookOutput -Outcome $outcome -ReasonPrefix $script:DiscoveryPlanningReasonPrefix
+    [Console]::Out.WriteLine(($decision | ConvertTo-Json -Compress -Depth 5))
+    return 0
+}
+
+# Guard allows dot-sourcing in tests without executing the entrypoint.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('DISCOVERY_PLANNING_GATE_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'DISCOVERY_PLANNING_GATE_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
+
+exit (Invoke-DiscoveryPlanningGateEntryPoint -PayloadRaw ([Console]::In.ReadToEnd()))

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-orchestration-preimplementation-gate-epic-scope.ps1

@@ -4,12 +4,20 @@
 
 .DESCRIPTION
     Dot-sourced by enforce-orchestration-preimplementation-gate.ps1. The Codex counterpart
-    of the issue #663 Claude sibling, holding two groups of functions:
+    of the issue #663 Claude sibling, holding three groups of functions:
 
     - The two per-mode read seams of issue #554 (Get-EpicCheckpointContent and
       Get-ParallelCheckpointContent), relocated verbatim from the gate file so the gate
       stays inside the 500-line cap. Their names and behaviour are unchanged, so tests
       that mock or shadow them by name are unaffected.
+    - The target-resolution building blocks of issue #1010, byte-identical to the Claude
+      sibling: the worktree-list wrapper Get-OrchestrationGateWorktreeList (the only
+      listing seam), the recording invoker Invoke-OrchestrationGateWorktreeList, and the
+      command-operand parser Get-OrchestrationGateCommandOperandPath, plus the reason-code
+      pair restated from WorktreeResolution.psm1. They feed Resolve-OrchestrationGateTarget
+      and Read-OrchestrationGateCheckpoint, which read the single-feature checkpoint through
+      the Get-CheckpointContent seam (mandatory absolute Path, moved here from the gate)
+      beneath the worktree the file path, apply_patch markers, or command operands name.
     - The epic-scope decision for the command, apply_patch, and path legs. A call is epic
       scope when the effective worktree's HEAD (the -C selector worktree when present,
       otherwise the session root) equals the integration_branch of
@@ -29,13 +37,23 @@
     from the resolution sibling dot-sourced below. The per-segment target resolver comes
     from the targets file dot-sourced below (issue #738), which calls
     Read-CommandLineSegment, Get-CommandLineGlobalOption, and Get-CommandLineInvocation,
-    loaded by the gate's dot-source of hook-command-invocation.ps1.
+    loaded by the gate's dot-source of hook-command-invocation.ps1. Resolve-HookTargetWorktree
+    and ConvertFrom-HookTargetWorktreePorcelain come from the guarded dot-source of the
+    resolver twin hook-target-worktree.ps1 (issue #1009).
     Mirrored byte-identically under extensions/drm-copilot/resources/codex-and-agents-customizations/.
     AUTHORITY: PowerShell-authoritative. The epic readiness predicate has no reference implementation in another language, and this hook starts no interpreter process (issue #707, D15).
 #>
 
 . (Join-Path $PSScriptRoot 'enforce-orchestration-preimplementation-gate-epic-resolution.ps1')
 . (Join-Path $PSScriptRoot 'enforce-orchestration-preimplementation-gate-targets.ps1')
+try { . (Join-Path $PSScriptRoot 'hook-target-worktree.ps1') } catch { Add-HookDependencyFailure -Name 'hook-target-worktree.ps1' -ErrorRecord $_ }
+
+# The target-resolution reason codes (issue #1010). Their source is
+# Get-WorktreeResolutionAmbiguityReasonCode and Get-WorktreeResolutionNoTargetReasonCode
+# in .claude/lib/worktree-resolution/WorktreeResolution.psm1; Codex hooks cannot import
+# .claude/lib, so the two literals are restated once here and pinned equal by a test.
+$script:OrchestrationGateAmbiguousReasonCode = 'TARGET_WORKTREE_AMBIGUOUS'
+$script:OrchestrationGateNotDerivableReasonCode = 'TARGET_WORKTREE_NOT_DERIVABLE'
 
 # An epic manifest lives under the epics tree; the pattern is tested after backslash
 # normalisation so either separator spelling is accepted.
@@ -68,6 +86,225 @@ function Get-ParallelCheckpointContent {
     return Get-Content -Raw -LiteralPath $path
 }
 
+# The single-feature read seam (issue #1010, moved from the gate file). It takes the
+# absolute path composed beneath the resolved worktree root, so no read binds to the
+# calling process's directory; an absent file returns an empty string.
+function Get-CheckpointContent {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory)][ValidatePattern('^([A-Za-z]:[\\/]|/)')][string] $Path)
+
+    if (-not (Test-Path -LiteralPath $Path)) {
+        return ''
+    }
+    return Get-Content -Raw -LiteralPath $Path
+}
+
+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 single-feature path or command leg (issue #1010).
+    .DESCRIPTION
+        Calls Resolve-HookTargetWorktree with the recording invoker: a file path is passed as
+        -FilePath, the marker paths of an apply_patch body as -FilePath (markers in two
+        worktrees resolve as ambiguous), and any other command's
+        Get-OrchestrationGateCommandOperandPath result as -CommandOperandPath. A failed or
+        empty listing gives NoTarget instead of the session-root fallback; Ambiguous gives
+        Ambiguous; a null root gives NoTarget; otherwise SessionRoot or OtherWorktree.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject with Status, WorktreeRoot, ReasonCode, and Detail.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [AllowNull()][AllowEmptyString()][string] $FilePath = '',
+        [AllowNull()][AllowEmptyString()][string] $Command = ''
+    )
+
+    $sessionRoot = (Get-Location).Path
+    $script:OrchestrationGateWorktreeListFailed = $false
+    $invoker = { param($SessionRoot) Invoke-OrchestrationGateWorktreeList -SessionRoot $SessionRoot }
+    $markerPaths = if ($FilePath) { @() } else { @(Get-OrchestrationPatchMarkerPath -PatchText ([string]$Command)) }
+    $resolved = if ($FilePath) {
+        Resolve-HookTargetWorktree -SessionRoot $sessionRoot -FilePath @($FilePath) -WorktreeListInvoker $invoker
+    } elseif ($markerPaths.Count -gt 0) {
+        Resolve-HookTargetWorktree -SessionRoot $sessionRoot -FilePath $markerPaths -WorktreeListInvoker $invoker
+    } else {
+        Resolve-HookTargetWorktree -SessionRoot $sessionRoot -CommandOperandPath @(Get-OrchestrationGateCommandOperandPath -Command ([string]$Command)) -WorktreeListInvoker $invoker
+    }
+    $detail = "resolver source $($resolved.Source): $($resolved.Detail)"
+    if ($script:OrchestrationGateWorktreeListFailed) {
+        return [pscustomobject]@{ Status = 'NoTarget'; WorktreeRoot = $null; ReasonCode = $script:OrchestrationGateNotDerivableReasonCode; Detail = "the worktree listing failed or named no worktree; $detail" }
+    }
+    if ($resolved.Ambiguous) {
+        return [pscustomobject]@{ Status = 'Ambiguous'; WorktreeRoot = $null; ReasonCode = $script:OrchestrationGateAmbiguousReasonCode; Detail = $detail }
+    }
+    if ([string]::IsNullOrEmpty([string]$resolved.WorktreeRoot)) {
+        return [pscustomobject]@{ Status = 'NoTarget'; WorktreeRoot = $null; ReasonCode = $script:OrchestrationGateNotDerivableReasonCode; 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 {
+    <#
+    .SYNOPSIS
+        Reads the checkpoint beneath the resolved target worktree, or returns the deny reason.
+    .DESCRIPTION
+        Resolved is $false, with DenyReason set, when the target is NoTarget or Ambiguous.
+        Otherwise Raw holds the checkpoint text (empty when absent) and Path its absolute
+        path, composed beneath the resolved root with a forward slash.
+    .OUTPUTS
+        System.Management.Automation.PSCustomObject
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)][string] $Mode,
+        [AllowNull()][AllowEmptyString()][string] $FilePath = '',
+        [AllowNull()][AllowEmptyString()][string] $Command = ''
+    )
+
+    $target = Resolve-OrchestrationGateTarget -FilePath $FilePath -Command $Command
+    if ($target.Status -eq 'NoTarget' -or $target.Status -eq 'Ambiguous') {
+        return [pscustomobject]@{
+            Resolved   = $false
+            Raw        = ''
+            Path       = $null
+            DenyReason = ("PREIMPLEMENTATION_GATE_BLOCKED: $($target.ReasonCode): the target worktree of this $Mode call " +
+                "could not be resolved: $($target.Detail). Implementation operations require an identifiable target " +
+                'worktree whose checkpoint is ready.')
+        }
+    }
+
+    $path = ([string]$target.WorktreeRoot).TrimEnd('/') + '/artifacts/orchestration/orchestrator-state.json'
+    return [pscustomobject]@{
+        Resolved   = $true
+        Raw        = [string](Get-CheckpointContent -Path $path)
+        Path       = $path
+        DenyReason = $null
+    }
+}
+
 function Get-OrchestrationEpicScopeSelector {
     <#
     .SYNOPSIS

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-orchestration-preimplementation-gate.ps1

@@ -33,8 +33,6 @@ try { . (Join-Path $PSScriptRoot 'enforce-orchestration-preimplementation-gate-e
 # Shared command-line parser (issue #545): per-segment scan text and structural matching.
 try { . (Join-Path $PSScriptRoot 'hook-command-scanner.ps1') } catch { Add-HookDependencyFailure -Name 'hook-command-scanner.ps1' -ErrorRecord $_ }
 try { . (Join-Path $PSScriptRoot 'hook-command-invocation.ps1') } catch { Add-HookDependencyFailure -Name 'hook-command-invocation.ps1' -ErrorRecord $_ }
-# The readiness checkpoint this gate reads and names in its block message.
-$script:CheckpointPath = 'artifacts/orchestration/orchestrator-state.json'
 
 # Every orchestration checkpoint a planner or orchestrator surface writes. Writing one
 # of these is orchestration bookkeeping, not implementation, so the gate must not
@@ -270,7 +268,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) {
@@ -284,17 +282,6 @@ function Test-OrchestrationReady {
     )
 }
 
-function Get-CheckpointContent {
-    [CmdletBinding()]
-    [OutputType([string])]
-    param()
-
-    if (-not (Test-Path -LiteralPath $script:CheckpointPath)) {
-        return ''
-    }
-    return Get-Content -Raw -LiteralPath $script:CheckpointPath
-}
-
 function Get-OrchestrationPreimplementationGateAllowDecision {
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
@@ -445,8 +432,12 @@ function Invoke-OrchestrationPreimplementationGateDecision {
             Get-OrchestrationModeDenyReason -Mode $mode -Failure $failure)
     }
 
+    # Truthiness fall-through is kept: an empty -CheckpointRaw resolves like an unbound one.
+    # The checkpoint is read beneath the worktree the call targets (issue #1010).
     if (-not $CheckpointRaw) {
-        $CheckpointRaw = Get-CheckpointContent
+        $read = Read-OrchestrationGateCheckpoint -Mode 'single-feature' -FilePath $filePath -Command $command
+        if (-not $read.Resolved) { return Get-OrchestrationPreimplementationGateBlockDecision -Reason $read.DenyReason }
+        $CheckpointRaw = $read.Raw
     }
     try {
         $checkpoint = ConvertFrom-CheckpointJson -Json $CheckpointRaw

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-powershell-batch-budget.ps1

@@ -8,14 +8,26 @@
     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 Codex session. The
-    running set is persisted under .codex/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 .codex/prompts/orchestrate-work.md.
-
-    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 Codex 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 .codex/prompts/orchestrate-work.md.
+
+    Each evaluated path is placed with Resolve-HookTargetWorktree from the dot-sourced
+    hook-target-worktree.ps1. 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 route is read from
+    artifacts/orchestration/orchestrator-state.json in the resolved target worktree.
+    The running set is kept under the session root, in
+    .codex/state/powershell-batch-budget.<session_id>.json when the resolved target worktree
+    is the session root and in .codex/state/powershell-batch-budget.<session_id>.<worktree key>.json
+    otherwise; no state is written under another worktree. A path under the root-level
+    artifacts/ directory of the resolved target worktree is never counted and writes no
+    state. No containment filter applies: a path outside every registered worktree is
+    counted against the session root, as before.
+
+    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
@@ -36,9 +48,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+.
@@ -51,6 +66,9 @@ $script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot
 # mapping for every tool name the ^(apply_patch|Edit|Write)$ matcher admits.
 try { . (Join-Path $PSScriptRoot 'codex-pretooluse-file-mapping.ps1') } catch { Add-HookDependencyFailure -Name 'codex-pretooluse-file-mapping.ps1' -ErrorRecord $_ }
 
+# Shared target-worktree resolver; the Codex twin of HookTargetWorktree.psm1.
+try { . (Join-Path $PSScriptRoot 'hook-target-worktree.ps1') } catch { Add-HookDependencyFailure -Name 'hook-target-worktree.ps1' -ErrorRecord $_ }
+
 # Shared route helpers; this file is byte-identical to the Claude runtime copy.
 $script:PowerShellBatchBudgetRouteImportFailure = $null; try { . (Join-Path $PSScriptRoot 'enforce-batch-budget-route.ps1') } catch { $script:PowerShellBatchBudgetRouteImportFailure = 'enforce-batch-budget-route.ps1' }
 
@@ -194,7 +212,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
     )
 
     if (-not $ToolInputRaw) {
@@ -218,12 +237,31 @@ 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 path is evaluated against the registered worktree that holds it; the session root
+    # is the fallback for a relative path, a path in no registered worktree, and an ambiguous result.
+    $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 '.codex/state'
-    $stateFile = Join-Path -Path $stateDir -ChildPath ("powershell-batch-budget.$SessionId.json")
+    $stateLeaf = if ($isSessionRoot) { "powershell-batch-budget.$SessionId.json" } else { "powershell-batch-budget.$SessionId.$(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)
@@ -279,7 +317,8 @@ function Invoke-PowerShellBatchBudgetCodexEntryPoint {
     .PARAMETER PayloadRaw
         Raw PreToolUse payload text.
     .PARAMETER RepositoryRoot
-        Root used to locate the Codex state directory and the orchestrator checkpoint.
+        Session root: it locates the Codex state directory and is the fallback root. The
+        orchestrator checkpoint comes from the resolved target worktree of each path.
     .PARAMETER HookSeams
         Optional seam overrides splatted into Invoke-PowerShellBatchBudgetHook.
     #>