pantheon-opencode 1.2.0 → 1.2.2

package/scripts/doctor.mjs

@@ -24,9 +24,10 @@
  *   2 = errors (needs attention)
  */
 
-import { spawnSync } from 'node:child_process'
+import { spawn as spawnAsync, spawnSync } from 'node:child_process'
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { homedir } from 'node:os'
+import { basename, dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 // ---------------------------------------------------------------------------
@@ -44,8 +45,6 @@ const _ALL_PLATFORMS = ['opencode']
 const PLATFORM_LABELS = {
   opencode: 'OpenCode',
 }
-  opencode: 'OpenCode',
-}
 
 // ---------------------------------------------------------------------------
 // State
@@ -160,10 +159,13 @@ function showHelp() {
 
  Checks:
    A. Agent Files          — canonical vs platform sync
-   B. MCP Configuration    — opencode.json MCP settings
+   B. MCP Configuration    — opencode.json MCP settings (Config layer)
+   B.5 MCP Spawn Paths     — local MCP exe/args resolve to existing files
+   B.6 MCP Runtime Smoke   — spawn each local MCP + JSON-RPC initialize handshake
    C. Permission Checks    — frontmatter validation
    D. Sync Status          — npm run sync freshness
    E. Git Status           — uncommitted changes
+   F. Runtime Layer        — venv python + pinned pip dependencies
 
  Exit codes:
    0  — all checks pass
@@ -236,6 +238,10 @@ function checkAgentFiles(args) {
   pass(`${canonical.length} canonical agents found in agents/`)
 
   // Determine which platforms to check
+  if (!existsSync(PLATFORM_DIR)) {
+    warn('Platform component not distributed in this package — skipping platform agent check')
+    return
+  }
   const platformDirs = readdirSync(PLATFORM_DIR, { withFileTypes: true })
     .filter((d) => d.isDirectory() && d.name !== '_template' && d.name !== 'plans')
     .map((d) => d.name)
@@ -312,12 +318,12 @@ function checkAgentFiles(args) {
 // Check B: MCP Configuration
 // ---------------------------------------------------------------------------
 
-function checkMcpConfig(args) {
-  section('B. MCP Configuration')
-
-  // Determine which opencode.json to check:
-  // 1. Target project's opencode.json
-  // 2. Pantheon ROOT opencode.json
+/**
+ * Collect every reachable opencode.json (project → repository → user config)
+ * with its parsed content, for the config, spawn-path and runtime layers.
+ * @returns {{label:string, path:string, data:object}[]}
+ */
+function collectMcpConfigs(args) {
   const candidates = [
     { label: 'project root', path: join(args.target, 'opencode.json') },
     { label: 'repository root', path: join(ROOT, 'opencode.json') },
@@ -334,7 +340,6 @@ function checkMcpConfig(args) {
     candidates.push({ label: 'user config', path: homeConfig })
   }
 
-  /** @type {{label:string, data:object}[]} */
   const configs = []
   for (const c of candidates) {
     const data = readJson(c.path)
@@ -342,6 +347,13 @@ function checkMcpConfig(args) {
       configs.push({ label: c.label, data, path: c.path })
     }
   }
+  return configs
+}
+
+function checkMcpConfig(args) {
+  section('B. MCP Configuration')
+
+  const configs = collectMcpConfigs(args)
 
   if (configs.length === 0) {
     warn('No opencode.json found in target or user config')
@@ -410,6 +422,155 @@ function checkMcpConfig(args) {
     if (args.verbose) {
       checkAgentMcpReferences(cfg)
     }
+
+    // 5. Hermetic spawn check — every local MCP command must resolve to an
+    // existing executable and existing absolute script paths. Catches the
+    // ENOENT-on-spawn failure class (dead hardcoded path, ambiguous relative
+    // path) before opencode tries to spawn the server.
+    for (const [name, mcpEntry] of Object.entries(mcp)) {
+      if (!mcpEntry || mcpEntry.type !== 'local') continue
+      const cmd = mcpEntry.command
+      if (!Array.isArray(cmd) || cmd.length === 0) {
+        warn(`${cfg.label}: MCP "${name}" has no command array`)
+        continue
+      }
+      const exe = cmd[0]
+      if (!exe.includes('/')) {
+        // PATH-resolved executable — cannot verify statically; surface for manual check
+        info(`${cfg.label}: MCP "${name}" uses PATH executable "${exe}" (verify with \`which ${exe}\`)`)
+        continue
+      }
+      if (!existsSync(exe)) {
+        error(`${cfg.label}: MCP "${name}" executable does not exist: ${exe}`)
+        continue
+      }
+      const deadArgs = cmd.slice(1).filter((a) => a.startsWith('/') && !existsSync(a))
+      if (deadArgs.length > 0) {
+        error(`${cfg.label}: MCP "${name}" has missing script path(s): ${deadArgs.join(', ')}`)
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Check B.6: MCP Runtime Smoke (JSON-RPC initialize handshake)
+// ---------------------------------------------------------------------------
+// The static spawn-path check (B.5) proves the files exist; this layer proves
+// the server actually STARTS and answers the JSON-RPC initialize handshake.
+// Catches ENOENT-on-spawn, Python import errors and runtime crashes that the
+// static check cannot see — with a hard timeout so a hung server fails the
+// check instead of blocking the doctor run.
+
+/**
+ * Spawn one local MCP server, send a JSON-RPC `initialize` request and wait
+ * for a well-formed response.
+ * @param {string[]} command - argv of the MCP server (exe + args)
+ * @param {string} cwd - working directory (relative script args resolve here)
+ * @param {number} timeoutMs - hard timeout for the handshake
+ * @returns {Promise<{ok:boolean, serverName?:string, reason?:string}>}
+ */
+function mcpInitializeSmoke(command, cwd, timeoutMs) {
+  const payload = JSON.stringify({
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'initialize',
+    params: {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: { name: 'pantheon-doctor', version: '0.0.0' },
+    },
+  })
+  return new Promise((resolve) => {
+    let proc
+    try {
+      proc = spawnAsync(command[0], command.slice(1), { cwd, stdio: ['pipe', 'pipe', 'pipe'] })
+    } catch (err) {
+      resolve({ ok: false, reason: `spawn threw: ${err.message}` })
+      return
+    }
+    let stdout = ''
+    let stderr = ''
+    let done = false
+    const finish = (result) => {
+      if (done) return
+      done = true
+      clearTimeout(timer)
+      try {
+        proc.kill('SIGKILL')
+      } catch {
+        /* already gone */
+      }
+      resolve(result)
+    }
+    const timer = setTimeout(
+      () => finish({ ok: false, reason: `timeout after ${timeoutMs}ms (no initialize response)` }),
+      timeoutMs,
+    )
+    proc.stdout.on('data', (chunk) => {
+      stdout += chunk.toString()
+      const line = stdout.split('\n').find((l) => l.includes('"id":1'))
+      if (!line) return
+      try {
+        const msg = JSON.parse(line.trim())
+        if (msg.id === 1 && msg.result) {
+          const info = msg.result.serverInfo
+          const label = info?.name ? `${info.name}${info.version ? ` ${info.version}` : ''}` : undefined
+          finish({ ok: true, serverName: label })
+          return
+        }
+        if (msg.error) {
+          finish({ ok: false, reason: `initialize error: ${msg.error.code ?? ''} ${msg.error.message ?? ''}` })
+        }
+      } catch {
+        /* not JSON yet — keep buffering */
+      }
+    })
+    proc.stderr.on('data', (chunk) => {
+      stderr += chunk.toString()
+      if (stderr.length > 4096) stderr = stderr.slice(-4096)
+    })
+    proc.on('error', (err) =>
+      finish({ ok: false, reason: `spawn failed: ${err.code ?? err.message}` }),
+    )
+    proc.on('exit', (code, signal) => {
+      if (done) return
+      const tail = stderr.trim().split('\n').filter(Boolean).slice(-3).join(' | ')
+      finish({
+        ok: false,
+        reason: `process exited early (code=${code} signal=${signal})${tail ? ` — ${tail}` : ''}`,
+      })
+    })
+    proc.stdin.write(`${payload}\n`)
+    proc.stdin.end()
+  })
+}
+
+async function checkMcpRuntimeSmoke(args) {
+  section('B.6 MCP Runtime Smoke')
+
+  const local = []
+  for (const cfg of collectMcpConfigs(args)) {
+    for (const [name, entry] of Object.entries(cfg.data.mcp ?? {})) {
+      if (!entry || entry.type !== 'local') continue
+      if (!Array.isArray(entry.command) || entry.command.length === 0) continue
+      local.push({ name, command: entry.command, cwd: dirname(cfg.path), source: cfg.label })
+    }
+  }
+
+  if (local.length === 0) {
+    warn('No local MCP servers found in any config — nothing to smoke-test')
+    return
+  }
+
+  info(`Smoke-testing ${local.length} local MCP server(s) via JSON-RPC initialize`)
+
+  for (const { name, command, cwd, source } of local) {
+    const result = await mcpInitializeSmoke(command, cwd, 10000)
+    if (result.ok) {
+      pass(`MCP "${name}" (${source}): initialize handshake OK${result.serverName ? ` — ${result.serverName}` : ''}`)
+    } else {
+      error(`MCP "${name}" (${source}): ${result.reason}`)
+    }
   }
 }
 
@@ -633,6 +794,132 @@ function checkGitStatus(args) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Check F: Runtime Layer — Venv, Python & pinned dependencies
+// ---------------------------------------------------------------------------
+// The MCP servers run on the venv Python under ~/.config/opencode/.venv
+// (same resolution as scripts/install-mcp.mjs). This layer verifies the venv
+// exists, the interpreter responds, and the installed packages satisfy the
+// EXACT pins in src/mcp/requirements-mcp.txt and requirements-vision.txt
+// (issue #18 / #21).
+
+/** Parse `pip freeze` output into a normalized name → version map. */
+function parsePipFreeze(text) {
+  const map = {}
+  for (const line of text.split('\n')) {
+    const m = line.trim().match(/^([A-Za-z0-9_.-]+)==(\S+)/)
+    if (!m) continue
+    map[m[1].toLowerCase().replace(/-/g, '_')] = m[2]
+  }
+  return map
+}
+
+/** Split a version string into comparable numeric segments. */
+function parseVersion(v) {
+  const m = String(v).match(/(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:\.(\d+))?/)
+  if (!m) return []
+  return [m[1], m[2] ?? '0', m[3] ?? '0', m[4] ?? '0'].map(Number)
+}
+
+/** Compare two versions numerically. Returns <0, 0 or >0. */
+function compareVersions(a, b) {
+  const pa = parseVersion(a)
+  const pb = parseVersion(b)
+  for (let i = 0; i < 4; i++) {
+    const da = pa[i] ?? 0
+    const db = pb[i] ?? 0
+    if (da !== db) return da - db
+  }
+  return 0
+}
+
+/**
+ * Check one requirement line (name + operator + version) against installed.
+ * Emits pass/error through the doctor counters.
+ */
+function checkRequirementLine(line, installed) {
+  const m = line.match(/^\s*([A-Za-z0-9_.-]+)\s*(==|>=|<=|>|<|~=|!=)\s*([^\s#]+)/)
+  if (!m) return
+  const name = m[1].toLowerCase().replace(/-/g, '_')
+  const op = m[2]
+  const want = m[3]
+  const have = installed[name]
+  if (have === undefined) {
+    error(`Dependency "${m[1]}" not installed (required ${op}${want})`)
+    return
+  }
+  const cmp = compareVersions(have, want)
+  let ok = false
+  switch (op) {
+    case '==': ok = cmp === 0; break
+    case '>=': ok = cmp >= 0; break
+    case '<=': ok = cmp <= 0; break
+    case '>': ok = cmp > 0; break
+    case '<': ok = cmp < 0; break
+    case '!=': ok = cmp !== 0; break
+    case '~=': {
+      const spec = parseVersion(want)
+      const got = parseVersion(have)
+      ok = got[0] === spec[0] && got[1] === spec[1] && cmp >= 0
+      break
+    }
+  }
+  if (ok) {
+    pass(`Dependency ${m[1]}==${have} satisfies ${m[1]}${op}${want}`)
+  } else {
+    error(`Dependency ${m[1]} version mismatch: installed ${have}, required ${op}${want}`)
+  }
+}
+
+function checkVenvLayer() {
+  section('F. Runtime Layer — Venv, Python & Dependencies')
+
+  const configDir = join(homedir(), '.config', 'opencode')
+  const venvPython = join(configDir, '.venv', 'bin', 'python3')
+
+  if (!existsSync(venvPython)) {
+    error(`Venv python not found: ${venvPython} (run \`pantheon-opencode init\` to create it)`)
+    return
+  }
+  pass(`Venv python exists: ${venvPython}`)
+
+  const probe = spawn(venvPython, ['-c', 'import sys; print(sys.version.split()[0])'])
+  if (probe.status !== 0) {
+    error(`Venv python does not respond (exit ${probe.status}): ${probe.stderr}`)
+    return
+  }
+  pass(`Venv python responds (Python ${probe.stdout})`)
+
+  const freeze = spawn(venvPython, ['-m', 'pip', 'freeze'])
+  if (freeze.status !== 0) {
+    warn(`pip freeze failed (exit ${freeze.status}) — cannot verify pinned versions`)
+    return
+  }
+  const installed = parsePipFreeze(freeze.stdout)
+
+  const reqFiles = [
+    join(ROOT, 'src', 'mcp', 'requirements-mcp.txt'),
+    join(ROOT, 'src', 'mcp', 'requirements-vision.txt'),
+  ]
+  for (const reqFile of reqFiles) {
+    if (!existsSync(reqFile)) {
+      warn(`requirements file not found: ${reqFile}`)
+      continue
+    }
+    const base = basename(reqFile)
+    info(`Checking ${base} pins against installed packages`)
+    const lines = readFileSync(reqFile, 'utf8').split('\n')
+    let checked = 0
+    for (const line of lines) {
+      const trimmed = line.trim()
+      if (!trimmed || trimmed.startsWith('#')) continue
+      checked++
+      checkRequirementLine(trimmed, installed)
+    }
+    if (checked === 0) warn(`${base}: no requirement entries found`)
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Summary
 // ---------------------------------------------------------------------------
@@ -663,7 +950,7 @@ function printSummary(targetPath) {
 // Main
 // ---------------------------------------------------------------------------
 
-function main() {
+async function main() {
   const args = parseArgs(process.argv)
 
   if (args.help) {
@@ -693,9 +980,11 @@ function main() {
     join(args.target, 'scripts', 'doctor.mjs') === join(ROOT, 'scripts', 'doctor.mjs') ||
     existsSync(join(args.target, 'scripts', 'doctor.mjs')) === false
 
-  // Run checks
+  // Run checks (layer order: Config → Venv → spawn paths → runtime smoke)
   checkAgentFiles(args)
   checkMcpConfig(args)
+  checkVenvLayer(args)
+  await checkMcpRuntimeSmoke(args)
   checkPermissionMismatches(args)
   checkSyncStatus(args)
   checkGitStatus(args)
@@ -705,4 +994,7 @@ function main() {
   process.exit(exitCode)
 }
 
-main()
+main().catch((err) => {
+  console.error(`❌ Doctor crashed: ${err.stack ?? err.message}`)
+  process.exit(2)
+})

package/scripts/hooks/audit-imports.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# audit-imports.sh — Pantheon PostToolUse Import Audit Hook
+# Blocks wildcard imports and flags suspicious patterns.
+set -euo pipefail
+
+FILE_PATH="${FILE_PATH:-${1:-}}"
+
+if [[ -z "$FILE_PATH" ]] || [[ ! -f "$FILE_PATH" ]]; then
+    # Scan all Python/JS files in recent changes if no file specified
+    FILES=$(git diff --name-only HEAD 2>/dev/null | grep -E '\.(py|js|ts|jsx|tsx)$' || true)
+    if [[ -z "$FILES" ]]; then
+        exit 0
+    fi
+else
+    FILES="$FILE_PATH"
+fi
+
+FOUND=0
+for f in $FILES; do
+    [[ -f "$f" ]] || continue
+    EXT="${f##*.}"
+    case "$EXT" in
+        py)
+            if grep -qE '^from\s+\S+\s+import\s+\*' "$f"; then
+                echo "[IMPORT AUDIT] Wildcard import found in $f" >&2
+                FOUND=1
+            fi
+            ;;
+        js|jsx|ts|tsx)
+            # Flag require() without destructuring as suspicious
+            if grep -qE 'require\([^)]+\)' "$f"; then
+                echo "[IMPORT AUDIT] CommonJS require() found in $f — consider ES modules" >&2
+            fi
+            ;;
+    esac
+done
+
+if [[ $FOUND -eq 1 ]]; then
+    echo "[IMPORT AUDIT] Fix wildcard imports before committing." >&2
+    exit 1
+fi
+
+exit 0

package/scripts/hooks/format-multi-language.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# format-multi-language.sh — Pantheon PostToolUse Formatting Hook
+# Runs appropriate formatter on the modified file.
+# Supports both Claude Code stdin protocol and legacy env-var input.
+set -euo pipefail
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd -- "$SCRIPT_DIR/../.." && pwd)"
+
+# ── Claude Code stdin protocol ──────────────────────────────────────────
+# Parse JSON from stdin when piped (PostToolUse hook format).
+# Extracts file_path from Edit/Write or file paths from Bash commands.
+if [ -p /dev/stdin ]; then
+  STDIN_JSON=$(cat)
+  TOOL_NAME=$(echo "$STDIN_JSON" | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+print(d.get('tool_name', ''))
+" 2>/dev/null || echo "")
+
+  case "$TOOL_NAME" in
+    Edit|Write)
+      JSON_PATH=$(echo "$STDIN_JSON" | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+print(d.get('tool_input', {}).get('file_path', ''))
+" 2>/dev/null || echo "")
+      if [ -n "$JSON_PATH" ]; then
+        FILE_PATH="$JSON_PATH"
+      fi
+      ;;
+    Bash)
+      COMMAND=$(echo "$STDIN_JSON" | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+print(d.get('tool_input', {}).get('command', ''))
+" 2>/dev/null || echo "")
+      if [ -n "$COMMAND" ]; then
+        # Extract first file-like path from bash command (supports relative and quoted paths)
+        CANDIDATE=$(python3 -c "
+import re, shlex, sys
+command = sys.argv[1]
+try:
+    tokens = shlex.split(command)
+except ValueError:
+    tokens = command.split()
+path_re = re.compile(r'^([^\\n]+\\.[A-Za-z0-9]+)$')
+for token in tokens:
+    if token.startswith('-'):
+        continue
+    if path_re.match(token):
+        print(token)
+        break
+" "$COMMAND" 2>/dev/null || echo "")
+        if [ -n "$CANDIDATE" ]; then
+          FILE_PATH="$CANDIDATE"
+        fi
+      fi
+      ;;
+  esac
+fi
+
+FILE_PATH="${FILE_PATH:-${1:-}}"
+if [[ -n "$FILE_PATH" ]] && [[ "$FILE_PATH" != /* ]]; then
+    if [[ -f "$REPO_ROOT/$FILE_PATH" ]]; then
+        FILE_PATH="$REPO_ROOT/$FILE_PATH"
+    fi
+fi
+
+if [[ -z "$FILE_PATH" ]] || [[ ! -f "$FILE_PATH" ]]; then
+    exit 0
+fi
+
+EXT="${FILE_PATH##*.}"
+EXIT_CODE=0
+
+case "$EXT" in
+    py)
+        if command -v ruff >/dev/null 2>&1; then
+            ruff format "$FILE_PATH" || true
+        elif command -v black >/dev/null 2>&1; then
+            black -q "$FILE_PATH" || true
+        fi
+        ;;
+    js|jsx|ts|tsx|json|jsonc|md|yaml|yml|css|html)
+        if command -v prettier >/dev/null 2>&1; then
+            prettier --write "$FILE_PATH" || true
+        fi
+        ;;
+    sh|bash)
+        if command -v shfmt >/dev/null 2>&1; then
+            shfmt -w "$FILE_PATH" || true
+        fi
+        ;;
+esac
+
+exit 0

package/scripts/hooks/log-session-start.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# log-session-start.sh — Pantheon SessionStart Logging Hook
+# Logs session start with structured JSON.
+set -euo pipefail
+
+# Project-local by default; set XDG_STATE_HOME for system-wide logging
+if [ -n "${LOG_DIR:-}" ]; then
+    LOG_DIR="$LOG_DIR"
+elif [ -n "${XDG_STATE_HOME:-}" ]; then
+    LOG_DIR="$XDG_STATE_HOME/pantheon/hooks"
+else
+    LOG_DIR="logs/agent-sessions"
+fi
+mkdir -p "$LOG_DIR"
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+SESSION_ID="${SESSION_ID:-$(date +%s)}"
+
+cat >> "$LOG_DIR/sessions.log" << JSON
+{"event":"SessionStart","timestamp":"$TIMESTAMP","session_id":"$SESSION_ID","platform":"${PLATFORM:-unknown}"}
+JSON
+
+echo "[LOG] Session start logged → $LOG_DIR/sessions.log" >&2
+exit 0

package/scripts/hooks/on-subagent-delegation-start.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# on-subagent-delegation-start.sh — Pantheon SubagentStart Audit Hook
+# Logs when Zeus delegates to a subagent.
+set -euo pipefail
+
+# Project-local by default; set XDG_STATE_HOME for system-wide logging
+if [ -n "${LOG_DIR:-}" ]; then
+    LOG_DIR="$LOG_DIR"
+elif [ -n "${XDG_STATE_HOME:-}" ]; then
+    LOG_DIR="$XDG_STATE_HOME/pantheon/hooks"
+else
+    LOG_DIR="logs/agent-sessions"
+fi
+mkdir -p "$LOG_DIR"
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+AGENT_NAME="${AGENT_NAME:-unknown}"
+TASK_DESC="${TASK_DESC:-${1:-}}"
+
+cat >> "$LOG_DIR/delegations.log" << JSON
+{"event":"SubagentStart","timestamp":"$TIMESTAMP","agent":"$AGENT_NAME","task":"$TASK_DESC"}
+JSON
+
+echo "[DELEGATION] $AGENT_NAME started → $LOG_DIR/delegations.log" >&2
+
+# --- Dispatch-time validation: check target against routing.yml ---
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd -- "$SCRIPT_DIR/../.." && pwd)"
+ROUTING_FILE="$REPO_ROOT/routing.yml"
+if [ -f "$ROUTING_FILE" ] && [ -n "$AGENT_NAME" ]; then
+    ESCAPED_AGENT_NAME=$(printf '%s\n' "$AGENT_NAME" | sed 's/[][(){}.^$*+?|\/\\-]/\\&/g')
+    if grep -qE "^[[:space:]]*-[[:space:]]+target:[[:space:]]+$ESCAPED_AGENT_NAME[[:space:]]*$" "$ROUTING_FILE" 2>/dev/null; then
+        echo "[VALIDATION] ✅ Target '$AGENT_NAME' found in routing.yml" >&2
+    else
+        echo "[VALIDATION] ⚠️ Target '$AGENT_NAME' NOT in routing.yml delegation rules" >&2
+    fi
+elif [ ! -f "$ROUTING_FILE" ]; then
+    echo "[VALIDATION] ⚠️ Could not read routing.yml for validation" >&2
+fi
+
+# --- Cost estimation for delegation ---
+declare -A TIER_MAP
+TIER_MAP[athena]="premium"
+TIER_MAP[themis]="premium"
+TIER_MAP[hermes]="default"
+TIER_MAP[aphrodite]="default"
+TIER_MAP[demeter]="default"
+TIER_MAP[prometheus]="default"
+TIER_MAP[hephaestus]="default"
+TIER_MAP[gaia]="default"
+TIER_MAP[zeus]="default"
+TIER_MAP[apollo]="fast"
+TIER_MAP[nyx]="fast"
+TIER_MAP[iris]="fast"
+TIER_MAP[mnemosyne]="fast"
+TIER_MAP[talos]="fast"
+
+TIER="${TIER_MAP[$AGENT_NAME]:-default}"
+
+case "$TIER" in
+    premium)
+        COST_MIN=0.50
+        COST_MAX=2.00
+        COST_EST=1.25
+        ;;
+    fast)
+        COST_MIN=0.02
+        COST_MAX=0.10
+        COST_EST=0.06
+        ;;
+    *)
+        COST_MIN=0.10
+        COST_MAX=0.50
+        COST_EST=0.30
+        ;;
+esac
+
+# Format cost with 2 decimal places
+COST_EST_FMT=$(printf "%.2f" "$COST_EST")
+
+if [ "$TIER" = "premium" ]; then
+    echo "[COST_WARN] High-cost delegation to $AGENT_NAME — estimated \$$COST_EST_FMT" >&2
+fi
+
+if (( $(echo "$COST_EST > 5.00" | bc -l 2>/dev/null) )); then
+    echo "[COST_ALERT] Expensive delegation to $AGENT_NAME — consider if subtask is possible" >&2
+fi
+
+echo "[COST] Delegation to $AGENT_NAME — tier: $TIER — estimated: \$$COST_EST_FMT" >&2
+
+exit 0

package/scripts/hooks/on-subagent-delegation-stop.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# on-subagent-delegation-stop.sh — Pantheon SubagentStop Audit Hook
+# Logs completion or failure of subagent tasks.
+set -euo pipefail
+
+# Project-local by default; set XDG_STATE_HOME for system-wide logging
+if [ -n "${LOG_DIR:-}" ]; then
+    LOG_DIR="$LOG_DIR"
+elif [ -n "${XDG_STATE_HOME:-}" ]; then
+    LOG_DIR="$XDG_STATE_HOME/pantheon/hooks"
+else
+    LOG_DIR="logs/agent-sessions"
+fi
+mkdir -p "$LOG_DIR"
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+AGENT_NAME="${AGENT_NAME:-unknown}"
+STATUS="${STATUS:-success}"
+REASON="${REASON:-${1:-}}"
+
+LOG_FILE="$LOG_DIR/delegations.log"
+if [[ "$STATUS" == "failure" ]]; then
+    LOG_FILE="$LOG_DIR/delegation-failures.log"
+fi
+
+cat >> "$LOG_FILE" << JSON
+{"event":"SubagentStop","timestamp":"$TIMESTAMP","agent":"$AGENT_NAME","status":"$STATUS","reason":"$REASON"}
+JSON
+
+echo "[DELEGATION] $AGENT_NAME stopped ($STATUS) → $LOG_FILE" >&2
+
+# --- Post-condition validation: remind about Themis review ---
+if echo "hermes aphrodite demeter prometheus" | grep -wq "$AGENT_NAME" 2>/dev/null; then
+    echo "[POST-CONDITION] 🔔 Reminder: '$AGENT_NAME' should call Themis for review after implementation" >&2
+fi
+
+exit 0