@danmoisan/drm-copilot-mcp 1.0.26 → 1.1.0

package/resources/claude-customizations/.claude/hooks/enforce-parallel-cohort-barrier.ps1

@@ -4,7 +4,7 @@
 
 .DESCRIPTION
     Invoked by the Claude Code PreToolUse hook on the "Agent" matcher before any Agent
-    (Task) call runs. Activates only when CLAUDE_TOOL_INPUT.subagent_type == "orchestrator"
+    (Task) call runs. Activates only when the envelope's tool_input.subagent_type == "orchestrator"
     and the serialized prompt contains the parallel kickoff marker "Parallel mode: true".
 
     Adapted from enforce-epic-wave-barrier.ps1. The parallel surface has no depends_on
@@ -47,10 +47,16 @@
 [CmdletBinding()]
 param()
 
+
+Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
 $script:ParallelCheckpointPath = 'artifacts/orchestration/parallel-orchestrator-state.json'
 $script:AllowedMergeStatuses = @('merged', 'worktree_removed')
 $script:ParallelModeMarker = 'Parallel mode: true'
 
+# Dot-source the record-resolution and barrier helpers. Guarded so dot-sourcing this
+# hook in tests loads the helpers too (issue #501 headroom split).
+. (Join-Path $PSScriptRoot 'enforce-parallel-cohort-barrier-helpers.ps1')
+
 function Get-ParallelCohortBarrierCheckpointContent {
     <#
     .SYNOPSIS
@@ -145,255 +151,6 @@ function Find-ParallelCohortBarrierFeatureFolderFromPrompt {
     return (Get-ParallelCohortBarrierFolderBasename -FolderPath $candidates[0])
 }
 
-function Find-ParallelCohortBarrierItemRecord {
-    <#
-    .SYNOPSIS
-        Locate the items[] record whose feature_folder resolves to the target basename.
-    .PARAMETER Checkpoint
-        Parsed parallel checkpoint, or $null when absent/unreadable.
-    .PARAMETER FeatureFolder
-        The target feature_folder basename resolved from the prompt.
-    .OUTPUTS
-        System.Object or $null
-    #>
-    [CmdletBinding()]
-    param(
-        [AllowNull()]
-        $Checkpoint,
-
-        [AllowNull()]
-        [string] $FeatureFolder
-    )
-
-    if ($null -eq $Checkpoint -or [string]::IsNullOrWhiteSpace($FeatureFolder)) {
-        return $null
-    }
-    $checkpointProps = @($Checkpoint.PSObject.Properties.Name)
-    if ($checkpointProps -notcontains 'items') {
-        return $null
-    }
-
-    # Scan every recorded item for a feature_folder whose basename equals the target.
-    foreach ($item in @($Checkpoint.items)) {
-        $itemProps = @($item.PSObject.Properties.Name)
-        if ($itemProps -notcontains 'feature_folder') {
-            continue
-        }
-        $itemBasename = Get-ParallelCohortBarrierFolderBasename -FolderPath ([string]$item.feature_folder)
-        if ($itemBasename -eq $FeatureFolder) {
-            return $item
-        }
-    }
-    return $null
-}
-
-function Find-ParallelCohortBarrierItemByKey {
-    <#
-    .SYNOPSIS
-        Locate the items[] record whose issue_num equals the supplied key.
-    .PARAMETER Checkpoint
-        Parsed parallel checkpoint, or $null when absent/unreadable.
-    .PARAMETER IssueKey
-        The item primary key (issue_num) rendered as a string.
-    .OUTPUTS
-        System.Object or $null
-    #>
-    [CmdletBinding()]
-    param(
-        [AllowNull()]
-        $Checkpoint,
-
-        [AllowNull()]
-        [string] $IssueKey
-    )
-
-    if ($null -eq $Checkpoint -or [string]::IsNullOrWhiteSpace($IssueKey)) {
-        return $null
-    }
-    $checkpointProps = @($Checkpoint.PSObject.Properties.Name)
-    if ($checkpointProps -notcontains 'items') {
-        return $null
-    }
-
-    foreach ($item in @($Checkpoint.items)) {
-        $itemProps = @($item.PSObject.Properties.Name)
-        if ($itemProps -notcontains 'issue_num') {
-            continue
-        }
-        if (([string]$item.issue_num) -eq $IssueKey) {
-            return $item
-        }
-    }
-    return $null
-}
-
-function Find-ParallelCohortBarrierCohortIndex {
-    <#
-    .SYNOPSIS
-        Return the current-generation cohort index that holds the supplied item key.
-    .DESCRIPTION
-        The cohort projection is restricted to cohorts[] rows whose generation equals the
-        top-level recolor_generation, which is the current coloring. Rows from a superseded
-        generation are ignored. Returns $null when the checkpoint records no
-        recolor_generation, no cohorts, or no current-generation cohort containing the key.
-    .PARAMETER Checkpoint
-        Parsed parallel checkpoint, or $null when absent/unreadable.
-    .PARAMETER IssueKey
-        The item primary key (issue_num) rendered as a string.
-    .OUTPUTS
-        System.Int32 or $null
-    #>
-    [CmdletBinding()]
-    [OutputType([int])]
-    param(
-        [AllowNull()]
-        $Checkpoint,
-
-        [AllowNull()]
-        [string] $IssueKey
-    )
-
-    if ($null -eq $Checkpoint -or [string]::IsNullOrWhiteSpace($IssueKey)) {
-        return $null
-    }
-    $checkpointProps = @($Checkpoint.PSObject.Properties.Name)
-    if ($checkpointProps -notcontains 'cohorts' -or $checkpointProps -notcontains 'recolor_generation') {
-        return $null
-    }
-
-    $currentGeneration = [string]$Checkpoint.recolor_generation
-
-    foreach ($cohort in @($Checkpoint.cohorts)) {
-        $cohortProps = @($cohort.PSObject.Properties.Name)
-        if ($cohortProps -notcontains 'index' -or $cohortProps -notcontains 'generation' -or $cohortProps -notcontains 'item_keys') {
-            continue
-        }
-        if (([string]$cohort.generation) -ne $currentGeneration) {
-            continue
-        }
-        $parsedIndex = 0
-        if (-not [int]::TryParse(([string]$cohort.index), [ref] $parsedIndex)) {
-            continue
-        }
-        foreach ($key in @($cohort.item_keys)) {
-            if (([string]$key) -eq $IssueKey) {
-                return $parsedIndex
-            }
-        }
-    }
-    return $null
-}
-
-function Get-ParallelCohortBarrierConflictNeighborList {
-    <#
-    .SYNOPSIS
-        Return the item keys that share a conflict edge with the supplied item key.
-    .PARAMETER Checkpoint
-        Parsed parallel checkpoint, or $null when absent/unreadable.
-    .PARAMETER IssueKey
-        The item primary key (issue_num) rendered as a string.
-    .OUTPUTS
-        System.Object[] holding each neighbor item key rendered as a string.
-    #>
-    [CmdletBinding()]
-    [OutputType([object[]])]
-    param(
-        [AllowNull()]
-        $Checkpoint,
-
-        [AllowNull()]
-        [string] $IssueKey
-    )
-
-    $neighborList = @()
-    if ($null -eq $Checkpoint -or [string]::IsNullOrWhiteSpace($IssueKey)) {
-        return $neighborList
-    }
-    $checkpointProps = @($Checkpoint.PSObject.Properties.Name)
-    if ($checkpointProps -notcontains 'conflict_edges') {
-        return $neighborList
-    }
-
-    # Edges are undirected and canonically normalized to a < b, so both endpoints are
-    # inspected and the opposite endpoint is returned as the neighbor.
-    foreach ($edge in @($Checkpoint.conflict_edges)) {
-        $edgeProps = @($edge.PSObject.Properties.Name)
-        if ($edgeProps -notcontains 'a' -or $edgeProps -notcontains 'b') {
-            continue
-        }
-        $endpointA = [string]$edge.a
-        $endpointB = [string]$edge.b
-        if ($endpointA -eq $IssueKey) {
-            $neighborList += $endpointB
-        } elseif ($endpointB -eq $IssueKey) {
-            $neighborList += $endpointA
-        }
-    }
-    return $neighborList
-}
-
-function Test-ParallelCohortBarrierClear {
-    <#
-    .SYNOPSIS
-        Decision logic: true only when every conflicting neighbor in a strictly prior
-        current-generation cohort has merge_status merged or worktree_removed.
-    .PARAMETER Checkpoint
-        Parsed parallel checkpoint, or $null when absent/unreadable.
-    .PARAMETER ItemRecord
-        The target item's own items[] record, or $null when not found.
-    .OUTPUTS
-        System.Boolean
-    #>
-    [CmdletBinding()]
-    [OutputType([bool])]
-    param(
-        [AllowNull()]
-        $Checkpoint,
-
-        [AllowNull()]
-        $ItemRecord
-    )
-
-    if ($null -eq $Checkpoint -or $null -eq $ItemRecord) {
-        return $false
-    }
-    $itemProps = @($ItemRecord.PSObject.Properties.Name)
-    if ($itemProps -notcontains 'issue_num') {
-        return $false
-    }
-
-    $targetKey = [string]$ItemRecord.issue_num
-    $targetIndex = Find-ParallelCohortBarrierCohortIndex -Checkpoint $Checkpoint -IssueKey $targetKey
-    if ($null -eq $targetIndex) {
-        # No current-generation cohort assignment: position is unknown, so fail closed.
-        return $false
-    }
-
-    foreach ($neighborKey in @(Get-ParallelCohortBarrierConflictNeighborList -Checkpoint $Checkpoint -IssueKey $targetKey)) {
-        $neighborIndex = Find-ParallelCohortBarrierCohortIndex -Checkpoint $Checkpoint -IssueKey $neighborKey
-        if ($null -eq $neighborIndex) {
-            # Not part of the current coloring, so not a strictly prior cohort neighbor.
-            continue
-        }
-        if ($neighborIndex -ge $targetIndex) {
-            # Same-cohort and later-cohort contention is not a Layer 1 concern.
-            continue
-        }
-        $neighborRecord = Find-ParallelCohortBarrierItemByKey -Checkpoint $Checkpoint -IssueKey $neighborKey
-        if ($null -eq $neighborRecord) {
-            return $false
-        }
-        $neighborProps = @($neighborRecord.PSObject.Properties.Name)
-        if ($neighborProps -notcontains 'merge_status') {
-            return $false
-        }
-        if ($script:AllowedMergeStatuses -notcontains ([string]$neighborRecord.merge_status)) {
-            return $false
-        }
-    }
-    return $true
-}
-
 function Get-ParallelCohortBarrierAllowDecision {
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
@@ -427,7 +184,7 @@ function Get-ParallelCohortBarrierBlockDecision {
 function Invoke-ParallelCohortBarrierDecision {
     <#
     .SYNOPSIS
-        Parses CLAUDE_TOOL_INPUT and returns an allow-or-block decision.
+        Parses the PreToolUse envelope and returns an allow-or-block decision.
     .PARAMETER ToolInputRaw
         The raw JSON tool payload supplied by Claude Code.
     .OUTPUTS
@@ -439,22 +196,20 @@ function Invoke-ParallelCohortBarrierDecision {
         [string] $ToolInputRaw
     )
 
-    if (-not $ToolInputRaw) {
-        return Get-ParallelCohortBarrierAllowDecision
-    }
-
-    try {
-        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
-    } catch {
-        throw "enforce-parallel-cohort-barrier hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    $envelope = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
+    if (-not $envelope.IsValid) {
+        return Get-ParallelCohortBarrierBlockDecision -Reason (
+            'PARALLEL_COHORT_BARRIER_BLOCKED: payload anomaly - ' +
+            (Get-ClaudeHookPayloadAnomalyReason -Anomaly $envelope.Anomaly) +
+            '. The gate fails closed on an envelope it cannot read.')
     }
 
-    $subagent = $toolInput.subagent_type
+    $subagent = Get-ClaudeHookToolInputString -ToolInput $envelope.Value -Name 'subagent_type'
     if (-not $subagent -or $subagent -ne 'orchestrator') {
         return Get-ParallelCohortBarrierAllowDecision
     }
 
-    $prompt = [string]$toolInput.prompt
+    $prompt = Get-ClaudeHookToolInputString -ToolInput $envelope.Value -Name 'prompt'
     if (-not $prompt -or $prompt -notlike "*$script:ParallelModeMarker*") {
         return Get-ParallelCohortBarrierAllowDecision
     }
@@ -482,18 +237,47 @@ function Invoke-ParallelCohortBarrierDecision {
     return Get-ParallelCohortBarrierBlockDecision -Reason "PARALLEL_COHORT_BARRIER_BLOCKED: '$featureFolder' cannot start until every conflicting item in a strictly prior current-generation cohort is durably confirmed merged or worktree_removed in the parallel checkpoint. The checkpoint was unreadable, the items[] record was not found, the item has no current-generation cohort assignment, or a conflicting prior-cohort item is not yet safe (ci_green does not satisfy the barrier)."
 }
 
+function Invoke-ParallelCohortBarrierEntryPoint {
+    <#
+    .SYNOPSIS
+        Runs the hook decision and returns the process exit code.
+    .DESCRIPTION
+        Acquires the payload through the shared reader unless the caller supplies
+        one, emits the compact decision JSON, and returns 0. It never returns 1:
+        exit 1 is non-blocking for PreToolUse, so every anomaly is already a deny
+        decision by the time control reaches here. The function does not call exit;
+        the thin tail converts the returned code into a process exit.
+    .PARAMETER ToolInputRaw
+        Optional pre-acquired payload text. When omitted the ReadPayload seam runs.
+    .PARAMETER ReadPayload
+        Seam for payload acquisition, so tests can drive the empty-on-all-transports
+        case without touching a console.
+    .OUTPUTS
+        System.Int32
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $ToolInputRaw,
+
+        [scriptblock] $ReadPayload = { Read-ClaudeHookRawPayload }
+    )
+
+    if (-not $PSBoundParameters.ContainsKey('ToolInputRaw')) {
+        $ToolInputRaw = [string](& $ReadPayload)
+    }
+
+    $decision = Invoke-ParallelCohortBarrierDecision -ToolInputRaw $ToolInputRaw
+    $decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
+
+    return 0
+}
+
 # Guard allows dot-sourcing in tests without executing the entrypoint.
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
 
-try {
-    $decision = Invoke-ParallelCohortBarrierDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
-} catch {
-    Write-Error $_
-    exit 1
-}
-
-$decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
-
-exit 0
+exit (Invoke-ParallelCohortBarrierEntryPoint)

package/resources/claude-customizations/.claude/hooks/enforce-parallel-drift-gate.ps1

@@ -4,7 +4,7 @@
 
 .DESCRIPTION
     Invoked by the Claude Code PreToolUse hook on the "Agent" matcher. Activates only when
-    CLAUDE_TOOL_INPUT.subagent_type == "feature-review" and the prompt carries the
+    the envelope's nested tool_input.subagent_type == "feature-review" and the prompt carries the
     parallel-mode kickoff marker defined in the "Parallel-Mode Kickoff Parameter" section
     of .claude/skills/parallel-orchestrate/SKILL.md, matched byte-for-byte (ordinal).
 
@@ -61,6 +61,8 @@
 [CmdletBinding()]
 param()
 
+
+Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
 # Dot-source the shape-and-derivation helpers. Guarded so a missing file produces a clear error
 # and so dot-sourcing this hook in tests loads the helpers too.
 $script:ParallelDriftGateHelpersPath = Join-Path $PSScriptRoot 'enforce-parallel-drift-gate-helpers.ps1'
@@ -270,28 +272,32 @@ function Get-ParallelDriftGateBlockDecision {
 function Invoke-ParallelDriftGateDecision {
     <#
     .SYNOPSIS
-        Parse the raw CLAUDE_TOOL_INPUT JSON payload and return an allow-or-block decision.
+        Parse the PreToolUse envelope and return an allow-or-block decision.
     #>
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
-    param([string] $ToolInputRaw)
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $ToolInputRaw
+    )
 
-    if (-not $ToolInputRaw) {
-        return Get-ParallelDriftGateAllowDecision
-    }
-    try {
-        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
-    } catch {
-        throw "enforce-parallel-drift-gate hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    $envelope = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
+    if (-not $envelope.IsValid) {
+        return Get-ParallelDriftGateBlockDecision -Reason (
+            'PARALLEL_DRIFT_GATE_BLOCKED: payload anomaly - ' +
+            (Get-ClaudeHookPayloadAnomalyReason -Anomaly $envelope.Anomaly) +
+            '. The gate fails closed on an envelope it cannot read.')
     }
 
     # Two cheap disqualifiers first: this gate governs only feature-review delegations, and
     # only under the parallel-mode marker, matched byte-for-byte with an ordinal Contains
     # rather than a wildcard or a culture-sensitive comparison.
-    if (([string]$toolInput.subagent_type) -cne $script:ReviewSubagentType) {
+    $subagent = Get-ClaudeHookToolInputString -ToolInput $envelope.Value -Name 'subagent_type'
+    if ($subagent -cne $script:ReviewSubagentType) {
         return Get-ParallelDriftGateAllowDecision
     }
-    $prompt = [string]$toolInput.prompt
+    $prompt = Get-ClaudeHookToolInputString -ToolInput $envelope.Value -Name 'prompt'
     if (-not $prompt -or -not $prompt.Contains($script:ParallelModeMarker, [System.StringComparison]::Ordinal)) {
         return Get-ParallelDriftGateAllowDecision
     }
@@ -342,18 +348,47 @@ function Invoke-ParallelDriftGateDecision {
     return Get-ParallelDriftGateBlockDecision -Reason "PARALLEL_DRIFT_GATE_BLOCKED: item $itemKey ('$featureFolder') has an unresolved radius drift event and no $script:FindingFilePrefix<timestamp>$script:FindingFileSuffix finding dated at or after that event recorded in its feature folder. The synthetic Blocking finding for the current event must be written before review proceeds, or the drift event log was unreadable."
 }
 
+function Invoke-ParallelDriftGateEntryPoint {
+    <#
+    .SYNOPSIS
+        Runs the hook decision and returns the process exit code.
+    .DESCRIPTION
+        Acquires the payload through the shared reader unless the caller supplies
+        one, emits the compact decision JSON, and returns 0. It never returns 1:
+        exit 1 is non-blocking for PreToolUse, so every anomaly is already a deny
+        decision by the time control reaches here. The function does not call exit;
+        the thin tail converts the returned code into a process exit.
+    .PARAMETER ToolInputRaw
+        Optional pre-acquired payload text. When omitted the ReadPayload seam runs.
+    .PARAMETER ReadPayload
+        Seam for payload acquisition, so tests can drive the empty-on-all-transports
+        case without touching a console.
+    .OUTPUTS
+        System.Int32
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $ToolInputRaw,
+
+        [scriptblock] $ReadPayload = { Read-ClaudeHookRawPayload }
+    )
+
+    if (-not $PSBoundParameters.ContainsKey('ToolInputRaw')) {
+        $ToolInputRaw = [string](& $ReadPayload)
+    }
+
+    $decision = Invoke-ParallelDriftGateDecision -ToolInputRaw $ToolInputRaw
+    $decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
+
+    return 0
+}
+
 # Guard allows dot-sourcing in tests without executing the entrypoint.
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
 
-try {
-    $decision = Invoke-ParallelDriftGateDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
-} catch {
-    Write-Error $_
-    exit 1
-}
-
-$decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
-
-exit 0
+exit (Invoke-ParallelDriftGateEntryPoint)

package/resources/claude-customizations/.claude/hooks/enforce-parallel-worktree-removal-gate.ps1

@@ -4,7 +4,7 @@
 
 .DESCRIPTION
     Invoked by the Claude Code PreToolUse hook on the "Bash" matcher before any Bash
-    command runs. Regex-matches git worktree remove against CLAUDE_TOOL_INPUT.command,
+    command runs. Regex-matches git worktree remove against the envelope's tool_input.command,
     extracts the target worktree path argument, reads
     artifacts/orchestration/parallel-orchestrator-state.json, and finds the items[] record
     whose worktree_path matches. Allows removal only when that record's merge_status is
@@ -28,6 +28,8 @@
 [CmdletBinding()]
 param()
 
+
+Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
 $script:ParallelCheckpointPath = 'artifacts/orchestration/parallel-orchestrator-state.json'
 $script:AllowedMergeStatuses = @('merged', 'worktree_removed')
 
@@ -176,7 +178,7 @@ function Get-ParallelWorktreeGateBlockDecision {
 function Invoke-ParallelWorktreeRemovalGateDecision {
     <#
     .SYNOPSIS
-        Parses CLAUDE_TOOL_INPUT and returns an allow-or-block decision.
+        Parses the PreToolUse envelope and returns an allow-or-block decision.
     .PARAMETER ToolInputRaw
         The raw JSON tool payload supplied by Claude Code.
     .OUTPUTS
@@ -188,17 +190,15 @@ function Invoke-ParallelWorktreeRemovalGateDecision {
         [string] $ToolInputRaw
     )
 
-    if (-not $ToolInputRaw) {
-        return Get-ParallelWorktreeGateAllowDecision
-    }
-
-    try {
-        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
-    } catch {
-        throw "enforce-parallel-worktree-removal-gate hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
+    if (-not $payload.IsValid) {
+        return Get-ParallelWorktreeGateBlockDecision -Reason (
+            'PARALLEL_WORKTREE_REMOVAL_BLOCKED: payload anomaly - ' +
+            (Get-ClaudeHookPayloadAnomalyReason -Anomaly $payload.Anomaly) +
+            '. The gate fails closed on an envelope it cannot read.')
     }
 
-    $commandText = $toolInput.command
+    $commandText = Get-ClaudeHookToolInputString -ToolInput $payload.Value -Name 'command'
     if (-not $commandText) {
         return Get-ParallelWorktreeGateAllowDecision
     }
@@ -227,18 +227,55 @@ function Invoke-ParallelWorktreeRemovalGateDecision {
     return Get-ParallelWorktreeGateBlockDecision -Reason "PARALLEL_WORKTREE_REMOVAL_BLOCKED: git worktree remove for '$worktreePath' requires a matching parallel checkpoint items[] record with merge_status in {merged, worktree_removed}. The checkpoint was unreadable, no matching record was found, or merge_status was not yet safe for removal."
 }
 
+function Invoke-ParallelWorktreeRemovalGateEntryPoint {
+    <#
+    .SYNOPSIS
+        Runs the hook decision and returns the process exit code.
+    .DESCRIPTION
+        Acquires the payload through the shared reader unless the caller supplies
+        one, emits the compact decision JSON, and returns 0. It never returns 1:
+        exit 1 is non-blocking for PreToolUse, so every anomaly is already a deny
+        decision by the time control reaches here. The function does not call exit;
+        the thin tail converts the returned code into a process exit.
+    .PARAMETER ToolInputRaw
+        Optional pre-acquired payload text. When omitted the ReadPayload seam runs.
+    .PARAMETER ReadPayload
+        Seam for payload acquisition, so tests can drive the empty-on-all-transports
+        case without touching a console.
+    .OUTPUTS
+        System.Int32
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $ToolInputRaw,
+
+        [scriptblock] $ReadPayload = { Read-ClaudeHookRawPayload }
+    )
+
+    if (-not $PSBoundParameters.ContainsKey('ToolInputRaw')) {
+        $ToolInputRaw = [string](& $ReadPayload)
+    }
+
+    $decision = Invoke-ParallelWorktreeRemovalGateDecision -ToolInputRaw $ToolInputRaw
+    $decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
+
+    return 0
+}
+
 # Guard allows dot-sourcing in tests without executing the entrypoint.
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
 
-try {
-    $decision = Invoke-ParallelWorktreeRemovalGateDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
-} catch {
-    Write-Error $_
-    exit 1
+# The entry point returns its [int] exit code as the last pipeline element and the
+# decision JSON before it. `exit (<call>)` would capture BOTH into the exit
+# expression and emit nothing, so the decision is written explicitly here first.
+$entryPointResult = @(Invoke-ParallelWorktreeRemovalGateEntryPoint)
+if ($entryPointResult.Count -gt 1) {
+    $entryPointResult[0..($entryPointResult.Count - 2)] | Write-Output
 }
 
-$decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
-
-exit 0
+exit ([int]$entryPointResult[-1])