@danmoisan/drm-copilot-mcp 1.1.18 → 1.1.19

package/resources/claude-customizations/.claude/hooks/validate-orchestrator-output.ps1

@@ -1,4 +1,4 @@
-<#
+<#
 .SYNOPSIS
     SubagentStop hook for the orchestrator subagent.
 
@@ -11,7 +11,7 @@
     skills, the orchestrator must persist progress to the checkpoint file
     after every completed step. This hook confirms that:
 
-      - the hook payload is well-formed JSON,
+      - the SubagentStop envelope read from stdin through Read-SubagentStopEnvelope is valid,
       - the orchestrator's final output is non-empty,
       - the checkpoint file exists on disk,
       - the checkpoint is valid JSON,
@@ -19,11 +19,26 @@
             objective, completed_steps, next_step, last_updated,
       - the `objective` field is non-empty.
 
+    The checkpoint is resolved through WorktreeRunResolution.psm1 by the dot-sourced
+    sibling validate-orchestrator-output-resolution.ps1 (issue #787), so every read uses
+    an absolute path beneath the worktree of the run that stopped. An unresolved,
+    ambiguous, or mismatched target blocks with ORCHESTRATOR_CHECKPOINT_UNRESOLVED:
+    before any checkpoint is read. For epic-orchestrator-state, the Layer 2 wave-barrier
+    ordering check (OrchestratorStateEpicWaveBarrier.psm1, issue #840) runs after the
+    routing dispatch passes.
+
 .NOTES
-    Reads the hook payload from CLAUDE_HOOK_INPUT as JSON. Exits 0 to allow
-    termination; exits 1 with an error message to block. Filesystem reads go
-    through Get-CheckpointFileContent so tests can mock the boundary without
-    writing temporary files.
+    Reads the SubagentStop envelope from stdin through Read-SubagentStopEnvelope
+    (subagentstop-envelope.ps1); the assistant text comes from the helper's
+    AssistantText. A non-repairable condition blocks once: when StopHookActive is
+    set, the re-entered stop is allowed. Exits 0 to allow termination; a block is
+    written to stderr with exit 2 through Exit-SubagentStopBlock. Filesystem reads
+    go through Get-CheckpointFileContent so tests can mock the boundary without
+    writing temporary files. The routing sibling, the resolution sibling, the E1
+    helper, and the modules are guarded loads: a failure is recorded and blocks
+    every validation, naming the file, before any read. A failed Layer 2 import
+    blocks the epic leg only.
+    An unhandled error during validation blocks with exit 2 and a reason (issue #928).
 #>
 
 [CmdletBinding()]
@@ -34,11 +49,21 @@ param(
     [Parameter(Mandatory = $false)]
     [string] $ArtifactType = 'orchestrator-state'
 )
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 Set-StrictMode -Version Latest
-$ErrorActionPreference = 'Stop'
 
-Import-Module (Join-Path $PSScriptRoot '../lib/orchestrator-state/OrchestratorState.psm1') -Force
+try { . (Join-Path $PSScriptRoot 'validate-orchestrator-output-resolution.ps1') } catch { Add-HookDependencyFailure -Name 'validate-orchestrator-output-resolution.ps1' -ErrorRecord $_ }
+try { . (Join-Path $PSScriptRoot 'validate-orchestrator-output-routing.ps1') } catch { Add-HookDependencyFailure -Name 'validate-orchestrator-output-routing.ps1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeItemResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeItemResolution.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/worktree-resolution/WorktreeRunResolution.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'WorktreeRunResolution.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/orchestrator-state/OrchestratorStateEpicWaveBarrier.psm1') -Force -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'OrchestratorStateEpicWaveBarrier.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/orchestrator-state/OrchestratorStateCompletion.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'OrchestratorStateCompletion.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/orchestrator-state/OrchestratorStateUnconditional.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'OrchestratorStateUnconditional.psm1' -ErrorRecord $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/orchestrator-state/OrchestratorState.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'OrchestratorState.psm1' -ErrorRecord $_ }
+try { . (Join-Path $PSScriptRoot 'subagentstop-envelope.ps1') } catch { Add-HookDependencyFailure -Name 'subagentstop-envelope.ps1' -ErrorRecord $_ }
+$ErrorActionPreference = 'Stop'
+$script:SubagentStopReportAndHaltLine = 'This condition is not repairable by the subagent. Report it to the operator and halt.'
 
 function Get-CheckpointFileContent {
     <#
@@ -107,7 +132,7 @@ function Test-HumanInteractionShape {
 
     $hiProps = @($HumanInteraction.PSObject.Properties.Name)
     if ($hiProps -notcontains 'requirements') {
-        return @{ Ok = $false; Message = "orchestrator hook: 'human_interaction' is present but 'requirements' array is missing." }
+        return @{ Ok = $false; Repairable = $true; Message = "orchestrator hook: 'human_interaction' is present but 'requirements' array is missing." }
     }
 
     $requirements = @($HumanInteraction.requirements)
@@ -121,15 +146,15 @@ function Test-HumanInteractionShape {
         if ($reqProps -contains 'response') { $response = [string]$req.response }
 
         if ([string]::IsNullOrWhiteSpace($response)) {
-            return @{ Ok = $false; Message = "orchestrator hook: 'human_interaction.requirements[$i]' has no resolved 'response'. Every unautomatable requirement must resolve to one of: scope_change, exception, halt." }
+            return @{ Ok = $false; Repairable = $true; Message = "orchestrator hook: 'human_interaction.requirements[$i]' has no resolved 'response'. Every unautomatable requirement must resolve to one of: scope_change, exception, halt." }
         }
 
         if ($allowedResponses -notcontains $response) {
-            return @{ Ok = $false; Message = "orchestrator hook: 'human_interaction.requirements[$i]' has 'response' value '$response' outside the allowed set (scope_change, exception, halt)." }
+            return @{ Ok = $false; Repairable = $true; Message = "orchestrator hook: 'human_interaction.requirements[$i]' has 'response' value '$response' outside the allowed set (scope_change, exception, halt)." }
         }
 
         if ($response -eq 'halt') {
-            return @{ Ok = $false; Message = "orchestrator hook: 'human_interaction.requirements[$i]' has 'response' == 'halt'; DONE is blocked while a halt is present." }
+            return @{ Ok = $false; Repairable = $false; Message = "orchestrator hook: 'human_interaction.requirements[$i]' has 'response' == 'halt'; DONE is blocked while a halt is present." }
         }
 
         if ($response -eq 'exception') {
@@ -137,11 +162,11 @@ function Test-HumanInteractionShape {
             if ($reqProps -contains 'runbook_path') { $runbookPath = [string]$req.runbook_path }
 
             if ([string]::IsNullOrWhiteSpace($runbookPath)) {
-                return @{ Ok = $false; Message = "orchestrator hook: 'human_interaction.requirements[$i]' has 'response' == 'exception' but no non-empty 'runbook_path'. A permitted exception requires a runbook." }
+                return @{ Ok = $false; Repairable = $true; Message = "orchestrator hook: 'human_interaction.requirements[$i]' has 'response' == 'exception' but no non-empty 'runbook_path'. A permitted exception requires a runbook." }
             }
 
             if (-not (& $FileExistsCheck $runbookPath)) {
-                return @{ Ok = $false; Message = "orchestrator hook: 'human_interaction.requirements[$i]' references runbook_path '$runbookPath' but no file exists at that location." }
+                return @{ Ok = $false; Repairable = $true; Message = "orchestrator hook: 'human_interaction.requirements[$i]' references runbook_path '$runbookPath' but no file exists at that location." }
             }
         }
     }
@@ -149,211 +174,101 @@ function Test-HumanInteractionShape {
     return @{ Ok = $true; Message = $null }
 }
 
-function Test-OrchestratorCheckpointStructure {
-    <#
-    .SYNOPSIS
-        Type-scoped structural check for the epic and parallel checkpoint types.
-    .DESCRIPTION
-        PD-3 implementation. The Python reference exposes no validation surface for
-        `epic-orchestrator-state` or `parallel-orchestrator-state` under this hook's
-        flag pair: argparse rejects the pair and exits 2 without running a single
-        check, so parity is UNDEFINED in this region. Rather than inherit an
-        undefined behavior, this hook defines it: the checkpoint must exist, parse
-        as JSON, and have an object root. That is the largest assertion that holds
-        for every checkpoint type without importing a schema this hook does not own.
-
-        Deliberately NOT applied here:
-          - the standard-checkpoint REQUIRED_STATE_KEYS presence block, whose key
-            set belongs to the standard checkpoint and would produce false
-            ROUTING_CONTRACT_BLOCKED verdicts against a well-formed epic or
-            parallel checkpoint (defect D-1),
-          - the model-routing gate, whose receipts live on the standard checkpoint.
-
-        The check fails closed: a missing file, unreadable content, invalid JSON, or
-        a non-object root all yield ExitCode 1 with the load error as Output.
-    .PARAMETER CheckpointPath
-        The path to the checkpoint JSON file.
-    .OUTPUTS
-        System.Collections.Hashtable with keys ExitCode (int, 0 or 1) and Output (string).
-    #>
-    [CmdletBinding()]
-    [OutputType([hashtable])]
-    param(
-        [Parameter(Mandatory = $true)]
-        [string] $CheckpointPath
-    )
-
-    # Get-OrchestratorStateCheckpoint already implements exactly the three
-    # structural conditions (exists, parses, object root) and reports each as a
-    # fail-closed Error string, so the structural leg reuses it rather than
-    # duplicating the load contract.
-    $loaded = Get-OrchestratorStateCheckpoint -CheckpointPath $CheckpointPath
-    if (-not $loaded.Ok) {
-        return @{ ExitCode = 1; Output = $loaded.Error }
-    }
-
-    return @{ ExitCode = 0; Output = '' }
-}
-
-function Invoke-RoutingContractValidation {
+function Invoke-OrchestratorOutputValidation {
     <#
     .SYNOPSIS
-        Runs the portable routing-contract validation against the on-disk
-        checkpoint and reports whether it emitted errors.
+        Reads the SubagentStop envelope, validates the assistant text, and applies the re-entry policy.
     .DESCRIPTION
-        Invokes the validation through an injectable scriptblock seam. As of issue
-        #475 the default Invoker names no interpreter and starts no subprocess: the
-        portable PowerShell path is the ONLY path, so the hook behaves identically
-        in this repository and in every destination that received only the
-        pushed-down `.claude` pack. The former capability-detection probe and the
-        interpreter-subprocess leg it guarded are both gone.
-
-        The default Invoker dispatches on ArtifactType:
-
-          orchestrator-state
-              the COMPLETE-PARITY completion validation
-              (Test-OrchestratorStateCompletionReadiness), a row-by-row port of the
-              Python call surface `--require-complete --require-model-routing`.
-
-          epic-orchestrator-state, parallel-orchestrator-state
-              the type-scoped structural check
-              (Test-OrchestratorCheckpointStructure): exists, parses as JSON,
-              object root. PD-3: this is DEFINED behavior in a region where Python
-              parity is UNDEFINED (argparse exit 2, zero checks run). It is a
-              design decision, not a deferral. The standard-checkpoint
-              REQUIRED_STATE_KEYS block and the model-routing gate are deliberately
-              not applied, which is the D-1 fix.
-
-          anything else
-              fail closed, naming the unsupported type. An unrecognized type must
-              never read as a clean pass.
-
-        ArtifactType defaults to 'orchestrator-state' so every existing caller of
-        this hook keeps its current behavior.
-
         Returns a hashtable with keys:
-          - HasErrors:  $true only when the validation reported a non-zero exit
-                        code; $false when it exited 0. The exit code is the sole
-                        discriminator.
-          - ErrorText:  the validation's output text, carried through unchanged:
-                        the error lines on a failure, empty on a clean pass.
+          - Ok:      $true to allow termination, $false to block.
+          - Message: error message when blocking; $null on success.
+        SessionRoot is the calling process's path, used only to find the repository
+        when the run checkpoint is resolved.
     #>
     [CmdletBinding()]
     [OutputType([hashtable])]
     param(
-        [Parameter(Mandatory = $true)]
-        [string] $CheckpointPath,
-
-        [Parameter(Mandatory = $false)]
+        [AllowNull()] [AllowEmptyString()] [string] $InputText,
+        [string] $CheckpointPath = 'artifacts/orchestration/orchestrator-state.json',
         [string] $ArtifactType = 'orchestrator-state',
+        [string] $SessionRoot = (Get-Location).Path,
 
         [Parameter(Mandatory = $false)]
-        [scriptblock] $Invoker = {
-            param($Path, $Type)
-            switch ($Type) {
-                'orchestrator-state' {
-                    # Import the portable completion module only when its function is not
-                    # already available, so a repeated call (or a test that pre-imports and
-                    # mocks the function) does not reload the module and reset the seam.
-                    if (-not (Get-Command -Name Test-OrchestratorStateCompletionReadiness -ErrorAction SilentlyContinue)) {
-                        Import-Module (Join-Path $PSScriptRoot '../lib/orchestrator-state/OrchestratorStateCompletion.psm1') -Force
-                    }
-                    $portable = Test-OrchestratorStateCompletionReadiness -CheckpointPath $Path
-                    [pscustomobject]@{
-                        ExitCode = $portable.ExitCode
-                        Output   = $portable.Output
-                    }
-                }
-                { $_ -in @('epic-orchestrator-state', 'parallel-orchestrator-state') } {
-                    # PD-3: defined fail-closed structural behavior in an
-                    # undefined-parity region. See Test-OrchestratorCheckpointStructure.
-                    $structural = Test-OrchestratorCheckpointStructure -CheckpointPath $Path
-                    [pscustomobject]@{
-                        ExitCode = $structural.ExitCode
-                        Output   = $structural.Output
-                    }
-                }
-                default {
-                    # Fail closed on an unwired type: an unrecognized artifact type is
-                    # not a clean pass.
-                    [pscustomobject]@{
-                        ExitCode = 1
-                        Output   = "orchestrator hook: unsupported artifact type '$Type'; no validation surface is wired for it. Supported types: orchestrator-state, epic-orchestrator-state, parallel-orchestrator-state."
-                    }
-                }
-            }
-        }
+        [scriptblock] $RoutingInvoker
     )
-
-    $result = & $Invoker $CheckpointPath $ArtifactType
-    $exitCode = 0
-    if ($null -ne $result -and ($result.PSObject.Properties.Name -contains 'ExitCode')) {
-        $exitCode = [int]$result.ExitCode
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'ORCHESTRATOR_CHECKPOINT_UNRESOLVED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
+
+    $envelope = if ($PSBoundParameters.ContainsKey('InputText')) { Read-SubagentStopEnvelope -InputText $InputText } else { Read-SubagentStopEnvelope }
+    if (-not $envelope.IsValid) { $decision = @{ Ok = $false; Repairable = $false; Message = ('{0} payload anomaly - {1}' -f 'orchestrator hook:', (Get-SubagentStopEnvelopeAnomalyReason -Anomaly $envelope.Anomaly)) } }
+    else {
+        $agentOutput = $envelope.AssistantText
+        $blockArguments = @{ AgentOutput = ([string]$agentOutput); CheckpointPath = $CheckpointPath; ArtifactType = $ArtifactType; SessionRoot = $SessionRoot }
+        if ($PSBoundParameters.ContainsKey('RoutingInvoker')) { $blockArguments['RoutingInvoker'] = $RoutingInvoker }
+        $decision = Get-OrchestratorOutputBlockDecision @blockArguments
     }
-    $outputText = ''
-    if ($null -ne $result -and ($result.PSObject.Properties.Name -contains 'Output')) {
-        $outputText = ([string]$result.Output).Trim()
+    if ($decision.Ok) { return @{ Ok = $true; Message = $null } }
+    if (-not $decision.Repairable) {
+        if ($envelope.StopHookActive) { return @{ Ok = $true; Message = $null } }
+        if (-not $decision.Message.Contains('to the operator and halt.')) { $decision.Message = $decision.Message + "`n" + $script:SubagentStopReportAndHaltLine }
     }
-
-    # The exit code is the complete failure discriminator: every dispatch leg
-    # returns a non-zero ExitCode with its error text on failure and ExitCode 0
-    # with empty Output on a clean pass, so output text must not influence this
-    # decision.
-    $hasErrors = ($exitCode -ne 0)
-    return @{ HasErrors = $hasErrors; ErrorText = $outputText }
+    return @{ Ok = $false; Message = $decision.Message }
 }
 
-function Invoke-OrchestratorOutputValidation {
+function Get-OrchestratorOutputBlockDecision {
     <#
     .SYNOPSIS
-        Parses the hook payload and returns an ok-or-block decision.
+        Applies the orchestrator completion checks to the assistant text and returns the block decision.
     .DESCRIPTION
-        Returns a hashtable with keys:
-          - Ok:      $true to allow termination, $false to block.
-          - Message: error message when blocking; $null on success.
+        Returns @{ Ok = $true; Message = $null } to allow, or a hashtable with Ok = $false, a
+        Repairable boolean, and Message. Repairable is $true when the resumed subagent can clear
+        the condition (message content, its checkpoint, or its runbook) and $false when it cannot
+        (a registration argument, an internal evaluation failure, or a state it may not clear).
+        The caller applies the re-entry policy to that flag.
     #>
     [CmdletBinding()]
     [OutputType([hashtable])]
     param(
-        [string] $RawPayload,
+        [Parameter(Mandatory = $true)] [AllowEmptyString()] [string] $AgentOutput,
         [string] $CheckpointPath = 'artifacts/orchestration/orchestrator-state.json',
         [string] $ArtifactType = 'orchestrator-state',
+        [string] $SessionRoot = (Get-Location).Path,
 
         [Parameter(Mandatory = $false)]
         [scriptblock] $RoutingInvoker
     )
 
-    if ([string]::IsNullOrWhiteSpace($RawPayload)) {
-        return @{ Ok = $false; Message = 'orchestrator hook: CLAUDE_HOOK_INPUT is empty; cannot validate orchestrator output.' }
+    if ([string]::IsNullOrWhiteSpace($agentOutput)) {
+        return @{ Ok = $false; Repairable = $true; Message = 'orchestrator hook: agent output is empty (last_assistant_message carries no text); orchestrator must report final completion summary before termination.' }
     }
 
+    # Resolve the run checkpoint before any read (issue #787). A failed import, or an
+    # unresolved, ambiguous, or mismatched target, blocks here, so nothing is read.
     try {
-        $payload = $RawPayload | ConvertFrom-Json -ErrorAction Stop
-    } catch {
-        return @{ Ok = $false; Message = "orchestrator hook: failed to parse CLAUDE_HOOK_INPUT as JSON: $($_.Exception.Message)" }
+        $resolution = Resolve-OrchestratorOutputCheckpointPath -ArtifactType $ArtifactType -CheckpointPath $CheckpointPath -AgentOutput ([string]$agentOutput) -SessionRoot $SessionRoot
     }
-
-    $agentOutput = $null
-    if ($payload.PSObject.Properties.Name -contains 'output') {
-        $agentOutput = $payload.output
+    catch {
+        return @{ Ok = $false; Repairable = $false; Message = ('ORCHESTRATOR_CHECKPOINT_UNRESOLVED: {0}: NoTarget (RESOLVER_FAILED): {1}' -f $ArtifactType, $_.Exception.Message) }
     }
-    if ([string]::IsNullOrWhiteSpace($agentOutput)) {
-        return @{ Ok = $false; Message = 'orchestrator hook: agent output is empty; orchestrator must report final completion summary before termination.' }
+    if (-not $resolution.Resolved) {
+        $resolutionRepairable = ($resolution.Status -in @('NoTarget', 'Ambiguous')) -and ($ArtifactType -in @('epic-orchestrator-state', 'parallel-orchestrator-state'))
+        return @{ Ok = $false; Repairable = $resolutionRepairable; Message = ('ORCHESTRATOR_CHECKPOINT_UNRESOLVED: {0}: {1} ({2}): {3}' -f
+                $ArtifactType, $resolution.Status, $resolution.ReasonCode, $resolution.Detail) }
     }
 
-    $file = Get-CheckpointFileContent -Path $CheckpointPath
+    $file = Get-CheckpointFileContent -Path $resolution.CheckpointPath
     if (-not $file.Exists) {
-        return @{ Ok = $false; Message = "orchestrator hook: checkpoint file '$CheckpointPath' does not exist. Orchestrator must persist progress per powershell-orchestration-state-machine before termination." }
+        return @{ Ok = $false; Repairable = $true; Message = "orchestrator hook: checkpoint file '$($resolution.CheckpointPath)' does not exist. Orchestrator must persist progress per powershell-orchestration-state-machine before termination." }
     }
 
     if ([string]::IsNullOrWhiteSpace($file.Content)) {
-        return @{ Ok = $false; Message = "orchestrator hook: checkpoint file '$CheckpointPath' is empty; cannot validate orchestrator progress." }
+        return @{ Ok = $false; Repairable = $true; Message = "orchestrator hook: checkpoint file '$($resolution.CheckpointPath)' is empty; cannot validate orchestrator progress." }
     }
 
     try {
         $checkpoint = $file.Content | ConvertFrom-Json -ErrorAction Stop
     } catch {
-        return @{ Ok = $false; Message = "orchestrator hook: checkpoint file '$CheckpointPath' is not valid JSON: $($_.Exception.Message)" }
+        return @{ Ok = $false; Repairable = $true; Message = "orchestrator hook: checkpoint file '$($resolution.CheckpointPath)' is not valid JSON: $($_.Exception.Message)" }
     }
 
     $requiredFields = @('objective', 'completed_steps', 'next_step', 'last_updated')
@@ -367,41 +282,51 @@ function Invoke-OrchestratorOutputValidation {
 
     if ($missingFields.Count -gt 0) {
         $missingList = ($missingFields -join ', ')
-        return @{ Ok = $false; Message = "orchestrator hook: checkpoint file '$CheckpointPath' is missing required field(s): $missingList. Orchestrator must persist objective, completed_steps, next_step, and last_updated." }
+        return @{ Ok = $false; Repairable = $true; Message = "orchestrator hook: checkpoint file '$($resolution.CheckpointPath)' is missing required field(s): $missingList. Orchestrator must persist objective, completed_steps, next_step, and last_updated." }
     }
 
     if ([string]::IsNullOrWhiteSpace([string]$checkpoint.objective)) {
-        return @{ Ok = $false; Message = "orchestrator hook: checkpoint file '$CheckpointPath' has an empty 'objective' field; orchestrator must record the active objective." }
+        return @{ Ok = $false; Repairable = $true; Message = "orchestrator hook: checkpoint file '$($resolution.CheckpointPath)' has an empty 'objective' field; orchestrator must record the active objective." }
     }
 
     $humanInteraction = $null
     if ($checkpointProps -contains 'human_interaction') {
         $humanInteraction = $checkpoint.human_interaction
     }
-    $hiResult = Test-HumanInteractionShape -HumanInteraction $humanInteraction
+    # A relative runbook_path is checked beneath the resolved root, not the process location.
+    $hiResult = Test-HumanInteractionShape -HumanInteraction $humanInteraction -FileExistsCheck {
+        param($Path) Test-OrchestratorOutputRunbookFile -Path (Resolve-OrchestratorOutputRunbookPath -WorktreeRoot $resolution.WorktreeRoot -RunbookPath $Path)
+    }
     if (-not $hiResult.Ok) {
-        return @{ Ok = $false; Message = $hiResult.Message }
+        return @{ Ok = $false; Repairable = $hiResult.Repairable; Message = $hiResult.Message }
     }
 
     # Delegate to the portable routing-contract validation, dispatched on
     # ArtifactType. The optional RoutingInvoker seam lets tests inject a mock; the
     # default seam runs the in-process PowerShell validation and starts no
     # subprocess.
-    $routingArgs = @{ CheckpointPath = $CheckpointPath; ArtifactType = $ArtifactType }
+    $routingArgs = @{ CheckpointPath = $resolution.CheckpointPath; ArtifactType = $ArtifactType }
     if ($PSBoundParameters.ContainsKey('RoutingInvoker') -and $null -ne $RoutingInvoker) {
         $routingArgs['Invoker'] = $RoutingInvoker
     }
     $routingResult = Invoke-RoutingContractValidation @routingArgs
     if ($routingResult.HasErrors) {
-        # One subprocess call now covers both --require-complete and
-        # --require-model-routing. Surface a model-routing gate failure under its
-        # own block reason (its errors name model_routing_receipts or
-        # complexity_assessments); otherwise fall back to the routing-contract
+        # The in-process validation (issue #475) covers both the completion check
+        # and the model-routing check in one call. Surface a model-routing gate
+        # failure under its own block reason (its errors name model_routing_receipts
+        # or complexity_assessments); otherwise fall back to the routing-contract
         # block reason for a generic completion/routing failure.
         if ($routingResult.ErrorText -match 'model_routing_receipts|complexity_assessments') {
-            return @{ Ok = $false; Message = "MODEL_ROUTING_BLOCKED: $($routingResult.ErrorText)" }
+            return @{ Ok = $false; Repairable = $true; Message = "MODEL_ROUTING_BLOCKED: $($routingResult.ErrorText)" }
         }
-        return @{ Ok = $false; Message = "ROUTING_CONTRACT_BLOCKED: $($routingResult.ErrorText)" }
+        return @{ Ok = $false; Repairable = $true; Message = "ROUTING_CONTRACT_BLOCKED: $($routingResult.ErrorText)" }
+    }
+
+    # Layer 2 (issue #840): the epic checkpoint only, after the routing dispatch passes,
+    # on the checkpoint text already read.
+    if ($ArtifactType -eq 'epic-orchestrator-state') {
+        $barrier = Get-OrchestratorOutputWaveBarrierDecision -CheckpointText $file.Content
+        if (-not $barrier.Ok) { return @{ Ok = $false; Repairable = $barrier.Repairable; Message = $barrier.Message } }
     }
 
     return @{ Ok = $true; Message = $null }
@@ -411,11 +336,11 @@ function Invoke-OrchestratorOutputValidation {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('ORCHESTRATOR_CHECKPOINT_UNRESOLVED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'ORCHESTRATOR_CHECKPOINT_UNRESOLVED:'
+if ($null -ne $dependencyDecision) { [Console]::Error.WriteLine($dependencyDecision.Reason); exit $dependencyDecision.ExitCode }
 
-$result = Invoke-OrchestratorOutputValidation -RawPayload $env:CLAUDE_HOOK_INPUT -CheckpointPath $CheckpointPath -ArtifactType $ArtifactType
-if (-not $result.Ok) {
-    Write-Error $result.Message
-    exit 1
-}
-
+try { $result = Invoke-OrchestratorOutputValidation -CheckpointPath $CheckpointPath -ArtifactType $ArtifactType }
+catch { Exit-SubagentStopBlock -Message ('ORCHESTRATOR_CHECKPOINT_UNRESOLVED: validator error: ' + ([string]$_.Exception.Message -split "`r?`n")[0] + '; the gate fails closed.' + "`n" + $script:SubagentStopReportAndHaltLine) }
+if (-not $result.Ok) { Exit-SubagentStopBlock -Message $result.Message }
 exit 0

package/resources/claude-customizations/.claude/hooks/validate-planner-output.ps1

@@ -9,7 +9,7 @@
     structure requirements.
 
     Enforced checks:
-      - hook payload is valid JSON and contains non-empty output,
+      - the SubagentStop envelope read from stdin carries a non-empty last_assistant_message,
       - output advertises `plan-path: <path>` (or supported equivalent forms),
       - output contains `PREFLIGHT: ALL CLEAR` or
         `PREFLIGHT: REVISIONS REQUIRED`,
@@ -22,17 +22,25 @@
       - the final phase contains QA-oriented work.
 
 .NOTES
-    Reads the hook payload from CLAUDE_HOOK_INPUT as JSON. Exits 0 to allow
-    termination; exits 1 with an error message to block. Filesystem reads go
-    through Get-PlanFileContent so tests can mock the boundary without writing
-    temporary files.
+    Reads the SubagentStop envelope from stdin through Read-SubagentStopEnvelope
+    (subagentstop-envelope.ps1); the assistant text comes from the helper's
+    AssistantText. A non-repairable condition blocks once: when StopHookActive is
+    set, the re-entered stop is allowed. Exits 0 to allow termination; a block is
+    written to stderr with exit 2 through Exit-SubagentStopBlock. The dependency
+    guard and the E1 helper are guarded loads: a failure blocks with exit 2,
+    naming the file. Filesystem reads go through Get-PlanFileContent so tests can
+    mock the boundary without writing temporary files.
+    An unhandled error during validation blocks with exit 2 and a reason (issue #928).
 #>
 
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 Set-StrictMode -Version Latest
+try { . (Join-Path $PSScriptRoot 'subagentstop-envelope.ps1') } catch { Add-HookDependencyFailure -Name 'subagentstop-envelope.ps1' -ErrorRecord $_ }
 $ErrorActionPreference = 'Stop'
+$script:SubagentStopReportAndHaltLine = 'This condition is not repairable by the subagent. Report it to the operator and halt.'
 
 function Get-PlanFileContent {
     [CmdletBinding()]
@@ -232,7 +240,7 @@ function Get-PlanStructureValidationReport {
     [OutputType([string[]])]
     param(
         [Parameter(Mandatory = $true)]
-        [string[]] $Lines
+        [AllowEmptyString()] [string[]] $Lines
     )
 
     $phasePattern = '^### Phase (?<Phase>\d+)\s+—\s+(?<Title>.+)$'
@@ -243,12 +251,14 @@ function Get-PlanStructureValidationReport {
     $currentPhase = $null
     $expectedPhase = 0
     $foundTask = $false
+    $insidePhaseSection = $false
 
     for ($i = 0; $i -lt $Lines.Count; $i++) {
         $lineNumber = $i + 1
         $line = $Lines[$i]
 
         if ($line -match '^### Phase ') {
+            $insidePhaseSection = $true
             $phaseMatch = [regex]::Match($line, $phasePattern)
             if (-not $phaseMatch.Success) {
                 $errors.Add("Line ${lineNumber}: phase heading must match `### Phase N — <Title>`.")
@@ -269,10 +279,12 @@ function Get-PlanStructureValidationReport {
             continue
         }
 
+        if ($line -match '^#{1,2} ') { $insidePhaseSection = $false; continue }
         if ($line -notmatch '^- \[') {
             continue
         }
 
+        if (-not $insidePhaseSection -and $line -notmatch $taskPattern) { continue }
         $foundTask = $true
         $taskMatch = [regex]::Match($line, $taskPattern)
         if (-not $taskMatch.Success) {
@@ -344,54 +356,74 @@ function Get-PlanStructureValidationReport {
 }
 
 function Invoke-PlannerOutputValidation {
+    <#
+    .SYNOPSIS
+        Reads the SubagentStop envelope, validates the assistant text, and applies the re-entry policy.
+    #>
     [CmdletBinding()]
     [OutputType([hashtable])]
     param(
-        [string] $RawPayload
+        [AllowNull()] [AllowEmptyString()] [string] $InputText
     )
-
-    if ([string]::IsNullOrWhiteSpace($RawPayload)) {
-        return @{ Ok = $false; Message = 'atomic-planner hook: CLAUDE_HOOK_INPUT is empty; cannot validate planner output.' }
-    }
-
-    try {
-        $payload = $RawPayload | ConvertFrom-Json -ErrorAction Stop
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'validate-planner-output:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
+    $envelope = if ($PSBoundParameters.ContainsKey('InputText')) { Read-SubagentStopEnvelope -InputText $InputText } else { Read-SubagentStopEnvelope }
+    if (-not $envelope.IsValid) { $decision = @{ Ok = $false; Repairable = $false; Message = ('{0} payload anomaly - {1}' -f 'atomic-planner hook:', (Get-SubagentStopEnvelopeAnomalyReason -Anomaly $envelope.Anomaly)) } }
+    else {
+        $agentOutput = $envelope.AssistantText
+        $decision = Get-PlannerOutputBlockDecision -AgentOutput ([string]$agentOutput)
     }
-    catch {
-        return @{ Ok = $false; Message = "atomic-planner hook: failed to parse CLAUDE_HOOK_INPUT as JSON: $($_.Exception.Message)" }
+    if ($decision.Ok) { return @{ Ok = $true; Message = $null } }
+    if (-not $decision.Repairable) {
+        if ($envelope.StopHookActive) { return @{ Ok = $true; Message = $null } }
+        if (-not $decision.Message.Contains('to the operator and halt.')) { $decision.Message = $decision.Message + "`n" + $script:SubagentStopReportAndHaltLine }
     }
+    return @{ Ok = $false; Message = $decision.Message }
+}
+
+function Get-PlannerOutputBlockDecision {
+    <#
+    .SYNOPSIS
+        Applies the planner completion checks to the assistant text and returns the block decision.
+    .DESCRIPTION
+        Returns @{ Ok = $true; Message = $null } to allow, or a hashtable with Ok = $false, a
+        Repairable boolean, and Message. Every planner content check is repairable by the subagent.
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyString()]
+        [string] $AgentOutput
+    )
 
-    $agentOutput = $null
-    if ($null -ne $payload.PSObject.Properties['output']) {
-        $agentOutput = $payload.output
-    }
     if ([string]::IsNullOrWhiteSpace($agentOutput)) {
-        return @{ Ok = $false; Message = 'atomic-planner hook: agent output is empty; planner must return plan-path and final preflight signal.' }
+        return @{ Ok = $false; Repairable = $true; Message = 'atomic-planner hook: agent output is empty (last_assistant_message carries no text); planner must return plan-path and final preflight signal.' }
     }
 
     if (-not (Test-HasPreflightSignal -AgentOutput $agentOutput)) {
-        return @{ Ok = $false; Message = 'atomic-planner hook: agent output must include `PREFLIGHT: ALL CLEAR` or `PREFLIGHT: REVISIONS REQUIRED`.' }
+        return @{ Ok = $false; Repairable = $true; Message = 'atomic-planner hook: agent output must include `PREFLIGHT: ALL CLEAR` or `PREFLIGHT: REVISIONS REQUIRED`.' }
     }
 
     $planPath = Get-PlanPathFromOutput -AgentOutput $agentOutput
     if ($null -eq $planPath) {
-        return @{ Ok = $false; Message = 'atomic-planner hook: agent output does not advertise a plan-path. Planner must report `plan-path: <path>` per atomic-plan-contract.' }
+        return @{ Ok = $false; Repairable = $true; Message = 'atomic-planner hook: agent output does not advertise a plan-path. Planner must report `plan-path: <path>` per atomic-plan-contract.' }
     }
 
     $file = Get-PlanFileContent -Path $planPath
     if (-not $file.Exists) {
-        return @{ Ok = $false; Message = "atomic-planner hook: planner advertised plan-path '$planPath' but no file exists at that location." }
+        return @{ Ok = $false; Repairable = $true; Message = "atomic-planner hook: planner advertised plan-path '$planPath' but no file exists at that location." }
     }
 
     $errors = @(Get-PlanStructureValidationReport -Lines $file.Lines)
     if ($errors.Count -gt 0) {
         $message = "atomic-planner hook: plan '$planPath' violates the atomic plan contract:`n  - " + ($errors -join "`n  - ")
-        return @{ Ok = $false; Message = $message }
+        return @{ Ok = $false; Repairable = $true; Message = $message }
     }
 
     $review = Get-PlannerInternalReviewValidation -AgentOutput $agentOutput
     if (-not $review.Ok) {
-        return @{ Ok = $false; Message = "atomic-planner hook: $($review.Message)" }
+        return @{ Ok = $false; Repairable = $true; Message = "atomic-planner hook: $($review.Message)" }
     }
 
     return @{ Ok = $true; Message = $null }
@@ -400,11 +432,11 @@ function Invoke-PlannerOutputValidation {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('validate-planner-output: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'validate-planner-output:'
+if ($null -ne $dependencyDecision) { [Console]::Error.WriteLine($dependencyDecision.Reason); exit $dependencyDecision.ExitCode }
 
-$result = Invoke-PlannerOutputValidation -RawPayload $env:CLAUDE_HOOK_INPUT
-if (-not $result.Ok) {
-    Write-Error $result.Message
-    exit 1
-}
-
+try { $result = Invoke-PlannerOutputValidation }
+catch { Exit-SubagentStopBlock -Message ('validate-planner-output: validator error: ' + ([string]$_.Exception.Message -split "`r?`n")[0] + '; the gate fails closed.' + "`n" + $script:SubagentStopReportAndHaltLine) }
+if (-not $result.Ok) { Exit-SubagentStopBlock -Message $result.Message }
 exit 0