@danmoisan/drm-copilot-mcp 1.0.11 → 1.0.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danmoisan/drm-copilot-mcp",
-  "version": "1.0.11",
+  "version": "1.0.14",
   "description": "Stdio MCP server exposing drm-copilot repo-automation tools.",
   "license": "MIT",
   "type": "commonjs",

package/resources/claude-customizations/.claude/agents/epic-orchestrator.md

@@ -63,7 +63,31 @@ On every invocation:
    `git branch`, and `gh pr view --json state,mergedAt,headRefOid` per the `epic-orchestrate`
    skill's resume procedure, not from in-memory notifications alone).
 5. If no checkpoint exists or the objective is new, begin from manifest parsing
-   (`docs/features/epics/<epic-slug>/epic-plan.md`).
+   (`docs/features/epics/<epic-slug>/epic.md`).
+
+## Invocation Origin
+
+You are invoked from the main session — via `/epic-orchestrate <epic-manifest-path>`, via
+`/epic-run <epic-slug>` (which replays the kickoff artifact `epic-planner` emitted), or by a
+direct prompt. You delegate to `Agent(orchestrator)`, so an invocation that itself
+originates from an `orchestrator` agent would nest `orchestrator` inside its own delegation
+chain; the PreToolUse hook `.claude/hooks/enforce-epic-invocation-origin.ps1` denies any
+`Agent(epic-orchestrator)` or `Agent(epic-planner)` call whose calling agent is `orchestrator`
+(`EPIC_INVOCATION_ORIGIN_BLOCKED`).
+
+## Prepared-Epic Execution (epic-planner Handoff)
+
+When the epic was prepared by `epic-planner` (the integration branch already exists and
+`docs/features/epics/<epic-slug>/epic-kickoff.md` is present), each child feature folder already
+contains its issue, research, `spec.md`, `user-story.md`, an approved atomic plan, and a
+recorded preflight clearance. In that case:
+
+1. Do not recreate the integration branch; fetch and reuse it.
+2. Each child `Agent(orchestrator)` delegation prompt cites the child's committed `plan-path`
+   and instructs the run to resume at atomic execution from that plan rather than re-running
+   promotion, research, or planning.
+3. The wave barrier, merge-on-green fan-in, and final integration-to-`main` PR proceed
+   unchanged per the `epic-orchestrate` skill.
 
 ## Delegation Model
 
@@ -112,8 +136,9 @@ route's required names from `config/orchestration-routing.json`.
 Maintain `docs/features/epics/<epic-slug>/epic-status.md` as a human-readable projection of the
 epic checkpoint's `features[]` array, regenerated (not hand-edited) at epic kickoff, at every
 `merge_status` transition, at every wave transition, and at final integration-PR completion, per
-the `epic-orchestrate` skill's documentation-maintenance procedure. `epic-plan.md` itself (the
-manifest) is treated as static, human-authored input and is not rewritten by you.
+the `epic-orchestrate` skill's documentation-maintenance procedure. `epic.md` itself (the merged
+manifest + narrative source of truth) is treated as static, human-authored input and is not
+rewritten by you; `epic-status.md` is a generated projection only and is never hand-authored.
 
 ## Completion Requirements
 

package/resources/claude-customizations/.claude/agents/epic-planner.md

@@ -0,0 +1,121 @@
+---
+name: epic-planner
+model: opus
+description: Epic-scale planning agent that fully scopes an epic before any execution. It decomposes the objective into child features, computes the dependency graph and wave layering, assesses per-feature complexity, drives per-feature preparation (promotion, research, spec/user-story, atomic plan, preflight clearance) through parallel preparation-mode Agent(orchestrator) delegations, commits all planning outputs to the epic integration branch, and emits the epic-orchestrator kickoff prompt artifact. Performs no atomic execution. Must not be invoked from an orchestrator agent (enforced by enforce-epic-invocation-origin.ps1).
+tools:
+  - "Agent(orchestrator)"
+  - Read
+  - Grep
+  - Glob
+  - "Write(docs/features/epics/**)"
+  - "Edit(docs/features/epics/**)"
+  - "Write(artifacts/orchestration/**)"
+  - "Edit(artifacts/orchestration/**)"
+  - "Bash(git *)"
+  - "Bash(gh *)"
+  - "mcp__drm-copilot__validate_orchestration_artifacts"
+skills:
+  - policy-compliance-order
+  - epic-plan
+  - epic-orchestrate
+  - feature-promotion-lifecycle
+  - atomic-plan-contract
+  - evidence-and-timestamp-conventions
+memory: project
+---
+
+# Epic Planner Agent
+
+You are the epic-scale planning agent. You take an epic-sized objective from raw intent to a
+fully prepared, execution-ready state without performing any execution. You are distinct from
+`.claude/agents/epic-orchestrator.md`: `epic-orchestrator` schedules and executes an already
+planned epic; you produce that plan. Your terminal deliverable is a committed epic integration
+branch containing the epic manifest, one prepared feature folder per child feature (issue,
+research, spec, user-story, approved atomic plan, preflight clearance), and a kickoff prompt
+artifact the user replays to launch `epic-orchestrator` on command.
+
+## Skill
+
+Apply the `epic-plan` skill (`.claude/skills/epic-plan/SKILL.md`) as the canonical procedure for
+the epic-worthiness gate, decomposition, wave computation, complexity assessment, the
+integration-branch lifecycle, preparation-mode child delegation, fan-in of prepared work, the
+kickoff-prompt artifact, and checkpoint persistence. This agent frames the *who* and *when*; the
+skill documents the *how* in full. The epic manifest schema and wave-assignment formula are
+defined once in the `epic-orchestrate` skill and are consumed here, not redefined.
+
+## Invocation Origin
+
+You are invoked from the main session only. You delegate to `Agent(orchestrator)`, so an
+invocation that itself originates from an `orchestrator` agent would nest `orchestrator` inside
+its own delegation chain; the PreToolUse hook
+`.claude/hooks/enforce-epic-invocation-origin.ps1` denies any `Agent(epic-planner)` or
+`Agent(epic-orchestrator)` call whose calling agent is `orchestrator`
+(`EPIC_INVOCATION_ORIGIN_BLOCKED`).
+
+## Startup Protocol
+
+On every invocation:
+
+1. Read `CLAUDE.md` for repository tone policy and architecture context.
+2. Read applicable `.claude/rules/` files for languages in scope.
+3. Read `artifacts/orchestration/epic-planner-state.json` to check for existing planning
+   checkpoint state.
+4. If a valid checkpoint exists with a matching objective, resume from the recorded `next_step`,
+   re-deriving durable ground truth from the integration branch, the epic manifest, and the
+   prepared feature folders rather than from in-memory notifications alone.
+5. If no checkpoint exists or the objective is new, begin from the epic-worthiness gate.
+
+## Epic-Worthiness Gate
+
+Your first planning action is to assess whether the objective warrants an epic at all, per the
+`epic-plan` skill's criteria (independent child-feature count and per-feature change budget).
+When the objective does not warrant an epic, report that finding to the user with the rationale
+and offer to delegate the work directly to a single `Agent(orchestrator)` run as one feature.
+Do not build epic scaffolding for a single-feature objective; proceed to epic planning only when
+the gate passes or the user directs you to.
+
+## Delegation Model
+
+You delegate exclusively through `Agent(orchestrator)`, one delegation per child feature, each
+carrying the preparation-mode kickoff line defined in the `epic-plan` skill. Each child
+`orchestrator` runs promotion, research, feature documents, atomic planning, and preflight
+clearance under `route_id: preparation`, then stops before any execution. You do not delegate
+directly to `atomic-planner`, `atomic-executor`, `task-researcher`, or `prd-feature`; those
+delegations belong to each child's own `orchestrator` instance. You never delegate to
+`Agent(epic-orchestrator)`; executing the plan is the user's explicit next command.
+
+## Integration Branch
+
+All planning outputs are committed to the epic integration branch
+(`epic/<epic-slug>-integration`, created off `origin/main` if absent), so `epic-orchestrator`
+can later execute against the exact planned state. The branch lifecycle and fan-in procedure are
+defined in the `epic-plan` skill.
+
+## Kickoff Prompt Artifact
+
+At completion you write the epic-orchestrator kickoff prompt to
+`artifacts/orchestration/epic-kickoff-<epic-slug>.md` and commit a durable copy at
+`docs/features/epics/<epic-slug>/epic-kickoff.md` (the `artifacts/` tree is gitignored). The
+artifact contains the exact prompt the user replays to launch `Agent(epic-orchestrator)` against
+the prepared epic, per the template in the `epic-plan` skill.
+
+## Checkpoint Persistence
+
+Update `artifacts/orchestration/epic-planner-state.json` after every completed step with:
+`objective`, `epic_feature_folder`, `epic_manifest_path`, `integration_branch`,
+`epic_worthiness` (`{verdict, rationale}`), `features[]` (per-feature `issue_num`,
+`feature_folder`, `depends_on`, `wave`, `complexity_band`, `preparation_status`, `plan_path`,
+`preflight_status`), `kickoff_prompt_path`, `completed_steps`, `next_step`, and `last_updated`.
+
+## Completion Requirements
+
+Do not report completion until:
+
+1. The epic manifest at `docs/features/epics/<epic-slug>/epic.md` parses against the
+   `epic-orchestrate` schema with a cycle-free dependency graph.
+2. Every child feature has an issue, an active feature folder, research, `spec.md`,
+   `user-story.md`, an approved atomic plan, and a recorded `PREFLIGHT: ALL CLEAR`.
+3. All planning outputs are committed and pushed on the integration branch.
+4. The kickoff prompt artifact exists at both paths listed above.
+5. The final report lists each feature's `plan-path:` and preflight status, plus the kickoff
+   artifact path.

package/resources/claude-customizations/.claude/agents/orchestrator.md

@@ -4,7 +4,6 @@ model: opus
 description: Deterministic repository orchestrator that estimates change budget, selects small or large workflow path, delegates to specialist subagents, persists checkpoint state, and enforces completion gates proactively.
 tools:
   - "Agent(atomic-planner,atomic-executor,feature-review,task-researcher,prd-feature,staged-review,epic-review,status-updater,pr-author,commit-message,human-exception-runbook,python-typed-engineer,powershell-typed-engineer,csharp-typed-engineer,typescript-engineer)"
-  - "Agent(epic-orchestrator)"
   - Read
   - Grep
   - Glob
@@ -75,7 +74,8 @@ The first action is always to estimate the change budget by identifying likely a
 
 - **Small path** (1–3 production files + corresponding tests): promotion, active folder, minimal plan, implementation, QC, small-audit review.
 - **Large path** (4+ production files or cross-cutting changes): scope, promotion, research, spec, atomic planning, atomic execution, feature review.
-- **Epic path**: the objective names or references an epic manifest (`docs/features/epics/<epic-slug>/epic-plan.md`) or explicitly requests multi-feature/epic orchestration. On this outcome the orchestrator delegates to `Agent(epic-orchestrator)` with the manifest path, instead of running change-budget/small/large routing itself.
+- **Epic outcome**: the objective names or references an epic manifest (`docs/features/epics/<epic-slug>/epic.md`) or explicitly requests multi-feature/epic orchestration. On this outcome the orchestrator does not route the work itself and does not delegate it: it halts and reports that epic-scale objectives are invoked from the main session — `Agent(epic-planner)` for planning, `Agent(epic-orchestrator)` for execution. The orchestrator never invokes either epic agent; both delegate to `Agent(orchestrator)`, so an orchestrator-originated invocation would nest orchestrator inside its own delegation chain, and the PreToolUse hook `enforce-epic-invocation-origin.ps1` denies it (`EPIC_INVOCATION_ORIGIN_BLOCKED`).
+- **Preparation mode (epic planning)**: the delegation prompt carries the literal marker `Preparation mode: true` (issued by `epic-planner` per the `epic-plan` skill). The orchestrator selects `route_id: preparation` and runs promotion, research, feature documents, atomic planning, and the atomic-executor preflight only, per `## Preparation Mode` in `.claude/skills/orchestrate/SKILL.md`. It stops after `PREFLIGHT: ALL CLEAR` with `next_step: "S5_atomic_execution"`, out-of-scope step statuses `not-applicable`, and no completion assertion; atomic execution, PR authoring, and CI monitoring are out of scope for the run.
 
 ## Delegation Model
 

package/resources/claude-customizations/.claude/hooks/enforce-epic-invocation-origin.ps1

@@ -0,0 +1,246 @@
+<#
+.SYNOPSIS
+    Pre-tool-use hook that blocks epic-planner and epic-orchestrator delegations
+    originating from an orchestrator agent.
+
+.DESCRIPTION
+    Invoked by the Claude Code PreToolUse hook on the "Agent" matcher before any
+    Agent (Task) call runs. Activates only when the delegation target
+    subagent_type is 'epic-planner' or 'epic-orchestrator'.
+
+    Caller identity resolution:
+      - The full PreToolUse payload (CLAUDE_HOOK_INPUT) carries a top-level
+        'agent_type' field only when the tool call is made from inside a
+        subagent context. A main-thread call carries no 'agent_type'.
+      - The Agent tool input (CLAUDE_TOOL_INPUT, or the payload's 'tool_input'
+        object) carries the delegation target 'subagent_type'.
+
+    Decision procedure:
+      1. Resolve the target subagent_type from CLAUDE_TOOL_INPUT, falling back
+         to the payload's tool_input object. A non-epic target allows.
+      2. Resolve the calling agent_type from the payload. An absent or empty
+         agent_type indicates a main-thread invocation, which allows.
+      3. Deny with reason EPIC_INVOCATION_ORIGIN_BLOCKED when the calling
+         agent_type is exactly 'orchestrator'. Both epic agents delegate to
+         Agent(orchestrator); an orchestrator-originated invocation would nest
+         orchestrator inside its own delegation chain.
+
+.NOTES
+    Compatible with PowerShell 7+. No external module dependencies. Read-only
+    validation gate; malformed JSON in either payload throws so the entrypoint
+    exits 1.
+#>
+[CmdletBinding()]
+param()
+
+$script:GatedSubagentTypes = @('epic-planner', 'epic-orchestrator')
+$script:ProhibitedCallerAgentType = 'orchestrator'
+
+function Get-EpicInvocationOriginAllowDecision {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param()
+
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName      = 'PreToolUse'
+            permissionDecision = 'allow'
+        }
+    }
+}
+
+function Get-EpicInvocationOriginBlockDecision {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Reason
+    )
+
+    return [ordered]@{
+        hookSpecificOutput = [ordered]@{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = $Reason
+        }
+    }
+}
+
+function ConvertFrom-EpicInvocationOriginPayload {
+    <#
+    .SYNOPSIS
+        Parses a raw JSON payload string, returning $null for a blank payload
+        and throwing a named error for malformed JSON.
+    .PARAMETER RawPayload
+        The raw JSON text under evaluation.
+    .PARAMETER PayloadName
+        The payload's environment-variable name, used in the error message.
+    .OUTPUTS
+        System.Object or $null
+    #>
+    [CmdletBinding()]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $RawPayload,
+
+        [Parameter(Mandatory)]
+        [string] $PayloadName
+    )
+
+    if ([string]::IsNullOrWhiteSpace($RawPayload)) {
+        return $null
+    }
+
+    try {
+        return $RawPayload | ConvertFrom-Json -ErrorAction Stop
+    } catch {
+        throw "enforce-epic-invocation-origin hook received malformed JSON in ${PayloadName}: $_"
+    }
+}
+
+function Get-EpicInvocationOriginTargetSubagent {
+    <#
+    .SYNOPSIS
+        Resolves the delegation target subagent_type from the tool input,
+        falling back to the full payload's tool_input object.
+    .PARAMETER ToolInput
+        Parsed CLAUDE_TOOL_INPUT object, or $null when absent.
+    .PARAMETER HookInput
+        Parsed CLAUDE_HOOK_INPUT object, or $null when absent.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [AllowNull()]
+        $ToolInput,
+
+        [AllowNull()]
+        $HookInput
+    )
+
+    if ($null -ne $ToolInput -and
+        (@($ToolInput.PSObject.Properties.Name) -contains 'subagent_type') -and
+        -not [string]::IsNullOrWhiteSpace([string]$ToolInput.subagent_type)) {
+        return [string]$ToolInput.subagent_type
+    }
+
+    if ($null -ne $HookInput -and
+        (@($HookInput.PSObject.Properties.Name) -contains 'tool_input')) {
+        $nested = $HookInput.tool_input
+        if ($null -ne $nested -and
+            (@($nested.PSObject.Properties.Name) -contains 'subagent_type') -and
+            -not [string]::IsNullOrWhiteSpace([string]$nested.subagent_type)) {
+            return [string]$nested.subagent_type
+        }
+    }
+
+    return $null
+}
+
+function Get-EpicInvocationOriginCallerAgentType {
+    <#
+    .SYNOPSIS
+        Resolves the calling agent_type from the full hook payload. Returns
+        $null for a main-thread invocation (no agent_type field).
+    .PARAMETER HookInput
+        Parsed CLAUDE_HOOK_INPUT object, or $null when absent.
+    .OUTPUTS
+        System.String or $null
+    #>
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [AllowNull()]
+        $HookInput
+    )
+
+    if ($null -eq $HookInput) {
+        return $null
+    }
+    if (@($HookInput.PSObject.Properties.Name) -notcontains 'agent_type') {
+        return $null
+    }
+
+    $agentType = [string]$HookInput.agent_type
+    if ([string]::IsNullOrWhiteSpace($agentType)) {
+        return $null
+    }
+    return $agentType
+}
+
+function Invoke-EpicInvocationOriginDecision {
+    <#
+    .SYNOPSIS
+        Parses the hook payloads and returns an allow-or-block decision.
+    .PARAMETER HookInputRaw
+        The raw full PreToolUse payload JSON supplied via CLAUDE_HOOK_INPUT.
+    .PARAMETER ToolInputRaw
+        The raw Agent tool input JSON supplied via CLAUDE_TOOL_INPUT.
+    .OUTPUTS
+        System.Collections.Specialized.OrderedDictionary
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $HookInputRaw,
+
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $ToolInputRaw
+    )
+
+    # The tool input identifies the delegation target; a non-epic target is
+    # outside this hook's scope, so the hook input is not parsed for it.
+    $toolInput = ConvertFrom-EpicInvocationOriginPayload -RawPayload $ToolInputRaw -PayloadName 'CLAUDE_TOOL_INPUT'
+    $hookInputParsed = $false
+    $hookInput = $null
+
+    $target = Get-EpicInvocationOriginTargetSubagent -ToolInput $toolInput -HookInput $hookInput
+    if (-not $target -and -not [string]::IsNullOrWhiteSpace($HookInputRaw)) {
+        # Fallback: some harness surfaces supply only the full payload, whose
+        # tool_input object carries the target subagent_type.
+        $hookInput = ConvertFrom-EpicInvocationOriginPayload -RawPayload $HookInputRaw -PayloadName 'CLAUDE_HOOK_INPUT'
+        $hookInputParsed = $true
+        $target = Get-EpicInvocationOriginTargetSubagent -ToolInput $toolInput -HookInput $hookInput
+    }
+
+    if (-not $target -or $script:GatedSubagentTypes -notcontains $target) {
+        return Get-EpicInvocationOriginAllowDecision
+    }
+
+    if (-not $hookInputParsed) {
+        $hookInput = ConvertFrom-EpicInvocationOriginPayload -RawPayload $HookInputRaw -PayloadName 'CLAUDE_HOOK_INPUT'
+    }
+
+    # An absent agent_type marks a main-thread invocation, which is the
+    # intended entry point for both epic agents; only an orchestrator-context
+    # invocation is prohibited.
+    $caller = Get-EpicInvocationOriginCallerAgentType -HookInput $hookInput
+    if ($caller -ne $script:ProhibitedCallerAgentType) {
+        return Get-EpicInvocationOriginAllowDecision
+    }
+
+    $reason = "EPIC_INVOCATION_ORIGIN_BLOCKED: Agent($target) must not be invoked from an orchestrator agent. Both epic-planner and epic-orchestrator delegate to Agent(orchestrator), so an orchestrator-originated invocation would nest orchestrator inside its own delegation chain. Invoke $target from the main session instead."
+    return Get-EpicInvocationOriginBlockDecision -Reason $reason
+}
+
+# Guard allows dot-sourcing in tests without executing the entrypoint.
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+try {
+    $decision = Invoke-EpicInvocationOriginDecision -HookInputRaw $env:CLAUDE_HOOK_INPUT -ToolInputRaw $env:CLAUDE_TOOL_INPUT
+} catch {
+    Write-Error $_
+    exit 1
+}
+
+$decision | ConvertTo-Json -Compress -Depth 5 | Write-Output
+
+exit 0

package/resources/claude-customizations/.claude/hooks/persist-session-id.ps1

@@ -0,0 +1,153 @@
+<#
+.SYNOPSIS
+    SessionStart hook that persists the current Claude Code session id.
+
+.DESCRIPTION
+    Invoked by the Claude Code SessionStart hook event (registered in
+    .claude/settings.json). Reads the hook payload JSON from standard input,
+    falling back to the CLAUDE_HOOK_INPUT environment variable (the existing
+    SubagentStop-hook precedent), and extracts the 'session_id' field.
+
+    Persistence channel:
+      - When CLAUDE_ENV_FILE is set, appends the line
+        'CLAUDE_SESSION_ID=<id>' to that file. Variables persisted there are
+        exported to subsequent Bash tool commands in the session, which is how
+        this hook provisions the otherwise-unset CLAUDE_SESSION_ID variable.
+      - When CLAUDE_ENV_FILE is unset, writes the id to
+        .claude/state/current-session-id instead.
+
+    On malformed or empty input (missing/blank payload, unparseable JSON, or an
+    absent/blank session_id) the hook performs no write. It always exits 0 so a
+    SessionStart hook never blocks session start.
+
+.NOTES
+    Compatible with PowerShell 7+. Does not use Invoke-Expression.
+#>
+[CmdletBinding()]
+param()
+
+function Get-PersistSessionIdDecision {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [string] $RawPayload,
+
+        [string] $EnvFilePath,
+
+        [Parameter(Mandatory)]
+        [string] $StateFilePath
+    )
+
+    $none = [ordered]@{ action = 'none'; sessionId = ''; path = '' }
+
+    if ([string]::IsNullOrWhiteSpace($RawPayload)) {
+        return $none
+    }
+
+    try {
+        $payload = $RawPayload | ConvertFrom-Json -ErrorAction Stop
+    } catch {
+        Write-Verbose "persist-session-id: ignoring unparseable payload: $($_.Exception.Message)"
+        return $none
+    }
+
+    $sessionId = $null
+    if ($null -ne $payload -and $payload.PSObject.Properties.Name -contains 'session_id') {
+        $sessionId = [string]$payload.session_id
+    }
+
+    if ([string]::IsNullOrWhiteSpace($sessionId)) {
+        return $none
+    }
+
+    if (-not [string]::IsNullOrWhiteSpace($EnvFilePath)) {
+        return [ordered]@{ action = 'env-file'; sessionId = $sessionId; path = $EnvFilePath }
+    }
+
+    return [ordered]@{ action = 'state-file'; sessionId = $sessionId; path = $StateFilePath }
+}
+
+function Invoke-PersistSessionIdHook {
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [string] $RawPayload,
+
+        [string] $EnvFilePath,
+
+        [Parameter(Mandatory)]
+        [string] $StateFilePath,
+
+        [scriptblock] $AppendLine = {
+            param([string] $Path, [string] $Line)
+            Add-Content -Path $Path -Value $Line -Encoding utf8
+        },
+
+        [scriptblock] $WriteStateFile = {
+            param([string] $Path, [string] $Content)
+            Set-Content -Path $Path -Value $Content -Encoding utf8 -NoNewline
+        },
+
+        [scriptblock] $EnsureDirectory = {
+            param([string] $Path)
+            if (-not (Test-Path -Path $Path)) {
+                New-Item -ItemType Directory -Path $Path -Force | Out-Null
+            }
+        }
+    )
+
+    $decision = Get-PersistSessionIdDecision -RawPayload $RawPayload -EnvFilePath $EnvFilePath -StateFilePath $StateFilePath
+
+    switch ($decision.action) {
+        'env-file' {
+            & $AppendLine $decision.path ("CLAUDE_SESSION_ID={0}" -f $decision.sessionId)
+        }
+        'state-file' {
+            $stateDir = Split-Path -Path $decision.path -Parent
+            if ($stateDir) {
+                & $EnsureDirectory $stateDir
+            }
+            & $WriteStateFile $decision.path $decision.sessionId
+        }
+        default {
+            # 'none': malformed or empty input; perform no write.
+        }
+    }
+
+    return $decision
+}
+
+function Read-HookPayload {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [scriptblock] $ReadStandardInput = { [Console]::In.ReadToEnd() },
+
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $FallbackPayload = $env:CLAUDE_HOOK_INPUT
+    )
+
+    $raw = ''
+    try {
+        $raw = & $ReadStandardInput
+    } catch {
+        $raw = ''
+    }
+
+    if ([string]::IsNullOrWhiteSpace($raw)) {
+        return $FallbackPayload
+    }
+
+    return $raw
+}
+
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+$rawPayload = Read-HookPayload
+$stateFilePath = Join-Path -Path (Get-Location).Path -ChildPath '.claude/state/current-session-id'
+Invoke-PersistSessionIdHook -RawPayload $rawPayload -EnvFilePath $env:CLAUDE_ENV_FILE -StateFilePath $stateFilePath | Out-Null
+
+exit 0

package/resources/claude-customizations/.claude/settings.json

@@ -1,6 +1,5 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-settings.json",
-  "agent": "orchestrator",
   "permissions": {
     "allow": [
       "Bash(git *)",
@@ -22,6 +21,7 @@
       "mcp__drm-copilot__new_active_feature_folder",
       "mcp__drm-copilot__validate_orchestration_artifacts",
       "mcp__drm-copilot__resolve_atomic_plan_prompt",
+      "mcp__drm-copilot__render_subagent_tree",
       "Agent(atomic-planner)",
       "Agent(atomic-executor)",
       "Agent(feature-review)",
@@ -38,7 +38,11 @@
       "Agent(csharp-typed-engineer)",
       "Agent(typescript-engineer)",
       "Agent(epic-orchestrator)",
+      "Agent(epic-planner)",
       "Skill(orchestrate *)",
+      "Skill(epic-plan *)",
+      "Skill(epic-orchestrate *)",
+      "Skill(epic-run *)",
       "Skill(commit-message *)",
       "Skill(pr-author *)",
       "Skill(research-issue *)",
@@ -55,6 +59,8 @@
       "Skill(invoke-powershell-engineer *)",
       "Skill(translate-copilot-to-claude *)",
       "Skill(execute-hard-lock *)",
+      "Skill(identify-session-id *)",
+      "Skill(show-my-agent-tree *)",
       "Edit(/.claude/skills/execute-hard-lock/**)",
       "Edit(/.claude/skills/feature-review-workflow/**)",
       "Edit(/.claude/skills/csharp-qa-gate/**)"
@@ -71,6 +77,16 @@
     ]
   },
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File .claude/hooks/persist-session-id.ps1"
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "Bash",
@@ -160,13 +176,17 @@
           {
             "type": "command",
             "command": "pwsh -NoProfile -File .claude/hooks/enforce-model-routing-receipt.ps1"
+          },
+          {
+            "type": "command",
+            "command": "pwsh -NoProfile -File .claude/hooks/enforce-epic-invocation-origin.ps1"
           }
         ]
       }
     ],
     "SubagentStop": [
       {
-        "matcher": "atomic-planner|atomic-executor|feature-review|task-researcher|prd-feature|staged-review|epic-review|status-updater|python-typed-engineer|powershell-typed-engineer|csharp-typed-engineer|typescript-engineer|orchestrator|epic-orchestrator",
+        "matcher": "atomic-planner|atomic-executor|feature-review|task-researcher|prd-feature|staged-review|epic-review|status-updater|python-typed-engineer|powershell-typed-engineer|csharp-typed-engineer|typescript-engineer|orchestrator|epic-orchestrator|epic-planner",
         "hooks": [
           {
             "type": "command",