@danmoisan/drm-copilot-mcp 1.0.26 → 1.1.0

package/resources/claude-customizations/.claude/hooks/enforce-epic-merge-gate.ps1

@@ -5,7 +5,7 @@
 .DESCRIPTION
     Invoked by the Claude Code PreToolUse hook on the "Bash" matcher before any Bash
     command runs. Regex-matches gh pr merge with a --merge flag against
-    CLAUDE_TOOL_INPUT.command and, when matched, allows the merge only when one of two
+    the envelope's tool_input.command and, when matched, allows the merge only when one of three
     checkpoint-only conditions holds:
 
       1. Child-feature path: artifacts/orchestration/orchestrator-state.json exists,
@@ -14,11 +14,17 @@
       2. Epic-integration path: artifacts/orchestration/epic-orchestrator-state.json exists,
          epic_merge_pr.ci_gate.conclusion == "success", and, when the command names an
          explicit PR number, that number matches epic_merge_pr.pr_number.
+      3. Parallel path: artifacts/orchestration/parallel-orchestrator-state.json exists,
+         route_id == "parallel", and the command's explicit PR number matches an items[]
+         entry whose merge_status == "ci_green". A parallel run always names an explicit PR
+         number (each item merges from its own isolated worktree), so a bare command with no
+         PR number cannot satisfy this branch.
 
     Otherwise the command is denied with reason EPIC_MERGE_GATE_BLOCKED. A missing or
-    unreadable checkpoint in either branch fails closed (denies); standalone (non-epic)
-    orchestration never sets epic_mode or populates epic_merge_pr, so it is structurally
-    prevented from invoking gh pr merge --merge at all.
+    unreadable checkpoint in any branch fails closed (denies); standalone (non-epic,
+    non-parallel) orchestration never sets epic_mode, populates epic_merge_pr, or writes a
+    parallel checkpoint with route_id == "parallel", so it is structurally prevented from
+    invoking gh pr merge --merge at all.
 
     Design decision: this gate trusts the on-disk checkpoint rather than shelling out live
     to gh pr view for a real-time head-SHA check, matching the same non-adversarial,
@@ -33,8 +39,11 @@
 [CmdletBinding()]
 param()
 
+Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+
 $script:ChildCheckpointPath = 'artifacts/orchestration/orchestrator-state.json'
 $script:EpicCheckpointPath = 'artifacts/orchestration/epic-orchestrator-state.json'
+$script:ParallelCheckpointPath = 'artifacts/orchestration/parallel-orchestrator-state.json'
 
 function Get-ChildOrchestratorCheckpointContent {
     <#
@@ -72,6 +81,24 @@ function Get-EpicOrchestratorCheckpointContent {
     return (Get-Content -LiteralPath $script:EpicCheckpointPath -Raw)
 }
 
+function Get-ParallelOrchestratorCheckpointContent {
+    <#
+    .SYNOPSIS
+        Read the raw JSON text of the parallel-orchestrator checkpoint. Tests mock
+        this function (read seam).
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param()
+
+    if (-not (Test-Path -LiteralPath $script:ParallelCheckpointPath -PathType Leaf)) {
+        return $null
+    }
+    return (Get-Content -LiteralPath $script:ParallelCheckpointPath -Raw)
+}
+
 function ConvertFrom-EpicMergeGateJson {
     <#
     .SYNOPSIS
@@ -113,9 +140,20 @@ function Get-EpicMergeGateCommandPrNumber {
         [string] $CommandText
     )
 
+    # Original form: the PR number appears immediately after "merge"
+    # (e.g. "gh pr merge 410 --merge"). Preserved verbatim so epic-path outcomes
+    # for the forms the epic path uses are unchanged.
     if ($CommandText -match '(?i)\bgh\s+pr\s+merge\s+(\d+)\b') {
         return [int]$Matches[1]
     }
+    # Broadened, additive form: the parallel command places the flag before the
+    # number (e.g. "gh pr merge --merge 410"). Once "gh pr merge" is confirmed,
+    # capture the first standalone run of digits that is not preceded by "-" or a
+    # word character, so a flag token such as "--merge" is not treated as a number
+    # and a bare "gh pr merge --merge" still yields $null.
+    if ($CommandText -match '(?i)\bgh\s+pr\s+merge\b' -and $CommandText -match '(?<![-\w])(\d+)\b') {
+        return [int]$Matches[1]
+    }
     return $null
 }
 
@@ -206,6 +244,69 @@ function Test-EpicCheckpointAllowsMerge {
     return $true
 }
 
+function Test-ParallelCheckpointAllowsMerge {
+    <#
+    .SYNOPSIS
+        Decision logic for the parallel-orchestrator checkpoint path (branch 3).
+    .PARAMETER Checkpoint
+        Parsed parallel-orchestrator checkpoint, or $null when absent/unreadable.
+    .PARAMETER CommandPrNumber
+        The explicit PR number parsed from the command, or $null when the command
+        does not name one. A parallel run always names an explicit PR number because
+        each item merges from its own isolated worktree, so a $null value denies.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowNull()]
+        $Checkpoint,
+
+        [AllowNull()]
+        [Nullable[int]] $CommandPrNumber
+    )
+
+    if ($null -eq $Checkpoint) {
+        return $false
+    }
+    $props = @($Checkpoint.PSObject.Properties.Name)
+    if ($props -notcontains 'route_id' -or ([string]$Checkpoint.route_id) -ne 'parallel') {
+        return $false
+    }
+    # A parallel merge always names an explicit PR number; without one the target
+    # item cannot be identified, so fail closed.
+    if ($null -eq $CommandPrNumber) {
+        return $false
+    }
+    if ($props -notcontains 'items' -or $null -eq $Checkpoint.items) {
+        return $false
+    }
+
+    foreach ($item in @($Checkpoint.items)) {
+        if ($null -eq $item) {
+            continue
+        }
+        $itemProps = @($item.PSObject.Properties.Name)
+        if ($itemProps -notcontains 'pr_number') {
+            continue
+        }
+        $itemPrNumber = 0
+        if (-not [int]::TryParse([string]$item.pr_number, [ref] $itemPrNumber)) {
+            continue
+        }
+        if ($itemPrNumber -ne $CommandPrNumber) {
+            continue
+        }
+        if ($itemProps -notcontains 'merge_status') {
+            return $false
+        }
+        return ([string]$item.merge_status) -eq 'ci_green'
+    }
+
+    return $false
+}
+
 function Get-EpicMergeGateAllowDecision {
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
@@ -239,29 +340,34 @@ function Get-EpicMergeGateBlockDecision {
 function Invoke-EpicMergeGateDecision {
     <#
     .SYNOPSIS
-        Parses CLAUDE_TOOL_INPUT and returns an allow-or-block decision.
+        Parses the PreToolUse envelope and returns an allow-or-block decision.
+    .DESCRIPTION
+        Envelope-level anomalies (empty payload, unparseable JSON, missing or
+        malformed tool_input) fail closed as a deny; the legacy flat root shape is
+        one such anomaly. Property-level absence of command inside a well-formed
+        tool_input remains an allow, because that is this gate's scope filter.
     .PARAMETER ToolInputRaw
-        The raw JSON tool payload supplied by Claude Code.
+        The raw JSON hook payload acquired by Read-ClaudeHookRawPayload.
     .OUTPUTS
         System.Collections.Specialized.OrderedDictionary
     #>
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
     param(
+        [AllowNull()]
+        [AllowEmptyString()]
         [string] $ToolInputRaw
     )
 
-    if (-not $ToolInputRaw) {
-        return Get-EpicMergeGateAllowDecision
-    }
-
-    try {
-        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
-    } catch {
-        throw "enforce-epic-merge-gate hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
+    if (-not $payload.IsValid) {
+        return Get-EpicMergeGateBlockDecision -Reason (
+            'EPIC_MERGE_GATE_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-EpicMergeGateAllowDecision
     }
@@ -284,7 +390,50 @@ function Invoke-EpicMergeGateDecision {
         return Get-EpicMergeGateAllowDecision
     }
 
-    return Get-EpicMergeGateBlockDecision -Reason 'EPIC_MERGE_GATE_BLOCKED: gh pr merge --merge requires either a per-feature checkpoint with epic_mode == true and step9_status == "passed", or an epic checkpoint with epic_merge_pr.ci_gate.conclusion == "success" and a matching pr_number. Neither checkpoint satisfied this gate.'
+    $parallelCheckpoint = ConvertFrom-EpicMergeGateJson -Raw (Get-ParallelOrchestratorCheckpointContent)
+    if (Test-ParallelCheckpointAllowsMerge -Checkpoint $parallelCheckpoint -CommandPrNumber $commandPrNumber) {
+        return Get-EpicMergeGateAllowDecision
+    }
+
+    return Get-EpicMergeGateBlockDecision -Reason 'EPIC_MERGE_GATE_BLOCKED: gh pr merge --merge requires either a per-feature checkpoint with epic_mode == true and step9_status == "passed", an epic checkpoint with epic_merge_pr.ci_gate.conclusion == "success" and a matching pr_number, or a parallel-orchestrator checkpoint with route_id == "parallel" whose target item (matched by pr_number) has merge_status == "ci_green". No checkpoint satisfied this gate.'
+}
+
+function Invoke-EpicMergeGateEntryPoint {
+    <#
+    .SYNOPSIS
+        Runs the merge-gate 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-EpicMergeGateDecision -ToolInputRaw $ToolInputRaw
+    $decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
+
+    return 0
 }
 
 # Guard allows dot-sourcing in tests without executing the entrypoint.
@@ -292,13 +441,12 @@ if ($MyInvocation.InvocationName -eq '.') {
     return
 }
 
-try {
-    $decision = Invoke-EpicMergeGateDecision -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-EpicMergeGateEntryPoint)
+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])

package/resources/claude-customizations/.claude/hooks/enforce-epic-wave-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 nested tool_input.subagent_type == "orchestrator"
     and the serialized prompt contains the epic-mode kickoff marker "Epic mode: true".
 
     Resolution and decision procedure:
@@ -33,6 +33,8 @@
 [CmdletBinding()]
 param()
 
+
+Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
 $script:EpicCheckpointPath = 'artifacts/orchestration/epic-orchestrator-state.json'
 $script:AllowedMergeStatuses = @('merged', 'worktree_removed')
 $script:EpicModeMarker = 'Epic mode: true'
@@ -232,7 +234,7 @@ function Get-EpicWaveBarrierBlockDecision {
 function Invoke-EpicWaveBarrierDecision {
     <#
     .SYNOPSIS
-        Parses CLAUDE_TOOL_INPUT and returns an allow-or-block decision.
+        Parses the envelope's nested tool_input and returns an allow-or-block decision.
     .PARAMETER ToolInputRaw
         The raw JSON tool payload supplied by Claude Code.
     .OUTPUTS
@@ -244,22 +246,20 @@ function Invoke-EpicWaveBarrierDecision {
         [string] $ToolInputRaw
     )
 
-    if (-not $ToolInputRaw) {
-        return Get-EpicWaveBarrierAllowDecision
-    }
-
-    try {
-        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
-    } catch {
-        throw "enforce-epic-wave-barrier hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    $envelope = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
+    if (-not $envelope.IsValid) {
+        return Get-EpicWaveBarrierBlockDecision -Reason (
+            'EPIC_WAVE_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-EpicWaveBarrierAllowDecision
     }
 
-    $prompt = [string]$toolInput.prompt
+    $prompt = Get-ClaudeHookToolInputString -ToolInput $envelope.Value -Name 'prompt'
     if (-not $prompt -or $prompt -notlike "*$script:EpicModeMarker*") {
         return Get-EpicWaveBarrierAllowDecision
     }
@@ -287,18 +287,47 @@ function Invoke-EpicWaveBarrierDecision {
     return Get-EpicWaveBarrierBlockDecision -Reason "EPIC_WAVE_BARRIER_BLOCKED: '$featureFolder' cannot start until every dependency in its depends_on list is durably confirmed merged or worktree_removed in the epic checkpoint. The checkpoint was unreadable, the feature record was not found, or a dependency is not yet safe."
 }
 
+function Invoke-EpicWaveBarrierEntryPoint {
+    <#
+    .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-EpicWaveBarrierDecision -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-EpicWaveBarrierDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
-} catch {
-    Write-Error $_
-    exit 1
-}
-
-$decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
-
-exit 0
+exit (Invoke-EpicWaveBarrierEntryPoint)

package/resources/claude-customizations/.claude/hooks/enforce-epic-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/epic-orchestrator-state.json, and finds the features[] record
     whose worktree_path matches. Allows removal only when that record's merge_status is
@@ -21,6 +21,8 @@
 [CmdletBinding()]
 param()
 
+
+Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
 $script:EpicCheckpointPath = 'artifacts/orchestration/epic-orchestrator-state.json'
 $script:AllowedMergeStatuses = @('merged', 'worktree_removed')
 
@@ -169,7 +171,7 @@ function Get-EpicWorktreeGateBlockDecision {
 function Invoke-EpicWorktreeRemovalGateDecision {
     <#
     .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
@@ -181,17 +183,15 @@ function Invoke-EpicWorktreeRemovalGateDecision {
         [string] $ToolInputRaw
     )
 
-    if (-not $ToolInputRaw) {
-        return Get-EpicWorktreeGateAllowDecision
-    }
-
-    try {
-        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
-    } catch {
-        throw "enforce-epic-worktree-removal-gate hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
+    if (-not $payload.IsValid) {
+        return Get-EpicWorktreeGateBlockDecision -Reason (
+            'EPIC_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-EpicWorktreeGateAllowDecision
     }
@@ -220,18 +220,55 @@ function Invoke-EpicWorktreeRemovalGateDecision {
     return Get-EpicWorktreeGateBlockDecision -Reason "EPIC_WORKTREE_REMOVAL_BLOCKED: git worktree remove for '$worktreePath' requires a matching epic checkpoint features[] 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-EpicWorktreeRemovalGateEntryPoint {
+    <#
+    .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-EpicWorktreeRemovalGateDecision -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-EpicWorktreeRemovalGateDecision -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-EpicWorktreeRemovalGateEntryPoint)
+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])

package/resources/claude-customizations/.claude/hooks/enforce-evidence-locations.ps1

@@ -4,9 +4,9 @@
 
 .DESCRIPTION
     This script is invoked by the Claude Code PreToolUse hook before any Write or Edit
-    operation. It reads the tool input from the CLAUDE_TOOL_INPUT environment variable
-    (JSON with a 'file_path' field) and rejects the operation when the target path is
-    a non-canonical evidence location.
+    operation. It acquires the hook payload through the shared reader and reads
+    file_path from the envelope's nested tool_input, then rejects the operation when
+    the target path is a non-canonical evidence location.
 
     Forbidden path prefixes (case-sensitive, normalized to forward-slash):
       - artifacts/baselines/
@@ -31,7 +31,9 @@
     response to stdout with hookSpecificOutput.permissionDecision = 'deny' and exits with
     code 0 so Claude Code surfaces the reason. For allowed paths, a PreToolUse response
     with permissionDecision = 'allow' is written to stdout and the script exits 0. On hard
-    failure (malformed JSON input), the script exits 1.
+    failure the script still exits 0 with a deny decision: exit 1 is non-blocking for
+    PreToolUse, so an envelope anomaly (empty payload, unparseable JSON, missing or
+    malformed tool_input) is emitted as a deny rather than raised.
 
 .NOTES
     Compatible with PowerShell 7+.
@@ -40,6 +42,8 @@
 [CmdletBinding()]
 param()
 
+Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+
 function Test-EvidenceLocationForbidden {
     <#
     .SYNOPSIS
@@ -104,32 +108,55 @@ function Get-EvidenceLocationBlockDecision {
     }
 }
 
+function Get-EvidenceLocationAnomalyDecision {
+    <#
+    .SYNOPSIS
+        Build the fail-closed deny decision for an unreadable PreToolUse envelope.
+    .PARAMETER Anomaly
+        The anomaly code reported by the shared payload reader.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Anomaly
+    )
+
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = 'EVIDENCE_LOCATION_BLOCKED: payload anomaly - ' +
+            (Get-ClaudeHookPayloadAnomalyReason -Anomaly $Anomaly) +
+            '. The gate fails closed on an envelope it cannot read.'
+        }
+    }
+}
+
 function Invoke-EvidenceLocationDecision {
     <#
     .SYNOPSIS
         Parses the Claude Code tool-input JSON and returns an allow-or-block decision.
     .PARAMETER ToolInputRaw
-        The raw JSON string from $env:CLAUDE_TOOL_INPUT. An empty or null value
-        results in an allow decision (non-file tool calls have no file_path).
+        The raw JSON hook payload acquired by Read-ClaudeHookRawPayload. An envelope
+        anomaly fails closed as a deny; a well-formed tool_input carrying no file_path
+        remains an allow (non-file tool calls have no file_path).
     #>
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
     param(
+        [AllowNull()]
+        [AllowEmptyString()]
         [string] $ToolInputRaw
     )
 
-    if (-not $ToolInputRaw) {
-        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
+    $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
+    if (-not $payload.IsValid) {
+        return Get-EvidenceLocationAnomalyDecision -Anomaly $payload.Anomaly
     }
 
-    try {
-        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
-    } catch {
-        # Malformed JSON is a hard failure; caller exits 1 to surface the issue.
-        throw "enforce-evidence-locations hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
-    }
-
-    $filePath = $toolInput.file_path
+    $filePath = Get-ClaudeHookToolInputString -ToolInput $payload.Value -Name 'file_path'
     if (-not $filePath) {
         return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
@@ -147,26 +174,34 @@ function Invoke-EvidenceLocationEntryPoint {
         Runs the evidence-location decision and returns the process exit code.
     .DESCRIPTION
         Wraps the dispatch logic that the hook entry point performs so it can be
-        exercised by unit tests. On success it writes the compact JSON decision to
-        the output stream and returns 0. On a hard failure (malformed JSON) it
-        writes the error record and returns 1. This function does not call exit;
-        the thin entry-point wiring converts the returned code into a process exit.
+        exercised by unit tests. It acquires the payload through the shared reader
+        unless the caller supplies one, writes the compact JSON decision to the output
+        stream, and returns 0. It never returns 1: exit 1 is non-blocking for
+        PreToolUse, so every envelope anomaly is already a deny decision by the time
+        control reaches here. This function does not call exit; the thin entry-point
+        wiring converts the returned code into a process exit.
     .PARAMETER ToolInputRaw
-        The raw JSON string from $env:CLAUDE_TOOL_INPUT.
+        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.
     #>
     [CmdletBinding()]
     [OutputType([int])]
     param(
-        [string] $ToolInputRaw = $env:CLAUDE_TOOL_INPUT
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $ToolInputRaw,
+
+        [scriptblock] $ReadPayload = { Read-ClaudeHookRawPayload }
     )
 
-    try {
-        $decision = Invoke-EvidenceLocationDecision -ToolInputRaw $ToolInputRaw
-    } catch {
-        Write-Error $_
-        return 1
+    if (-not $PSBoundParameters.ContainsKey('ToolInputRaw')) {
+        $ToolInputRaw = [string](& $ReadPayload)
     }
 
+    $decision = Invoke-EvidenceLocationDecision -ToolInputRaw $ToolInputRaw
+
     $decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
 
     return 0
@@ -177,4 +212,12 @@ if ($MyInvocation.InvocationName -eq '.') {
     return
 }
 
-exit (Invoke-EvidenceLocationEntryPoint)
+# 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-EvidenceLocationEntryPoint)
+if ($entryPointResult.Count -gt 1) {
+    $entryPointResult[0..($entryPointResult.Count - 2)] | Write-Output
+}
+
+exit ([int]$entryPointResult[-1])