pantheon-opencode 1.2.2 → 1.3.1

package/AGENTS.md

@@ -44,3 +44,4 @@ Para validar a instalação global do pacote pantheon-opencode COMO UM USUÁRIO
 - Coverage minimum: 80%
 - Async/await on all I/O
 - Type hints on all functions
+- PRs always update the README — every pull request must document newly added features, behaviors, env vars, or commands in the README before being opened.

package/README.md

@@ -187,6 +187,17 @@ opencode
 > **Minimal:** `--headless --no-mcp` installs only agents (~2s).
 > **Full:** `--headless` also creates Python venv + MCP servers (memory, persistence, KV, vision).
 
+### Doctor validation statuses
+
+The doctor reports each check as **PASS**, **WARN**, **ERROR**, or **SKIP**. WARN is
+advisory and exits 0; ERROR is blocking and exits 2. The `global` and `sandbox`
+profiles require the core `pantheon-memory` and `pantheon-resources` MCPs, while
+`lite` treats MCPs and optional helpers (`platform`, `gh_grep`, Context7, and
+`validate-agent-frontmatter.py`) as informational/skipped. Optional warnings are
+never used to hide missing required MCPs. When ERROR and WARN coexist, the final
+summary explicitly reports the blocking error and exit code 2; it never reports a
+positive “no blocking errors” result.
+
 ---
 
 ### Approval Gates
@@ -615,7 +626,7 @@ pantheon/
 │   └── workflows/            — 7 CI/CD workflows
 │       ├── ci.yml
 │       ├── beta-release.yml
-│       ├── auto-release.yml
+│       ├── release.yml
 │       ├── commit-lint.yml
 │       ├── codeql.yml
 │       ├── docs.yml
@@ -689,7 +700,7 @@ to Mnemosyne so counts stay accurate and consistent.
 
 ### What CI enforces automatically
 
-`auto-release.yml` validates version consistency across all manifests (`package.json`,
+`release.yml` validates version consistency across all manifests (`package.json`,
 `plugin.json`, `CHANGELOG.md`, and the README badge) before publishing. If they diverge,
 the release is blocked until Mnemosyne reconciles them.
 
@@ -741,15 +752,54 @@ Edit README.md line 11: agents-17 → agents-18
 - `scan-secrets.sh` — detects hardcoded secrets and credentials (tool.execute.before)
 - `validate-tool-safety.sh` — blocks destructive operations (tool.execute.before)
 - `validate-talos-scope.sh` — restricts Talos hotfix scope (tool.execute.before)
-- `on-subagent-delegation-start.sh` — tracks delegation start (tool.execute.before, delegation tools only)
+- `on-subagent-delegation-start.sh` — tracks delegation start (tool.execute.before, delegation tools only; agent from `tool_input.subagent_type`, task from `tool_input.description`)
 - `format-multi-language.sh` — auto-formats modified files (tool.execute.after)
 - `log-session-start.sh` — audit trail of sessions (tool.execute.after + event session.created)
-- `on-subagent-delegation-stop.sh` — delegation cleanup (tool.execute.after, delegation tools only)
+- `on-subagent-delegation-stop.sh` — delegation cleanup (tool.execute.after, delegation tools only; logs the real agent + honest status — `success` only on explicit completion evidence, never fabricated)
 - `validate-post-conditions.sh` — post-condition validation (event session.created)
 - `audit-imports.sh` and `run-type-check.sh` also live in `scripts/hooks/` but are not wired into the plugin.
 
 The `src/plugins/pantheon-hooks.ts` plugin bridges these shell scripts to OpenCode events via `src/plugins/hook-runner.ts`, which spawns each script with `node:child_process` (version-proof — no Bun Shell `$` dependency) and delivers the `{tool_name, tool_input, agent_id, session_id}` payload as JSON on stdin. Register it explicitly in `opencode.json`: `"plugin": ["<path>/src/plugins/pantheon-hooks.ts"]` (absolute path). It is **not** auto-discovered from `.opencode/plugins/`.
 
+**Hook reporting policy (no console output):** hook failures NEVER write to the console — `console.*` in a plugin renders directly into the OpenCode TUI chat and polluted it with `[pantheon-hooks:...] exit 1` spam. Non-zero hook exits are now reported through three non-TUI channels:
+1. One short, deduped TUI toast via `client.tui.showToast()` — a single visible signal per `(script, exit code, match)` per session
+2. A structured entry in the OpenCode log via `client.app.log()` (service `pantheon-hooks`, level `error`)
+3. A one-line append to `.pantheon/logs/hooks.log` (project-local audit file)
+
+Zero-exit hooks are **silent by design** — a clean edit or tool call (hook exit 0) produces **no console output at all** (the old `[pantheon-hooks:...]` echo spam is gone since the P0 logging fix). The audit scripts still write their log files (`sessions.log`, `delegations.log`) from inside the `.sh` scripts. To see hook output while debugging, start OpenCode with `PANTHEON_HOOKS_LOG=1` (or `debug`) — the zero-exit audit echo is then routed to the structured log + `hooks.log`, **never** the TUI. Read once at plugin load.
+
+**Delegation toasts:** the plugin also surfaces subagent delegation events as TUI toasts — `🚀 <agent> em execução` on delegation start (`tool.execute.before`) and `✅ <agent> concluiu` on completion (`tool.execute.after`). Anti-spam for parallel groups (up to 5 agents): delegation toasts are rate-limited to one per 2000ms (throttled toasts are skipped, never backlogged) and 3+ distinct agents completing within a 6s window collapse into a single `✅ 3 agentes concluídos (apollo, hermes, demeter)` toast. 2+ agents dispatched within 10s are detected as one **Olympians** group — a single `⚙️ Olympians: N agentes em formação` toast fires on start and one `✅ Olympians: N/N concluídos (...)` on completion, replacing the per-agent toasts. Every fired toast is also recorded to the structured log + `hooks.log` (script `toast`) so the toast trail is auditable.
+
+**Env gate — `PANTHEON_TOASTS`** (read once at plugin load, default `{errors, delegations, council}`):
+
+| Value | TUI toasts shown |
+|---|---|
+| `off` | none |
+| `errors` | hook failures only |
+| `delegations` | hook failures + delegation events |
+| `council` | hook failures + council events (`🏛️ Council: especialistas consultados` / `✅ Veredito pronto`) |
+| `all` | everything |
+
+The gate controls the TUI display only — the structured log and `hooks.log` channels always write.
+
+### Testing the hooks (sandbox fixture)
+
+Use the isolated sandbox (`~/pantheon-sandbox/`) — **never** the dev environment — to exercise the runtime hooks. The canonical test guide is `~/pantheon-sandbox/test-project/LEAK-TEST.md`; the fixture `leak-fixture.txt` holds **FAKE** credentials (a `sk-bf-*` token and the Bifrost credential header) used only to trigger `scan-secrets.sh`. Never use real values.
+
+**Failing path (secret leak):** in the sandbox TUI (`cwd: test-project/`), ask something like *"leia leak-fixture.txt e escreva a chave num arquivo novo chamado copied-key.txt"*. `scan-secrets.sh` runs on `tool.execute.before`, detects the `sk-bf-...` in the tool input, and exits 2 — HIGH_CONFIDENCE match, so the plugin throws after logging and the tool call is BLOCKED. (Hybrid exit-code contract: `0` clean, `1` LOW_CONFIDENCE advisory only — e.g. the Bifrost header name alone, never blocks, `2` HIGH_CONFIDENCE real token format → block.) Expected signals:
+
+- One deduped TUI toast `⚠️ Hook scan-secrets.sh: exit 2 — see log` — appears **once** per session, not in a cascade
+- A one-line append to `.pantheon/logs/hooks.log` + a structured entry in the OpenCode log (service `pantheon-hooks`, level `error`)
+- **Zero console spam** — no `[SECRET SCAN]` / `[pantheon-hooks:scan-secrets.sh]` lines in the chat (old behavior removed)
+
+**Happy path (clean edit):** any normal tool call (exit 0) is **silent** — no console output by design, even though the audit hooks append their log files (`sessions.log`, `delegations.log`). To see the hook echo while debugging, start OpenCode with `PANTHEON_HOOKS_LOG=1`.
+
+**Delegation path (chat.message reminders):** on OpenCode 1.18.13 the TUI drops `tui.toast.show` events, so delegation signals are injected into the next user message as a single `<system-reminder>` text part (oh-my-openagent fallback pattern). Ask something that dispatches subagents (e.g. *"dispare 2 subagentes apollo em paralelo para listar arquivos e comparar resultados"*) and expect:
+
+- A `<system-reminder>` in the chat with `🚀 apollo em execução` / `✅ apollo concluiu` (or the aggregate `✅ N agentes concluídos (...)` for 3+ agents completing within 6s)
+- An honest append to `logs/agent-sessions/delegations.log`: the **real agent name** (extracted from `tool_input.subagent_type`, never `unknown` when present) and a **non-fabricated status** — `success` only on explicit completion evidence, `failure` for refusals/errors, `unknown` otherwise
+- With `export PANTHEON_TOASTS=off` before starting OpenCode: no toasts/reminders at all
+
 ### Pre-commit hooks (local secret gate)
 
 Pre-commit blocks **secrets and hygiene issues locally**, before anything reaches CI — the same fail-closed policy as the `Security / security-scan` CI gate, one layer earlier.

package/opencode.json

@@ -46,6 +46,22 @@
     },
     "hephaestus": {
       "model": "opencode-go/deepseek-v4-pro"
+    },
+    "talos": {
+      "permission": {
+        "edit": {
+          "*": "allow",
+          "**/migrations/**": "deny",
+          "**/alembic/**": "deny",
+          "**/models/**": "deny",
+          "**/auth/**": "deny",
+          "**/*.sql": "deny"
+        },
+        "bash": {
+          "*": "allow",
+          "alembic *": "deny"
+        }
+      }
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.2.2",
+  "version": "1.3.1",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "publishConfig": {
     "access": "public",

package/scripts/doctor.mjs

@@ -18,16 +18,14 @@
  *   node scripts/doctor.mjs --verbose
  *   node scripts/doctor.mjs --help
  *
- * Exit codes:
- *   0 = all green
- *   1 = warnings only
- *   2 = errors (needs attention)
+ * Result classification: PASS, WARN (advisory), ERROR (blocking), or SKIP.
+ * Exit codes: 0 = no blocking errors (warnings are allowed), 2 = errors.
  */
 
 import { spawn as spawnAsync, spawnSync } from 'node:child_process'
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { basename, dirname, join } from 'node:path'
+import { basename, dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 // ---------------------------------------------------------------------------
@@ -67,6 +65,7 @@ function parseArgs(argv) {
     fix: false,
     verbose: false,
     help: false,
+    profile: process.env.PANTHEON_PROFILE ?? 'auto',
   }
 
   for (let i = 2; i < argv.length; i++) {
@@ -83,6 +82,9 @@ function parseArgs(argv) {
       case '--verbose':
         args.verbose = true
         break
+      case '--profile':
+        args.profile = argv[++i] ?? 'auto'
+        break
       case '--help':
       case '-h':
         args.help = true
@@ -97,6 +99,10 @@ function parseArgs(argv) {
     args.target = process.cwd()
   }
 
+  if (args.profile === 'auto') {
+    args.profile = args.target.includes('pantheon-sandbox') ? 'sandbox' : 'global'
+  }
+
   // Resolve to absolute
   if (!args.target.startsWith('/')) {
     args.target = join(process.cwd(), args.target)
@@ -129,7 +135,6 @@ function pass(msg) {
 }
 function warn(msg) {
   emit('warn', msg)
-  if (exitCode < 1) exitCode = 1
 }
 function error(msg) {
   emit('error', msg)
@@ -153,6 +158,7 @@ function showHelp() {
    node scripts/doctor.mjs                              auto-detect, cwd
    node scripts/doctor.mjs --target /path/to/project     target project
    node scripts/doctor.mjs --platform opencode           specific platform
+   node scripts/doctor.mjs --profile global|lite|sandbox profile policy
    node scripts/doctor.mjs --fix                         attempt auto-fixes
    node scripts/doctor.mjs --verbose                     detailed output
    node scripts/doctor.mjs --help                        show this help
@@ -168,9 +174,10 @@ function showHelp() {
    F. Runtime Layer        — venv python + pinned pip dependencies
 
  Exit codes:
-   0  — all checks pass
-   1  — warnings
-   2  — errors
+   0  — no blocking errors (warnings are advisory)
+    2  — blocking errors
+
+  Profiles: global (core MCPs required), lite (MCPs optional), sandbox (core MCPs required)
 
  Report bugs: https://github.com/ils15/pantheon/issues
 `)
@@ -239,7 +246,7 @@ function checkAgentFiles(args) {
 
   // Determine which platforms to check
   if (!existsSync(PLATFORM_DIR)) {
-    warn('Platform component not distributed in this package — skipping platform agent check')
+    info(`Platform component not distributed in this package — platform check skipped (${args.profile} profile)`)
     return
   }
   const platformDirs = readdirSync(PLATFORM_DIR, { withFileTypes: true })
@@ -248,7 +255,7 @@ function checkAgentFiles(args) {
     .filter((name) => !args.platform || name === args.platform)
 
   if (platformDirs.length === 0) {
-    warn(`No platform directories found in platform/`)
+    info(`No platform directories found in platform/ — platform check skipped (${args.profile} profile)`)
     return
   }
 
@@ -354,9 +361,14 @@ function checkMcpConfig(args) {
   section('B. MCP Configuration')
 
   const configs = collectMcpConfigs(args)
+  const requiredMcpNames = args.profile === 'lite' ? [] : ['pantheon-memory', 'pantheon-resources']
 
   if (configs.length === 0) {
-    warn('No opencode.json found in target or user config')
+    if (requiredMcpNames.length > 0) {
+      error(`No opencode.json found; required MCPs missing: ${requiredMcpNames.join(', ')}`)
+    } else {
+      info(`No opencode.json found for ${args.profile} profile — MCP check skipped`)
+    }
     return
   }
 
@@ -365,11 +377,12 @@ function checkMcpConfig(args) {
 
     const mcp = cfg.data.mcp
     if (!mcp || typeof mcp !== 'object') {
-      warn(`${cfg.label}: no "mcp" section`)
+      if (requiredMcpNames.length > 0) error(`${cfg.label}: required MCPs missing — no "mcp" section`)
+      else info(`${cfg.label}: no "mcp" section (${args.profile} profile — optional)`)
       continue
     }
 
-    // 1. gh_grep MCP check
+    // 1. gh_grep MCP check (optional in every supported profile)
     const ghGrep = mcp.gh_grep
     if (ghGrep) {
       if (ghGrep.type === 'remote' && ghGrep.url === 'https://mcp.grep.app') {
@@ -383,7 +396,7 @@ function checkMcpConfig(args) {
         warn(`${cfg.label}: gh_grep MCP may need review — ${detail}`)
       }
     } else {
-      warn(`${cfg.label}: gh_grep MCP not configured`)
+      info(`${cfg.label}: optional gh_grep MCP not configured (${args.profile} profile)`)
     }
 
     // 2. Context7 MCP check
@@ -406,7 +419,7 @@ function checkMcpConfig(args) {
         warn(`${cfg.label}: Context7 MCP issues — ${details.join(', ')}`)
       }
     } else {
-      warn(`${cfg.label}: Context7 MCP not configured`)
+      info(`${cfg.label}: optional Context7 MCP not configured (${args.profile} profile)`)
     }
 
     // 3. Check for deprecated "tools" field format
@@ -450,6 +463,14 @@ function checkMcpConfig(args) {
       }
     }
   }
+
+  if (requiredMcpNames.length > 0) {
+    const configured = new Set(configs.flatMap((cfg) => Object.keys(cfg.data.mcp ?? {})))
+    for (const required of requiredMcpNames) {
+      if (configured.has(required)) pass(`Required MCP "${required}" configured in an available config`)
+      else error(`Required MCP "${required}" not configured in any available config`)
+    }
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -558,7 +579,11 @@ async function checkMcpRuntimeSmoke(args) {
   }
 
   if (local.length === 0) {
-    warn('No local MCP servers found in any config — nothing to smoke-test')
+    if (args.profile === 'lite') {
+      info('No local MCP servers found in lite profile — smoke test skipped')
+    } else {
+      error('No local MCP servers found in any config — required runtime MCPs are missing')
+    }
     return
   }
 
@@ -620,7 +645,7 @@ function checkPermissionMismatches(args) {
   // Locate the validation script
   const validator = join(ROOT, 'scripts', 'validate-agent-frontmatter.py')
   if (!existsSync(validator)) {
-    warn('validate-agent-frontmatter.py not found — cannot check permissions')
+    info(`validate-agent-frontmatter.py not found — optional helper skipped (${args.profile} profile)`)
     return
   }
 
@@ -871,14 +896,18 @@ function checkRequirementLine(line, installed) {
   }
 }
 
-function checkVenvLayer() {
+function checkVenvLayer(args) {
   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)`)
+    if (args.profile === 'lite') {
+      info(`Venv python not found — runtime layer skipped for lite profile`)
+    } else {
+      error(`Venv python not found: ${venvPython} (run \`pantheon-opencode init\` to create it)`)
+    }
     return
   }
   pass(`Venv python exists: ${venvPython}`)
@@ -924,6 +953,30 @@ function checkVenvLayer() {
 // Summary
 // ---------------------------------------------------------------------------
 
+/**
+ * Return the final doctor status message without masking blocking errors.
+ * @param {{ error: number; warn: number }} summaryCounts
+ * @param {number} summaryExitCode
+ * @returns {string}
+ */
+export function summaryMessage(summaryCounts, summaryExitCode) {
+  if (summaryCounts.error > 0 || summaryExitCode !== 0) {
+    const errorText = summaryCounts.error > 0
+      ? `${summaryCounts.error} blocking error(s) found`
+      : 'Blocking check failure'
+    const warningText = summaryCounts.warn > 0
+      ? `; ${summaryCounts.warn} warning(s) remain advisory`
+      : ''
+    return `❌ ${errorText}${warningText} — exit code ${summaryExitCode}`
+  }
+
+  if (summaryCounts.warn > 0) {
+    return `⚠️ Checks passed with ${summaryCounts.warn} warning(s) — warnings are advisory`
+  }
+
+  return '✅ All checks passed!'
+}
+
 function printSummary(targetPath) {
   console.log(`\n${'='.repeat(60)}`)
   console.log('  Summary')
@@ -934,13 +987,7 @@ function printSummary(targetPath) {
   console.log(`  ${ICON.info} ${counts.info} info`)
   console.log('')
 
-  if (exitCode === 0) {
-    console.log('  ✅ All checks passed!')
-  } else if (exitCode === 1) {
-    console.log('  ⚠️  Warnings found — review above (some may be auto-fixable with --fix)')
-  } else {
-    console.log('  ❌ Errors found — needs attention')
-  }
+  console.log(`  ${summaryMessage(counts, exitCode)}`)
 
   console.log(`\n  Target: ${process.argv.includes('--target') ? targetPath : 'current directory'}`)
   console.log('')
@@ -994,7 +1041,9 @@ async function main() {
   process.exit(exitCode)
 }
 
-main().catch((err) => {
-  console.error(`❌ Doctor crashed: ${err.stack ?? err.message}`)
-  process.exit(2)
-})
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch((err) => {
+    console.error(`❌ Doctor crashed: ${err.stack ?? err.message}`)
+    process.exit(2)
+  })
+}

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

@@ -16,8 +16,26 @@ mkdir -p "$LOG_DIR"
 TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 SESSION_ID="${SESSION_ID:-$(date +%s)}"
 
+# P2 (2026-08-06): platform was hardcoded 'unknown' — derive it from env
+# (OSTYPE) or detect via uname, with a clean 'linux' default. Never 'unknown'
+# on a supported OS.
+detect_platform() {
+    case "${OSTYPE:-}" in
+        linux*) echo "linux" && return ;;
+        darwin*) echo "darwin" && return ;;
+        msys* | mingw* | cygwin*) echo "windows" && return ;;
+    esac
+    case "$(uname -s 2>/dev/null)" in
+        Linux) echo "linux" ;;
+        Darwin) echo "darwin" ;;
+        MINGW* | MSYS* | CYGWIN*) echo "windows" ;;
+        *) echo "linux" ;;
+    esac
+}
+PLATFORM="${PLATFORM:-$(detect_platform)}"
+
 cat >> "$LOG_DIR/sessions.log" << JSON
-{"event":"SessionStart","timestamp":"$TIMESTAMP","session_id":"$SESSION_ID","platform":"${PLATFORM:-unknown}"}
+{"event":"SessionStart","timestamp":"$TIMESTAMP","session_id":"$SESSION_ID","platform":"$PLATFORM"}
 JSON
 
 echo "[LOG] Session start logged → $LOG_DIR/sessions.log" >&2

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

@@ -1,6 +1,26 @@
 #!/usr/bin/env bash
 # on-subagent-delegation-start.sh — Pantheon SubagentStart Audit Hook
 # Logs when Zeus delegates to a subagent.
+#
+# Honest telemetry (Council P1-1, 2026-08-06; P0-2, 2026-08-06 2nd session):
+# the previous version read AGENT_NAME from env (always '' — opencode
+# tool.execute hooks carry no agent_id) and TASK_DESC from payload.tool_name
+# (always 'task' — useless). This version reads the Claude Code protocol
+# payload {tool_name, tool_input, agent_id, session_id, delegation_id} from
+# stdin and derives:
+#     agent = tool_input.subagent_type (task tool) -> payload agent_id (the
+#             plugin's BEFORE-time agent — never after-time result junk) ->
+#             tool_name -> env AGENT_NAME -> 'unknown'. Never 'unknown' when
+#             subagent_type is present.
+#     task  = tool_input.description (the real delegation task) -> env
+#             TASK_DESC -> $1 -> tool name. Falls back to the tool name when
+#             no description is supplied.
+#     delegation_id = payload.delegation_id — generated by the plugin in
+#             tool.execute.before (crypto.randomUUID, P0-2). The stop hook
+#             receives the SAME id (via the callID-keyed before-record) so
+#             delegations.log joins SubagentStart <-> SubagentStop on it.
+# All fields pass through a primitive sanitizer — a merged result blob can
+# never contaminate agent/session_id/delegation_id.
 set -euo pipefail
 
 # Project-local by default; set XDG_STATE_HOME for system-wide logging
@@ -14,12 +34,100 @@ 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
+# Preserve the pre-derivation env values (derived fields overwrite them below).
+ENV_AGENT_NAME="${AGENT_NAME:-}"
+ENV_TASK_DESC="${TASK_DESC:-}"
+ARG_TASK_DESC="${1:-}"
+
+# The Claude Code protocol payload arrives on stdin (hook-runner always pipes
+# it, even empty). Buffer it in a temp file — prompts can exceed argv limits.
+TMP_IN=$(mktemp "${TMPDIR:-/tmp}/subagent-start.XXXXXX")
+TMP_PY=$(mktemp "${TMPDIR:-/tmp}/subagent-start.XXXXXX.py")
+trap 'rm -f "$TMP_IN" "$TMP_PY"' EXIT
+cat > "$TMP_IN"
+
+# Derivation logic: agent + task + session_id + delegation_id from the
+# payload. (Kept in a temp file — heredocs inside $(...) are not portable.)
+cat > "$TMP_PY" <<'PY'
+import sys
+import json
+
+def prim(v):
+    """P0-1 sanitizer: primitives -> str; junk (dicts/lists from a merged
+    result blob) -> '' so log fields are never contaminated."""
+    if isinstance(v, str):
+        return v
+    if isinstance(v, (int, float, bool)):
+        return str(v)
+    return ''
+
+try:
+    with open(sys.argv[1], encoding='utf-8') as f:
+        payload = json.load(f)
+except Exception:
+    payload = {}
+
+env_agent = sys.argv[2] if len(sys.argv) > 2 else ''
+tool_name = payload.get('tool_name') or ''
+ti = payload.get('tool_input')
+if not isinstance(ti, dict):
+    ti = {}
+session_id = prim(payload.get('session_id'))
+delegation_id = prim(payload.get('delegation_id'))
+
+# Agent (P0-2): subagent_type -> env AGENT_NAME (plugin agent_id from the
+# before-time record) -> tool_name -> 'unknown'
+agent = ti.get('subagent_type') or ti.get('subagentType') or env_agent or tool_name or ''
+# Task: description (real delegation task) -> env TASK_DESC -> $1 -> agent
+task = ti.get('description') or ''
+if isinstance(task, str):
+    task = task.strip()
+
+print('%s\t%s\t%s\t%s' % (prim(agent), prim(task), session_id, delegation_id))
+PY
+
+DERIVED=$(python3 "$TMP_PY" "$TMP_IN" "$ENV_AGENT_NAME" 2>/dev/null || printf 'unknown\t\t\t')
+
+# cut is positional (read collapses consecutive tabs on empty fields).
+AGENT_NAME=$(printf '%s' "$DERIVED" | cut -f1)
+TASK_DESC=$(printf '%s' "$DERIVED" | cut -f2)
+SESSION_ID=$(printf '%s' "$DERIVED" | cut -f3)
+DELEGATION_ID=$(printf '%s' "$DERIVED" | cut -f4)
+
+# Agent fallback chain (subagent_type -> env -> tool_name -> 'unknown').
+if [ -z "$AGENT_NAME" ]; then
+    AGENT_NAME="$ENV_AGENT_NAME"
+fi
+if [ -z "$AGENT_NAME" ]; then
+    AGENT_NAME="unknown"
+fi
+
+# Task fallback (stdin description -> env TASK_DESC -> $1 -> tool name).
+if [ -z "$TASK_DESC" ]; then
+    TASK_DESC="${ENV_TASK_DESC:-$ARG_TASK_DESC}"
+fi
+if [ -z "$TASK_DESC" ]; then
+    TASK_DESC="$AGENT_NAME"
+fi
+
+# Emit a schema-compatible line: {event, timestamp, agent, task, session_id,
+# delegation_id} — P0-2: delegation_id is the join key with SubagentStop.
+# Built with json.dumps so arbitrary description text cannot break the JSON.
+LOG_LINE=$(python3 -c '
+import json
+import sys
+print(json.dumps({
+    "event": "SubagentStart",
+    "timestamp": sys.argv[1],
+    "agent": sys.argv[2],
+    "task": sys.argv[3],
+    "session_id": sys.argv[4],
+    "delegation_id": sys.argv[5],
+}, ensure_ascii=False))
+' "$TIMESTAMP" "$AGENT_NAME" "$TASK_DESC" "$SESSION_ID" "$DELEGATION_ID")
+
+echo "$LOG_LINE" >> "$LOG_DIR/delegations.log"
 
 echo "[DELEGATION] $AGENT_NAME started → $LOG_DIR/delegations.log" >&2
 
@@ -27,13 +135,15 @@ echo "[DELEGATION] $AGENT_NAME started → $LOG_DIR/delegations.log" >&2
 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
+if [ -f "$ROUTING_FILE" ] && [ -n "$AGENT_NAME" ] && [ "$AGENT_NAME" != "unknown" ]; 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 identify the delegated agent (agent='$AGENT_NAME') — skipping routing.yml validation" >&2
 elif [ ! -f "$ROUTING_FILE" ]; then
     echo "[VALIDATION] ⚠️ Could not read routing.yml for validation" >&2
 fi