@danmoisan/drm-copilot-mcp 1.1.18 → 1.1.20

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

@@ -32,27 +32,21 @@
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 
-Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+try { Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'HookPayload.psm1' -ErrorRecord $_ }
 # Sanctioned-removal manifest reader (issue #635), consumed by the manifest branch in
 # Invoke-ParallelWorktreeRemovalGateDecision. Same module the epic gate imports.
-Import-Module (Join-Path $PSScriptRoot '../lib/cleanup-manifest/CleanupWorktreeManifest.psm1') -Force
+try { Import-Module (Join-Path $PSScriptRoot '../lib/cleanup-manifest/CleanupWorktreeManifest.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'CleanupWorktreeManifest.psm1' -ErrorRecord $_ }
 # Shared command-line parser (issue #545), consumed by the scope filter in
-# Invoke-ParallelWorktreeRemovalGateDecision and by Get-ParallelWorktreeRemovalCommandPath.
+# Invoke-ParallelWorktreeRemovalGateDecision and by Resolve-CommandLineInvocationTarget.
 # Both call sites are byte-for-byte the calls the epic gate makes, so the duplicated
 # concern now has one implementation.
-. (Join-Path $PSScriptRoot 'hook-command-scanner.ps1')
-. (Join-Path $PSScriptRoot 'hook-command-invocation.ps1')
+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 $_ }
 
-# Import guard (issue #690): a failed import denies instead of failing open.
-$script:ParallelWorktreeGateResolutionImportFailure = $null
-try {
-    Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop
-}
-catch {
-    $script:ParallelWorktreeGateResolutionImportFailure = 'WorktreeRunResolution.psm1'
-}
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeRunResolution.psm1' -ErrorRecord $_ }
 
 $script:AllowedMergeStatuses = @('merged', 'worktree_removed')
 # Sanctioned-removal manifest location. Recorded here so every hook-read document this
@@ -164,52 +158,6 @@ function Read-ParallelWorktreeGateRunCheckpoint {
     }
 }
 
-function Get-ParallelWorktreeRemovalCommandPath {
-    <#
-    .SYNOPSIS
-        Extract the target worktree path argument from a git worktree remove command.
-    .DESCRIPTION
-        The operand comes from the segment that structurally invokes git worktree remove,
-        so a 'cd <path> &&' segment chained before the removal contributes nothing and a
-        quoted mention of the phrase resolves to no operand at all. Quotes around the path
-        are already stripped by the tokenizer.
-
-        '--force' is a zero-argument flag, so it never contributes an operand and may be
-        written on either side of the target path. Its presence is read structurally through
-        Test-CommandLineFlag rather than by searching the raw text, so a '--force' spelling
-        that appears inside an unrelated quoted argument cannot change how the operand list
-        is read. When no operand resolves, a present '--force' is reported in its place, so
-        the checkpoint lookup fails closed on a value that matches no recorded worktree_path
-        - the same value the previous raw-text pattern returned for that input.
-
-        This body is identical to Get-EpicWorktreeRemovalCommandPath in
-        enforce-epic-worktree-removal-gate.ps1. The two gates fire on the same command and
-        now delegate the shared concern to one parser rather than to two patterns that had
-        already diverged from the Codex copy.
-    .PARAMETER CommandText
-        The Bash command text under evaluation.
-    .OUTPUTS
-        System.String or $null
-    #>
-    [CmdletBinding()]
-    [OutputType([string])]
-    param(
-        [Parameter(Mandatory)]
-        [string] $CommandText
-    )
-
-    $hasForce = Test-CommandLineFlag -CommandText $CommandText -CommandWord 'git' -SubcommandPath @('worktree', 'remove') -FlagName '--force'
-    $operands = @(Get-CommandLineOperand -CommandText $CommandText -CommandWord 'git' -SubcommandPath @('worktree', 'remove'))
-
-    if ($operands.Count -gt 0) {
-        return $operands[0]
-    }
-    if ($hasForce) {
-        return '--force'
-    }
-    return $null
-}
-
 function Find-ParallelWorktreeItemRecord {
     <#
     .SYNOPSIS
@@ -334,13 +282,8 @@ function Invoke-ParallelWorktreeRemovalGateDecision {
     param(
         [string] $ToolInputRaw
     )
-
-    # A failed worktree-resolution import denies before any other logic (issue #690).
-    if ($script:ParallelWorktreeGateResolutionImportFailure) {
-        return Get-ParallelWorktreeGateBlockDecision -Reason (
-            "PARALLEL_WORKTREE_REMOVAL_BLOCKED: the worktree-resolution module '$($script:ParallelWorktreeGateResolutionImportFailure)' " +
-            'failed to import, so the run checkpoint that governs this removal cannot be located; the gate fails closed.')
-    }
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'PARALLEL_WORKTREE_REMOVAL_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
     if (-not $payload.IsValid) {
@@ -362,7 +305,43 @@ function Invoke-ParallelWorktreeRemovalGateDecision {
         return Get-ParallelWorktreeGateAllowDecision
     }
 
-    $worktreePath = Get-ParallelWorktreeRemovalCommandPath -CommandText $commandText
+    # Issue #824: the removal targets are derived structurally from every invocation.
+    # A target that cannot be derived denies before any checkpoint is read, and every
+    # derived target must be authorized on its own.
+    $resolution = Resolve-CommandLineInvocationTarget -CommandText $commandText -CommandWord 'git' -SubcommandPath @('worktree', 'remove')
+    if ($resolution.Status -eq 'NoMatch') {
+        return Get-ParallelWorktreeGateAllowDecision
+    }
+    if ($resolution.Status -ne 'Targets') {
+        return Get-ParallelWorktreeGateBlockDecision -Reason 'PARALLEL_WORKTREE_REMOVAL_BLOCKED: TARGET_WORKTREE_NOT_DERIVABLE: the git worktree remove target cannot be derived from the command text. No checkpoint can authorize this removal.'
+    }
+    foreach ($target in @($resolution.Targets)) {
+        $denial = Get-ParallelWorktreeRemovalTargetDenial -WorktreePath $target
+        if ($null -ne $denial) {
+            return $denial
+        }
+    }
+    return Get-ParallelWorktreeGateAllowDecision
+}
+
+function Get-ParallelWorktreeRemovalTargetDenial {
+    <#
+    .SYNOPSIS
+        Evaluate one derived removal target and return its deny decision, or $null when authorized.
+    .DESCRIPTION
+        Holds the per-path authorization cascade (parallel checkpoint, epic checkpoint,
+        sanctioned-removal manifest) for a single worktree path (issue #824).
+    .PARAMETER WorktreePath
+        One removal target derived by Resolve-CommandLineInvocationTarget.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $WorktreePath
+    )
 
     # Each run checkpoint is read beneath the worktree that records this path (issue #690),
     # parallel kind first; an ambiguous target denies before any allow or manifest check.
@@ -377,7 +356,7 @@ function Invoke-ParallelWorktreeRemovalGateDecision {
 
     $itemRecord = Find-ParallelWorktreeItemRecord -Checkpoint $checkpoint -WorktreePath $worktreePath
     if (Test-ParallelWorktreeRemovalAllowed -ItemRecord $itemRecord) {
-        return Get-ParallelWorktreeGateAllowDecision
+        return $null
     }
 
     # Epic-authorization branch (issue #688). It runs after the parallel allow above and
@@ -394,7 +373,7 @@ function Invoke-ParallelWorktreeRemovalGateDecision {
 
     $featureRecord = Find-ParallelWorktreeItemRecord -Checkpoint $epicCheckpoint -WorktreePath $worktreePath -RecordArrayName 'features'
     if (Test-ParallelWorktreeRemovalAllowed -ItemRecord $featureRecord) {
-        return Get-ParallelWorktreeGateAllowDecision
+        return $null
     }
 
     # Sanctioned-removal manifest branch (issue #635). It runs last, so a
@@ -409,15 +388,15 @@ function Invoke-ParallelWorktreeRemovalGateDecision {
     # only; the epic gate covers the features array with its own exclusion.
     if (-not (Test-CleanupManifestCheckpointCoversPath -Checkpoint $checkpoint -RecordArrayName 'items' -WorktreePath $worktreePath) -and
         (Test-CleanupWorktreeManifestAuthorizesRemoval -WorktreePath $worktreePath)) {
-        return Get-ParallelWorktreeGateAllowDecision
+        return $null
     }
 
     # When neither kind resolved, the deny names the resolution reason first (issue #690).
     $prefix = ''
     if ($parallelRead.Target.Status -eq 'NoTarget' -and $epicRead.Target.Status -eq 'NoTarget') {
-        $prefix = "PARALLEL_WORKTREE_REMOVAL_BLOCKED: $($parallelRead.Target.ReasonCode): $($parallelRead.Target.Detail). "
+        $prefix = "$($parallelRead.Target.ReasonCode): $($parallelRead.Target.Detail). "
     }
-    return Get-ParallelWorktreeGateBlockDecision -Reason ($prefix + "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.")
+    return Get-ParallelWorktreeGateBlockDecision -Reason ('PARALLEL_WORKTREE_REMOVAL_BLOCKED: ' + $prefix + "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 {
@@ -462,6 +441,9 @@ function Invoke-ParallelWorktreeRemovalGateEntryPoint {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('PARALLEL_WORKTREE_REMOVAL_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'PARALLEL_WORKTREE_REMOVAL_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 # 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

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

@@ -57,10 +57,11 @@
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 
-Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
-. (Join-Path $PSScriptRoot 'enforce-batch-budget-route.ps1')
+try { Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'HookPayload.psm1' -ErrorRecord $_ }
+try { . (Join-Path $PSScriptRoot 'enforce-batch-budget-route.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-batch-budget-route.ps1' -ErrorRecord $_ }
 
 function Test-PowerShellBatchBudgetPathInRoot {
     <#
@@ -277,6 +278,8 @@ function Invoke-PowerShellBatchBudgetDecision {
         [AllowEmptyString()]
         [string] $ObservedRoute = ''
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'POWERSHELL_LARGE_PATH_REQUIRED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $normalized = $FilePath -replace '\\', '/'
     if ($normalized -notmatch '\.(ps1|psm1|psd1)$') {
@@ -474,6 +477,9 @@ function Invoke-PowerShellBatchBudgetEntryPoint {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('POWERSHELL_LARGE_PATH_REQUIRED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'POWERSHELL_LARGE_PATH_REQUIRED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 # 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

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

@@ -0,0 +1,279 @@
+<#
+.SYNOPSIS
+    PreToolUse hook that limits the pr-author subagent's Bash calls to an allowlist of forms.
+
+.DESCRIPTION
+    Registered in the frontmatter of .claude/agents/pr-author.md on the "Bash" matcher
+    (issue #824, #733). Every command is read with Read-CommandLineInvocationSegment, so a
+    wrapper payload, a substitution body, or an xargs-injected command is a record of its own.
+    The command is allowed only when every record is a literal, top-level, unwrapped command
+    in one of these forms, matched by token position:
+
+      - git log ...            and git rev-parse ...        (no git global option)
+      - gh pr create ...       and gh pr edit ...           (no gh global option)
+      - sha256sum artifacts/pr_body_<N>.md                  (only as the whole command)
+      - date -u [+<format>]                                 (only as the whole command)
+
+    Segments may be joined only by ';', '&&', '||', '|', or a newline. A record that is
+    nested, unbalanced, opaque, non-literal, wrapper-led, led by a VAR=value assignment, or
+    whose scanner segment carries a redirection is denied. Every deny reason begins
+    PR_AUTHOR_COMMAND_NOT_ALLOWED: and names the first rejected segment.
+
+    The hook is read-only: it inspects the attempted command and emits a JSON
+    allow-or-deny decision without mutating the command text.
+
+.NOTES
+    Compatible with PowerShell 7+. Pure string logic over the shared command-line parser;
+    no disk, process, or network access beyond payload acquisition.
+#>
+[CmdletBinding()]
+param()
+
+
+Import-Module (Join-Path $PSScriptRoot '../lib/hook-payload/HookPayload.psm1') -Force
+# Shared command-line parser (issues #545 and #824).
+. (Join-Path $PSScriptRoot 'hook-command-scanner.ps1')
+. (Join-Path $PSScriptRoot 'hook-command-invocation.ps1')
+
+$script:PrAuthorAllowlistReasonPrefix = 'PR_AUTHOR_COMMAND_NOT_ALLOWED: '
+$script:PrAuthorAllowlistDelimiters = @('', ';', '&&', '||', '|', "`n")
+$script:PrAuthorAllowlistWrapperWords = @(
+    'sh', 'bash', 'zsh', 'dash', 'ksh', 'pwsh', 'powershell', 'eval', 'xargs',
+    'env', 'timeout', 'time', 'command', 'nohup'
+)
+$script:PrAuthorAllowlistFormText = 'git log, git rev-parse, gh pr create, gh pr edit, sha256sum artifacts/pr_body_<N>.md, date -u [+<format>]'
+
+function Test-PrAuthorAllowlistForm {
+    <#
+    .SYNOPSIS
+        Report whether one record's tokens match an allowed command form by token position.
+    .PARAMETER Token
+        The record's tokens, quotes already stripped.
+    .PARAMETER IsWholeCommand
+        Whether the command has exactly one top-level record; sha256sum and date require it.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)][AllowEmptyCollection()][string[]] $Token,
+        [Parameter(Mandatory)][bool] $IsWholeCommand
+    )
+
+    if ($Token.Count -eq 0) {
+        return $false
+    }
+    switch -CaseSensitive ($Token[0]) {
+        'git' {
+            return ($Token.Count -ge 2 -and @('log', 'rev-parse') -ccontains $Token[1])
+        }
+        'gh' {
+            return ($Token.Count -ge 3 -and $Token[1] -ceq 'pr' -and @('create', 'edit') -ccontains $Token[2])
+        }
+        'sha256sum' {
+            return ($IsWholeCommand -and $Token.Count -eq 2 -and $Token[1] -cmatch '^artifacts/pr_body_\d+\.md$')
+        }
+        'date' {
+            if (-not $IsWholeCommand -or $Token.Count -lt 2 -or $Token[1] -cne '-u') {
+                return $false
+            }
+            return ($Token.Count -eq 2 -or ($Token.Count -eq 3 -and $Token[2].StartsWith('+')))
+        }
+    }
+    return $false
+}
+
+function Get-PrAuthorAllowlistRecordProblem {
+    <#
+    .SYNOPSIS
+        Return the reason one record is rejected, or $null when the record is allowed.
+    .PARAMETER Record
+        One Read-CommandLineInvocationSegment record.
+    .PARAMETER MaskedText
+        The masked text of the record's depth-0 scanner segment, or '' for a nested record.
+    .PARAMETER IsWholeCommand
+        Whether the command has exactly one top-level record.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)][pscustomobject] $Record,
+        [Parameter(Mandatory)][AllowEmptyString()][string] $MaskedText,
+        [Parameter(Mandatory)][bool] $IsWholeCommand
+    )
+
+    $tokens = [string[]]@($Record.Tokens)
+    if ($Record.Depth -gt 0) { return "it is a nested $($Record.Origin) command" }
+    if ($Record.Unbalanced) { return 'its quoting or grouping is unbalanced' }
+    if ($Record.Opaque) { return "its payload cannot be read ($($Record.OpaqueReason))" }
+    if (-not $Record.Literal) { return 'it carries a variable, substitution, or other non-literal token' }
+    if ($script:PrAuthorAllowlistWrapperWords -contains $Record.CommandWord) { return "it is led by the wrapper '$($Record.CommandWord)'" }
+    if ($script:PrAuthorAllowlistDelimiters -notcontains $Record.Delimiter) { return "it is joined by the delimiter '$($Record.Delimiter)'" }
+    if ($MaskedText.Contains('<') -or $MaskedText.Contains('>')) { return 'it carries a redirection' }
+    if ($tokens.Count -gt 0 -and $tokens[0] -match '^[A-Za-z_][A-Za-z0-9_]*=') { return 'it is led by a VAR=value assignment' }
+    if (-not (Test-PrAuthorAllowlistForm -Token $tokens -IsWholeCommand $IsWholeCommand)) { return 'it is not an allowed command form' }
+    return $null
+}
+
+function Get-PrAuthorCommandAllowlistReason {
+    <#
+    .SYNOPSIS
+        Return the deny reason for a command outside the pr-author allowlist, or $null.
+    .PARAMETER CommandText
+        The Bash command text extracted from the envelope's tool_input.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyString()]
+        [string] $CommandText
+    )
+
+    if ([string]::IsNullOrWhiteSpace($CommandText)) {
+        return $null
+    }
+
+    $records = @(Read-CommandLineInvocationSegment -CommandText $CommandText)
+    $segments = @(Read-CommandLineSegment -CommandText (ConvertTo-CommandLineNormalizedText -CommandText $CommandText))
+    $topLevel = @($records | Where-Object { $_.Depth -eq 0 })
+    $isWholeCommand = $topLevel.Count -eq 1
+    $topLevelPosition = 0
+
+    foreach ($record in $records) {
+        $maskedText = ''
+        if ($record.Depth -eq 0) {
+            if ($topLevelPosition -lt $segments.Count) {
+                $maskedText = [string]$segments[$topLevelPosition].MaskedText
+            }
+            $topLevelPosition++
+        }
+        $problem = Get-PrAuthorAllowlistRecordProblem -Record $record -MaskedText $maskedText -IsWholeCommand $isWholeCommand
+        if ($null -ne $problem) {
+            return ($script:PrAuthorAllowlistReasonPrefix +
+                "the segment '$($record.RawText.Trim())' is rejected because $problem. The pr-author agent may run only: $($script:PrAuthorAllowlistFormText), each without wrappers, substitutions, or redirections.")
+        }
+    }
+
+    return $null
+}
+
+function Get-PrAuthorCommandAllowlistDecision {
+    <#
+    .SYNOPSIS
+        Build an ordered allow or deny decision.
+    .PARAMETER Reason
+        The deny reason, or $null for an allow.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [AllowNull()]
+        [string] $Reason
+    )
+
+    if ([string]::IsNullOrEmpty($Reason)) {
+        return [ordered]@{
+            hookSpecificOutput = [ordered]@{
+                hookEventName      = 'PreToolUse'
+                permissionDecision = 'allow'
+            }
+        }
+    }
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = $Reason
+        }
+    }
+}
+
+function Invoke-PrAuthorCommandAllowlistDecision {
+    <#
+    .SYNOPSIS
+        Return the ordered allow-or-deny decision for one command text.
+    .PARAMETER CommandText
+        The Bash command text.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyString()]
+        [string] $CommandText
+    )
+
+    return Get-PrAuthorCommandAllowlistDecision -Reason (Get-PrAuthorCommandAllowlistReason -CommandText $CommandText)
+}
+
+function Invoke-PrAuthorCommandAllowlistEntryPoint {
+    <#
+    .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)
+    }
+
+    $payload = Resolve-ClaudeHookToolInput -Raw $ToolInputRaw
+    if (-not $payload.IsValid) {
+        $decision = Get-PrAuthorCommandAllowlistDecision -Reason (
+            $script:PrAuthorAllowlistReasonPrefix + 'payload anomaly - ' +
+            (Get-ClaudeHookPayloadAnomalyReason -Anomaly $payload.Anomaly) +
+            '. The hook fails closed on an envelope it cannot read.')
+    } else {
+        $commandText = [string](Get-ClaudeHookToolInputString -ToolInput $payload.Value -Name 'command')
+        $decision = Invoke-PrAuthorCommandAllowlistDecision -CommandText $commandText
+    }
+    $decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
+
+    return 0
+}
+
+# Allow dot-sourcing in tests without executing the entrypoint.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+# 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-PrAuthorCommandAllowlistEntryPoint)
+if ($entryPointResult.Count -gt 1) {
+    $entryPointResult[0..($entryPointResult.Count - 2)] | Write-Output
+}
+
+exit ([int]$entryPointResult[-1])