@danmoisan/drm-copilot-mcp 1.1.18 → 1.1.19

package/resources/claude-customizations/.claude/hooks/validate-pr-author-output.ps1

@@ -3,18 +3,21 @@
     SubagentStop hook that verifies the pr-author agent reported a created or updated PR.
 
 .DESCRIPTION
-    Invoked by the Claude Code SubagentStop hook for the pr-author matcher. Reads the agent
-    transcript JSON from the CLAUDE_HOOK_INPUT environment variable, extracts the .output field,
-    and confirms the output reports that a pull request was created or updated. The hook allows
-    (exit 0) when the output contains:
+    Invoked by the Claude Code SubagentStop hook for the pr-author matcher. Reads the SubagentStop
+    envelope JSON from stdin through the shared envelope helper (subagentstop-envelope.ps1) and
+    validates its last_assistant_message field, the pr-author agent's last assistant message. The
+    hook allows (exit 0) when that message contains:
       - a GitHub PR URL (github.com/<owner>/<repo>/pull/<n>), or
       - a PR reference of the form "PR #<n>", or
       - a "gh pr create"/"gh pr edit" confirmation that includes a PR number.
-    The hook blocks (exit 1) when:
-      - CLAUDE_HOOK_INPUT is empty,
-      - the input is not valid JSON,
-      - the .output field is empty, or
-      - the output contains no PR URL or PR number.
+    The hook blocks, writing the reason to stderr and exiting 2 through the shared envelope
+    helper, when:
+      - the envelope is empty, is not valid JSON, is not a JSON object, or carries no string
+        last_assistant_message (reason prefix "PR_AUTHOR_OUTPUT_MALFORMED: payload anomaly"),
+      - the last assistant message is blank (PR_AUTHOR_OUTPUT_EMPTY), or
+      - the last assistant message contains no PR URL or PR number (PR_AUTHOR_OUTPUT_NO_PR).
+    A hook dependency that fails to load blocks with exit 2 and the PR_AUTHOR_OUTPUT_MISSING:
+    prefix.
 
 .NOTES
     Compatible with PowerShell 7+. No external module dependencies.
@@ -24,9 +27,12 @@
     that the referenced PR actually exists on GitHub, and the output text is forgeable by any actor
     that controls the agent transcript. It MUST NOT be described as tamper-proof or as a security
     boundary.
+    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 }
+try { . (Join-Path $PSScriptRoot 'subagentstop-envelope.ps1') } catch { Add-HookDependencyFailure -Name 'subagentstop-envelope.ps1' -ErrorRecord $_ }
 
 function Test-PrAuthorOutputReportsPr {
     <#
@@ -36,7 +42,7 @@ function Test-PrAuthorOutputReportsPr {
         Detection helper (injectable boundary for tests). Matches a GitHub PR URL, a "PR #<n>"
         reference, or a "gh pr create"/"gh pr edit" confirmation that contains a PR number.
     .PARAMETER OutputText
-        The pr-author agent's final output text extracted from CLAUDE_HOOK_INPUT.output.
+        The pr-author agent's last assistant message text.
     .OUTPUTS
         System.Boolean
     #>
@@ -71,53 +77,43 @@ function Test-PrAuthorOutputReportsPr {
 function Get-PrAuthorOutputDecision {
     <#
     .SYNOPSIS
-        Parse CLAUDE_HOOK_INPUT and return an allow-or-block decision with exit code semantics.
+        Read the SubagentStop envelope and return an allow-or-block decision.
     .DESCRIPTION
         Returns an ordered dictionary with 'allowed' (bool) and 'reason' (string). Allowed is $true
-        only when the parsed .output reports a PR per Test-PrAuthorOutputReportsPr. Empty input,
-        malformed JSON, empty output, and PR-less output all yield allowed = $false.
-    .PARAMETER HookInputRaw
-        The raw JSON transcript payload supplied by Claude Code via CLAUDE_HOOK_INPUT.
+        only when the envelope's last assistant message reports a PR per
+        Test-PrAuthorOutputReportsPr. An invalid envelope (payload anomaly), a blank last assistant
+        message, and a message without a PR reference all yield allowed = $false.
+    .PARAMETER InputText
+        The SubagentStop envelope JSON. When the parameter is not bound, Read-SubagentStopEnvelope
+        reads the envelope from stdin.
     .OUTPUTS
         System.Collections.Specialized.OrderedDictionary
     #>
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
     param(
-        [string] $HookInputRaw
+        [AllowNull()] [AllowEmptyString()] [string] $InputText
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'PR_AUTHOR_OUTPUT_MISSING:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
+    $envelope = if ($PSBoundParameters.ContainsKey('InputText')) { Read-SubagentStopEnvelope -InputText $InputText } else { Read-SubagentStopEnvelope }
+    if (-not $envelope.IsValid) { return [ordered]@{ allowed = $false; reason = "PR_AUTHOR_OUTPUT_MALFORMED: payload anomaly - $(Get-SubagentStopEnvelopeAnomalyReason -Anomaly $envelope.Anomaly)" } }
+    $assistantMessage = [string]$envelope.AssistantText
 
-    if ([string]::IsNullOrWhiteSpace($HookInputRaw)) {
+    if ([string]::IsNullOrWhiteSpace($assistantMessage)) {
         return [ordered]@{
             allowed = $false
-            reason  = 'PR_AUTHOR_OUTPUT_MISSING: CLAUDE_HOOK_INPUT is empty; the pr-author agent produced no transcript to validate.'
+            reason  = 'PR_AUTHOR_OUTPUT_EMPTY: the pr-author last assistant message is empty; it must report the created or updated PR URL or number.'
         }
     }
 
-    try {
-        $parsed = $HookInputRaw | ConvertFrom-Json -ErrorAction Stop
-    } catch {
-        return [ordered]@{
-            allowed = $false
-            reason  = 'PR_AUTHOR_OUTPUT_MALFORMED: CLAUDE_HOOK_INPUT is not valid JSON.'
-        }
-    }
-
-    $outputText = [string]$parsed.output
-    if ([string]::IsNullOrWhiteSpace($outputText)) {
-        return [ordered]@{
-            allowed = $false
-            reason  = 'PR_AUTHOR_OUTPUT_EMPTY: the pr-author agent output is empty; it must report the created or updated PR URL or number.'
-        }
-    }
-
-    if (Test-PrAuthorOutputReportsPr -OutputText $outputText) {
+    if (Test-PrAuthorOutputReportsPr -OutputText $assistantMessage) {
         return [ordered]@{ allowed = $true }
     }
 
     return [ordered]@{
         allowed = $false
-        reason  = 'PR_AUTHOR_OUTPUT_NO_PR: the pr-author agent output does not reference a PR URL or PR number; it must report the created or updated pull request.'
+        reason  = 'PR_AUTHOR_OUTPUT_NO_PR: the pr-author last assistant message does not reference a PR URL or PR number; it must report the created or updated pull request.'
     }
 }
 
@@ -125,12 +121,11 @@ function Get-PrAuthorOutputDecision {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('PR_AUTHOR_OUTPUT_MISSING: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'PR_AUTHOR_OUTPUT_MISSING:'
+if ($null -ne $dependencyDecision) { [Console]::Error.WriteLine($dependencyDecision.Reason); exit $dependencyDecision.ExitCode }
 
-$decision = Get-PrAuthorOutputDecision -HookInputRaw $env:CLAUDE_HOOK_INPUT
-
-if (-not $decision['allowed']) {
-    Write-Error $decision['reason']
-    exit 1
-}
-
+try { $decision = Get-PrAuthorOutputDecision }
+catch { Exit-SubagentStopBlock -Message ('PR_AUTHOR_OUTPUT_MISSING: validator error: ' + ([string]$_.Exception.Message -split "`r?`n")[0] + '; the gate fails closed.' + "`n" + 'This condition is not repairable by the subagent. Report it to the operator and halt.') }
+if (-not $decision['allowed']) { Exit-SubagentStopBlock -Message $decision['reason'] }
 exit 0

package/resources/claude-customizations/.claude/hooks/validate-prd-feature-output.ps1

@@ -1,10 +1,21 @@
 <#
 .SYNOPSIS
     Validates numeric acceptance criteria produced by the prd-feature worker.
+
+.NOTES
+    Reads the SubagentStop envelope JSON from stdin through the shared envelope helper
+    (subagentstop-envelope.ps1) and validates its last_assistant_message field, the prd-feature
+    worker's last assistant message. Exits 0 to allow. A block writes the reason to stderr and
+    exits 2 through the shared envelope helper; an invalid envelope blocks with a payload anomaly
+    reason. A hook dependency that fails to load blocks with exit 2 and the
+    validate-prd-feature-output: prefix.
+    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 }
+try { . (Join-Path $PSScriptRoot 'subagentstop-envelope.ps1') } catch { Add-HookDependencyFailure -Name 'subagentstop-envelope.ps1' -ErrorRecord $_ }
 
 Set-StrictMode -Version Latest
 $ErrorActionPreference = 'Stop'
@@ -38,7 +49,7 @@ function Test-NumericDerivationEvidence {
         if (-not $match.Success) { return @{ Ok = $false; Message = "prd-feature hook: numeric derivation evidence is missing $label." } }
         $values[$label] = $match.Groups['value'].Value.Trim()
     }
-    if ($values['Exhaustive Search Scope'] -notmatch '(?i)\b(entire|all|complete)\b.*\b(repository|repo|source tree|tree)\b') { return @{ Ok = $false; Message = 'prd-feature hook: numeric derivation evidence does not declare an exhaustive repository search scope.' } }
+    if ($values['Exhaustive Search Scope'] -notmatch '(?i)\b(entire|whole|all|complete)\b.*\b(repository|repo|worktree|source tree|tree)\b') { return @{ Ok = $false; Message = 'prd-feature hook: numeric derivation evidence does not declare an exhaustive repository search scope.' } }
     $primaryStrategy = $values['Primary Search Strategy or Query Expression']
     $crossCheckStrategy = $values['Cross-check Search Strategy or Query Expression']
     if ($primaryStrategy -match '(?i)\b(single|narrow|named[- ]?pattern)\b' -or $crossCheckStrategy -match '(?i)\b(single|narrow|named[- ]?pattern)\b') { return @{ Ok = $false; Message = 'prd-feature hook: numeric derivation evidence uses a narrow named-pattern search.' } }
@@ -64,28 +75,46 @@ function Test-SpecNumericCriterion {
     param([Parameter(Mandatory = $true)][AllowEmptyString()][string] $SpecContent)
 
     $section = [regex]::Match($SpecContent, '(?ims)^##\s+Acceptance\s+Criteria\s*$.*?(?=^##\s|\z)')
-    return $section.Success -and [regex]::IsMatch($section.Value, '(?m)^\s*[-*]\s*\[.\].*\b\d+\b')
+    if (-not $section.Success) { return $false }
+    # Rule R2 (issue #905): a criterion is numeric only when it states a determiner-led cardinal count of a
+    # plural noun and cites no policy file.
+    $derivedCountPattern = '\b(?:all|exactly|the|these|those)\s+(?:[1-9]\d*|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve|thirteen|fourteen|fifteen|sixteen|seventeen|eighteen|nineteen|twenty)\s+(?:(?!(?:seconds|minutes|hours|days|weeks|milliseconds|lines|bytes|characters|percent|is|as|us|has|was|does|this|its|thus|plus|less|unless|across|always|yes)\b)[\w`./-]+\s+){0,3}?(?!(?:seconds|minutes|hours|days|weeks|milliseconds|lines|bytes|characters|percent|is|as|us|has|was|does|this|its|thus|plus|less|unless|across|always|yes)\b)[a-z][\w-]*s\b'
+    $policyMarkers = @('.claude/rules/', '.github/instructions/', '.github/copilot-instructions.md')
+    foreach ($line in ($section.Value -split "`r?`n")) {
+        if ($line -notmatch '^\s*[-*]\s*\[.\]') { continue }
+        if (-not [regex]::IsMatch($line, $derivedCountPattern, [System.Text.RegularExpressions.RegexOptions]::IgnoreCase)) { continue }
+        $normalized = $line -replace '\\', '/'
+        if (@($policyMarkers | Where-Object { $normalized.Contains($_) }).Count -gt 0) { continue }
+        return $true
+    }
+    return $false
 }
 
 function Invoke-PrdFeatureOutputValidation {
     [CmdletBinding()]
     [OutputType([hashtable])]
-    param([string] $RawPayload)
-
-    if ([string]::IsNullOrWhiteSpace($RawPayload)) { return @{ Ok = $false; Message = 'prd-feature hook: CLAUDE_HOOK_INPUT is empty.' } }
-    try { $payload = $RawPayload | ConvertFrom-Json -ErrorAction Stop } catch { return @{ Ok = $false; Message = "prd-feature hook: failed to parse CLAUDE_HOOK_INPUT as JSON: $($_.Exception.Message)" } }
-    $output = if ($null -ne $payload.PSObject.Properties['output']) { $payload.output } else { $null }
-    if ([string]::IsNullOrWhiteSpace($output)) { return @{ Ok = $false; Message = 'prd-feature hook: agent output is empty.' } }
-    $specPath = Get-ArtifactPathFromOutput -Output $output -Label 'spec-path'
+    param([AllowNull()] [AllowEmptyString()] [string] $InputText)
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'validate-prd-feature-output:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
+    $envelope = if ($PSBoundParameters.ContainsKey('InputText')) { Read-SubagentStopEnvelope -InputText $InputText } else { Read-SubagentStopEnvelope }
+    if (-not $envelope.IsValid) { return @{ Ok = $false; Message = "prd-feature hook: payload anomaly - $(Get-SubagentStopEnvelopeAnomalyReason -Anomaly $envelope.Anomaly)" } }
+    $assistantMessage = [string]$envelope.AssistantText
+    if ([string]::IsNullOrWhiteSpace($assistantMessage)) { return @{ Ok = $false; Message = 'prd-feature hook: last assistant message is empty.' } }
+    $specPath = Get-ArtifactPathFromOutput -Output $assistantMessage -Label 'spec-path'
     if ([string]::IsNullOrWhiteSpace($specPath) -or -not (Test-Path -LiteralPath $specPath -PathType Leaf)) { return @{ Ok = $false; Message = 'prd-feature hook: spec-path is required and must exist.' } }
-    $specContent = Get-Content -LiteralPath $specPath -Raw -ErrorAction Stop
+    try { $specContent = Get-Content -LiteralPath $specPath -Raw -ErrorAction Stop } catch { return @{ Ok = $false; Message = "prd-feature hook: failed to read spec-path '$specPath': $($_.Exception.Message)" } }
     if (-not (Test-SpecNumericCriterion -SpecContent $specContent)) { return @{ Ok = $true; Message = $null } }
-    $researchPath = Get-ArtifactPathFromOutput -Output $output -Label 'research-path'
+    $researchPath = Get-ArtifactPathFromOutput -Output $assistantMessage -Label 'research-path'
     if ([string]::IsNullOrWhiteSpace($researchPath) -or -not (Test-Path -LiteralPath $researchPath -PathType Leaf)) { return @{ Ok = $false; Message = 'prd-feature hook: numeric acceptance criterion requires an existing research-path.' } }
-    return Test-NumericDerivationEvidence -Content (Get-Content -LiteralPath $researchPath -Raw -ErrorAction Stop)
+    try { $researchContent = Get-Content -LiteralPath $researchPath -Raw -ErrorAction Stop } catch { return @{ Ok = $false; Message = "prd-feature hook: failed to read research-path '$researchPath': $($_.Exception.Message)" } }
+    return Test-NumericDerivationEvidence -Content $researchContent
 }
 
 if ($MyInvocation.InvocationName -eq '.') { return }
-$result = Invoke-PrdFeatureOutputValidation -RawPayload $env:CLAUDE_HOOK_INPUT
-if (-not $result.Ok) { Write-Error $result.Message; exit 1 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('validate-prd-feature-output: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'validate-prd-feature-output:'
+if ($null -ne $dependencyDecision) { [Console]::Error.WriteLine($dependencyDecision.Reason); exit $dependencyDecision.ExitCode }
+try { $result = Invoke-PrdFeatureOutputValidation }
+catch { Exit-SubagentStopBlock -Message ('validate-prd-feature-output: validator error: ' + ([string]$_.Exception.Message -split "`r?`n")[0] + '; the gate fails closed.' + "`n" + 'This condition is not repairable by the subagent. Report it to the operator and halt.') }
+if (-not $result.Ok) { Exit-SubagentStopBlock -Message $result.Message }
 exit 0

package/resources/claude-customizations/.claude/hooks/validate-required-artifact-output.ps1

@@ -3,10 +3,10 @@
     Generic SubagentStop hook for agents that must advertise exact artifact paths.
 
 .DESCRIPTION
-    Validates that the hook payload is well-formed JSON, the agent output is
-    non-empty, each required artifact token is advertised in the output, the
-    advertised path matches the configured contract regex, and the file exists
-    on disk.
+    Validates that the SubagentStop envelope read from stdin carries a non-empty
+    last_assistant_message, each required artifact token is advertised in that
+    text, the advertised path matches the configured contract regex, and the file
+    exists on disk.
 
     Each required artifact spec must use:
         token|regex|description
@@ -15,10 +15,17 @@
         spec-path|^docs/features/active/.+/spec\.md$|spec artifact
 
 .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 existence
-    checks go through Test-ArtifactFile 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. A missing
+    AgentName or RequiredArtifact argument exits 2 inline and blocks once. The
+    dependency guard and the E1 helper are guarded loads: a failure blocks with
+    exit 2, naming the file. Filesystem existence checks go through
+    Test-ArtifactFile 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()]
@@ -27,9 +34,12 @@ param(
 
     [string[]] $RequiredArtifact
 )
+$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 Test-ArtifactFile {
     [CmdletBinding()]
@@ -90,31 +100,53 @@ function Get-ArtifactPathFromOutput {
 }
 
 function Invoke-RequiredArtifactOutputValidation {
+    <#
+    .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,
         [string] $AgentName,
         [string[]] $RequiredArtifact
     )
 
-    if ([string]::IsNullOrWhiteSpace($RawPayload)) {
-        return @{ Ok = $false; Message = "$AgentName hook: CLAUDE_HOOK_INPUT is empty; cannot validate required artifact output." }
+    $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 ("$AgentName hook:"), (Get-SubagentStopEnvelopeAnomalyReason -Anomaly $envelope.Anomaly)) } }
+    else {
+        $agentOutput = $envelope.AssistantText
+        $decision = Get-RequiredArtifactOutputBlockDecision -AgentOutput ([string]$agentOutput) -AgentName $AgentName -RequiredArtifact $RequiredArtifact
     }
-
-    try {
-        $payload = $RawPayload | ConvertFrom-Json -ErrorAction Stop
-    }
-    catch {
-        return @{ Ok = $false; Message = "$AgentName 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-RequiredArtifactOutputBlockDecision {
+    <#
+    .SYNOPSIS
+        Applies the required-artifact 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. A malformed RequiredArtifact spec is a registration
+        defect the subagent cannot clear, so it is not repairable; the other blocks are.
+    #>
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [AllowEmptyString()]
+        [string] $AgentOutput,
+        [string] $AgentName,
+        [string[]] $RequiredArtifact
+    )
 
-    $agentOutput = $null
-    if ($payload.PSObject.Properties.Name -contains 'output') {
-        $agentOutput = $payload.output
-    }
     if ([string]::IsNullOrWhiteSpace($agentOutput)) {
-        return @{ Ok = $false; Message = "$AgentName hook: agent output is empty; artifact paths must be reported before termination." }
+        return @{ Ok = $false; Repairable = $true; Message = "$AgentName hook: agent output is empty (last_assistant_message carries no text); artifact paths must be reported before termination." }
     }
 
     $errors = [System.Collections.Generic.List[string]]::new()
@@ -123,7 +155,7 @@ function Invoke-RequiredArtifactOutputValidation {
             $spec = ConvertTo-ArtifactSpec -Spec $specText
         }
         catch {
-            return @{ Ok = $false; Message = "$AgentName hook: $($_.Exception.Message)" }
+            return @{ Ok = $false; Repairable = $false; Message = "$AgentName hook: $($_.Exception.Message)" }
         }
 
         $path = Get-ArtifactPathFromOutput -AgentOutput $agentOutput -Token $spec.Token
@@ -144,7 +176,7 @@ function Invoke-RequiredArtifactOutputValidation {
 
     if ($errors.Count -gt 0) {
         $message = "$AgentName hook: required artifact validation failed:`n  - " + ($errors -join "`n  - ")
-        return @{ Ok = $false; Message = $message }
+        return @{ Ok = $false; Repairable = $true; Message = $message }
     }
 
     return @{ Ok = $true; Message = $null }
@@ -154,18 +186,16 @@ if ($MyInvocation.InvocationName -eq '.') {
     return
 }
 
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('validate-required-artifact-output: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'validate-required-artifact-output:'
+if ($null -ne $dependencyDecision) { [Console]::Error.WriteLine($dependencyDecision.Reason); exit $dependencyDecision.ExitCode }
 if ([string]::IsNullOrWhiteSpace($AgentName) -or $null -eq $RequiredArtifact -or $RequiredArtifact.Count -eq 0) {
-    Write-Error 'validate-required-artifact-output hook: AgentName and at least one RequiredArtifact spec are required.'
-    exit 1
-}
-
-$result = Invoke-RequiredArtifactOutputValidation `
-    -RawPayload $env:CLAUDE_HOOK_INPUT `
-    -AgentName $AgentName `
-    -RequiredArtifact $RequiredArtifact
-if (-not $result.Ok) {
-    Write-Error $result.Message
-    exit 1
+    $argumentEnvelope = Read-SubagentStopEnvelope
+    if ($argumentEnvelope.StopHookActive) { exit 0 }
+    [Console]::Error.WriteLine("validate-required-artifact-output hook: AgentName and at least one RequiredArtifact spec are required.`n$($script:SubagentStopReportAndHaltLine)")
+    exit 2
 }
-
+try { $result = Invoke-RequiredArtifactOutputValidation -AgentName $AgentName -RequiredArtifact $RequiredArtifact }
+catch { Exit-SubagentStopBlock -Message ('validate-required-artifact-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

package/resources/claude-customizations/.claude/hooks/validate-task-researcher-output.ps1

@@ -11,14 +11,22 @@
     convention, and the file exists on disk.
 
 .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 Test-ResearchFile so tests can mock the boundary without writing
-    temporary files.
+    Reads the SubagentStop envelope JSON from stdin through the shared
+    envelope helper (subagentstop-envelope.ps1) and validates its
+    last_assistant_message field, the researcher's last assistant message.
+    Exits 0 to allow termination. A block writes the reason to stderr and
+    exits 2 through the shared envelope helper; an invalid envelope blocks
+    with a payload anomaly reason. A hook dependency that fails to load
+    blocks with exit 2 and the validate-task-researcher-output: prefix.
+    Filesystem reads go through Test-ResearchFile 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 }
+try { . (Join-Path $PSScriptRoot 'subagentstop-envelope.ps1') } catch { Add-HookDependencyFailure -Name 'subagentstop-envelope.ps1' -ErrorRecord $_ }
 
 Set-StrictMode -Version Latest
 $ErrorActionPreference = 'Stop'
@@ -94,7 +102,7 @@ function Test-IsValidResearchFileName {
     $fileName = [System.IO.Path]::GetFileName($normalized)
     return [regex]::IsMatch(
         $fileName,
-        '^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-[A-Za-z0-9][A-Za-z0-9-]*-research\.md$'
+        '^(?:(?:\d{4}-\d{2}-\d{2}(?:T\d{2}-?\d{2})?|\d{8})-[A-Za-z0-9][A-Za-z0-9-]*[-.]research|research(?:-addendum)?\.\d{4}-\d{2}-\d{2}(?:T\d{2}-\d{2})?)\.md$'
     )
 }
 
@@ -192,7 +200,7 @@ function Test-NumericDerivationEvidence {
         if (-not $match.Success) { return @{ Ok = $false; Message = "task-researcher hook: numeric derivation evidence is missing $label." } }
         $values[$label] = $match.Groups['value'].Value.Trim()
     }
-    if ($values['Exhaustive Search Scope'] -notmatch '(?i)\b(entire|all|complete)\b.*\b(repository|repo|source tree|tree)\b') {
+    if ($values['Exhaustive Search Scope'] -notmatch '(?i)\b(entire|whole|all|complete)\b.*\b(repository|repo|worktree|source tree|tree)\b') {
         return @{ Ok = $false; Message = 'task-researcher hook: numeric derivation evidence does not declare an exhaustive repository search scope.' }
     }
     $primaryStrategy = $values['Primary Search Strategy or Query Expression']
@@ -227,29 +235,18 @@ function Invoke-TaskResearcherOutputValidation {
     [CmdletBinding()]
     [OutputType([hashtable])]
     param(
-        [string] $RawPayload
+        [AllowNull()] [AllowEmptyString()] [string] $InputText
     )
-
-    if ([string]::IsNullOrWhiteSpace($RawPayload)) {
-        return @{ Ok = $false; Message = 'task-researcher hook: CLAUDE_HOOK_INPUT is empty; cannot validate task-researcher output.' }
-    }
-
-    try {
-        $payload = $RawPayload | ConvertFrom-Json -ErrorAction Stop
-    }
-    catch {
-        return @{ Ok = $false; Message = "task-researcher hook: failed to parse CLAUDE_HOOK_INPUT as JSON: $($_.Exception.Message)" }
-    }
-
-    $agentOutput = $null
-    if ($payload.PSObject.Properties.Name -contains 'output') {
-        $agentOutput = $payload.output
-    }
-    if ([string]::IsNullOrWhiteSpace($agentOutput)) {
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'validate-task-researcher-output:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
+    $envelope = if ($PSBoundParameters.ContainsKey('InputText')) { Read-SubagentStopEnvelope -InputText $InputText } else { Read-SubagentStopEnvelope }
+    if (-not $envelope.IsValid) { return @{ Ok = $false; Message = "task-researcher hook: payload anomaly - $(Get-SubagentStopEnvelopeAnomalyReason -Anomaly $envelope.Anomaly)" } }
+    $assistantMessage = [string]$envelope.AssistantText
+    if ([string]::IsNullOrWhiteSpace($assistantMessage)) {
         return @{ Ok = $false; Message = 'task-researcher hook: agent output is empty; researcher must return research-path before termination.' }
     }
 
-    $researchPath = Get-ResearchPathFromOutput -AgentOutput $agentOutput
+    $researchPath = Get-ResearchPathFromOutput -AgentOutput $assistantMessage
     if ($null -eq $researchPath) {
         return @{ Ok = $false; Message = 'task-researcher hook: agent output does not advertise a research-path. Researcher must report `research-path: <path>` pointing to docs/features/<feature>/research/ (feature-associated) or docs/research/ (one-off).' }
     }
@@ -266,13 +263,14 @@ function Invoke-TaskResearcherOutputValidation {
         return @{ Ok = $false; Message = "task-researcher hook: researcher advertised research-path '$researchPath' but no file exists at that location." }
     }
 
-    $feasibilityResult = Test-AutomationFeasibilitySection -ResearchFilePath $researchPath -AgentOutput $agentOutput
+    $feasibilityResult = Test-AutomationFeasibilitySection -ResearchFilePath $researchPath -AgentOutput $assistantMessage
     if (-not $feasibilityResult.Ok) {
         return @{ Ok = $false; Message = $feasibilityResult.Message }
     }
 
     if (Test-Path -LiteralPath $researchPath -PathType Leaf) {
-        $numericEvidenceResult = Test-NumericDerivationEvidence -Content (Get-Content -LiteralPath $researchPath -Raw -ErrorAction Stop)
+        try { $researchContent = Get-Content -LiteralPath $researchPath -Raw -ErrorAction Stop } catch { return @{ Ok = $false; Message = "task-researcher hook: failed to read research-path '$researchPath': $($_.Exception.Message)" } }
+        $numericEvidenceResult = Test-NumericDerivationEvidence -Content $researchContent
         if (-not $numericEvidenceResult.Ok) {
             return $numericEvidenceResult
         }
@@ -284,11 +282,10 @@ function Invoke-TaskResearcherOutputValidation {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
-
-$result = Invoke-TaskResearcherOutputValidation -RawPayload $env:CLAUDE_HOOK_INPUT
-if (-not $result.Ok) {
-    Write-Error $result.Message
-    exit 1
-}
-
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('validate-task-researcher-output: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'validate-task-researcher-output:'
+if ($null -ne $dependencyDecision) { [Console]::Error.WriteLine($dependencyDecision.Reason); exit $dependencyDecision.ExitCode }
+try { $result = Invoke-TaskResearcherOutputValidation }
+catch { Exit-SubagentStopBlock -Message ('validate-task-researcher-output: validator error: ' + ([string]$_.Exception.Message -split "`r?`n")[0] + '; the gate fails closed.' + "`n" + 'This condition is not repairable by the subagent. Report it to the operator and halt.') }
+if (-not $result.Ok) { Exit-SubagentStopBlock -Message $result.Message }
 exit 0