pantheon-opencode 1.2.1 → 1.3.0

package/AGENTS.md

@@ -29,9 +29,19 @@ See [INSTALLATION.md](docs/INSTALLATION.md) for setup instructions.
 - Test: `npm test`
 - Lint: `npm run lint`
 
+## Teste de Instalação Global (sandbox)
+
+Para validar a instalação global do pacote pantheon-opencode COMO UM USUÁRIO REAL, use o sandbox isolado em `~/pantheon-sandbox/` (fora do repo, HOME + prefix npm + venv próprios). O ambiente de dev mistura 3 instalações + config global + venv — NÃO serve para testar instalação/empacotamento.
+
+- Rodar: `bash ~/pantheon-sandbox/run-test.sh` (opencode mcp list 5/5 connected + doctor 0 erros + abre TUI isolado)
+- Regra para agentes: ao validar instalação global (npm pack, `init`, MCPs, hooks), usar o sandbox — NUNCA testar no ambiente de dev
+- Descarte: `rm -rf ~/pantheon-sandbox`
+- Detalhes: ver `~/pantheon-sandbox/README.md`
+
 ## Conventions
 
 - TDD: Write failing test first, then implement
 - 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

@@ -615,7 +615,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 +689,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.
 
@@ -737,19 +737,57 @@ Edit README.md line 11: agents-17 → agents-18
 - Hardcoded secret detection
 - Minimum 80% test coverage (hard block)
 
-**Agent hooks enforce at runtime (`scripts/hooks/` + `.opencode/plugins/pantheon-hooks.ts`):**
-- `scan-secrets.sh` — detects hardcoded secrets and credentials (PreToolUse)
-- `validate-tool-safety.sh` — blocks destructive operations (PreToolUse)
-- `validate-talos-scope.sh` — restricts Talos hotfix scope (PreToolUse)
-- `on-subagent-delegation-start.sh` — tracks delegation start (PreToolUse)
-- `format-multi-language.sh` — auto-formats modified files (PostToolUse)
-- `log-session-start.sh` — audit trail of sessions (PostToolUse)
-- `on-subagent-delegation-stop.sh` — delegation cleanup (PostToolUse)
-- `validate-post-conditions.sh` — post-condition validation (event)
-- `audit-imports.sh` — detects wildcard imports and suspicious patterns (PostToolUse)
-- `run-type-check.sh` — runs mypy/tsc if config exists (PostToolUse)
-
-The `.opencode/plugins/pantheon-hooks.ts` plugin bridges these shell scripts to OpenCode events. OpenCode auto-discovers plugins from `.opencode/plugins/` when running from the project directory.
+**Agent hooks enforce at runtime (`scripts/hooks/` + `src/plugins/pantheon-hooks.ts`):**
+- `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; 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; 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)
 

package/bin/pantheon-init.mjs

@@ -37,6 +37,8 @@ function printUsage() {
   console.log('  npx pantheon-opencode init --preset <name> # Install and activate model preset');
   console.log('  npx pantheon-opencode set-tier <name>      # Set active model preset (global)');
   console.log('  npx pantheon-opencode set-tier <name> --project  # Set active model preset (project)');
+  console.log('  npx pantheon-opencode prune               # List legacy artifacts (dry-run)');
+  console.log('  npx pantheon-opencode prune --apply       # Remove stale backups');
   console.log('  npx pantheon-opencode --help              # Show this help');
 }
 
@@ -44,6 +46,18 @@ async function main() {
   const args = process.argv.slice(2);
   const command = args[0];
 
+  // prune handles its own --help (delegated to scripts/prune.mjs), so its
+  // dispatch must run BEFORE the generic --help check.
+  if (command === 'prune') {
+    const { spawnSync } = await import('child_process');
+    const pruneScript = path.join(ROOT, 'scripts', 'prune.mjs');
+    const result = spawnSync(process.execPath, [pruneScript, ...args.slice(1)], {
+      stdio: 'inherit',
+      cwd: ROOT,
+    });
+    process.exit(result.status ?? 1);
+  }
+
   if (args.includes('--help')) { printUsage(); process.exit(0); }
 
   if (command === 'set-tier') {

package/opencode.json

@@ -29,7 +29,7 @@
     }
   },
   "instructions": ["AGENTS.md", "src/instructions/*.instructions.md"],
-  "plugin": [],
+  "plugin": ["/home/ils15/pantheon/src/plugins/pantheon-hooks.ts"],
   "mcp": {
     "bifrost": {
       "type": "remote",
@@ -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.1",
+  "version": "1.3.0",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "publishConfig": {
     "access": "public",
@@ -8,9 +8,11 @@
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
+    "prepare": "husky",
     "setup": "node bin/pantheon-init.mjs init",
     "setup:lite": "node bin/pantheon-init.mjs init --clean --components agents,skills,instructions",
     "doctor": "node scripts/doctor.mjs",
+    "prune": "node scripts/prune.mjs",
     "init": "node bin/pantheon-init.mjs init",
     "opencode": "OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true opencode",
     "start": "OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true opencode",
@@ -18,6 +20,7 @@
     "postpublish": "node -e \"console.log('✅ Published pantheon-opencode v' + require('./package.json').version + ' to npm')\"",
     "version:status": "node scripts/versioning.mjs status",
     "version:apply": "node scripts/versioning.mjs apply",
+    "version:check": "node scripts/version-check.mjs",
     "release:dry-run": "node scripts/versioning.mjs status && npm pack --dry-run",
     "publish:next": "npm publish --tag next --access public",
     "lint": "npx biome ci .",
@@ -26,7 +29,8 @@
     "secret-scan": "node scripts/secret-scan.mjs",
     "hooks:install": "pre-commit install",
     "hooks:update": "pre-commit autoupdate",
-    "test:security": "npm run secret-scan && node tests/test_install_mcp_vision.mjs",
+    "test:security": "npm run secret-scan && node tests/test_install_mcp_vision.mjs && node tests/test_doctor_layers.mjs",
+    "test:node": "node --test tests/*.mjs",
     "test": "python3 -m pytest tests/ -q 2>&1 || echo \"No tests found\"",
     "test:ci": "python3 -m pytest tests/ -q --tb=short 2>&1 || true"
   },
@@ -55,6 +59,8 @@
     "src/mcp/*.sh",
     "src/routing.yml",
     "src/pantheon/**",
+    "src/plugins/**",
+    "scripts/hooks/**",
     "src/mcp/requirements*",
     "src/plugins/tui/**",
     "src/skills/**"
@@ -66,13 +72,16 @@
     "@commitlint/cli": "^19.8.0",
     "@commitlint/config-conventional": "^19.8.0",
     "@opencode-ai/plugin": "1.18.11",
-    "husky": "^9.1.7",
-    "pantheon-opencode": "^1.2.0-beta.9.7bef03e"
+    "husky": "^9.1.7"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/ils15/pantheon-opencode.git"
   },
+  "homepage": "https://github.com/ils15/pantheon-opencode",
+  "bugs": {
+    "url": "https://github.com/ils15/pantheon-opencode/issues"
+  },
   "keywords": [
     "github",
     "copilot",

package/scripts/changelog-extract.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * changelog-extract.mjs — print a version section from CHANGELOG.md
+ *
+ * The release workflow needs the CHANGELOG entry for the version it is about
+ * to tag. This script extracts the body of `## [<version>] - YYYY-MM-DD`
+ * (leading `v` tolerated, date optional) and prints it to stdout. When the
+ * section is missing it exits 1, so the workflow fails loudly: "add the
+ * section in the version-bump PR".
+ *
+ * Usage:
+ *   node scripts/changelog-extract.mjs 1.2.1
+ *   node scripts/changelog-extract.mjs v1.2.1 --changelog /path/to/CHANGELOG.md
+ */
+
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const DEFAULT_CHANGELOG = join(dirname(fileURLToPath(import.meta.url)), '..', 'CHANGELOG.md')
+
+/** Escape regex metacharacters so a version like 1.0.0 matches literally. */
+function escapeRegExp(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * Extract the body of a version section from changelog text.
+ *
+ * Finds the heading `## [<version>] - YYYY-MM-DD` (leading `v` and the date
+ * are optional) and returns everything after the heading line up to the next
+ * `## [` heading (or end of text). The `## [Unreleased]` heading is never
+ * matched, even when asked for explicitly.
+ *
+ * @param {string} changelogText - full CHANGELOG.md content
+ * @param {string} version - e.g. "1.2.1" or "v1.2.1"
+ * @returns {{found: boolean, body: string|null}} body is null when not found
+ */
+export function extractSection(changelogText, version) {
+  const normalized = String(version).trim().replace(/^v/i, '')
+  if (!normalized || /^unreleased$/i.test(normalized)) {
+    return { found: false, body: null }
+  }
+
+  const escaped = escapeRegExp(normalized)
+  // Single-line heading: `## [v?1.2.1]` optionally followed by ` - YYYY-MM-DD`.
+  // [ \t] (not \s) keeps the match from crossing newlines; the lookahead
+  // requires end-of-line or whitespace so `[1.0.0-beta]` can never match `1.0.0`.
+  const headingRe = new RegExp(
+    `^##[ \\t]+\\[v?${escaped}\\](?:[ \\t]*-[ \\t]*\\d{4}-\\d{2}-\\d{2})?(?=[ \\t]|$)`,
+    'm',
+  )
+  const match = headingRe.exec(changelogText)
+  if (!match) return { found: false, body: null }
+
+  // Advance past the heading line (match.index may point mid-line).
+  const newline = changelogText.indexOf('\n', match.index)
+  const start = newline === -1 ? changelogText.length : newline + 1
+
+  // Body ends at the next `## [` heading or end of text.
+  const nextHeading = /^##[ \t]+\[/m.exec(changelogText.slice(start))
+  const end = nextHeading ? start + nextHeading.index : changelogText.length
+
+  return { found: true, body: changelogText.slice(start, end).trim() }
+}
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href
+
+if (isDirectRun) {
+  const args = process.argv.slice(2)
+  let changelogPath = DEFAULT_CHANGELOG
+  let version = null
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]
+    if (arg === '--changelog') {
+      changelogPath = args[i + 1]
+      i += 1
+      continue
+    }
+    if (arg.startsWith('--changelog=')) {
+      changelogPath = arg.slice('--changelog='.length)
+      continue
+    }
+    version = arg
+  }
+
+  if (!version) {
+    console.error('Usage: node scripts/changelog-extract.mjs <version> [--changelog <path>]')
+    process.exitCode = 2
+  } else {
+    let text
+    try {
+      text = readFileSync(changelogPath, 'utf-8')
+    } catch {
+      console.error(`changelog-extract: cannot read ${changelogPath}`)
+      process.exitCode = 1
+    }
+
+    if (text !== undefined) {
+      const { found, body } = extractSection(text, version)
+      if (!found) {
+        console.error(`changelog-extract: section [${version}] not found in ${changelogPath}`)
+        console.error('Add the section in the version-bump PR — the release workflow requires it.')
+        process.exitCode = 1
+      } else {
+        process.stdout.write(`${body}\n`)
+        process.exitCode = 0
+      }
+    }
+  }
+}