@danmoisan/drm-copilot-mcp 1.1.18 → 1.1.20

package/resources/claude-customizations/.claude/hooks/subagentstop-envelope.ps1

@@ -0,0 +1,192 @@
+<#
+.SYNOPSIS
+    Shared SubagentStop envelope reader and exit-2 block helper (issue #897, epic subagentstop-envelope).
+
+.DESCRIPTION
+    Dot-sourced by the SubagentStop validators under .claude/hooks. It is not registered as a hook in
+    either settings.json copy. It imports nothing (no Import-Module, no using module, no dot-source),
+    reads no environment variable, and writes nothing to the success or warning streams; the only
+    stream it ever writes is standard error, from Exit-SubagentStopBlock.
+
+    The governing contract is the section "## Authoritative Helper Contract" of
+    docs/features/archive/subagentstop-envelope-core-897/spec.md (issue #897; at
+    docs/features/active/subagentstop-envelope-core-897/ until the archive move). Where this file
+    and any other document differ, that section governs.
+
+.NOTES
+    PowerShell 7.5 or later (ConvertFrom-Json -DateKind). Byte-identical bundled mirror at
+    extensions/drm-copilot/resources/claude-customizations/.claude/hooks/subagentstop-envelope.ps1.
+#>
+
+function Get-SubagentStopEnvelopeAnomalyReason {
+    <#
+    .SYNOPSIS
+        Returns the reason clause for one SubagentStop envelope anomaly code.
+    .DESCRIPTION
+        Consumers write '<PREFIX> payload anomaly - <clause>', where <PREFIX> is the validator's own
+        reason prefix. Any value that is not one of the six codes (including $null, an empty string, and
+        a case variant) is a consumer programming error and throws System.ArgumentException naming the
+        rejected value. No [ValidateSet()] is used, so the exception is an ArgumentException rather than a
+        parameter-binding exception.
+    .PARAMETER Anomaly
+        One of EmptyPayload, UnparseableJson, NonObjectEnvelope, MissingAssistantMessage,
+        NullAssistantMessage or NonStringAssistantMessage (case-sensitive).
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter()]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Anomaly
+    )
+
+    switch -CaseSensitive ($Anomaly) {
+        'EmptyPayload' { return 'the SubagentStop payload on stdin was empty' }
+        'UnparseableJson' { return 'the SubagentStop payload is not valid JSON' }
+        'NonObjectEnvelope' { return 'the SubagentStop payload root is not a JSON object' }
+        'MissingAssistantMessage' { return 'the SubagentStop payload has no last_assistant_message field' }
+        'NullAssistantMessage' { return 'the SubagentStop payload last_assistant_message is null' }
+        'NonStringAssistantMessage' { return 'the SubagentStop payload last_assistant_message is not a string' }
+        default { throw [System.ArgumentException]::new("Unknown SubagentStop envelope anomaly code: '$Anomaly'.", 'Anomaly') }
+    }
+}
+
+function Read-SubagentStopEnvelope {
+    <#
+    .SYNOPSIS
+        Reads and classifies a SubagentStop hook envelope from -InputText or from standard input.
+    .DESCRIPTION
+        When -InputText is bound (including an empty string or $null) the function parses that text and
+        does not read standard input. When -InputText is not bound the function reads standard input to
+        end; a manual run without redirected stdin therefore waits for end-of-input (Ctrl+Z then Enter on
+        Windows, Ctrl+D elsewhere). A read failure is treated as empty input. One leading BOM (U+FEFF) is
+        stripped before any other evaluation. The function never throws and never exits; every failure
+        maps to one of six anomaly codes, and the derived fields are read from any object root regardless
+        of validity.
+    .PARAMETER InputText
+        The raw envelope text. Omit the parameter to read standard input.
+    .OUTPUTS
+        Exactly one PSCustomObject with the properties IsValid, Anomaly, Envelope, AssistantText,
+        StopHookActive, AgentType and HookEventName, in that order.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter()]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $InputText
+    )
+
+    if ($PSBoundParameters.ContainsKey('InputText')) {
+        $text = $InputText
+    }
+    else {
+        try {
+            $text = [Console]::In.ReadToEnd()
+        }
+        catch {
+            $text = ''
+        }
+    }
+
+    if ($null -ne $text -and $text.Length -gt 0 -and $text[0] -eq [char]0xFEFF) {
+        $text = $text.Substring(1)
+    }
+
+    $isValid = $false
+    $anomaly = $null
+    $envelope = $null
+    $assistantText = ''
+    $stopHookActive = $false
+    $agentType = ''
+    $hookEventName = ''
+
+    if ([string]::IsNullOrWhiteSpace($text)) {
+        $anomaly = 'EmptyPayload'
+    }
+    else {
+        $parsed = $null
+        $parseFailed = $false
+        try {
+            $parsed = ConvertFrom-Json -InputObject $text -NoEnumerate -DateKind String -ErrorAction Stop
+        }
+        catch {
+            $parseFailed = $true
+        }
+
+        if ($parseFailed) {
+            $anomaly = 'UnparseableJson'
+        }
+        elseif (-not ($parsed -is [System.Management.Automation.PSCustomObject])) {
+            # The [pscustomobject] accelerator resolves to PSObject and would match non-objects; the full type name does not.
+            $anomaly = 'NonObjectEnvelope'
+        }
+        else {
+            $envelope = $parsed
+
+            $messageProperty = @($parsed.PSObject.Properties | Where-Object { $_.Name -ceq 'last_assistant_message' })
+            if ($messageProperty.Count -eq 0) {
+                $anomaly = 'MissingAssistantMessage'
+            }
+            elseif ($null -eq $messageProperty[0].Value) {
+                $anomaly = 'NullAssistantMessage'
+            }
+            elseif ($messageProperty[0].Value -is [string]) {
+                $isValid = $true
+                $assistantText = $messageProperty[0].Value
+            }
+            else {
+                $anomaly = 'NonStringAssistantMessage'
+            }
+
+            $stopHookProperty = @($parsed.PSObject.Properties | Where-Object { $_.Name -ceq 'stop_hook_active' })
+            if ($stopHookProperty.Count -gt 0 -and $stopHookProperty[0].Value -is [bool]) {
+                $stopHookActive = $stopHookProperty[0].Value
+            }
+
+            $agentTypeProperty = @($parsed.PSObject.Properties | Where-Object { $_.Name -ceq 'agent_type' })
+            if ($agentTypeProperty.Count -gt 0 -and $agentTypeProperty[0].Value -is [string]) {
+                $agentType = $agentTypeProperty[0].Value
+            }
+
+            $hookEventProperty = @($parsed.PSObject.Properties | Where-Object { $_.Name -ceq 'hook_event_name' })
+            if ($hookEventProperty.Count -gt 0 -and $hookEventProperty[0].Value -is [string]) {
+                $hookEventName = $hookEventProperty[0].Value
+            }
+        }
+    }
+
+    return [pscustomobject][ordered]@{
+        IsValid        = $isValid
+        Anomaly        = $anomaly
+        Envelope       = $envelope
+        AssistantText  = $assistantText
+        StopHookActive = $stopHookActive
+        AgentType      = $agentType
+        HookEventName  = $hookEventName
+    }
+}
+
+function Exit-SubagentStopBlock {
+    <#
+    .SYNOPSIS
+        Blocks a SubagentStop by writing the reason to standard error and exiting with code 2.
+    .DESCRIPTION
+        Exit code 2 is the only exit code that blocks a SubagentStop; the stderr text is delivered to the
+        subagent as its next instruction. A null or empty Message fails parameter binding before the
+        body runs, so no exit occurs in that case.
+    .PARAMETER Message
+        The block reason written to standard error.
+    #>
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
+        [string] $Message
+    )
+
+    [Console]::Error.WriteLine($Message)
+    exit 2
+}

package/resources/claude-customizations/.claude/hooks/validate-bash.ps1

@@ -37,13 +37,14 @@ param(
     [Parameter(Position = 0, Mandatory = $false)]
     [string]$CommandInput
 )
+$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 $_ }
 # Shared command-line parser (issue #545). Both detectors below run against the segment
 # list rather than against the unsegmented command string, so a dangerous phrase quoted
 # inside a message body is no longer a match and a relocating spelling no longer escapes.
-. (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 $_ }
 
 function Get-BlockedBashPattern {
     [CmdletBinding()]
@@ -417,6 +418,8 @@ function Invoke-ValidateBashDecision {
         [AllowNull()]
         [string] $PositionalInput
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'HOOK_DEPENDENCY_LOAD_FAILED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $commandToCheck = Get-BashCommandToCheck -ToolInputRaw $ToolInputRaw -PositionalInput $PositionalInput
 
@@ -431,6 +434,9 @@ function Invoke-ValidateBashDecision {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('HOOK_DEPENDENCY_LOAD_FAILED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'HOOK_DEPENDENCY_LOAD_FAILED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 $toolInputRaw = Read-ClaudeHookRawPayload
 

package/resources/claude-customizations/.claude/hooks/validate-discovery-artifact-gate.ps1

@@ -5,19 +5,24 @@
 
 .DESCRIPTION
     Invoked by the Claude Code SubagentStop hook under the existing broad
-    generic-agent matcher group. The hook reads $env:CLAUDE_HOOK_INPUT JSON
-    containing .output (the terminating subagent's final text), scans that
-    text for discovery-artifact path references via Get-DiscoveryArtifactType,
-    and for each recognized reference (when a required-artifact declaration is
-    present) invokes the discovery validator CLI via
-    Invoke-DiscoveryValidatorExe.
+    generic-agent matcher group. The hook reads the SubagentStop envelope JSON
+    from stdin through the shared envelope helper (subagentstop-envelope.ps1),
+    takes its last_assistant_message field (the terminating subagent's last
+    assistant message), scans that text for discovery-artifact path references
+    via Get-DiscoveryArtifactType, and for each recognized reference (when a
+    required-artifact declaration is present) invokes the discovery validator
+    via Invoke-DiscoveryValidatorExe.
 
     Any referenced artifact that fails validation blocks the subagent's
-    termination: the hook writes an error with a
-    DISCOVERY_ARTIFACT_GATE_BLOCKED: prefix and exits with a non-zero code.
-    When no reference fails validation, or when no discovery-artifact path is
-    referenced, or when the required-artifact declaration is absent
-    (fail-open), the hook allows termination.
+    termination: the hook writes the reason with a
+    DISCOVERY_ARTIFACT_GATE_BLOCKED: prefix to stderr and exits 2 through the
+    shared envelope helper. An invalid envelope (empty, not valid JSON, not a
+    JSON object, or without a string last_assistant_message) also blocks, with
+    a "DISCOVERY_ARTIFACT_GATE_BLOCKED: payload anomaly" reason. The hook
+    allows termination when the last assistant message is blank, when it
+    references no discovery-artifact path, when the required-artifact
+    declaration is absent (fail-open), or when every referenced artifact
+    passes validation.
 
     This hook provides the authoritative, defense-in-depth check of final
     workspace state, regardless of which tool produced the artifact,
@@ -32,9 +37,13 @@
     `Test-Json -SchemaFile` Draft 2020-12 support). Read-only validation gate that
     invokes NO external process: validation runs in-process through
     `.claude/lib/discovery-validation/DiscoveryValidation.psm1` (issue #475).
+    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 $_ }
+try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryValidation.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryValidation.psm1' -ErrorRecord $_ }
 
 function Invoke-DiscoveryValidatorExe {
     <#
@@ -179,7 +188,7 @@ function Find-DiscoveryArtifactReference {
     $foundReferences = New-Object System.Collections.Generic.List[string]
     foreach ($token in $tokens) {
         $trimmed = $token.Trim('`', '"', "'", ',', ';', '(', ')', '[', ']')
-        if (Get-DiscoveryArtifactType -Path $trimmed) {
+        if ($trimmed -and (Get-DiscoveryArtifactType -Path $trimmed)) {
             if (-not $foundReferences.Contains($trimmed)) {
                 $foundReferences.Add($trimmed)
             }
@@ -192,35 +201,24 @@ function Find-DiscoveryArtifactReference {
 function Invoke-DiscoveryArtifactGateValidation {
     <#
     .SYNOPSIS
-        Parses CLAUDE_HOOK_INPUT and returns an Ok/Message validation result
-        for a discovery-artifact completion gate.
+        Reads the SubagentStop envelope and returns an Ok/Message validation
+        result for a discovery-artifact completion gate.
     #>
     [CmdletBinding()]
     [OutputType([hashtable])]
     param(
-        [string] $RawPayload,
+        [AllowNull()] [AllowEmptyString()] [string] $InputText,
 
         [Parameter(Mandatory = $false)]
         [scriptblock] $RequiredArtifactReader = { Get-RequiredDiscoveryArtifactDeclaration }
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'DISCOVERY_ARTIFACT_GATE_BLOCKED:'
+    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 = "DISCOVERY_ARTIFACT_GATE_BLOCKED: payload anomaly - $(Get-SubagentStopEnvelopeAnomalyReason -Anomaly $envelope.Anomaly)" } }
+    $assistantMessage = [string]$envelope.AssistantText
 
-    if ([string]::IsNullOrWhiteSpace($RawPayload)) {
-        return @{ Ok = $false; Message = 'discovery artifact gate hook: CLAUDE_HOOK_INPUT is empty' }
-    }
-
-    try {
-        $payload = $RawPayload | ConvertFrom-Json -ErrorAction Stop
-    }
-    catch {
-        return @{ Ok = $false; Message = "discovery artifact gate hook: CLAUDE_HOOK_INPUT is not valid JSON: $_" }
-    }
-
-    $outputText = ''
-    if ($null -ne $payload -and ($payload.PSObject.Properties.Name -contains 'output')) {
-        $outputText = [string]$payload.output
-    }
-
-    $references = Find-DiscoveryArtifactReference -OutputText $outputText
+    $references = Find-DiscoveryArtifactReference -OutputText $assistantMessage
     if ($references.Count -eq 0) {
         return @{ Ok = $true; Message = $null }
     }
@@ -233,10 +231,10 @@ function Invoke-DiscoveryArtifactGateValidation {
 
     foreach ($reference in $references) {
         $artifactType = Get-DiscoveryArtifactType -Path $reference
-        $result = Invoke-DiscoveryValidatorExe -ValidatorArgs @($artifactType, $reference)
-        $hasErrorOutput = -not [string]::IsNullOrWhiteSpace($result.Output)
-        if ($result.ExitCode -ne 0 -or $hasErrorOutput) {
-            return @{ Ok = $false; Message = "DISCOVERY_ARTIFACT_GATE_BLOCKED: $($result.Output)" }
+        $validatorResult = Invoke-DiscoveryValidatorExe -ValidatorArgs @($artifactType, $reference)
+        $hasErrorOutput = -not [string]::IsNullOrWhiteSpace($validatorResult['Output'])
+        if ($validatorResult['ExitCode'] -ne 0 -or $hasErrorOutput) {
+            return @{ Ok = $false; Message = "DISCOVERY_ARTIFACT_GATE_BLOCKED: $($validatorResult['Output'])" }
         }
     }
 
@@ -247,11 +245,11 @@ function Invoke-DiscoveryArtifactGateValidation {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('DISCOVERY_ARTIFACT_GATE_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix 'DISCOVERY_ARTIFACT_GATE_BLOCKED:'
+if ($null -ne $dependencyDecision) { [Console]::Error.WriteLine($dependencyDecision.Reason); exit $dependencyDecision.ExitCode }
 
-$result = Invoke-DiscoveryArtifactGateValidation -RawPayload $env:CLAUDE_HOOK_INPUT
-if (-not $result.Ok) {
-    Write-Error $result.Message
-    exit 1
-}
-
+try { $result = Invoke-DiscoveryArtifactGateValidation }
+catch { Exit-SubagentStopBlock -Message ('DISCOVERY_ARTIFACT_GATE_BLOCKED: 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