@danmoisan/drm-copilot-mcp 1.0.27 → 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 three
+    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,
@@ -39,6 +39,8 @@
 [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'
@@ -338,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
     }
@@ -391,18 +398,55 @@ function Invoke-EpicMergeGateDecision {
     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.
 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])

package/resources/claude-customizations/.claude/hooks/enforce-feature-folder-order.ps1

@@ -4,8 +4,9 @@
     spec.md, or user-story.md are not yet present in that same folder.
 
 .DESCRIPTION
-    Invoked by the Claude Code PreToolUse hook on Write or Edit operations. Reads
-    tool input JSON from the CLAUDE_TOOL_INPUT environment variable. When the
+    Invoked by the Claude Code PreToolUse hook on Write or Edit operations. Acquires
+    the hook payload through the shared reader and reads file_path from the envelope's
+    nested tool_input. When the
     target file_path matches a feature-folder plan.md path under
     docs/features/(active|archive)/<folder>/plan.md, the script verifies that
     each of issue.md, spec.md, and user-story.md exists in the same folder.
@@ -24,6 +25,8 @@
 [CmdletBinding()]
 param()
 
+
+Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
 function Get-FeatureFolderFileExistence {
     <#
     .SYNOPSIS
@@ -87,28 +90,34 @@ function Test-IsFeaturePlanPath {
 function Invoke-FeatureFolderOrderDecision {
     <#
     .SYNOPSIS
-        Parses CLAUDE_TOOL_INPUT and produces an allow-or-block decision.
+        Parses the PreToolUse envelope and produces an allow-or-block decision.
     .PARAMETER ToolInputRaw
-        Raw JSON string. Empty/null returns allow.
+        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.
     #>
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
     param(
+        [AllowNull()]
+        [AllowEmptyString()]
         [string] $ToolInputRaw
     )
 
-    if (-not $ToolInputRaw) {
-        return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
-    }
-
-    try {
-        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
-    }
-    catch {
-        throw "enforce-feature-folder-order hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
+    if (-not $payload.IsValid) {
+        return [ordered]@{
+            hookSpecificOutput = [ordered]@{
+                hookEventName            = 'PreToolUse'
+                permissionDecision       = 'deny'
+                permissionDecisionReason = 'FEATURE_FOLDER_ORDER_BLOCKED: payload anomaly - ' +
+                (Get-ClaudeHookPayloadAnomalyReason -Anomaly $payload.Anomaly) +
+                '. The gate fails closed on an envelope it cannot read.'
+            }
+        }
     }
 
-    $filePath = $toolInput.file_path
+    $filePath = Get-ClaudeHookToolInputString -ToolInput $payload.Value -Name 'file_path'
     if (-not $filePath) {
         return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
@@ -134,19 +143,55 @@ function Invoke-FeatureFolderOrderDecision {
     }
 }
 
+function Invoke-FeatureFolderOrderEntryPoint {
+    <#
+    .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-FeatureFolderOrderDecision -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-FeatureFolderOrderDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
+# 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-FeatureFolderOrderEntryPoint)
+if ($entryPointResult.Count -gt 1) {
+    $entryPointResult[0..($entryPointResult.Count - 2)] | Write-Output
 }
-catch {
-    Write-Error $_
-    exit 1
-}
-
-$decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
 
-exit 0
+exit ([int]$entryPointResult[-1])