@danmoisan/drm-copilot-mcp 1.1.23 → 1.1.24

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.23"]
+args = ["-y", "@danmoisan/drm-copilot-mcp@1.1.24"]
 required = true
 enabled_tools = [
     "collect_commit_context",
@@ -107,7 +107,7 @@ timeout = 15
 statusMessage = "Authorizing root epic entry"
 
 [[hooks.SubagentStart]]
-matcher = "epic-planner|epic-orchestrator|orchestrator|atomic-planner|atomic-executor|feature-review|feature-reviewer|task-researcher|prd-feature|pr-author|typed-engineer|-c"
+matcher = "epic-planner|epic-orchestrator|orchestrator|atomic-planner|atomic-executor|feature-review|feature-reviewer|task-researcher|prd-feature|pr-author|typed-engineer|-c|legacy-parity-analyst|runtime-characterization-analyst|requirements-reconciler|migration-coverage-reviewer"
 
 [[hooks.SubagentStart.hooks]]
 type = "command"
@@ -152,6 +152,12 @@ timeout = 30
 [[hooks.PreToolUse]]
 matcher = "^(Bash|shell_command|apply_patch|Edit|Write|mcp__.*)$"
 
+[[hooks.PreToolUse.hooks]]
+type = "command"
+command = 'pwsh -NoProfile -File "$(git rev-parse --show-toplevel)/.codex/hooks/enforce-discovery-artifact-gate.ps1"'
+command_windows = 'pwsh -NoProfile -File "$(git rev-parse --show-toplevel)/.codex/hooks/enforce-discovery-artifact-gate.ps1"'
+timeout = 30
+
 [[hooks.PreToolUse.hooks]]
 type = "command"
 command = 'pwsh -NoProfile -File "$(git rev-parse --show-toplevel)/.codex/hooks/enforce-epic-root-invocation.ps1"'
@@ -239,8 +245,23 @@ command = 'pwsh -NoProfile -File "$(git rev-parse --show-toplevel)/.codex/hooks/
 command_windows = 'pwsh -NoProfile -File "$(git rev-parse --show-toplevel)/.codex/hooks/enforce-completion-consistency.ps1"'
 timeout = 30
 
+[[hooks.PreToolUse]]
+matcher = "^(Agent|Task|spawn_agent|run_subagent|delegate)$"
+
+[[hooks.PreToolUse.hooks]]
+type = "command"
+command = 'pwsh -NoProfile -File "$(git rev-parse --show-toplevel)/.codex/hooks/enforce-discovery-artifact-gate.ps1"'
+command_windows = 'pwsh -NoProfile -File "$(git rev-parse --show-toplevel)/.codex/hooks/enforce-discovery-artifact-gate.ps1"'
+timeout = 30
+
+[[hooks.PreToolUse.hooks]]
+type = "command"
+command = 'pwsh -NoProfile -File "$(git rev-parse --show-toplevel)/.codex/hooks/enforce-discovery-planning-gate.ps1"'
+command_windows = 'pwsh -NoProfile -File "$(git rev-parse --show-toplevel)/.codex/hooks/enforce-discovery-planning-gate.ps1"'
+timeout = 30
+
 [[hooks.SubagentStop]]
-matcher = "epic-planner|epic-orchestrator|orchestrator|atomic-planner|atomic-executor|feature-review|feature-reviewer|task-researcher|prd-feature|pr-author|typed-engineer|-c"
+matcher = "epic-planner|epic-orchestrator|orchestrator|atomic-planner|atomic-executor|feature-review|feature-reviewer|task-researcher|prd-feature|pr-author|typed-engineer|-c|legacy-parity-analyst|runtime-characterization-analyst|requirements-reconciler|migration-coverage-reviewer"
 
 [[hooks.SubagentStop.hooks]]
 type = "command"
@@ -248,6 +269,15 @@ command = 'pwsh -NoProfile -File "$(git rev-parse --show-toplevel)/.codex/hooks/
 command_windows = 'pwsh -NoProfile -File "$(git rev-parse --show-toplevel)/.codex/hooks/validate-codex-subagent-routing.ps1"'
 timeout = 30
 
+[[hooks.SubagentStop]]
+matcher = "legacy-parity-analyst|runtime-characterization-analyst|requirements-reconciler|migration-coverage-reviewer"
+
+[[hooks.SubagentStop.hooks]]
+type = "command"
+command = 'pwsh -NoProfile -File "$(git rev-parse --show-toplevel)/.codex/hooks/validate-discovery-agent-output.ps1"'
+command_windows = 'pwsh -NoProfile -File "$(git rev-parse --show-toplevel)/.codex/hooks/validate-discovery-agent-output.ps1"'
+timeout = 30
+
 [[hooks.SubagentStop]]
 matcher = "feature-review|feature-reviewer"
 

package/resources/codex-and-agents-customizations/.codex/hooks/codex-agent-profile-attestation.ps1

@@ -119,6 +119,28 @@ function Test-CodexAgentProfileBinding {
     return $true
 }
 
+function ConvertTo-CodexSharedAgentProfile {
+    <#
+    .SYNOPSIS
+        Projects a Codex profile attestation into the shared discovery agent-profile shape.
+    .DESCRIPTION
+        The shared DiscoveryStart decision compares ProfileName, ProfileSha256,
+        ProfileModel and ProfileReasoningEffort against the protected invocation;
+        this projection keeps the Codex TOML reader as the single source of those values.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param([Parameter(Mandatory)] $AgentProfile)
+
+    return [pscustomobject]@{
+        ProfilePath            = [string]$AgentProfile.profile_path
+        ProfileSha256          = [string]$AgentProfile.profile_sha256
+        ProfileName            = [string]$AgentProfile.profile_name
+        ProfileModel           = [string]$AgentProfile.profile_model
+        ProfileReasoningEffort = [string]$AgentProfile.profile_reasoning_effort
+    }
+}
+
 function Test-CodexRoutedAgentType {
     [CmdletBinding()]
     [OutputType([bool])]

package/resources/codex-and-agents-customizations/.codex/hooks/discovery-capability-probe.ps1

@@ -0,0 +1,97 @@
+<#
+.SYNOPSIS
+    Codex capability probe for discovery agents: observes registration, handler hashes and the recorded sentinel observations.
+
+.DESCRIPTION
+    Not an event hook. The gateway doctor and the operator script
+    scripts/dev-tools/Test-DiscoveryHostCapability.ps1 run this probe to observe
+    whether this workspace's Codex host provides the required discovery controls:
+    the SubagentStart, PreToolUse and SubagentStop handlers registered in
+    .codex/config.toml for the four discovery agents and the controlled tools, their
+    current hashes, and the host observations the PreToolUse gate recorded while the
+    discovery-capability-sentinel agent ran in session SessionId. The result is a
+    capability-attestation-shaped JSON document on stdout; exit 0 when supported, 1
+    when unsupported. A session without observations, or whose sentinel observation
+    carries no agent_id, is unsupported.
+
+.NOTES
+    Issue #980. Requires PowerShell 7+. Invokes NO external process and makes no
+    in-process sentinel decision.
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $false)][string]$WorkspaceRoot = (Split-Path (Split-Path $PSScriptRoot -Parent) -Parent),
+    [Parameter(Mandatory = $false)][string]$SessionId = 'capability-probe',
+    [Parameter(Mandatory = $false)][AllowNull()][string]$Nonce = $null,
+    [Parameter(Mandatory = $false)][bool]$WorkspaceTrusted = $true,
+    [Parameter(Mandatory = $false)][AllowNull()][string]$RuntimeJson = $null
+)
+
+. (Join-Path $PSScriptRoot 'enforce-discovery-artifact-gate.ps1')
+Import-Module (Get-DiscoveryHelperModulePath -ModuleName 'DiscoveryCapability.psm1') -Force -Global -ErrorAction Stop
+
+function Get-DiscoveryProbeRuntime {
+    <#
+    .SYNOPSIS
+        Returns the runtime identity the probe records: the caller's JSON, or the local configuration digest.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param([Parameter(Mandatory = $false)][AllowNull()][string]$RuntimeJson, [Parameter(Mandatory = $true)][string]$WorkspaceRoot)
+
+    if (-not [string]::IsNullOrWhiteSpace($RuntimeJson)) {
+        $parsed = ConvertFrom-Json -InputObject $RuntimeJson -Depth 4
+        $runtime = [ordered]@{}
+        foreach ($key in @('build_sha256', 'package_version', 'policy_sha256', 'policy_version', 'schema_version')) {
+            # The runtime identity contract types policy_version as an integer; the hosts compare it canonically.
+            $runtime[$key] = $(if ($key -eq 'policy_version') { [int]$parsed.$key } else { [string]$parsed.$key })
+        }
+        return $runtime
+    }
+    # The workspace root is a host-modelled path string; Join-Path would require its drive to exist locally.
+    $configuration = "$($WorkspaceRoot.TrimEnd('/', '\'))/.codex/config.toml"
+    $digest = $(if (Test-Path -LiteralPath $configuration -PathType Leaf) { Get-DiscoveryBytesSha256Hex -Bytes ([System.IO.File]::ReadAllBytes($configuration)) } else { '0' * 64 })
+    return [ordered]@{ build_sha256 = $digest; package_version = '2.0.0'; policy_sha256 = $digest; policy_version = 2; schema_version = '2.0.0' }
+}
+
+function Invoke-DiscoveryCapabilityProbe {
+    <#
+    .SYNOPSIS
+        Runs the Codex capability observation and returns the attestation-shaped document.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory = $true)][string]$WorkspaceRoot,
+        [Parameter(Mandatory = $true)][string]$SessionId,
+        [Parameter(Mandatory = $false)][AllowNull()][string]$Nonce = $null,
+        [Parameter(Mandatory = $false)][bool]$WorkspaceTrusted = $true,
+        [Parameter(Mandatory = $false)][AllowNull()][string]$RuntimeJson = $null,
+        [Parameter(Mandatory = $false)][AllowNull()][hashtable]$HostEnvironment = $null,
+        [Parameter(Mandatory = $false)][AllowNull()][hashtable]$Store = $null,
+        [Parameter(Mandatory = $false)][AllowNull()][scriptblock]$ReadBytes = $null,
+        [Parameter(Mandatory = $false)][AllowNull()][nullable[datetime]]$Now = $null
+    )
+
+    if ([string]::IsNullOrEmpty($Nonce)) { $Nonce = Get-DiscoveryAuthorizationNonce }
+    if ($null -eq $HostEnvironment) { $HostEnvironment = Get-DiscoveryTrustedHostEnvironment }
+    if ($null -eq $Store) { $Store = Get-DiscoveryDefaultStore }
+    if ($null -eq $Now) { $Now = [datetime]::UtcNow }
+    $parameters = @{
+        HostName = 'codex'; WorkspaceRoot = $WorkspaceRoot; SessionId = $SessionId; Nonce = $Nonce; WorkspaceTrusted = $WorkspaceTrusted; Now = $Now
+        Runtime = (Get-DiscoveryProbeRuntime -RuntimeJson $RuntimeJson -WorkspaceRoot $WorkspaceRoot)
+        HostEnvironment = $HostEnvironment; Store = $Store
+    }
+    if ($null -ne $ReadBytes) { $parameters['ReadBytes'] = $ReadBytes }
+    $observation = Get-DiscoveryCapabilityObservation @parameters
+    # The doctor, the agent preparation and the start attestation read only the protected session copy.
+    [void](Write-DiscoveryCapabilityAttestation -Observation $observation -WorkspaceRoot $WorkspaceRoot -HostEnvironment $HostEnvironment -Store $Store)
+    return $observation
+}
+
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+$observation = Invoke-DiscoveryCapabilityProbe -WorkspaceRoot $WorkspaceRoot -SessionId $SessionId -Nonce $Nonce -WorkspaceTrusted $WorkspaceTrusted -RuntimeJson $RuntimeJson
+$observation | ConvertTo-Json -Depth 8 | Write-Output
+exit $(if ($observation['status'] -eq 'supported') { 0 } else { 1 })

package/resources/codex-and-agents-customizations/.codex/hooks/discovery-start-attestation.ps1

@@ -0,0 +1,171 @@
+<#
+.SYNOPSIS
+    Codex SubagentStart attestation for discovery specialists through the protected discovery store.
+
+.DESCRIPTION
+    Dot-sourced by record-subagent-routing-attestation.ps1. A Codex start whose agent
+    type names a discovery specialist is attested against the explicit
+    `discovery-invocation` receipt the root prepared in the protected store, through
+    the shared DiscoveryStart module (published under .codex/lib/discovery-validation,
+    or read from .claude/lib when this repository hosts itself). The result is
+    projected into the schema-2 routing attestation the Codex PreToolUse gates
+    already consume, with receipt_kind `discovery-invocation`, so an unattested or
+    drifted specialist is denied before its first tool use. No orchestrator
+    checkpoint, repository HEAD or epic receipt is read for a discovery start.
+#>
+[CmdletBinding()]
+param()
+
+$script:CodexDiscoveryAgentTypePattern = '^(legacy-parity-analyst|runtime-characterization-analyst|requirements-reconciler|migration-coverage-reviewer)(-c(1|2|3|4|3-elevated))?$'
+$script:CodexDiscoveryStartPrefix = 'DISCOVERY_START_ATTESTATION_BLOCKED:'
+$script:CodexDiscoveryStartModules = @('DiscoveryEncoding.psm1', 'DiscoveryAuthority.psm1', 'DiscoveryPayload.psm1', 'DiscoveryStartRecord.psm1', 'DiscoveryStart.psm1')
+
+function Test-CodexDiscoveryAgentType {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param([AllowNull()][AllowEmptyString()][string] $AgentType)
+
+    return -not [string]::IsNullOrWhiteSpace($AgentType) -and $AgentType -cmatch $script:CodexDiscoveryAgentTypePattern
+}
+
+function Get-CodexDiscoveryStartModulePath {
+    <#
+    .SYNOPSIS
+        Returns the published (.codex/lib) or self-hosting (.claude/lib) path of one helper module.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)][string] $ModuleName,
+        [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-CodexDiscoveryStartModule {
+    <#
+    .SYNOPSIS
+        Loads the shared discovery modules a discovery start needs; ordinary starts never load them.
+    #>
+    [CmdletBinding()]
+    param([string] $ScriptRoot = $PSScriptRoot)
+
+    foreach ($moduleName in $script:CodexDiscoveryStartModules) {
+        Import-Module (Get-CodexDiscoveryStartModulePath -ModuleName $moduleName -ScriptRoot $ScriptRoot) -Force -Global -ErrorAction Stop
+    }
+}
+
+function Get-CodexDiscoveryStartAttestation {
+    <#
+    .SYNOPSIS
+        Builds the schema-2 attestation of a Codex discovery start from the protected invocation.
+    .DESCRIPTION
+        The actual model comes from the SubagentStart payload and the actual effort and
+        profile hash from the generated Codex profile; both must equal the deployment
+        the root prepared. routing_valid is true only when the shared decision
+        attested the start; discovery_code and discovery_reason carry the decision.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)] $Payload,
+        [Parameter(Mandatory)][string] $RepositoryRoot,
+        [Parameter(Mandatory)][datetimeoffset] $Now,
+        [AllowNull()][hashtable] $HostEnvironment = $null,
+        [AllowNull()][hashtable] $Store = $null,
+        [AllowNull()][string] $Nonce = $null,
+        [AllowNull()] $AgentProfile = $null,
+        [string] $HandlerPath = (Join-Path $PSScriptRoot 'record-subagent-routing-attestation.ps1')
+    )
+
+    $agentId = [string]$Payload.agent_id
+    $agentType = [string]$Payload.agent_type
+    $model = [string]$Payload.model
+    if (-not $agentId -or -not $agentType -or -not $model) {
+        throw "$($script:CodexDiscoveryStartPrefix) SubagentStart requires agent_id, agent_type, and model."
+    }
+    Import-CodexDiscoveryStartModule
+    $profileValidationError = $null
+    if ($null -eq $AgentProfile) {
+        try { $AgentProfile = Get-CodexAgentProfileAttestation -RepositoryRoot $RepositoryRoot -AgentType $agentType } catch { $profileValidationError = [string]$_ }
+    }
+    $sharedProfile = $(if ($null -ne $AgentProfile) { ConvertTo-CodexSharedAgentProfile -AgentProfile $AgentProfile } else { $null })
+    # The principal comes from the payload alone: Codex supplies no parent identifier, so the parent is the literal root.
+    $normalized = [pscustomobject]@{
+        HostName = 'codex'; Event = 'SubagentStart'; SessionId = [string]$Payload.session_id; AgentId = $agentId; AgentType = $agentType; ParentAgentId = $null
+        ToolName = $null; ToolInput = $null; Cwd = $RepositoryRoot; ToolUseId = $null; Anomaly = $null
+    }
+    if ([string]::IsNullOrWhiteSpace($normalized.SessionId)) { $normalized.Anomaly = 'MissingSessionId' }
+    $handlerSha256 = $(if (Test-Path -LiteralPath $HandlerPath -PathType Leaf) { Get-DiscoveryBytesSha256Hex -Bytes ([System.IO.File]::ReadAllBytes($HandlerPath)) } else { '0' * 64 })
+    $parameters = @{ Normalized = $normalized; HandlerSha256 = $handlerSha256; Now = $Now.UtcDateTime; ActualModel = $model }
+    $parameters['HostEnvironment'] = $(if ($null -ne $HostEnvironment) { $HostEnvironment } else { Get-DiscoveryTrustedHostEnvironment })
+    if ($null -ne $Store) { $parameters['Store'] = $Store }
+    if (-not [string]::IsNullOrEmpty($Nonce)) { $parameters['Nonce'] = $Nonce }
+    if ($null -ne $sharedProfile) { $parameters['AgentProfile'] = $sharedProfile; $parameters['ActualReasoningEffort'] = $sharedProfile.ProfileReasoningEffort }
+    $outcome = $(if ($null -eq $sharedProfile) {
+            [pscustomobject]@{ Decision = 'deny'; Code = 'PROFILE'; Reason = "the agent profile could not be read: $profileValidationError"; Attestation = $null; AttestationPath = $null; Invocation = $null }
+        } else { Get-DiscoveryStartDecision @parameters })
+    $record = $outcome.Invocation
+    $attested = ($outcome.Decision -eq 'attest')
+    return [ordered]@{
+        schema_version              = 2
+        receipt_kind                = 'discovery-invocation'
+        session_id                  = [string]$Payload.session_id
+        turn_id                     = [string]$Payload.turn_id
+        agent_id                    = $agentId
+        agent_type                  = $agentType
+        transcript_path             = [string]$Payload.transcript_path
+        attestation_key             = Get-SubagentAttestationKey -TranscriptPath ([string]$Payload.transcript_path) -AgentId $agentId
+        actual_model                = $model
+        expected_model              = $(if ($null -ne $record) { [string]$record.deployment.model } else { '' })
+        actual_reasoning_effort     = $(if ($null -ne $AgentProfile) { [string]$AgentProfile.profile_reasoning_effort } else { $null })
+        expected_reasoning_effort   = $(if ($null -ne $record) { [string]$record.deployment.reasoning_effort } else { '' })
+        profile_name                = $(if ($null -ne $AgentProfile) { [string]$AgentProfile.profile_name } else { $null })
+        profile_model               = $(if ($null -ne $AgentProfile) { [string]$AgentProfile.profile_model } else { $null })
+        profile_path                = $(if ($null -ne $AgentProfile) { [string]$AgentProfile.profile_path } else { $null })
+        profile_sha256              = $(if ($null -ne $AgentProfile) { [string]$AgentProfile.profile_sha256 } else { $null })
+        profile_validation_error    = $profileValidationError
+        routing_valid               = $attested
+        launch_authority_valid      = $attested
+        root_authorized             = $null
+        root_entry_kind             = $null
+        root_epic_reference         = $null
+        root_kickoff_path           = $null
+        authority_repository_sha256 = Get-CodexAuthorityRepositoryKey -RepositoryRoot $RepositoryRoot
+        provenance_valid            = $true
+        enforcement_marker          = $(if ($attested) { $null } else { 'DISCOVERY_START_ATTESTATION_BLOCKED' })
+        invocation_id               = $(if ($null -ne $record) { [string]$record.invocation_id } else { $null })
+        start_attestation_ref       = $(if ($attested) { [string]$outcome.Attestation['start_attestation_ref'] } else { $null })
+        discovery_code              = $outcome.Code
+        discovery_reason            = $outcome.Reason
+        recorded_at                 = $Now.ToUniversalTime().ToString('o')
+    }
+}
+
+function Get-CodexDiscoveryStartCommandOutput {
+    <#
+    .SYNOPSIS
+        Returns the SubagentStart stdout for a discovery attestation, or $null when the start was attested.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory)][System.Collections.IDictionary] $Attestation,
+        [Parameter(Mandatory)][string] $AttestationPath
+    )
+
+    if ([bool]$Attestation.routing_valid) { return $null }
+    return [ordered]@{
+        systemMessage      = "$($script:CodexDiscoveryStartPrefix) $($Attestation.discovery_reason) Attestation: $AttestationPath"
+        hookSpecificOutput = [ordered]@{
+            hookEventName     = 'SubagentStart'
+            additionalContext = "$($script:CodexDiscoveryStartPrefix) no discovery tool grant is active for this agent. Do not read or mutate state; report the blocked start and stop."
+        }
+    } | ConvertTo-Json -Compress -Depth 5
+}

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

@@ -127,7 +127,10 @@ function Test-CodexModelGateAgentType {
     [OutputType([bool])]
     param([Parameter(Mandatory)][string] $AgentType)
 
-    return $AgentType -match '-c(?:1|2|3|4|3-elevated)$' -or @(
+    # Discovery specialists are gated by their SubagentStart attestation of the
+    # protected invocation (issue #980); a start without one denies the first tool use.
+    return $AgentType -match '-c(?:1|2|3|4|3-elevated)$' -or
+    $AgentType -cmatch '^(legacy-parity-analyst|runtime-characterization-analyst|requirements-reconciler|migration-coverage-reviewer)$' -or @(
         'orchestrator', 'atomic-planner', 'atomic-executor', 'feature-review',
         'feature-reviewer', 'task-researcher', 'prd-feature', 'pr-author',
         'python-typed-engineer', 'powershell-typed-engineer',

package/resources/codex-and-agents-customizations/.codex/hooks/enforce-discovery-artifact-gate.ps1

@@ -0,0 +1,187 @@
+<#
+.SYNOPSIS
+    Native PreToolUse authorization adapter for Codex discovery agents.
+
+.DESCRIPTION
+    Invoked by the Codex PreToolUse hook. The hook reads the Codex envelope from
+    stdin, derives the trusted principal from the payload alone (session, the
+    host-assigned agent_id and agent_type when the payload carries them, and the
+    literal parent root), and takes its decision from the shared
+    DiscoveryAuthorization module (published under .codex/lib/discovery-validation,
+    or read from .claude/lib when this repository hosts itself):
+
+    - a root call (no agent_id) of prepare_discovery_agent, run_discovery_doctor or
+      a controlled discovery tool is allowed with a one-use root grant the MCP
+      server consumes; every other root call and every call of an agent that is
+      not a discovery specialist allows silently (no stdout), so ordinary
+      sessions keep the behavior of their other gates;
+    - a sentinel envelope is observed for the capability probe and never granted;
+    - a discovery specialist may use read-only native tools and the controlled
+      discovery MCP tools only; shell, exec and evaluation tools, generic
+      apply_patch/Write/Edit mutations, nested agents, foreign MCP servers,
+      root-only discovery operations and caller-supplied identity fields are denied
+      before execution with a PreToolUse deny decision at exit 0;
+    - every controlled call must name the specialist's started invocation through
+      invocation_ref and is recorded as one short-lived, one-use tool-authorization;
+      the Codex SubagentStart attestation binds the prepared invocation, and the
+      gate's first-call binding reports PROFILE when no start attested the agent.
+
+    An envelope the hook cannot read is a hard failure: the reason goes to stderr
+    and the hook exits 2. Dependency failures deny with the
+    DISCOVERY_ARTIFACT_GATE_BLOCKED: prefix (issue #980).
+
+.NOTES
+    Requires PowerShell 7+. Invokes NO external process and never reads a profile,
+    locator or request field to decide identity or authority.
+#>
+[CmdletBinding()]
+param()
+$script:HookDependencyGuardLoadFailed = $false; try { . (Join-Path $PSScriptRoot 'hook-dependency-guard.ps1') } catch { $script:HookDependencyGuardLoadFailed = $true }
+
+function Get-DiscoveryHelperModulePath {
+    <#
+    .SYNOPSIS
+        Returns the published (.codex/lib) or self-hosting (.claude/lib) path of one helper module.
+    .DESCRIPTION
+        The published destination holds the helpers beside .codex/hooks under
+        .codex/lib/discovery-validation; this repository holds them under
+        .claude/lib/discovery-validation. The first existing candidate wins; when
+        neither exists the published path is returned so the import failure names it.
+    #>
+    [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"
+    # Resolution order: the destination layout first, then the repository layout.
+    foreach ($candidate in @($published, $selfHosted)) {
+        if (Test-Path -LiteralPath $candidate -PathType Leaf) { return $candidate }
+    }
+    return $published
+}
+
+function Import-DiscoveryGateSelfHostedModule {
+    <#
+    .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/DiscoveryPayload.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryPayload.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $ScriptRoot '../../.claude/lib/discovery-validation/DiscoveryToolRouting.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryToolRouting.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/DiscoveryRootGrant.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryRootGrant.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $ScriptRoot '../../.claude/lib/discovery-validation/DiscoveryObservation.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryObservation.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $ScriptRoot '../../.claude/lib/discovery-validation/DiscoveryStart.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryStart.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $ScriptRoot '../../.claude/lib/discovery-validation/DiscoveryAuthorization.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryAuthorization.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/DiscoveryPayload.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryPayload.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryToolRouting.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryToolRouting.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/DiscoveryRootGrant.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryRootGrant.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryObservation.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryObservation.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryStart.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryStart.psm1' -ErrorRecord $_ }
+    try { Import-Module (Join-Path $PSScriptRoot '../lib/discovery-validation/DiscoveryAuthorization.psm1') -Force -Global -ErrorAction Stop } catch { Add-HookDependencyFailure -Name 'DiscoveryAuthorization.psm1' -ErrorRecord $_ }
+} else {
+    Import-DiscoveryGateSelfHostedModule
+}
+
+$script:DiscoveryGateReasonPrefix = 'DISCOVERY_ARTIFACT_GATE_BLOCKED:'
+$script:DiscoveryGateHandlerPath = $PSCommandPath
+
+function Get-DiscoveryGateHandlerSha256 {
+    <#
+    .SYNOPSIS
+        Returns the SHA-256 of this handler's own bytes for the authorization writer record.
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param([Parameter(Mandatory = $false)][AllowNull()][string]$HandlerPath = $script:DiscoveryGateHandlerPath)
+
+    if ([string]::IsNullOrEmpty($HandlerPath) -or -not (Test-Path -LiteralPath $HandlerPath -PathType Leaf)) {
+        return ('0' * 64)
+    }
+    return Get-DiscoveryBytesSha256Hex -Bytes ([System.IO.File]::ReadAllBytes($HandlerPath))
+}
+
+function Invoke-DiscoveryArtifactGateDecision {
+    <#
+    .SYNOPSIS
+        Parses the Codex PreToolUse envelope and returns the decision outcome.
+    .DESCRIPTION
+        Returns the shared outcome object (Decision, Code, Reason, Record,
+        RecordPath). Every seam defaults to the real host and is injectable. A
+        recorded dependency failure returns a deny outcome before the envelope is read.
+    #>
+    [CmdletBinding()]
+    [OutputType([pscustomobject])]
+    param(
+        [Parameter(Mandatory = $false)][AllowNull()][AllowEmptyString()][string]$ToolInputRaw,
+        [Parameter(Mandatory = $false)][AllowNull()][hashtable]$HostEnvironment = $null,
+        [Parameter(Mandatory = $false)][AllowNull()][hashtable]$Store = $null,
+        [Parameter(Mandatory = $false)][AllowNull()][nullable[datetime]]$Now = $null,
+        [Parameter(Mandatory = $false)][AllowNull()][string]$Nonce = $null
+    )
+    $dependencyDecision = Get-HookDependencyFailureDecision -HookEvent PreToolUse -ReasonPrefix $script:DiscoveryGateReasonPrefix
+    if ($null -ne $dependencyDecision) { return $dependencyDecision }
+
+    # Seams resolve only after the dependency check so a missing module denies
+    # instead of raising while a default is evaluated.
+    if ($null -eq $HostEnvironment) { $HostEnvironment = Get-DiscoveryTrustedHostEnvironment }
+    if ($null -eq $Store) { $Store = Get-DiscoveryDefaultStore }
+    if ($null -eq $Now) { $Now = [datetime]::UtcNow }
+    if ([string]::IsNullOrEmpty($Nonce)) { $Nonce = Get-DiscoveryAuthorizationNonce }
+
+    $normalized = ConvertFrom-DiscoveryHostPayloadText -HostName 'codex' -Text $ToolInputRaw
+    return Get-DiscoveryPreToolDecision -Normalized $normalized -HostEnvironment $HostEnvironment `
+        -HandlerSha256 (Get-DiscoveryGateHandlerSha256) -Store $Store -Now $Now -Nonce $Nonce
+}
+
+function Invoke-DiscoveryArtifactGateEntryPoint {
+    <#
+    .SYNOPSIS
+        Reads one Codex PreToolUse payload, writes the decision and returns the process exit code.
+    .DESCRIPTION
+        An unreadable envelope writes its reason to stderr and returns 2. A deny
+        writes the PreToolUse decision JSON to stdout and returns 0. An allow writes
+        nothing and returns 0, as the Codex gates do.
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param([Parameter(Mandatory = $false)][AllowNull()][AllowEmptyString()][string]$PayloadRaw)
+
+    $outcome = Invoke-DiscoveryArtifactGateDecision -ToolInputRaw $PayloadRaw
+    # A dependency failure is already the PreToolUse deny decision.
+    if ($outcome -is [System.Collections.IDictionary]) { [Console]::Out.WriteLine(($outcome | ConvertTo-Json -Compress -Depth 5)); return 0 }
+    if ($outcome.Decision -eq 'allow') { return 0 }
+    if ($outcome.Code -eq 'ENVELOPE') {
+        [Console]::Error.WriteLine("$($script:DiscoveryGateReasonPrefix) $($outcome.Reason)")
+        return 2
+    }
+    $decision = ConvertTo-DiscoveryPreToolHookOutput -Outcome $outcome -ReasonPrefix $script:DiscoveryGateReasonPrefix
+    [Console]::Out.WriteLine(($decision | 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 PreToolUse -ReasonPrefix 'DISCOVERY_ARTIFACT_GATE_BLOCKED:'
+if ($null -ne $dependencyDecision) { $dependencyDecision | ConvertTo-Json -Compress -Depth 5 | Write-Output; exit 0 }
+
+exit (Invoke-DiscoveryArtifactGateEntryPoint -PayloadRaw ([Console]::In.ReadToEnd()))