@mutagent/helix 0.1.0-alpha.14

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/wireframes/diagnostics/WF-2.1-nl-query.md

@@ -0,0 +1,59 @@
+# WF-2.1 — Natural Language Query Entry
+
+> Entry point for a diagnostics run.
+> User states what they want in plain language; skill translates to TraceFilter.
+
+## Trigger
+
+User says: "run diagnostics", "diagnose my agents", "why is my agent failing?",
+"check last week's agent sessions", etc.
+
+## Display
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  mutagent-diagnostics — Running                             │
+│                                                             │
+│  What would you like to diagnose?                           │
+│  (or press Enter to use defaults from config.yaml)          │
+│                                                             │
+│  Examples:                                                  │
+│  • "Why did my search agent fail last week?"                │
+│  • "Show me sessions with negative feedback"                │
+│  • "Analyze errors from yesterday"                          │
+│  • "Check the checkout-agent sessions"                      │
+│                                                             │
+│  > _                                                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## NL → TraceFilter Translation
+
+The orchestrator translates the query:
+
+| NL Fragment | TraceFilter Field |
+|-------------|------------------|
+| "last week" | `time_window.from = "7daysAgo"` |
+| "yesterday" | `time_window.from = "1daysAgo"` |
+| "errors" / "failed" | `has_error = true` |
+| "negative feedback" | `has_feedback = true, score_below = <auto-discovered>` |
+| "search agent" | `agent_id = "search-agent"` |
+| (empty / Enter) | use `config.yaml` defaults |
+
+## After Translation
+
+Show confirmation before running:
+
+```
+  Interpreted as:
+  • Time window: last 7 days
+  • Filter: errors only
+  • Agent: all agents
+  • Limit: 100 traces
+
+  [1] Run with these filters
+  [2] Adjust filters
+  [3] Cancel
+```
+
+→ On confirm: proceed to WF-2.2 (tier-0 scan progress)

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/wireframes/diagnostics/WF-2.2-tier0-progress.md

@@ -0,0 +1,58 @@
+# WF-2.2 — Tier-0 Scan Progress
+
+> Displayed while tier-0-scan.ts runs (CODE-FIRST pre-LLM analysis).
+> This runs before any LLM call — fast, deterministic.
+
+## Display (In Progress)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Running diagnostics...                                     │
+│                                                             │
+│  [1/4] Fetching traces from langfuse...        ████░░ 62%  │
+│  [2/4] Tier-0 scan (pre-LLM)...               ░░░░░░  0%  │
+│  [3/4] Deep analysis (LLM)...                 pending      │
+│  [4/4] Rendering report...                    pending      │
+│                                                             │
+│  Fetched 73 trace metadata records                         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Display (After Tier-0 Scan)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Running diagnostics...                                     │
+│                                                             │
+│  [1/4] Fetching traces...                     ████████ done │
+│  [2/4] Tier-0 scan (pre-LLM)...               ████████ done │
+│  [3/4] Deep analysis (LLM)...                 ████░░░░  55%│
+│  [4/4] Rendering report...                    pending      │
+│                                                             │
+│  Tier-0 findings:                                           │
+│  • Error spike: 12 errors in last 2h (threshold: 3)        │
+│  • Latency spike: p95 = 45s (threshold: 15s)               │
+│  • Analyzing 4 trace clusters (cap: 5)                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Tier-0 Pattern Summary (shown after step 2)
+
+| Pattern | Found | Value |
+|---------|-------|-------|
+| P-001 Error spike | Yes | 12 errors / 2h (threshold: 3) |
+| P-002 Latency spike | Yes | p95=45s (threshold: 15s) |
+| P-003 Feedback cluster | No | — |
+
+## Slice Plan Display
+
+```
+  Slice plan (cap=5):
+  Cluster 1: 8 error traces (2026-05-27 10:00–12:00)
+  Cluster 2: 5 high-latency traces
+  Cluster 3: 3 negative-feedback traces
+  Cluster 4: 2 remaining samples
+  → 4 clusters queued (under cap of 5)
+```
+
+→ Proceeds automatically to WF-2.3 (LLM analysis running)

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/wireframes/diagnostics/WF-2.3-analysis-progress.md

@@ -0,0 +1,44 @@
+# WF-2.3 — LLM Analysis Progress
+
+> Displayed while diagnostics-analyzer sub-agents run in parallel (cap: 5).
+> Each cluster is analyzed by one sub-agent.
+
+## Display (Parallel Execution)
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Deep analysis running (4 clusters, cap=5)                  │
+│                                                             │
+│  Cluster 1 [errors, 8 traces]        ████████ complete     │
+│  Cluster 2 [latency, 5 traces]       ████░░░░ tier-2...    │
+│  Cluster 3 [feedback, 3 traces]      ██░░░░░░ tier-1...    │
+│  Cluster 4 [sample, 2 traces]        ░░░░░░░░ queued       │
+│                                                             │
+│  Findings so far: 3 critical, 1 warning                     │
+│  Budget: 142s elapsed / 240s cap                           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Analysis Tiers (shown in progress labels)
+
+| Label | Tier |
+|-------|------|
+| "tier-0..." | Pre-LLM pattern scan |
+| "tier-1..." | Known pattern matching |
+| "tier-2..." | Tree-based structural analysis |
+| "tier-3..." | Deep structural (LLM) |
+| "tier-4..." | LLM deviation detection |
+| "complete" | All tiers done for this cluster |
+
+## Budget Exhaustion Warning
+
+If budget cap (240s) is reached before all clusters complete:
+```
+  ⚠ Analysis budget reached (240s). 1 cluster not fully analyzed.
+  Partial findings included in report.
+
+  [1] View partial report
+  [2] Resume analysis (run again with narrower scope)
+```
+
+→ On all clusters complete: proceed to WF-2.4 (report HTML)

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/wireframes/diagnostics/WF-2.4-html-report.md

@@ -0,0 +1,61 @@
+# WF-2.4 — HTML Report + Findings
+
+> Primary output of a diagnostics run.
+> Rendered via `scripts/report/render.ts` using `assets/templates/report.html.tpl`.
+
+## Layout
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  mutagent-diagnostics — Report                                  │
+│  Generated: 2026-05-27 10:42 | Source: langfuse | 73 traces    │
+├─────────────────────────────────────────────────────────────────┤
+│  [3 CRITICAL]  [1 WARNING]  [0 OK]  [73 traces]               │
+├─────────────────────────────────────────────────────────────────┤
+│  Discovered Checks                                              │
+│  ┌──────────────┬──────────┬──────────┬─────────┐              │
+│  │ Check        │ Pattern  │ Severity │ Found   │              │
+│  ├──────────────┼──────────┼──────────┼─────────┤              │
+│  │ Error spike  │ P-001    │ critical │ ✓ yes   │              │
+│  │ Latency p95  │ P-002    │ critical │ ✓ yes   │              │
+│  │ Low feedback │ P-003    │ warning  │ ✓ yes   │              │
+│  └──────────────┴──────────┴──────────┴─────────┘              │
+├─────────────────────────────────────────────────────────────────┤
+│  Findings                                                       │
+│  ▼ [CRITICAL] Tool call timeout causing search failures         │
+│    WHAT: tool-timeout  WHY: env-config  WHERE: tool-invocation  │
+│    Evidence: ▸ 8 traces, latency p95 = 45s                     │
+│    Root cause: SEARCH_TIMEOUT env var missing → default 5s     │
+│    ─────────────────────────────────────────────────────────    │
+│    REMEDY: Set SEARCH_TIMEOUT=30000 in .mutagentrc             │
+│    Target: local-claude (config)                                │
+│    [ Copy markdown ] [ Accept fix ]                             │
+│                                                                 │
+│  ▶ [CRITICAL] Prompt hallucination on empty product list...     │
+│  ▶ [WARNING] Feedback cluster: 3 sessions scored <2/5...        │
+└─────────────────────────────────────────────────────────────────┘
+│  [ Copy as Markdown ]                                           │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Finding Card Layers (4 layers per PR-014)
+
+1. **Header**: severity badge + title + WHAT/WHY/WHERE taxonomy chips (collapsed by default)
+2. **Evidence**: trace IDs, message excerpts, score values, timestamps
+3. **RCA chain**: recursive why-chain until origin (no fixed depth)
+4. **Remedy**: target platform, change type, copy button, Accept/Dismiss actions
+
+## HITL Interaction
+
+- **Copy markdown**: copies finding + remedy as markdown to clipboard
+- **Accept fix**: triggers apply-worker for this specific finding (→ WF-3.1)
+- **Dismiss**: marks finding as dismissed (recorded in audit)
+
+## Report File
+
+Report is written to: `.mutagent/diagnostics/reports/report-<timestamp>.html`
+Path is printed to console:
+```
+  Report written to: .mutagent/diagnostics/reports/report-2026-05-27T10-42.html
+  Opening in browser...
+```

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/wireframes/diagnostics/WF-2.5-rca-detail.md

@@ -0,0 +1,69 @@
+# WF-2.5 — RCA Detail Expansion
+
+> Expanded view of root cause analysis for a single finding.
+> Shown when user clicks "expand" on a finding card in WF-2.4.
+
+## Display (Expanded Finding Card)
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  ▼ [CRITICAL] Tool call timeout causing search failures         │
+│                                                                 │
+│  WHAT: tool-timeout   WHY: env-config   WHERE: tool-invocation  │
+│                                                                 │
+│  Evidence (8 traces)                                            │
+│  ──────────────────────────────────────────────────────────     │
+│  tr_abc123  2026-05-27 10:05  duration: 47.2s  error: timeout   │
+│  tr_abc124  2026-05-27 10:08  duration: 46.9s  error: timeout   │
+│  tr_abc125  2026-05-27 10:11  duration: 45.1s  error: timeout   │
+│  (+ 5 more)                                                     │
+│                                                                 │
+│  Root Cause Chain                                               │
+│  ──────────────────────────────────────────────────────────     │
+│  Why 1: Tool call `search` exceeded timeout limit               │
+│         Evidence: "Error: ETIMEDOUT after 5000ms"               │
+│                                                                 │
+│  Why 2: Default timeout is 5s; search API requires 15–30s      │
+│         Evidence: search API docs, observed latency p50=18s     │
+│                                                                 │
+│  Why 3: SEARCH_TIMEOUT env var not set in .mutagentrc          │
+│         Evidence: env probe shows SEARCH_TIMEOUT undefined      │
+│                                                                 │
+│  Origin: Missing env configuration (env-config class)           │
+│                                                                 │
+│  Remedy                                                         │
+│  ──────────────────────────────────────────────────────────     │
+│  Type: config-patch                                             │
+│  Target: local-claude (local-agent class)                       │
+│  Action: Add SEARCH_TIMEOUT=30000 to .mutagentrc               │
+│                                                                 │
+│  [ Copy markdown ]  [ Accept fix ]  [ Dismiss ]                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## RCA Chain Rules (from references/workflows/rca.md)
+
+- No fixed depth — recurse until the ORIGIN is reached (a WHY that has no further cause)
+- Every WHY node must cite evidence from the trace (not inference)
+- Origin must map to one of the 8 WHERE categories
+
+## Finding JSON Shape (shown on demand via "Copy JSON")
+
+```json
+{
+  "id": "f-001",
+  "severity": "critical",
+  "what": "tool-timeout",
+  "why": "env-config",
+  "where": "tool-invocation",
+  "summary": "Tool call timeout causing search failures",
+  "evidence": [...],
+  "whyChain": [
+    { "depth": 1, "reason": "...", "evidence": "..." },
+    { "depth": 2, "reason": "...", "evidence": "..." },
+    { "depth": 3, "reason": "...", "evidence": "..." }
+  ],
+  "origin": { "depth": 3, "reason": "...", "evidence": "..." },
+  "remedy": { ... }
+}
+```

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/wireframes/diagnostics/WF-2.6-stale-warning.md

@@ -0,0 +1,53 @@
+# WF-2.6 — Stale Diagnosis Warning
+
+> Shown when the user tries to apply a fix, but the codebase has changed since diagnosis.
+> `scripts/stale-detector.ts` detects this by comparing git hashes.
+
+## Trigger
+
+User clicks "Accept fix" on a finding card in WF-2.4, but `stale-detector.ts` returns `stale=true`.
+
+## Display
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  ⚠ Stale Diagnosis                                              │
+│                                                                 │
+│  The codebase has changed since this diagnosis was run.         │
+│                                                                 │
+│  Diagnosed at: abc1234f (2026-05-27 09:00)                     │
+│  Current HEAD: f4e2a991 (2026-05-27 10:42)                     │
+│  Changed files: 3                                               │
+│                                                                 │
+│  Applying fixes from a stale diagnosis may be incorrect.        │
+│                                                                 │
+│  [1] Re-run diagnostics on current HEAD (recommended)           │
+│  [2] Apply anyway (I know what I'm doing)                      │
+│  [3] Cancel                                                     │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## On "Re-run" (Recommended)
+
+→ Restart diagnostics from WF-2.1 with the same filters as the original run
+→ Previous report is archived to `.mutagent/diagnostics/reports/archived/`
+
+## On "Apply Anyway"
+
+→ Proceed to WF-3.1 with a `stale=true` flag in the audit record
+→ Audit.json will record `staleCheck.status = "stale-override"`
+→ PR title will include "(stale diagnosis)" suffix for visibility
+
+## Hash Comparison Logic
+
+```typescript
+// scripts/stale-detector.ts
+const diagnosedHash = audit.diagnosedAtHash;  // hash at diagnosis time
+const currentHash   = getCurrentGitHash();    // HEAD at apply time
+
+if (diagnosedHash !== currentHash) {
+  const changedFiles = getChangedFiles(diagnosedHash, currentHash);
+  return { stale: true, diagnosedHash, currentHash, changedFiles };
+}
+return { stale: false };
+```

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/wireframes/onboarding/WF-1.1-welcome.md

@@ -0,0 +1,60 @@
+# WF-1.1 — Welcome / Entry Point
+
+> Phase 1 of onboarding: detect setup state and route user.
+> Rendered as: numbered chat options (chat-multi-choice) or AskUserQuestion (Claude Code)
+
+## Trigger
+
+User runs: `pnpx @mutagent/diagnostics init`
+
+## Setup State Detection
+
+`scripts/setup/detect.ts` runs first:
+
+```
+SetupState = "missing" | "partial" | "complete"
+```
+
+## Route Matrix
+
+| State | Route |
+|-------|-------|
+| `missing` | → WF-1.2 (source platform picker) |
+| `partial` | → WF-1.7 (resume partial setup) |
+| `complete` | → WF-1.8 (run diagnostics now?) |
+
+## Display (State = "missing")
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  mutagent-diagnostics — Setup                               │
+│                                                             │
+│  Welcome! Let's configure diagnostics for your AI agents.   │
+│                                                             │
+│  This will take about 5 minutes.                            │
+│                                                             │
+│  [1] Get started → (detect source platform)                 │
+│  [2] Show what will be configured                           │
+│  [3] Exit                                                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Display (State = "partial")
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  mutagent-diagnostics — Resume Setup                        │
+│                                                             │
+│  Partial config found. Missing fields:                      │
+│  • target.platform                                          │
+│  • ask_tool.runtime                                         │
+│                                                             │
+│  [1] Resume setup                                           │
+│  [2] Start over (backup existing config)                    │
+│  [3] Exit                                                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Display (State = "complete")
+
+→ Skip to WF-1.8

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/wireframes/onboarding/WF-1.2-source-platform-picker.md

@@ -0,0 +1,41 @@
+# WF-1.2 — Source Platform Picker
+
+> Phase 2 of onboarding: pick the trace source platform.
+> Prev: WF-1.1 | Next: WF-1.3
+
+## Display
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Step 1 of 7 — Where are your agent traces stored?          │
+│                                                             │
+│  [1] Langfuse                (cloud or self-hosted)         │
+│  [2] OpenTelemetry / Jaeger  (OTel-compatible backend)      │
+│  [3] Local JSONL file        (.jsonl or .ndjson)            │
+│  [4] Claude Code sessions    (auto-detected)                │
+│  [5] Codex CLI sessions      (auto-detected)                │
+│  [6] I don't know yet        (skip, configure later)        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## On Selection
+
+| Choice | Action |
+|--------|--------|
+| 1 (Langfuse) | → WF-1.3a (Langfuse auth check) |
+| 2 (OTel) | → WF-1.3b (OTel endpoint check) |
+| 3 (Local JSONL) | → WF-1.3c (file path input) |
+| 4 (Claude Code) | → probe `~/.claude/projects/` → WF-1.4 |
+| 5 (Codex) | → probe `~/.codex/sessions/` → WF-1.4 |
+| 6 (Skip) | → Set `source.platform: null` → WF-1.4 |
+
+## Validation
+
+After selection, validate connectivity:
+- Langfuse: `langfuse traces list --limit 1` → check exit code
+- OTel: `curl -m 5 $ENDPOINT/health` → check response
+- Local JSONL: `ls $FILE` → check file exists
+- Claude Code: `ls ~/.claude/projects/` → count sessions
+- Codex: `ls ~/.codex/sessions/` → count sessions
+
+If validation fails → show inline error + offer retry or skip

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/wireframes/onboarding/WF-1.3-source-auth.md

@@ -0,0 +1,75 @@
+# WF-1.3 — Source Auth / Connection
+
+> Phase 3 of onboarding: configure source connectivity.
+> Prev: WF-1.2 | Next: WF-1.4
+
+## WF-1.3a — Langfuse Auth
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Step 2 of 7 — Langfuse Connection                          │
+│                                                             │
+│  Checking .mutagentrc for LANGFUSE_* keys...                │
+│                                                             │
+│  ✓ LANGFUSE_SECRET_KEY found                               │
+│  ✓ LANGFUSE_PUBLIC_KEY found                               │
+│  ✓ LANGFUSE_HOST found (https://cloud.langfuse.com)        │
+│                                                             │
+│  Testing connection... ✓ Connected (12 traces found)        │
+│                                                             │
+│  [1] Continue with this config                              │
+│  [2] Use a different host                                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Keys Not Found Path
+
+```
+  ✗ LANGFUSE_SECRET_KEY not found in .mutagentrc
+  
+  Add the following to your .mutagentrc file:
+  
+    LANGFUSE_SECRET_KEY=sk-...
+    LANGFUSE_PUBLIC_KEY=pk-...
+    LANGFUSE_HOST=https://cloud.langfuse.com
+  
+  [1] I've added the keys — retry
+  [2] Skip Langfuse, choose another source
+```
+
+## WF-1.3b — OTel Endpoint
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Step 2 of 7 — OTel Endpoint                                │
+│                                                             │
+│  OTel endpoint (from .mutagentrc or enter):                 │
+│  > http://localhost:4318                                    │
+│                                                             │
+│  Testing connection... ✓ Jaeger reachable                   │
+│                                                             │
+│  [1] Continue                                               │
+│  [2] Change endpoint                                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## WF-1.3c — Local JSONL File
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Step 2 of 7 — JSONL File Path                              │
+│                                                             │
+│  Path to your trace file (.jsonl or .ndjson):               │
+│  > traces.jsonl                                             │
+│                                                             │
+│  ✓ File found (247 lines)                                   │
+│                                                             │
+│  [1] Continue                                               │
+│  [2] Enter a different path                                 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Key Rules
+
+- NEVER prompt for key values — only prompt for key NAMES to check in .mutagentrc
+- Keys are referenced by name in config.yaml — never stored as values

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/wireframes/onboarding/WF-1.4-target-picker.md

@@ -0,0 +1,48 @@
+# WF-1.4 — Target Platform Picker
+
+> Phase 4 of onboarding: pick the apply target.
+> Prev: WF-1.3 | Next: WF-1.5
+
+## Display
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Step 3 of 7 — Where should fixes be applied?               │
+│                                                             │
+│  Target class:                                              │
+│                                                             │
+│  LOCAL AGENTS (config changes only, HITL review)           │
+│  [1] Claude Code     (skills + settings)                    │
+│  [2] Codex CLI       (config.toml)                          │
+│  [3] Cursor          (.cursorrules + settings)              │
+│  [4] OpenCode        (opencode.json)                        │
+│                                                             │
+│  LOCAL CODE CONSTRUCTS (code edits via PR, lint gate)       │
+│  [5] Mastra.ai       (TypeScript agents)                    │
+│  [6] Cloud Agent SDK (Anthropic / OpenAI / Google / etc.)   │
+│                                                             │
+│  REMOTE (REST API mutations, HITL always required)          │
+│  [7] Cloud REST      (Langfuse annotations, remote config)  │
+│                                                             │
+│  [8] Skip for now                                           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## On Selection
+
+| Choice | Target Platform | Target Class |
+|--------|-----------------|--------------|
+| 1 | local-claude | local-agent |
+| 2 | local-codex | local-agent |
+| 3 | local-cursor | local-agent |
+| 4 | local-opencode | local-agent |
+| 5 | local-mastra | local-code-construct |
+| 6 | local-cloud-agent-sdk | local-code-construct |
+| 7 | cloud-rest | remote |
+| 8 | null | null |
+
+## Target Class Explanation (shown inline)
+
+- **local-agent**: reads config, proposes changes, you apply them (safe)
+- **local-code-construct**: opens a PR branch, lint+typecheck gate before any merge
+- **remote**: read-before-write, idempotent mutations, HITL confirmation for every change

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/assets/wireframes/onboarding/WF-1.5-ask-tool.md

@@ -0,0 +1,43 @@
+# WF-1.5 — ASK Tool Selection
+
+> Phase 5 of onboarding: configure the HITL interaction mode.
+> Prev: WF-1.4 | Next: WF-1.6
+
+## Display
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Step 4 of 7 — How should I ask you questions?              │
+│                                                             │
+│  When diagnostics finds an issue and wants your input,      │
+│  how do you want to respond?                                │
+│                                                             │
+│  [1] Claude Code (AskUserQuestion)                          │
+│      Best if you're running this from Claude Code           │
+│                                                             │
+│  [2] Chat multi-choice                                      │
+│      Numbered options in the conversation                   │
+│      Works everywhere: terminal, CLI, any chat              │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Auto-Detection
+
+Before showing this screen, check if running in Claude Code:
+- `process.env.CLAUDE_CODE_ENTRYPOINT` set → suggest [1] (Claude Code)
+- Otherwise → suggest [2] (chat-multi-choice)
+
+## On Selection
+
+| Choice | `ask_tool.runtime` |
+|--------|--------------------|
+| 1 | `claude-code` |
+| 2 | `chat-multi-choice` |
+
+## Context Note
+
+The ASK tool selection affects:
+- Destructive-action gates: `AskUserQuestion` in Claude Code vs numbered prompt in chat
+- HTML report copy-back: auto-paste to conversation (Claude Code) vs manual copy prompt (chat)
+- No functional difference for read-only diagnostics — only matters at apply time