@danmoisan/drm-copilot-mcp 1.1.22 → 1.1.24

package/resources/codex-and-agents-customizations/.codex/hooks/hook-target-worktree.ps1

@@ -0,0 +1,369 @@
+<#
+.SYNOPSIS
+    Codex twin of the HookTargetWorktree target-worktree resolver functions (issue #1009).
+
+.DESCRIPTION
+    Source: .claude/lib/worktree-resolution/HookTargetWorktree.psm1. This file carries the
+    six functions of that module with byte-identical function text, because Codex hooks
+    cannot import .claude/lib in a consumer repository: a consumer receives the .codex
+    runtime without the Claude library. tests/scripts/codex-hooks/hook-target-worktree.Tests.ps1
+    holds the function names and each function's text equal to the module and runs the
+    shared resolver behavior rows against this file.
+
+    Functions-only: the file has no entry point and no statement outside the function
+    definitions. It is dot-sourced by .codex/hooks/enforce-python-batch-budget.ps1 and
+    .codex/hooks/enforce-powershell-batch-budget.ps1. Edit the module first, then copy the
+    changed function text here.
+
+.NOTES
+    Compatible with PowerShell 7+. Mirrored byte-identically under
+    extensions/drm-copilot/resources/codex-and-agents-customizations/.
+#>
+
+function ConvertTo-HookTargetWorktreeNormalizedPath {
+    <#
+    .SYNOPSIS
+        Normalize a path to forward slashes with repeated and trailing slashes removed.
+    .DESCRIPTION
+        Backslashes become forward slashes, runs of slashes collapse to one, and a trailing
+        slash is trimmed except from a bare root ('/' or a drive root such as 'C:/'). Blank
+        input returns an empty string. Case is preserved; callers compare with
+        OrdinalIgnoreCase.
+    .PARAMETER Path
+        The path to normalize.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [AllowNull()] [AllowEmptyString()] [string] $Path
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Path)) { return '' }
+    $normalized = ($Path.Trim() -replace '\\', '/') -replace '/{2,}', '/'
+    if ($normalized.Length -gt 1 -and $normalized.EndsWith('/') -and $normalized -notmatch '^[A-Za-z]:/$') {
+        $normalized = $normalized.Substring(0, $normalized.Length - 1)
+    }
+    return $normalized
+}
+
+function Get-HookTargetWorktreeRelativePath {
+    <#
+    .SYNOPSIS
+        Return a path relative to a worktree root, or $null when it lies outside the root.
+    .DESCRIPTION
+        Both values are normalized first. A path equal to the root returns an empty string;
+        a path under the root returns its forward-slash remainder; any other path, or a
+        blank value, returns $null.
+    .PARAMETER Path
+        The path to express relative to the root.
+    .PARAMETER WorktreeRoot
+        The worktree root.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [AllowNull()] [AllowEmptyString()] [string] $Path,
+        [AllowNull()] [AllowEmptyString()] [string] $WorktreeRoot
+    )
+
+    $normalizedPath = ConvertTo-HookTargetWorktreeNormalizedPath -Path $Path
+    $normalizedRoot = ConvertTo-HookTargetWorktreeNormalizedPath -Path $WorktreeRoot
+    if ([string]::IsNullOrEmpty($normalizedPath) -or [string]::IsNullOrEmpty($normalizedRoot)) { return $null }
+    if ([string]::Equals($normalizedPath, $normalizedRoot, [System.StringComparison]::OrdinalIgnoreCase)) { return '' }
+    $prefix = if ($normalizedRoot.EndsWith('/')) { $normalizedRoot } else { $normalizedRoot + '/' }
+    if ($normalizedPath.StartsWith($prefix, [System.StringComparison]::OrdinalIgnoreCase)) {
+        return $normalizedPath.Substring($prefix.Length)
+    }
+    return $null
+}
+
+function Get-HookTargetWorktreeEnclosingRoot {
+    <#
+    .SYNOPSIS
+        Return the nearest root that encloses a path, or $null when none does.
+    .DESCRIPTION
+        A root encloses a path when the normalized path equals the normalized root or
+        starts with the root followed by a slash. When several roots enclose the path, the
+        longest one wins, so a worktree nested inside another wins for paths under it.
+    .PARAMETER Path
+        The path to place.
+    .PARAMETER Roots
+        The candidate worktree roots.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [AllowNull()] [AllowEmptyString()] [string] $Path,
+        [AllowNull()] [AllowEmptyCollection()] [string[]] $Roots
+    )
+
+    $best = $null
+    foreach ($root in @($Roots)) {
+        $normalizedRoot = ConvertTo-HookTargetWorktreeNormalizedPath -Path $root
+        if ([string]::IsNullOrEmpty($normalizedRoot)) { continue }
+        $relative = Get-HookTargetWorktreeRelativePath -Path $Path -WorktreeRoot $normalizedRoot
+        if ($null -ne $relative -and ($null -eq $best -or $normalizedRoot.Length -gt $best.Length)) { $best = $normalizedRoot }
+    }
+    return $best
+}
+
+function Get-HookTargetWorktreeKey {
+    <#
+    .SYNOPSIS
+        Return the stable key '<sanitized leaf>-<8 hex>' that names a worktree root.
+    .DESCRIPTION
+        The hex part is the first four bytes of the SHA-256 of the normalized root with no
+        trailing slash, and the leaf is reduced to file-name-safe characters. The algorithm
+        equals the worktree-derived batch-budget session id, which prefixes 'worktree-'.
+    .PARAMETER WorktreeRoot
+        The worktree root to key.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)] [string] $WorktreeRoot
+    )
+
+    $normalizedRoot = (ConvertTo-HookTargetWorktreeNormalizedPath -Path $WorktreeRoot).TrimEnd('/')
+    $leaf = $normalizedRoot.Substring($normalizedRoot.LastIndexOf('/') + 1) -replace '[^A-Za-z0-9._-]', '_'
+    $hashBytes = [System.Security.Cryptography.SHA256]::HashData([System.Text.Encoding]::UTF8.GetBytes($normalizedRoot))
+    $shortHash = -join (@($hashBytes[0..3]) | ForEach-Object { $_.ToString('x2') })
+    return "$leaf-$shortHash"
+}
+
+function ConvertFrom-HookTargetWorktreePorcelain {
+    <#
+    .SYNOPSIS
+        Parse `git worktree list --porcelain` text into worktree records.
+    .DESCRIPTION
+        Emits one record per non-bare stanza with Root (normalized), Branch (the short
+        branch name, or $null when detached), Bare, and Prunable. A bare stanza is skipped.
+        Blank lines separate stanzas, and CRLF line endings are tolerated.
+    .PARAMETER Text
+        The porcelain text.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [AllowNull()] [AllowEmptyString()] [string] $Text
+    )
+
+    $records = [System.Collections.Generic.List[object]]::new()
+    $stanza = $null
+    foreach ($rawLine in @(([string] $Text -split "`r?`n") + '')) {
+        $line = $rawLine.Trim()
+        if ($line -eq '' -or $line.StartsWith('worktree ')) {
+            if ($null -ne $stanza -and -not $stanza.Bare) {
+                $records.Add([pscustomobject]@{ Root = $stanza.Root; Branch = $stanza.Branch; Bare = $false; Prunable = $stanza.Prunable })
+            }
+            $stanza = $null
+            if ($line -ne '') {
+                $stanza = @{ Root = (ConvertTo-HookTargetWorktreeNormalizedPath -Path $line.Substring(9)); Branch = $null; Bare = $false; Prunable = $false }
+            }
+            continue
+        }
+        if ($null -eq $stanza) { continue }
+        if ($line -eq 'bare') {
+            $stanza.Bare = $true
+        } elseif ($line.StartsWith('branch ')) {
+            $reference = $line.Substring(7).Trim()
+            $stanza.Branch = if ($reference.StartsWith('refs/heads/')) { $reference.Substring(11) } else { $reference }
+        } elseif ($line -eq 'detached') {
+            $stanza.Branch = $null
+        } elseif ($line -eq 'prunable' -or $line.StartsWith('prunable ')) {
+            $stanza.Prunable = $true
+        }
+    }
+    return $records.ToArray()
+}
+
+function Resolve-HookTargetWorktree {
+    <#
+    .SYNOPSIS
+        Resolve the registered worktree that a hook call acts on.
+    .DESCRIPTION
+        The first present source decides, in the order FilePath, CommandOperand (paths
+        and/or branch), DelegationIdentity, SessionRoot; a later source is never consulted.
+        Relative paths map to the session root without enumerating worktrees. An absolute
+        path maps to its nearest enclosing registered worktree, and a path inside none, or
+        an invoker that throws or returns no worktree, falls back to the session root.
+        Disagreeing components yield TARGET_WORKTREE_AMBIGUOUS; a present branch or
+        identity that names no worktree yields TARGET_WORKTREE_NOT_DERIVABLE and never the
+        session root. The result carries WorktreeRoot, Source, Ambiguous, ReasonCode,
+        Detail, and Candidates. The invoker runs at most once.
+    .PARAMETER SessionRoot
+        The absolute session root (the hook's root); the fallback root.
+    .PARAMETER FilePath
+        File-tool target paths.
+    .PARAMETER CommandOperandPath
+        Command operand paths parsed by the caller.
+    .PARAMETER CommandBranch
+        A command branch operand parsed by the caller.
+    .PARAMETER DelegationPrompt
+        Agent delegation prompt text; its 'branch:' label and canonical issue line are read.
+    .PARAMETER CheckpointIssueReader
+        Optional { param($WorktreeRoot) <issue number or $null> } used only for an issue identity.
+    .PARAMETER WorktreeListInvoker
+        { param($SessionRoot) <porcelain text> }; the default runs git worktree list --porcelain.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory)] [string] $SessionRoot,
+        [AllowNull()] [AllowEmptyCollection()] [string[]] $FilePath,
+        [AllowNull()] [AllowEmptyCollection()] [string[]] $CommandOperandPath,
+        [AllowNull()] [AllowEmptyString()] [string] $CommandBranch,
+        [AllowNull()] [AllowEmptyString()] [string] $DelegationPrompt,
+        [scriptblock] $CheckpointIssueReader,
+        [scriptblock] $WorktreeListInvoker = { param($SessionRoot) $porcelain = & git -C $SessionRoot worktree list --porcelain 2>$null; if ($LASTEXITCODE -ne 0) { return '' }; return ($porcelain -join "`n") }
+    )
+
+    $ambiguousCode = 'TARGET_WORKTREE_AMBIGUOUS'
+    $notDerivableCode = 'TARGET_WORKTREE_NOT_DERIVABLE'
+    $ignoreCase = [System.StringComparison]::OrdinalIgnoreCase
+    $absolutePattern = '^(/|[A-Za-z]:/)'
+    $session = ConvertTo-HookTargetWorktreeNormalizedPath -Path $SessionRoot
+
+    # Nested helpers are called by constant name and read this function's variables.
+    function Get-HookTargetResult {
+        param($Root, [string] $Source, $Code, [string] $Detail = '', [string[]] $Candidates = @())
+        [pscustomobject]@{
+            WorktreeRoot = $Root
+            Source       = $Source
+            Ambiguous    = ($Code -eq $ambiguousCode)
+            ReasonCode   = $Code
+            Detail       = $Detail
+            Candidates   = [string[]] @($Candidates)
+        }
+    }
+    function Add-HookTargetDistinctValue {
+        param([System.Collections.Generic.List[string]] $List, [string] $Value)
+        foreach ($existing in $List) { if ([string]::Equals($existing, $Value, $ignoreCase)) { return } }
+        $List.Add($Value)
+    }
+    function Get-HookTargetRecordedIssue {
+        param([string] $Root)
+        try { $value = ([string] (& $CheckpointIssueReader $Root)).Trim().TrimStart('#') } catch { return $null }
+        if ($value -notmatch '^\d+$') { return $null }
+        $digits = $value.TrimStart('0')
+        return $(if ($digits -eq '') { '0' } else { $digits })
+    }
+    function Resolve-HookTargetPathSource {
+        param([string[]] $Paths, [string] $Source)
+        $resolved = [System.Collections.Generic.List[string]]::new()
+        $details = [System.Collections.Generic.List[string]]::new()
+        $fellBack = $false
+        foreach ($candidate in $Paths) {
+            $normalized = ConvertTo-HookTargetWorktreeNormalizedPath -Path $candidate
+            $root = $session
+            if ($normalized -notmatch $absolutePattern) {
+                $fellBack = $true
+                $details.Add("relative path '$normalized' maps to the session root")
+            } else {
+                $enclosing = Get-HookTargetWorktreeEnclosingRoot -Path $normalized -Roots $roots
+                if ($null -eq $enclosing) {
+                    $fellBack = $true
+                    $details.Add($(if ($listDetail) { $listDetail } else { "path '$normalized' is inside no registered worktree" }))
+                } else {
+                    $root = $enclosing
+                }
+            }
+            Add-HookTargetDistinctValue -List $resolved -Value $root
+        }
+        if ($resolved.Count -gt 1) {
+            return (Get-HookTargetResult -Root $null -Source $Source -Code $ambiguousCode -Detail ('the paths resolve to {0} different worktrees' -f $resolved.Count) -Candidates $resolved.ToArray())
+        }
+        $decidedBy = if ($fellBack) { 'SessionRoot' } else { $Source }
+        return (Get-HookTargetResult -Root $resolved[0] -Source $decidedBy -Code $null -Detail ($details -join '; '))
+    }
+    function Resolve-HookTargetBranchSource {
+        param([string] $Branch, [string] $Source)
+        $matched = @($records | Where-Object { $null -ne $_.Branch -and [string]::Equals($_.Branch, $Branch, $ignoreCase) } | ForEach-Object { $_.Root })
+        if ($matched.Count -eq 0) { return (Get-HookTargetResult -Root $null -Source $Source -Code $notDerivableCode -Detail "branch '$Branch' is checked out in no registered worktree") }
+        if ($matched.Count -gt 1) { return (Get-HookTargetResult -Root $null -Source $Source -Code $ambiguousCode -Detail "branch '$Branch' is checked out in $($matched.Count) registered worktrees" -Candidates $matched) }
+        return (Get-HookTargetResult -Root $matched[0] -Source $Source -Code $null)
+    }
+
+    # Select the deciding source: the first present one in precedence order.
+    $filePaths = @($FilePath | Where-Object { -not [string]::IsNullOrWhiteSpace($_) })
+    $operandPaths = @($CommandOperandPath | Where-Object { -not [string]::IsNullOrWhiteSpace($_) })
+    $branchOperand = if ([string]::IsNullOrWhiteSpace($CommandBranch)) { '' } else { $CommandBranch.Trim() }
+    $branches = [System.Collections.Generic.List[string]]::new()
+    $issues = [System.Collections.Generic.List[string]]::new()
+    if ($filePaths.Count -gt 0) {
+        $source = 'FilePath'
+    } elseif ($operandPaths.Count -gt 0 -or $branchOperand) {
+        $source = 'CommandOperand'
+    } elseif (-not [string]::IsNullOrWhiteSpace($DelegationPrompt)) {
+        $source = 'DelegationIdentity'
+        foreach ($match in [regex]::Matches($DelegationPrompt, '(?i)\bbranch:\s*(?<name>[A-Za-z0-9][A-Za-z0-9._/-]*)')) {
+            Add-HookTargetDistinctValue -List $branches -Value $match.Groups['name'].Value.TrimEnd('.', '/')
+        }
+        foreach ($match in [regex]::Matches($DelegationPrompt, 'Canonical issue number for this feature is #?(?<number>\d+)')) {
+            $digits = $match.Groups['number'].Value.TrimStart('0')
+            Add-HookTargetDistinctValue -List $issues -Value $(if ($digits -eq '') { '0' } else { $digits })
+        }
+    } else {
+        return (Get-HookTargetResult -Root $session -Source 'SessionRoot' -Code $null -Detail 'no target source is present; the session root applies')
+    }
+
+    # Enumerate registered worktrees at most once, and only when the deciding source needs them.
+    $needsList = switch ($source) {
+        'FilePath' { @($filePaths | Where-Object { (ConvertTo-HookTargetWorktreeNormalizedPath -Path $_) -match $absolutePattern }).Count -gt 0 }
+        'CommandOperand' { [bool] $branchOperand -or @($operandPaths | Where-Object { (ConvertTo-HookTargetWorktreeNormalizedPath -Path $_) -match $absolutePattern }).Count -gt 0 }
+        default { ($branches.Count -eq 1 -and $issues.Count -le 1) -or ($branches.Count -eq 0 -and $issues.Count -eq 1 -and $null -ne $CheckpointIssueReader) }
+    }
+    $records = @()
+    $listDetail = ''
+    if ($needsList) {
+        try {
+            $records = @(ConvertFrom-HookTargetWorktreePorcelain -Text (@(& $WorktreeListInvoker $SessionRoot) -join "`n"))
+            if ($records.Count -eq 0) { $listDetail = 'the worktree list returned no registered worktree' }
+        } catch {
+            $records = @()
+            $listDetail = "the worktree list failed: $($_.Exception.Message)"
+        }
+    }
+    $roots = @($records | ForEach-Object { $_.Root })
+
+    if ($source -eq 'FilePath') { return (Resolve-HookTargetPathSource -Paths $filePaths -Source 'FilePath') }
+
+    if ($source -eq 'CommandOperand') {
+        $pathResult = if ($operandPaths.Count -gt 0) { Resolve-HookTargetPathSource -Paths $operandPaths -Source 'CommandOperand' } else { $null }
+        if (-not $branchOperand) { return $pathResult }
+        $branchResult = Resolve-HookTargetBranchSource -Branch $branchOperand -Source 'CommandOperand'
+        if ($null -eq $pathResult) { return $branchResult }
+        if ($pathResult.Ambiguous) { return $pathResult }
+        if ($null -ne $branchResult.ReasonCode) { return $branchResult }
+        if (-not [string]::Equals($pathResult.WorktreeRoot, $branchResult.WorktreeRoot, $ignoreCase)) {
+            return (Get-HookTargetResult -Root $null -Source 'CommandOperand' -Code $ambiguousCode -Detail "the operand paths and branch '$branchOperand' resolve to different worktrees" -Candidates @($pathResult.WorktreeRoot, $branchResult.WorktreeRoot))
+        }
+        return $branchResult
+    }
+
+    if ($branches.Count -gt 1) { return (Get-HookTargetResult -Root $null -Source $source -Code $ambiguousCode -Detail ('the prompt names {0} different branches: {1}' -f $branches.Count, ($branches -join ', '))) }
+    if ($issues.Count -gt 1) { return (Get-HookTargetResult -Root $null -Source $source -Code $ambiguousCode -Detail ('the prompt names {0} different issue numbers: {1}' -f $issues.Count, ($issues -join ', '))) }
+    if ($branches.Count -eq 1) {
+        $branchResult = Resolve-HookTargetBranchSource -Branch $branches[0] -Source $source
+        if ($null -ne $branchResult.ReasonCode -or $issues.Count -eq 0 -or $null -eq $CheckpointIssueReader) { return $branchResult }
+        $target = $branchResult.WorktreeRoot
+        $recorded = Get-HookTargetRecordedIssue -Root $target
+        if ($null -ne $recorded) {
+            if ($recorded -eq $issues[0]) { return $branchResult }
+            return (Get-HookTargetResult -Root $null -Source $source -Code $ambiguousCode -Detail "branch '$($branches[0])' places the call in a worktree whose checkpoint records issue $recorded, not issue $($issues[0])" -Candidates @($target))
+        }
+        $elsewhere = @($records | Where-Object { -not [string]::Equals($_.Root, $target, $ignoreCase) -and (Get-HookTargetRecordedIssue -Root $_.Root) -eq $issues[0] } | ForEach-Object { $_.Root })
+        if ($elsewhere.Count -gt 0) {
+            return (Get-HookTargetResult -Root $null -Source $source -Code $ambiguousCode -Detail "branch '$($branches[0])' and issue $($issues[0]) place the call in different worktrees" -Candidates (@($target) + $elsewhere))
+        }
+        return $branchResult
+    }
+    if ($issues.Count -eq 1) {
+        if ($null -eq $CheckpointIssueReader) { return (Get-HookTargetResult -Root $null -Source $source -Code $notDerivableCode -Detail "issue $($issues[0]) cannot be placed without a checkpoint issue reader") }
+        $matched = @($records | Where-Object { (Get-HookTargetRecordedIssue -Root $_.Root) -eq $issues[0] } | ForEach-Object { $_.Root })
+        if ($matched.Count -eq 0) { return (Get-HookTargetResult -Root $null -Source $source -Code $notDerivableCode -Detail "issue $($issues[0]) is recorded by no registered worktree") }
+        if ($matched.Count -gt 1) { return (Get-HookTargetResult -Root $null -Source $source -Code $ambiguousCode -Detail "issue $($issues[0]) is recorded by $($matched.Count) registered worktrees" -Candidates $matched) }
+        return (Get-HookTargetResult -Root $matched[0] -Source $source -Code $null)
+    }
+    return (Get-HookTargetResult -Root $null -Source $source -Code $notDerivableCode -Detail 'the prompt carries no branch: label and no canonical issue line')
+}

package/resources/codex-and-agents-customizations/.codex/hooks/record-subagent-routing-attestation.ps1

@@ -13,6 +13,7 @@ param()
 . (Join-Path $PSScriptRoot 'codex-authority-store.ps1')
 . (Join-Path $PSScriptRoot 'codex-agent-profile-attestation.ps1')
 . (Join-Path $PSScriptRoot 'codex-epic-child-launch-attestation.ps1')
+. (Join-Path $PSScriptRoot 'discovery-start-attestation.ps1')
 $script:EpicPersonas = @('epic-planner', 'epic-orchestrator')
 
 function ConvertFrom-SubagentAttestationJson {
@@ -365,6 +366,13 @@ function Invoke-CodexSubagentAttestationCommand {
     )
     try {
         $payload = ConvertFrom-SubagentAttestationJson -Raw (& $ReadInput) -Name 'SubagentStart input'
+        if (Test-CodexDiscoveryAgentType -AgentType ([string]$payload.agent_type)) {
+            # A discovery specialist is attested against its protected invocation only;
+            # no checkpoint, HEAD or epic receipt is consulted (issue #980).
+            $attestation = Get-CodexDiscoveryStartAttestation -Payload $payload -RepositoryRoot $repositoryRoot -Now (& $GetNow)
+            $attestationPath = Write-CodexSubagentAttestation -RepositoryRoot $repositoryRoot -Attestation $attestation
+            return [ordered]@{ exit_code = 0; stdout = (Get-CodexDiscoveryStartCommandOutput -Attestation $attestation -AttestationPath $attestationPath); stderr = $null }
+        }
         $stateRoot = Join-Path $repositoryRoot 'artifacts/orchestration'
         $receiptPath = Get-CodexAuthorityReceiptPath `
             -RepositoryRoot $repositoryRoot `

package/resources/codex-and-agents-customizations/.codex/hooks/validate-codex-subagent-routing.ps1

@@ -31,7 +31,7 @@ function Test-CodexStopGatedAgent {
     [OutputType([bool])]
     param([Parameter(Mandatory)][string] $AgentType)
 
-    if ($AgentType -match '-c(?:1|2|3|4|3-elevated)$') {
+    if ($AgentType -match '-c(?:1|2|3|4|3-elevated)$' -or (Test-CodexStopDiscoveryAgent -AgentType $AgentType)) {
         return $true
     }
     return @(
@@ -42,6 +42,19 @@ function Test-CodexStopGatedAgent {
     ) -contains $AgentType
 }
 
+function Test-CodexStopDiscoveryAgent {
+    <#
+    .SYNOPSIS
+        True for a discovery specialist, whose stop requires the discovery-invocation start attestation (issue #980).
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([AllowNull()][AllowEmptyString()][string] $AgentType)
+
+    return -not [string]::IsNullOrWhiteSpace($AgentType) -and
+    $AgentType -cmatch '^(legacy-parity-analyst|runtime-characterization-analyst|requirements-reconciler|migration-coverage-reviewer)(-c(1|2|3|4|3-elevated))?$'
+}
+
 function Get-CodexStopContinuation {
     [CmdletBinding()]
     [OutputType([System.Collections.Specialized.OrderedDictionary])]
@@ -98,6 +111,14 @@ function Invoke-CodexSubagentStopDecision {
             return Get-CodexStopContinuation -Reason "EPIC_INVOCATION_ORIGIN_BLOCKED: '$agentType' lacks valid root provenance." -AlreadyContinued $alreadyContinued
         }
     }
+    if (Test-CodexStopDiscoveryAgent -AgentType $agentType) {
+        # A specialist's attestation must be the protected discovery-invocation receipt kind;
+        # the output authority itself is validated by validate-discovery-agent-output.ps1.
+        $attestationNames = @($attestation.PSObject.Properties.Name)
+        if ($attestationNames -notcontains 'receipt_kind' -or [string]$attestation.receipt_kind -cne 'discovery-invocation') {
+            return Get-CodexStopContinuation -Reason "DISCOVERY_START_ATTESTATION_BLOCKED: '$agentType' was not attested against a protected discovery invocation." -AlreadyContinued $alreadyContinued
+        }
+    }
     if ($attestation.routing_valid -isnot [bool] -or -not [bool]$attestation.routing_valid) {
         return Get-CodexStopContinuation -Reason "MODEL_ROUTING_ATTESTATION_BLOCKED: '$agentType' did not run under its recorded deployment model." -AlreadyContinued $alreadyContinued
     }

package/resources/codex-and-agents-customizations/.codex/hooks/validate-discovery-agent-output.ps1

@@ -0,0 +1,178 @@
+<#
+.SYNOPSIS
+    Native SubagentStop output validation adapter for Codex discovery agents.
+
+.DESCRIPTION
+    Invoked by the Codex SubagentStop hook. The hook reads the Codex stop envelope
+    from stdin, derives the stopping principal from the payload alone (session, the
+    host-assigned agent_id and agent_type, and the literal parent root), and
+    takes its decision from the shared DiscoveryStop module (published under
+    .codex/lib/discovery-validation, or read from .claude/lib when this repository
+    hosts itself):
+
+    - a stop whose agent type is not a discovery specialist writes nothing, so the
+      routing validator and the other Codex stop gates keep their behavior;
+    - a discovery specialist may stop only when its protected invocation was
+      finalized through the gateway with a current, gateway-written completion
+      receipt whose required outputs are present and whose inputs are unchanged;
+    - a stop that cannot be validated requests one continuation (decision=block at
+      exit 0) and, when stop_hook_active is already true, ends the stop with the
+      reason instead of looping.
+
+    An envelope the hook cannot read writes the reason to stderr at exit 2.
+    Dependency failures block with the DISCOVERY_ARTIFACT_GATE_BLOCKED: prefix
+    (issue #980). No orchestrator checkpoint is read or written.
+
+.NOTES
+    Requires PowerShell 7+. Invokes NO external process.
+#>
+[CmdletBinding()]
+param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
+
+function Get-DiscoveryStopHelperModulePath {
+    <#
+    .SYNOPSIS
+        Returns the published (.codex/lib) or self-hosting (.claude/lib) path of one helper module.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)][string]$ModuleName,
+        [Parameter(Mandatory = $false)][string]$ScriptRoot = $PSScriptRoot
+    )
+
+    $published = Join-Path $ScriptRoot "../lib/discovery-validation/$ModuleName"
+    $selfHosted = Join-Path $ScriptRoot "../../.claude/lib/discovery-validation/$ModuleName"
+    foreach ($candidate in @($published, $selfHosted)) {
+        if (Test-Path -LiteralPath $candidate -PathType Leaf) { return $candidate }
+    }
+    return $published
+}
+
+function Import-DiscoveryOutputSelfHostedModule {
+    <#
+    .SYNOPSIS
+        Imports the shared helpers from this repository's .claude/lib layout when no published .codex/lib exists (exemption D4).
+    #>
+    [CmdletBinding()]
+    param()
+
+    $ScriptRoot = $PSScriptRoot
+    try { Import-Module (Join-Path $ScriptRoot '../../.claude/lib/discovery-validation/DiscoveryEncoding.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryEncoding.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $ScriptRoot '../../.claude/lib/discovery-validation/DiscoveryAuthority.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryAuthority.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $ScriptRoot '../../.claude/lib/discovery-validation/DiscoveryManifest.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryManifest.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $ScriptRoot '../../.claude/lib/discovery-validation/DiscoveryPayload.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryPayload.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $ScriptRoot '../../.claude/lib/discovery-validation/DiscoveryStartRecord.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryStartRecord.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $ScriptRoot '../../.claude/lib/discovery-validation/DiscoveryStop.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryStop.psm1' -ErrorRecord $_ }
+}
+
+# The published destination keeps the helpers beside .codex/hooks; this repository hosts them under .claude/lib.
+if (Test-Path -LiteralPath (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryEncoding.psm1') -PathType Leaf) {
+    try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryEncoding.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryEncoding.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryAuthority.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryAuthority.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryManifest.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryManifest.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryPayload.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryPayload.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryStartRecord.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryStartRecord.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryStop.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryStop.psm1' -ErrorRecord $_ }
+} else {
+    Import-DiscoveryOutputSelfHostedModule
+}
+
+$script:DiscoveryGateReasonPrefix = 'DISCOVERY_ARTIFACT_GATE_BLOCKED:'
+
+function Invoke-DiscoveryAgentOutputDecision {
+    <#
+    .SYNOPSIS
+        Parses the Codex SubagentStop envelope and returns the shared stop outcome.
+    .DESCRIPTION
+        Returns the outcome object (Decision skip, allow or block; Code; Reason;
+        Receipt; Invocation). Every seam defaults to the real host and is injectable.
+        A recorded dependency failure blocks before the envelope is read.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory = $false)][AllowNull()][AllowEmptyString()][string]$PayloadRaw,
+        [Parameter(Mandatory = $false)][AllowNull()][hashtable]$HostEnvironment = $null,
+        [Parameter(Mandatory = $false)][AllowNull()][hashtable]$Store = $null,
+        [Parameter(Mandatory = $false)][AllowNull()][scriptblock]$ReadBytes = $null
+    )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent SubagentStop -ReasonPrefix $script:DiscoveryGateReasonPrefix
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
+
+    if ($null -eq $HostEnvironment) { $HostEnvironment = Get-DiscoveryTrustedHostEnvironment }
+    if ($null -eq $Store) { $Store = Get-DiscoveryStartStore }
+
+    $normalized = ConvertFrom-DiscoveryHostPayloadText -HostName 'codex' -Text $PayloadRaw
+    $assistantText = ''
+    $stopHookActive = $false
+    if ($null -eq $normalized.Anomaly) {
+        $payload = ConvertFrom-Json -InputObject $PayloadRaw -Depth 16
+        $names = @($payload.PSObject.Properties.Name)
+        if ($names -contains 'last_assistant_message' -and $payload.last_assistant_message -is [string]) { $assistantText = [string]$payload.last_assistant_message }
+        if ($names -contains 'stop_hook_active' -and $payload.stop_hook_active -is [bool]) { $stopHookActive = [bool]$payload.stop_hook_active }
+    }
+    $parameters = @{
+        Normalized = $normalized; HostEnvironment = $HostEnvironment
+        AssistantText = $assistantText; StopHookActive = $stopHookActive; Store = $Store
+    }
+    if ($null -ne $ReadBytes) { $parameters['ReadBytes'] = $ReadBytes }
+    return Get-DiscoveryStopDecision @parameters
+}
+
+function Get-DiscoveryAgentOutputContinuation {
+    <#
+    .SYNOPSIS
+        Renders a blocked stop as the Codex continuation (decision=block) or, when already continued, the stop reason.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory = $true)][string]$Reason,
+        [Parameter(Mandatory = $true)][bool]$AlreadyContinued
+    )
+
+    if ($AlreadyContinued) {
+        return [ordered]@{ continue = $false; stopReason = $Reason; systemMessage = $Reason }
+    }
+    return [ordered]@{ decision = 'block'; reason = $Reason }
+}
+
+function Invoke-DiscoveryAgentOutputEntryPoint {
+    <#
+    .SYNOPSIS
+        Reads one Codex SubagentStop payload, writes the decision and returns the process exit code.
+    .DESCRIPTION
+        An unreadable envelope or a dependency failure writes its reason to stderr and
+        returns 2. A blocked stop writes the continuation JSON and returns 0; a
+        CONTINUED allow writes the stop reason JSON and returns 0. A skipped or
+        validated stop writes nothing and returns 0.
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param([Parameter(Mandatory = $false)][AllowNull()][AllowEmptyString()][string]$PayloadRaw)
+
+    $outcome = Invoke-DiscoveryAgentOutputDecision -PayloadRaw $PayloadRaw
+    # A dependency failure is already the SubagentStop block result (ExitCode, Reason).
+    if ($null -ne $outcome.PSObject.Properties['ExitCode']) { [Console]::Error.WriteLine([string]$outcome.Reason); return [int]$outcome.ExitCode }
+    if ($outcome.Code -eq 'ENVELOPE') {
+        [Console]::Error.WriteLine("$($script:DiscoveryGateReasonPrefix) $($outcome.Reason)")
+        return 2
+    }
+    if ($outcome.Decision -eq 'block' -or $outcome.Code -eq 'CONTINUED') {
+        $continuation = Get-DiscoveryAgentOutputContinuation -Reason "$($script:DiscoveryGateReasonPrefix) $($outcome.Reason)" -AlreadyContinued ($outcome.Code -eq 'CONTINUED')
+        [Console]::Out.WriteLine(($continuation | ConvertTo-Json -Compress -Depth 5))
+    }
+    return 0
+}
+
+# Guard allows dot-sourcing in tests without executing the entrypoint.
+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 }
+
+exit (Invoke-DiscoveryAgentOutputEntryPoint -PayloadRaw ([Console]::In.ReadToEnd()))

package/resources/codex-and-agents-customizations/.codex/scripts/Resolve-CodexTopology.ps1

@@ -49,6 +49,14 @@ function Invoke-CodexTopologyCli {
             Default  = $null
         }
         '--cross-cutting'         = @{ Key = 'cross_cutting'; Kind = 'switch'; Required = $false; Default = $false }
+        '--invocation-kind'       = @{
+            Key      = 'invocation_kind'
+            Kind     = 'value'
+            Required = $false
+            Choices  = @('ordinary', 'discovery')
+            Default  = 'ordinary'
+        }
+        '--skill-id'              = @{ Key = 'skill_id'; Kind = 'value'; Required = $false; Default = $null }
         '--root-persona'          = @{
             Key      = 'root_persona'
             Kind     = 'value'
@@ -79,7 +87,9 @@ function Invoke-CodexTopologyCli {
             -TestFileCount $values['test_file_count'] `
             -ExecutionContext $values['execution_context'] `
             -CrossCutting ([bool]$values['cross_cutting']) `
-            -RootPersona $values['root_persona']
+            -RootPersona $values['root_persona'] `
+            -InvocationKind $values['invocation_kind'] `
+            -SkillId $values['skill_id']
     } catch [System.ArgumentException] {
         return New-CodexRoutingCliResult -ExitCode 1 -Stderr "$($_.Exception.Message)`n"
     }

package/resources/codex-and-agents-customizations/.codex-variants/csharp-legacy/agents/csharp-typed-engineer.toml

@@ -83,7 +83,7 @@ If the marker is missing or malformed, fail closed to `full-feature`.
 Stop implementation and return to the user when:
 
 - the scope estimate or an in-flight batch would exceed the 3-production-file cap in direct mode,
-- a file is near or would exceed the 500-line limit,
+- a file is above or would exceed the 800-line hard limit of the tiered file-size policy (split it before proceeding; at 500 lines look for a logical split, and at 700 lines split more aggressively),
 - any QA gate delta is non-zero after self-correction,
 - the toolchain cannot be executed in the current environment (mark the change **unverified**),
 - orchestrator handoff mode is requested but the required context package is incomplete,