@danmoisan/drm-copilot-mcp 0.0.1

package/resources/claude-customizations/.claude/hooks/check-python-test-purity.ps1

@@ -0,0 +1,146 @@
+<#
+.SYNOPSIS
+    Pre-tool-use hook for Claude Code that blocks forbidden patterns in Python unit tests.
+
+.DESCRIPTION
+    This script is invoked by the Claude Code PreToolUse hook before any Write or Edit
+    operation on a file path matching tests/**/*.py. It reads the tool input from the
+    CLAUDE_TOOL_INPUT environment variable (JSON with 'file_path' and a content field:
+    'content' for Write, 'new_string' for Edit) and rejects the operation when the
+    proposed content introduces forbidden runtime dependencies.
+
+    Forbidden patterns in unit tests include:
+      - temporary filesystem usage (tempfile, NamedTemporaryFile, TemporaryDirectory,
+        mkstemp, mkdtemp, Path.touch)
+      - network access (requests, httpx, urllib.request, socket, http.client)
+      - subprocess execution (subprocess, os.system, os.popen)
+      - time-based flakiness (time.sleep)
+      - real database drivers (psycopg2, pymysql, sqlite3.connect on real files)
+
+    If the content contains any forbidden pattern, the script writes a JSON response
+    to stdout with 'decision': 'block' and exits with code 0 to let Claude Code surface
+    the reason.
+
+.NOTES
+    Compatible with PowerShell 7+.
+    This script must not modify any state; it is a read-only validation gate.
+    It only inspects tool inputs targeting tests/ paths; all other paths pass through.
+#>
+[CmdletBinding()]
+param()
+
+function Get-PythonTestPurityBlockDecision {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Reason
+    )
+
+    [ordered]@{
+        decision = 'block'
+        reason   = $Reason
+    }
+}
+
+function Test-PythonTestFilePath {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $FilePath
+    )
+
+    $normalized = $FilePath -replace '\\', '/'
+    return (($normalized -match '(^|/)tests/.*\.py$') -or ($normalized -match '(^|/)test_[^/]+\.py$'))
+}
+
+function Invoke-PythonTestPurityDecision {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [string] $ToolInputRaw
+    )
+
+    if (-not $ToolInputRaw) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    try {
+        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
+    } catch {
+        return Get-PythonTestPurityBlockDecision -Reason 'Python unit test purity hook received malformed JSON in CLAUDE_TOOL_INPUT.'
+    }
+
+    $filePath = $toolInput.file_path
+    if (-not $filePath) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    if (-not (Test-PythonTestFilePath -FilePath $filePath)) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    $content = $null
+    if ($null -ne $toolInput.content) {
+        $content = [string]$toolInput.content
+    } elseif ($null -ne $toolInput.new_string) {
+        $content = [string]$toolInput.new_string
+    }
+
+    if (-not $content) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    $forbiddenPatterns = @(
+        @{ Pattern = 'import\s+tempfile'; Reason = 'tempfile usage forbidden in unit tests' },
+        @{ Pattern = 'from\s+tempfile\s+import'; Reason = 'tempfile usage forbidden in unit tests' },
+        @{ Pattern = 'NamedTemporaryFile'; Reason = 'temporary files forbidden in unit tests' },
+        @{ Pattern = 'TemporaryDirectory'; Reason = 'temporary directories forbidden in unit tests' },
+        @{ Pattern = '\bmkstemp\s*\('; Reason = 'temporary files forbidden in unit tests' },
+        @{ Pattern = '\bmkdtemp\s*\('; Reason = 'temporary directories forbidden in unit tests' },
+        @{ Pattern = '\.touch\s*\('; Reason = 'Path.touch forbidden in unit tests' },
+        @{ Pattern = 'import\s+requests\b'; Reason = 'network access forbidden in unit tests' },
+        @{ Pattern = 'from\s+requests\b'; Reason = 'network access forbidden in unit tests' },
+        @{ Pattern = 'import\s+httpx\b'; Reason = 'network access forbidden in unit tests' },
+        @{ Pattern = 'from\s+httpx\b'; Reason = 'network access forbidden in unit tests' },
+        @{ Pattern = 'urllib\.request'; Reason = 'network access forbidden in unit tests' },
+        @{ Pattern = 'import\s+socket\b'; Reason = 'raw socket access forbidden in unit tests' },
+        @{ Pattern = 'from\s+http\.client'; Reason = 'network access forbidden in unit tests' },
+        @{ Pattern = 'import\s+subprocess\b'; Reason = 'subprocess execution forbidden in unit tests' },
+        @{ Pattern = 'from\s+subprocess\s+import'; Reason = 'subprocess execution forbidden in unit tests' },
+        @{ Pattern = 'os\.system\s*\('; Reason = 'os.system forbidden in unit tests' },
+        @{ Pattern = 'os\.popen\s*\('; Reason = 'os.popen forbidden in unit tests' },
+        @{ Pattern = 'time\.sleep\s*\('; Reason = 'time.sleep forbidden in unit tests; avoid timing hacks' },
+        @{ Pattern = 'import\s+psycopg2\b'; Reason = 'real database drivers forbidden in unit tests' },
+        @{ Pattern = 'import\s+pymysql\b'; Reason = 'real database drivers forbidden in unit tests' },
+        @{ Pattern = 'sqlite3\.connect\s*\('; Reason = 'sqlite3.connect on real files forbidden in unit tests' }
+    )
+
+    $violations = @()
+    foreach ($entry in $forbiddenPatterns) {
+        if ($content -match $entry.Pattern) {
+            $violations += $entry.Reason
+        }
+    }
+
+    if ($violations.Count -eq 0) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    $uniqueViolations = $violations | Select-Object -Unique
+    $reason = "Python unit test purity violations in '$filePath': " + ($uniqueViolations -join '; ') + ". Replace with pure code paths, dependency-injection seams, or in-memory fakes per .claude/rules/python.md."
+
+    return Get-PythonTestPurityBlockDecision -Reason $reason
+}
+
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+$decision = Invoke-PythonTestPurityDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
+if ($decision.decision -eq 'block') {
+    $decision | ConvertTo-Json -Compress | Write-Output
+}
+
+exit 0

package/resources/claude-customizations/.claude/hooks/enforce-evidence-locations.ps1

@@ -0,0 +1,150 @@
+<#
+.SYNOPSIS
+    Pre-tool-use hook that blocks writes to non-canonical evidence storage locations.
+
+.DESCRIPTION
+    This script is invoked by the Claude Code PreToolUse hook before any Write or Edit
+    operation. It reads the tool input from the CLAUDE_TOOL_INPUT environment variable
+    (JSON with a 'file_path' field) and rejects the operation when the target path is
+    a non-canonical evidence location.
+
+    Forbidden path prefixes (case-sensitive, normalized to forward-slash):
+      - artifacts/baselines/
+      - artifacts/baseline/
+      - artifacts/qa/
+      - artifacts/qa-gates/
+      - artifacts/coverage/
+      - artifacts/evidence/
+      - artifacts/regression-testing/
+      - artifacts/post-change/
+
+    All other paths pass through, including canonical evidence paths of the form
+    <FEATURE>/evidence/<kind>/ and permitted artifacts/ sub-paths such as
+    artifacts/orchestration/, artifacts/research/, artifacts/pr_context,
+    artifacts/reviews/, artifacts/status/, artifacts/python/, artifacts/pester/,
+    and artifacts/csharp/.
+
+    If the file_path resolves to a forbidden prefix, the script writes a JSON response
+    to stdout with 'decision': 'block' and exits with code 0 so Claude Code surfaces
+    the reason. For allowed paths, 'decision': 'allow' is written to stdout and the
+    script exits 0. On hard failure (malformed JSON input), the script exits 1.
+
+.NOTES
+    Compatible with PowerShell 7+.
+    This script must not modify any state; it is a read-only validation gate.
+#>
+[CmdletBinding()]
+param()
+
+function Test-EvidenceLocationForbidden {
+    <#
+    .SYNOPSIS
+        Returns $true when the supplied file path targets a forbidden evidence sub-path.
+    .PARAMETER FilePath
+        The raw file_path value from the Claude Code tool-input JSON.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $FilePath
+    )
+
+    # Normalize separators so both absolute Windows paths and relative POSIX paths match.
+    $normalized = $FilePath -replace '\\', '/'
+
+    $forbiddenPrefixes = @(
+        'artifacts/baselines/',
+        'artifacts/baseline/',
+        'artifacts/qa/',
+        'artifacts/qa-gates/',
+        'artifacts/coverage/',
+        'artifacts/evidence/',
+        'artifacts/regression-testing/',
+        'artifacts/post-change/'
+    )
+
+    # Match the prefix either at the start of the string or after any directory separator,
+    # to handle both relative and absolute path forms.
+    foreach ($prefix in $forbiddenPrefixes) {
+        $escapedPrefix = [regex]::Escape($prefix)
+        if ($normalized -match "(^|/)$escapedPrefix") {
+            return $true
+        }
+    }
+
+    return $false
+}
+
+function Get-EvidenceLocationBlockDecision {
+    <#
+    .SYNOPSIS
+        Constructs a block-decision ordered dictionary for the supplied forbidden path.
+    .PARAMETER FilePath
+        The file path that triggered the block.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $FilePath
+    )
+
+    [ordered]@{
+        decision = 'block'
+        reason   = "EVIDENCE_LOCATION_BLOCKED: '$FilePath' is not a canonical evidence location. Use <FEATURE>/evidence/<kind>/ instead. See .claude/skills/evidence-and-timestamp-conventions/SKILL.md for the canonical scheme."
+    }
+}
+
+function Invoke-EvidenceLocationDecision {
+    <#
+    .SYNOPSIS
+        Parses the Claude Code tool-input JSON and returns an allow-or-block decision.
+    .PARAMETER ToolInputRaw
+        The raw JSON string from $env:CLAUDE_TOOL_INPUT. An empty or null value
+        results in an allow decision (non-file tool calls have no file_path).
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [string] $ToolInputRaw
+    )
+
+    if (-not $ToolInputRaw) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    try {
+        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
+    } catch {
+        # Malformed JSON is a hard failure; caller exits 1 to surface the issue.
+        throw "enforce-evidence-locations hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    }
+
+    $filePath = $toolInput.file_path
+    if (-not $filePath) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    if (Test-EvidenceLocationForbidden -FilePath $filePath) {
+        return Get-EvidenceLocationBlockDecision -FilePath $filePath
+    }
+
+    return [ordered]@{ decision = 'allow' }
+}
+
+# Guard allows dot-sourcing in tests without executing the entrypoint.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+try {
+    $decision = Invoke-EvidenceLocationDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
+} catch {
+    Write-Error $_
+    exit 1
+}
+
+$decision | ConvertTo-Json -Compress | Write-Output
+
+exit 0

package/resources/claude-customizations/.claude/hooks/enforce-powershell-batch-budget.ps1

@@ -0,0 +1,238 @@
+<#
+.SYNOPSIS
+    Pre-tool-use hook that enforces the PowerShell per-batch change budget.
+
+.DESCRIPTION
+    This script is invoked by the Claude Code PreToolUse hook before any Write or Edit
+    operation. When the target file is a PowerShell source file (.ps1, .psm1, .psd1),
+    it classifies the file as either production or test and checks the running count
+    against the per-batch cap:
+      - 3 production PowerShell files per batch
+      - 3 test PowerShell files per batch
+
+    A "batch" is scoped to the current Claude Code session. The running count is
+    persisted under .claude/state/powershell-batch-budget.<session_id>.json. Only
+    distinct file paths are counted; repeated edits to the same file consume one slot.
+
+    Test files are those matching:
+      - tests/**/*.ps1
+      - *.Tests.ps1
+
+    All other .ps1/.psm1/.psd1 files are treated as production files. Non-PowerShell
+    paths pass through.
+
+    The cap may be overridden per session by setting the environment variable
+    CLAUDE_POWERSHELL_BUDGET_PROD or CLAUDE_POWERSHELL_BUDGET_TEST to a positive integer
+    before the session starts, or by writing {"prodCap": N, "testCap": M} into the
+    state file.
+
+    When the cap would be exceeded by a new file, the script emits a JSON response with
+    'decision': 'block' and exits 0. The session must explicitly reset the counter by
+    deleting the state file before starting a new batch. Files already counted are
+    always allowed through.
+
+.NOTES
+    Compatible with PowerShell 7+.
+#>
+[CmdletBinding()]
+param()
+
+function Get-PowerShellBatchBudgetState {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [int] $ProdCap,
+
+        [Parameter(Mandatory)]
+        [int] $TestCap
+    )
+
+    [ordered]@{
+        prodCap   = $ProdCap
+        testCap   = $TestCap
+        prodFiles = @()
+        testFiles = @()
+    }
+}
+
+function ConvertTo-PowerShellBatchBudgetState {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        $InputObject,
+
+        [Parameter(Mandatory)]
+        [int] $ProdCap,
+
+        [Parameter(Mandatory)]
+        [int] $TestCap
+    )
+
+    $state = Get-PowerShellBatchBudgetState -ProdCap $ProdCap -TestCap $TestCap
+    if ($null -ne $InputObject.prodCap) { $state.prodCap = [int]$InputObject.prodCap }
+    if ($null -ne $InputObject.testCap) { $state.testCap = [int]$InputObject.testCap }
+    if ($null -ne $InputObject.prodFiles) { $state.prodFiles = @($InputObject.prodFiles) }
+    if ($null -ne $InputObject.testFiles) { $state.testFiles = @($InputObject.testFiles) }
+
+    return $state
+}
+
+function Get-PowerShellBatchBudgetBlockDecision {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Reason,
+
+        [System.Collections.IDictionary] $State
+    )
+
+    $decision = [ordered]@{
+        decision = 'block'
+        reason   = $Reason
+    }
+    if ($State) {
+        $decision.state = $State
+    }
+
+    return $decision
+}
+
+function Invoke-PowerShellBatchBudgetDecision {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $FilePath,
+
+        [Parameter(Mandatory)]
+        [System.Collections.IDictionary] $State,
+
+        [Parameter(Mandatory)]
+        [string] $StateFile
+    )
+
+    $normalized = $FilePath -replace '\\', '/'
+    if ($normalized -notmatch '\.(ps1|psm1|psd1)$') {
+        return [ordered]@{ decision = 'allow'; state = $State; shouldWriteState = $false }
+    }
+
+    $isTestFile = ($normalized -match '(^|/)tests/.*\.ps1$') -or ($normalized -match '\.Tests\.ps1$')
+    $targetList = if ($isTestFile) { @($State.testFiles) } else { @($State.prodFiles) }
+    $cap = if ($isTestFile) { [int]$State.testCap } else { [int]$State.prodCap }
+    $kind = if ($isTestFile) { 'test' } else { 'production' }
+
+    if ($targetList -contains $normalized) {
+        return [ordered]@{ decision = 'allow'; state = $State; shouldWriteState = $false }
+    }
+
+    if ($targetList.Count -ge $cap) {
+        $currentFiles = ($targetList -join ', ')
+        $kindUpper = $kind.ToUpperInvariant()
+        $reason = "PowerShell per-batch budget exceeded: $kind file cap is $cap and is already full ($currentFiles). Requested new file: $normalized. Split the work into a new batch, raise the cap via CLAUDE_POWERSHELL_BUDGET_$kindUpper environment variable with approved scope, or reset the batch by deleting $StateFile."
+        return Get-PowerShellBatchBudgetBlockDecision -Reason $reason -State $State
+    }
+
+    if ($isTestFile) {
+        $State.testFiles = @($State.testFiles) + @($normalized)
+    } else {
+        $State.prodFiles = @($State.prodFiles) + @($normalized)
+    }
+
+    return [ordered]@{ decision = 'allow'; state = $State; shouldWriteState = $true }
+}
+
+function Invoke-PowerShellBatchBudgetHook {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [string] $ToolInputRaw,
+        [string] $SessionId = 'default',
+        [string] $Root = (Get-Location).Path,
+        [int] $ProdCap = 3,
+        [int] $TestCap = 3,
+        [scriptblock] $TestPathExists = { param([string] $Path) Test-Path -Path $Path },
+        [scriptblock] $EnsureDirectory = { param([string] $Path) New-Item -ItemType Directory -Path $Path -Force | Out-Null },
+        [scriptblock] $ReadState = { param([string] $Path) Get-Content -Path $Path -Raw },
+        [scriptblock] $WriteState = {
+            param([string] $Path, [System.Collections.IDictionary] $State)
+            $State | ConvertTo-Json -Depth 5 | Set-Content -Path $Path -Encoding UTF8
+        }
+    )
+
+    if (-not $ToolInputRaw) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    try {
+        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
+    } catch {
+        return Get-PowerShellBatchBudgetBlockDecision -Reason 'PowerShell batch-budget hook received malformed JSON in CLAUDE_TOOL_INPUT.'
+    }
+
+    $filePath = $toolInput.file_path
+    if (-not $filePath) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    $normalized = $filePath -replace '\\', '/'
+    if ($normalized -notmatch '\.(ps1|psm1|psd1)$') {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    $stateDir = Join-Path -Path $Root -ChildPath '.claude/state'
+    if (-not (& $TestPathExists $stateDir)) {
+        & $EnsureDirectory $stateDir
+    }
+
+    $stateFile = Join-Path -Path $stateDir -ChildPath ("powershell-batch-budget.$SessionId.json")
+    $state = Get-PowerShellBatchBudgetState -ProdCap $ProdCap -TestCap $TestCap
+
+    if (& $TestPathExists $stateFile) {
+        try {
+            $loaded = & $ReadState $stateFile | ConvertFrom-Json -ErrorAction Stop
+            $state = ConvertTo-PowerShellBatchBudgetState -InputObject $loaded -ProdCap $ProdCap -TestCap $TestCap
+        } catch {
+            Write-Verbose "Ignoring unreadable PowerShell batch-budget state file '$stateFile': $($_.Exception.Message)"
+        }
+    }
+
+    $decision = Invoke-PowerShellBatchBudgetDecision -FilePath $filePath -State $state -StateFile $stateFile
+    if ($decision.shouldWriteState) {
+        try {
+            & $WriteState $stateFile $decision.state
+        } catch {
+            Write-Verbose "Unable to write PowerShell batch-budget state file '$stateFile': $($_.Exception.Message)"
+        }
+    }
+
+    return $decision
+}
+
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+$sessionId = $env:CLAUDE_SESSION_ID
+if (-not $sessionId) {
+    $sessionId = 'default'
+}
+
+$prodCap = 3
+$testCap = 3
+if ($env:CLAUDE_POWERSHELL_BUDGET_PROD -match '^\d+$') {
+    $prodCap = [int]$env:CLAUDE_POWERSHELL_BUDGET_PROD
+}
+if ($env:CLAUDE_POWERSHELL_BUDGET_TEST -match '^\d+$') {
+    $testCap = [int]$env:CLAUDE_POWERSHELL_BUDGET_TEST
+}
+
+$decision = Invoke-PowerShellBatchBudgetHook -ToolInputRaw $env:CLAUDE_TOOL_INPUT -SessionId $sessionId -ProdCap $prodCap -TestCap $testCap
+if ($decision.decision -eq 'block') {
+    $decision.Remove('state')
+    $decision | ConvertTo-Json -Compress | Write-Output
+}
+
+exit 0

package/resources/claude-customizations/.claude/hooks/enforce-promotion-mcp-only.ps1

@@ -0,0 +1,147 @@
+<#
+.SYNOPSIS
+    Pre-tool-use hook that blocks Bash promotion-script bypass attempts.
+
+.DESCRIPTION
+    This script is invoked by the Claude Code PreToolUse hook before any Bash
+    command runs. It reads the tool input from the CLAUDE_TOOL_INPUT environment
+    variable, inspects the attempted command text, and blocks direct promotion
+    script execution that would bypass the repository's MCP-only promotion path.
+
+    Forbidden command tokens:
+      - new-potential-entry.ps1
+      - new_potential_bug_entry
+      - potential_to_issue
+      - new_active_feature_folder
+
+    The hook is read-only: it inspects the attempted command and emits a JSON
+    allow-or-block decision without mutating the command text.
+
+.NOTES
+    Compatible with PowerShell 7+.
+#>
+[CmdletBinding()]
+param()
+
+$script:PromotionMcpOnlyBlockedReason = 'PROMOTION_MCP_ONLY_BLOCKED: Direct Bash promotion-script execution is not allowed in agent sessions. Use the drmCopilotExtension MCP promotion tools instead.'
+
+function Get-PromotionMcpOnlyBlockedReason {
+    <#
+    .SYNOPSIS
+        Return the canonical deny message for promotion-script bypass attempts.
+    .OUTPUTS
+        System.String
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param()
+
+    return $script:PromotionMcpOnlyBlockedReason
+}
+
+function Test-PromotionBypassToken {
+    <#
+    .SYNOPSIS
+        Return $true when a Bash command contains a forbidden promotion token.
+    .PARAMETER CommandText
+        The Bash command text extracted from CLAUDE_TOOL_INPUT.
+    .OUTPUTS
+        System.Boolean
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $CommandText
+    )
+
+    # Inspect only the command text so the hook remains a narrow, non-mutating
+    # policy gate for direct promotion-script bypass attempts.
+    $forbiddenTokens = @(
+        'new-potential-entry.ps1',
+        'new_potential_bug_entry',
+        'potential_to_issue',
+        'new_active_feature_folder'
+    )
+
+    foreach ($token in $forbiddenTokens) {
+        if ($CommandText.IndexOf($token, [System.StringComparison]::OrdinalIgnoreCase) -ge 0) {
+            return $true
+        }
+    }
+
+    return $false
+}
+
+function Get-PromotionMcpOnlyBlockDecision {
+    <#
+    .SYNOPSIS
+        Construct the structured block decision for a forbidden Bash command.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param()
+
+    return [ordered]@{
+        decision = 'block'
+        reason   = (Get-PromotionMcpOnlyBlockedReason)
+    }
+}
+
+function Invoke-PromotionMcpOnlyDecision {
+    <#
+    .SYNOPSIS
+        Parse CLAUDE_TOOL_INPUT and return an allow-or-block decision.
+    .PARAMETER ToolInputRaw
+        The raw JSON tool payload supplied by Claude Code.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary
+    .NOTES
+        Missing tool input or missing command text is treated as allow because
+        non-Bash invocations or empty Bash requests cannot bypass promotion flow.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [string] $ToolInputRaw
+    )
+
+    if (-not $ToolInputRaw) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    try {
+        $toolInput = $ToolInputRaw | ConvertFrom-Json -ErrorAction Stop
+    } catch {
+        throw "enforce-promotion-mcp-only hook received malformed JSON in CLAUDE_TOOL_INPUT: $_"
+    }
+
+    $commandText = $toolInput.command
+    if (-not $commandText) {
+        return [ordered]@{ decision = 'allow' }
+    }
+
+    if (Test-PromotionBypassToken -CommandText $commandText) {
+        return Get-PromotionMcpOnlyBlockDecision
+    }
+
+    return [ordered]@{ decision = 'allow' }
+}
+
+# Allow dot-sourcing in tests without executing the entrypoint.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+try {
+    $decision = Invoke-PromotionMcpOnlyDecision -ToolInputRaw $env:CLAUDE_TOOL_INPUT
+} catch {
+    Write-Error $_
+    exit 1
+}
+
+$decision | ConvertTo-Json -Compress | Write-Output
+
+exit 0