@danmoisan/drm-copilot-mcp 1.1.18 → 1.1.20

package/resources/codex-and-agents-customizations/.codex/config.toml

@@ -2,7 +2,7 @@ default_permissions = ":danger-full-access"
 
 [mcp_servers.drm-copilot]
 command = "npx"
-args = ["-y", "@danmoisan/drm-copilot-mcp@1.1.18"]
+args = ["-y", "@danmoisan/drm-copilot-mcp@1.1.20"]
 required = true
 enabled_tools = [
     "collect_commit_context",

package/resources/codex-and-agents-customizations/.codex/hooks/check-powershell-test-purity.ps1

@@ -32,10 +32,11 @@
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 # Shared Codex PreToolUse transport: stdin payload parsing and tool_input-to-file
 # mapping for every tool name the ^(apply_patch|Edit|Write)$ matcher admits.
-. (Join-Path $PSScriptRoot 'codex-pretooluse-file-mapping.ps1')
+try { . (Join-Path $PSScriptRoot 'codex-pretooluse-file-mapping.ps1') } catch { Add-HookDependencyFailure -Name 'codex-pretooluse-file-mapping.ps1' -ErrorRecord $_ }
 
 function Get-PowerShellTestPurityBlockDecision {
     [CmdletBinding()]
@@ -72,6 +73,8 @@ function Invoke-PowerShellTestPurityDecision {
     param(
         [string] $ToolInputRaw
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'check-powershell-test-purity:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     if (-not $ToolInputRaw) {
         return $null
@@ -145,6 +148,9 @@ function Invoke-PowerShellTestPurityDecision {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('check-powershell-test-purity: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'check-powershell-test-purity:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 try {
     # Transport and mapping come from the shared module. A well-formed payload

package/resources/codex-and-agents-customizations/.codex/hooks/check-python-test-purity.ps1

@@ -29,10 +29,11 @@
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 # Shared Codex PreToolUse transport: stdin payload parsing and tool_input-to-file
 # mapping for every tool name the ^(apply_patch|Edit|Write)$ matcher admits.
-. (Join-Path $PSScriptRoot 'codex-pretooluse-file-mapping.ps1')
+try { . (Join-Path $PSScriptRoot 'codex-pretooluse-file-mapping.ps1') } catch { Add-HookDependencyFailure -Name 'codex-pretooluse-file-mapping.ps1' -ErrorRecord $_ }
 
 function Get-PythonTestPurityBlockDecision {
     [CmdletBinding()]
@@ -69,6 +70,8 @@ function Invoke-PythonTestPurityDecision {
     param(
         [string] $ToolInputRaw
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'check-python-test-purity:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     if (-not $ToolInputRaw) {
         return $null
@@ -145,6 +148,9 @@ function Invoke-PythonTestPurityDecision {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('check-python-test-purity: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'check-python-test-purity:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 try {
     # Transport and mapping come from the shared module. A well-formed payload

package/resources/codex-and-agents-customizations/.codex/hooks/codex-epic-child-launch-attestation.ps1

@@ -2,7 +2,7 @@
 
 $contractPath = Join-Path (Split-Path $PSScriptRoot -Parent) 'scripts/epic-child-launch-contract.ps1'
 if (Test-Path -LiteralPath $contractPath -PathType Leaf) {
-    . $contractPath
+    try { . $contractPath } catch { Add-HookDependencyFailure -Name 'epic-child-launch-contract.ps1' -ErrorRecord $_ }
 }
 
 $script:CodexEpicChildContexts = @('epic_preparation_child', 'epic_execution_child')

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-checkpoint-monotonic.ps1

@@ -43,10 +43,11 @@
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 # Shared Codex PreToolUse transport: stdin payload parsing and tool_input-to-file
 # mapping for every tool name the ^(apply_patch|Edit|Write)$ matcher admits.
-. (Join-Path $PSScriptRoot 'codex-pretooluse-file-mapping.ps1')
+try { . (Join-Path $PSScriptRoot 'codex-pretooluse-file-mapping.ps1') } catch { Add-HookDependencyFailure -Name 'codex-pretooluse-file-mapping.ps1' -ErrorRecord $_ }
 
 # The only path this hook governs. On-disk reconstruction of an apply_patch
 # Update is requested for this path alone, so a patch that merely happens to
@@ -214,6 +215,8 @@ function Invoke-CheckpointMonotonicDecision {
     param(
         [string] $ToolInputRaw
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'CHECKPOINT_ORDER_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     if (-not $ToolInputRaw) {
         return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
@@ -312,6 +315,9 @@ function Invoke-CheckpointMonotonicDecision {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('CHECKPOINT_ORDER_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'CHECKPOINT_ORDER_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 try {
     # Transport and mapping come from the shared module. Update reconstruction is

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-codex-model-routing.ps1

@@ -4,9 +4,10 @@
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
-. (Join-Path $PSScriptRoot 'codex-authority-store.ps1')
-. (Join-Path $PSScriptRoot 'codex-agent-profile-attestation.ps1')
+try { . (Join-Path $PSScriptRoot 'codex-authority-store.ps1') } catch { Add-HookDependencyFailure -Name 'codex-authority-store.ps1' -ErrorRecord $_ }
+try { . (Join-Path $PSScriptRoot 'codex-agent-profile-attestation.ps1') } catch { Add-HookDependencyFailure -Name 'codex-agent-profile-attestation.ps1' -ErrorRecord $_ }
 
 $script:CodexModelGateRepositoryRoot = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
 
@@ -91,6 +92,8 @@ function Invoke-CodexModelRoutingDecision {
         [Parameter(Mandatory)][string] $PayloadRaw,
         [AllowNull()][AllowEmptyString()][string] $AttestationRaw
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'MODEL_ROUTING_ATTESTATION_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $payload = ConvertFrom-CodexModelGateJson -Raw $PayloadRaw -Name 'PreToolUse input'
     if ([string]::IsNullOrWhiteSpace($AttestationRaw)) {
@@ -150,6 +153,9 @@ function Get-CodexModelGateDenyDecision {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('MODEL_ROUTING_ATTESTATION_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'MODEL_ROUTING_ATTESTATION_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 try {
     $payloadRaw = [Console]::In.ReadToEnd()

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-completion-consistency.ps1

@@ -29,32 +29,37 @@
     completion is not asserted, the write is allowed via
     hookSpecificOutput.permissionDecision='allow' (backward compatibility).
 
-    Edit tool calls supply only old_string/new_string (a partial patch) and
-    cannot be reliably validated without the full target file content, so they
-    are allowed by this hook, matching enforce-checkpoint-monotonic.ps1. For
-    Write calls whose content is not valid JSON, the hook allows the operation
-    and defers to downstream tools to surface the error.
+    Edit tool calls supply only old_string/new_string (a partial patch). An Edit
+    call is validated by reading the checkpoint at the Edit's targeted file_path
+    through the injectable CheckpointReader seam and applying the old_string ->
+    new_string replacement in memory; the resulting content is then evaluated
+    like a Write. One occurrence of old_string is replaced unless replace_all is
+    true. The hook fails closed: a missing, empty, or unreadable targeted
+    checkpoint, an absent or empty old_string, zero or ambiguous occurrences of
+    old_string, and a Write with empty content all deny, and the deny reason
+    names the cause. Write content or patched content that is not valid JSON is
+    also denied, because the canonical checkpoint is required to stay valid JSON.
 
 .NOTES
     Compatible with PowerShell 7+. Read-only validation gate.
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 # Reuse the adjacent hook's shared checkpoint policy logic. This dot-source is by
 # design, not a copy-paste defect, so the hook is not renamed.
-. (Join-Path $PSScriptRoot 'enforce-checkpoint-monotonic.ps1')
+try { . (Join-Path $PSScriptRoot 'enforce-checkpoint-monotonic.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-checkpoint-monotonic.ps1' -ErrorRecord $_ }
 
 # Shared Codex PreToolUse transport. Dot-sourced explicitly rather than relying on
 # the transitive load above, so this hook's transport does not depend on its
 # neighbour's internals. Every transport error it raises names this hook, because
 # the shared parser is called with -HookName 'enforce-completion-consistency'.
-. (Join-Path $PSScriptRoot 'codex-pretooluse-file-mapping.ps1')
+try { . (Join-Path $PSScriptRoot 'codex-pretooluse-file-mapping.ps1') } catch { Add-HookDependencyFailure -Name 'codex-pretooluse-file-mapping.ps1' -ErrorRecord $_ }
 
 # Dot-source the shared validation helpers. Guarded so a missing file produces a
 # clear error and so dot-sourcing this hook in tests loads the helpers too.
-$script:CompletionHelpersPath = Join-Path $PSScriptRoot 'enforce-completion-helpers.ps1'
-. $script:CompletionHelpersPath
+try { . (Join-Path $PSScriptRoot 'enforce-completion-helpers.ps1') } catch { Add-HookDependencyFailure -Name 'enforce-completion-helpers.ps1' -ErrorRecord $_ }
 
 function ConvertFrom-CheckpointJson {
     <#
@@ -76,9 +81,10 @@ function Get-CheckpointFileContent {
         Reads the on-disk checkpoint content for the read-then-validate Edit path.
     .DESCRIPTION
         Returns the full file text when the path resolves to a file on disk, or
-        $null when the file does not exist. Tests inject a CheckpointReader
-        scriptblock instead of mocking this function so no temporary files are
-        required.
+        $null when the file does not exist. An existing empty file yields an
+        empty string, never $null, so a missing checkpoint and an empty
+        checkpoint stay distinct. Tests inject a CheckpointReader scriptblock
+        instead of mocking this function so no temporary files are required.
     #>
     [CmdletBinding()]
     [OutputType([string])]
@@ -90,7 +96,9 @@ function Get-CheckpointFileContent {
     if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
         return $null
     }
-    return Get-Content -LiteralPath $Path -Raw -ErrorAction Stop
+    $text = Get-Content -LiteralPath $Path -Raw -ErrorAction Stop
+    if ($null -eq $text) { return '' }
+    return [string]$text
 }
 
 function Test-IsCheckpointPath {
@@ -270,26 +278,34 @@ function Get-MissingCompletionEvidence {
 function Resolve-EditedCheckpointContent {
     <#
     .SYNOPSIS
-        Returns the patched checkpoint content for an Edit-tool call, or $null
-        when the patch cannot be applied against the on-disk checkpoint.
+        Returns an object with Content and Failure for an Edit-tool call: the
+        patched checkpoint content on success, or a failure cause when the patch
+        cannot be applied against the targeted checkpoint.
     .DESCRIPTION
-        Implements the read-then-validate Edit path. When the tool input carries
-        an old_string (an Edit patch), the on-disk checkpoint is read through the
-        injectable CheckpointReader seam and the old_string -> new_string
-        replacement is applied in memory (no on-disk mutation). Returns $null
-        when there is no old_string, the on-disk file does not exist, or the
-        old_string is not present in the on-disk content, signalling the caller
-        to allow (defer).
+        Implements the read-then-validate Edit path. The checkpoint at the
+        caller-supplied CheckpointPath (the Edit's targeted file_path, passed to
+        the reader unchanged) is read through the injectable CheckpointReader seam
+        and the old_string -> new_string replacement is applied in memory (no
+        on-disk mutation). One occurrence of old_string is replaced unless
+        replace_all is true. Failure is one of no-old_string (absent or empty
+        old_string), checkpoint-unreadable (the reader threw), checkpoint-missing
+        (the reader returned $null), checkpoint-empty (the reader returned an
+        empty string), old_string-not-found, or old_string-ambiguous. Content is
+        $null on failure and Failure is $null on success. The caller denies on
+        any Failure.
     #>
     [CmdletBinding()]
-    [OutputType([string])]
+    [OutputType([pscustomobject])]
     param(
         [Parameter(Mandatory)]
         [AllowNull()]
         $ToolInput,
 
         [Parameter(Mandatory)]
-        [scriptblock] $CheckpointReader
+        [scriptblock] $CheckpointReader,
+
+        [Parameter(Mandatory)]
+        [string] $CheckpointPath
     )
 
     $oldString = $null
@@ -297,7 +313,7 @@ function Resolve-EditedCheckpointContent {
         $oldString = [string]$ToolInput.old_string
     }
     if ([string]::IsNullOrEmpty($oldString)) {
-        return $null
+        return [pscustomobject]@{ Content = $null; Failure = 'no-old_string' }
     }
 
     $newString = ''
@@ -305,20 +321,46 @@ function Resolve-EditedCheckpointContent {
         $newString = [string]$ToolInput.new_string
     }
 
-    $onDisk = & $CheckpointReader 'artifacts/orchestration/orchestrator-state.json'
-    if ([string]::IsNullOrEmpty([string]$onDisk)) {
-        # The on-disk checkpoint does not exist (or is empty); cannot patch.
-        return $null
+    try {
+        $onDisk = & $CheckpointReader $CheckpointPath
+    }
+    catch {
+        # A reader exception must not escape the gate; report it as a failure cause.
+        return [pscustomobject]@{ Content = $null; Failure = 'checkpoint-unreadable' }
+    }
+    if ($null -eq $onDisk) {
+        return [pscustomobject]@{ Content = $null; Failure = 'checkpoint-missing' }
     }
 
     $onDiskText = [string]$onDisk
-    if (-not $onDiskText.Contains($oldString)) {
-        # The old_string is not present, so the patch does not apply here.
-        return $null
+    if ($onDiskText.Length -eq 0) {
+        return [pscustomobject]@{ Content = $null; Failure = 'checkpoint-empty' }
     }
 
-    # Apply the patch in memory using a literal (non-regex) replacement.
-    return $onDiskText.Replace($oldString, $newString)
+    # Apply the patch in memory; one occurrence unless replace_all is true.
+    $replaceAll = Get-EditReplaceAllFlag -ToolInput $ToolInput
+    return Invoke-SingleOccurrenceEdit -Text $onDiskText -OldString $oldString -NewString $newString -ReplaceAll $replaceAll
+}
+
+function ConvertTo-CompletionDenyDecision {
+    <#
+    .SYNOPSIS
+        Builds the PreToolUse deny decision for the given reason.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Reason
+    )
+
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = $Reason
+        }
+    }
 }
 
 function Invoke-CompletionConsistencyDecision {
@@ -341,6 +383,8 @@ function Invoke-CompletionConsistencyDecision {
         [Parameter(Mandatory = $false)]
         [scriptblock] $RoutingMatrixReader
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'COMPLETION_CONSISTENCY_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     if (-not $ToolInputRaw) {
         return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
@@ -363,19 +407,25 @@ function Invoke-CompletionConsistencyDecision {
         return [ordered]@{ hookSpecificOutput = [ordered]@{ hookEventName = 'PreToolUse'; permissionDecision = 'allow' } }
     }
 
-    # Write tool: validate the content payload directly. Edit tool: no content is
-    # supplied, so read the on-disk checkpoint through the injectable seam and
-    # apply the old_string -> new_string patch in memory (read-then-validate).
-    $content = $toolInput.content
-    if (-not $content) {
-        $content = Resolve-EditedCheckpointContent -ToolInput $toolInput -CheckpointReader $CheckpointReader
+    # Write tool: a present content property is validated directly, and empty
+    # content is denied. Edit tool: no content property is supplied, so read the
+    # targeted checkpoint through the injectable seam and apply the old_string ->
+    # new_string patch in memory (read-then-validate). Any failure cause denies.
+    $cause = $null
+    if ($toolInput.PSObject.Properties.Name -contains 'content') {
+        $content = $toolInput.content
         if (-not $content) {
-            return [ordered]@{ hookSpecificOutput = [ordered]@{
-                    hookEventName = 'PreToolUse'; permissionDecision = 'deny'
-                    permissionDecisionReason = 'COMPLETION_CONSISTENCY_BLOCKED: the canonical checkpoint cannot be deleted, emptied, or replaced through an unresolved patch.'
-                } }
+            $cause = 'write-content-empty'
         }
     }
+    else {
+        $edit = Resolve-EditedCheckpointContent -ToolInput $toolInput -CheckpointReader $CheckpointReader -CheckpointPath $filePath
+        $content = $edit.Content
+        $cause = $edit.Failure
+    }
+    if ($cause) {
+        return ConvertTo-CompletionDenyDecision -Reason "COMPLETION_CONSISTENCY_BLOCKED: the canonical checkpoint cannot be deleted, emptied, or replaced through an unresolved patch ($cause)."
+    }
 
     try {
         $payload = ConvertFrom-CheckpointJson -Json $content
@@ -414,6 +464,9 @@ function Invoke-CompletionConsistencyDecision {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('COMPLETION_CONSISTENCY_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'COMPLETION_CONSISTENCY_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 try {
     # -HookName makes every transport error name this hook rather than the

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-completion-helpers.ps1

@@ -11,6 +11,12 @@
       - Test-IsValidFeatureFolder: rejects sentinel/placeholder feature folders
         and folders not anchored under docs/features/active/<segment>; optionally
         verifies on-disk existence through an injectable scriptblock seam.
+      - Get-EditReplaceAllFlag: returns the boolean value of the replace_all
+        property of an Edit tool input; the string 'true' is honoured and the
+        string 'false' is not.
+      - Invoke-SingleOccurrenceEdit: pure single-occurrence patch of a text;
+        reports a failure cause instead of replacing when old_string is empty,
+        absent, or ambiguous.
 
     This script is dot-sourced by enforce-completion-consistency.ps1. It contains
     no entrypoint logic, so dot-sourcing it in tests has no side effects.
@@ -161,3 +167,102 @@ function Test-RouteRequiresPrGate {
     }
     return ([bool]$route.requires_pr_gate -eq $true)
 }
+
+function Get-EditReplaceAllFlag {
+    <#
+    .SYNOPSIS
+        Returns the boolean value of the replace_all property of an Edit tool input.
+    .DESCRIPTION
+        Returns $false when the tool input is null or has no replace_all property.
+        Returns the value when it is already a boolean. Returns $true for a string
+        whose trimmed, case-insensitive value is 'true'. Returns $false for every
+        other value. No [bool] cast is used because [bool]'false' is $true in
+        PowerShell.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        $ToolInput
+    )
+
+    if ($null -eq $ToolInput -or -not ($ToolInput.PSObject.Properties.Name -contains 'replace_all')) {
+        return $false
+    }
+
+    $value = $ToolInput.replace_all
+    if ($value -is [bool]) {
+        return $value
+    }
+    if ($value -is [string]) {
+        return $value.Trim() -ieq 'true'
+    }
+    return $false
+}
+
+function Invoke-SingleOccurrenceEdit {
+    <#
+    .SYNOPSIS
+        Applies an old_string to new_string patch to a text in memory and reports
+        a failure cause when the patch cannot be applied unambiguously.
+    .DESCRIPTION
+        Pure function with no I/O. Normalizes CRLF to LF in all three strings. An
+        empty OldString yields Failure 'no-old_string'. Zero ordinal occurrences
+        yield Failure 'old_string-not-found'. When ReplaceAll is true every
+        occurrence is replaced by ordinal String.Replace. Otherwise a second
+        ordinal search that starts after the end of the first match yields Failure
+        'old_string-ambiguous' when it finds a match (overlapping candidates are
+        counted once), and no match yields a single splice by Substring. No regular
+        expression is used, so a '$' in NewString stays literal. Returns an object
+        with Content and Failure; Content is $null on failure and Failure is $null
+        on success.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $Text,
+
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $OldString,
+
+        [Parameter(Mandatory)]
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $NewString,
+
+        [Parameter(Mandatory = $false)]
+        [bool] $ReplaceAll = $false
+    )
+
+    $normalizedText = $Text.Replace("`r`n", "`n")
+    $normalizedOld = $OldString.Replace("`r`n", "`n")
+    $normalizedNew = $NewString.Replace("`r`n", "`n")
+
+    if ($normalizedOld.Length -eq 0) {
+        return [pscustomobject]@{ Content = $null; Failure = 'no-old_string' }
+    }
+
+    $comparison = [System.StringComparison]::Ordinal
+    $firstIndex = $normalizedText.IndexOf($normalizedOld, $comparison)
+    if ($firstIndex -lt 0) {
+        return [pscustomobject]@{ Content = $null; Failure = 'old_string-not-found' }
+    }
+
+    if ($ReplaceAll) {
+        return [pscustomobject]@{ Content = $normalizedText.Replace($normalizedOld, $normalizedNew); Failure = $null }
+    }
+
+    $afterFirst = $firstIndex + $normalizedOld.Length
+    if ($normalizedText.IndexOf($normalizedOld, $afterFirst, $comparison) -ge 0) {
+        return [pscustomobject]@{ Content = $null; Failure = 'old_string-ambiguous' }
+    }
+
+    $spliced = $normalizedText.Substring(0, $firstIndex) + $normalizedNew + $normalizedText.Substring($afterFirst)
+    return [pscustomobject]@{ Content = $spliced; Failure = $null }
+}

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-epic-child-worktree-binding.ps1

@@ -10,10 +10,11 @@
 #>
 [CmdletBinding()]
 param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
 
 $contractPath = Join-Path (Split-Path $PSScriptRoot -Parent) 'scripts/epic-child-launch-contract.ps1'
 if (Test-Path -LiteralPath $contractPath -PathType Leaf) {
-    . $contractPath
+    try { . $contractPath } catch { Add-HookDependencyFailure -Name 'epic-child-launch-contract.ps1' -ErrorRecord $_ }
 }
 
 function ConvertFrom-CodexChildGuardJson {
@@ -218,6 +219,8 @@ function Invoke-CodexEpicChildGuardDecision {
         [Parameter(Mandatory)][AllowEmptyString()][string] $ActualSpecSha256,
         [Parameter(Mandatory)][AllowEmptyString()][string] $ActualProfileSha256
     )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'EPIC_WORKTREE_BINDING_BLOCKED:'
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
 
     $payload = ConvertFrom-CodexChildGuardJson -Raw $PayloadRaw -Name 'PreToolUse input'
     if ([string]::IsNullOrWhiteSpace([string]$Attestation.launch_id)) {
@@ -282,6 +285,9 @@ function Get-CodexChildGuardLiveBranch {
 if ($MyInvocation.InvocationName -eq '.') {
     return
 }
+if ($script:HookDependencyGuardLoadFailed) { [Console]::Error.WriteLine('EPIC_WORKTREE_BINDING_BLOCKED: hook-dependency-guard.ps1 failed to load; the gate fails closed.'); exit 2 }
+$dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix 'EPIC_WORKTREE_BINDING_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
 
 try {
     $payloadRaw = [Console]::In.ReadToEnd()