pantheon-opencode 1.6.0-beta.10 → 1.6.0-beta.11

package/scripts/install/strings.mjs

@@ -47,6 +47,16 @@ const TABLE = {
     prereqMissing:
       'runtime prerequisites missing — install the tools above, or re-run with --no-mcp to install without Python MCP servers',
     v2Migrating: 'Migrating config to V2 native format...',
+    nothingApplied: 'Nothing applied.',
+    planOnlyNoYes: 'Plan only — re-run with --yes to apply.',
+    driftHeader: 'State changed since preview — aborting before any write:',
+    driftAbort: 'No files were written. Re-run to re-review.',
+    applyFailed: (msg) => `❌ Apply failed: ${msg}`,
+    alreadyApplied: 'Paths already applied — no automatic rollback:',
+    restoreRecoveryHint: (dir) => `Recover with: pantheon-opencode restore  (backup at ${dir})`,
+    restoreNoBackup:
+      'No backup was created (the failure occurred before the first write); the target is unchanged.',
+    dryRunNothingWritten: 'Preview only — no files were written.',
     // summary (printSummary)
     summaryInstalled: (target) => `OpenCode installed in ${target}`,
     summaryWithErrors: (target) => `Installation finished WITH ERRORS in ${target}`,
@@ -95,6 +105,16 @@ const TABLE = {
     prereqMissing:
       'pré-requisitos do runtime ausentes — instale as ferramentas acima, ou rode de novo com --no-mcp para instalar sem os MCPs Python',
     v2Migrating: 'Migrando config para o formato nativo V2...',
+    nothingApplied: 'Nada foi aplicado.',
+    planOnlyNoYes: 'Apenas o plano — rode de novo com --yes para aplicar.',
+    driftHeader: 'O estado mudou desde o preview — abortando antes de qualquer escrita:',
+    driftAbort: 'Nenhum arquivo foi escrito. Rode de novo para revisar.',
+    applyFailed: (msg) => `❌ Falha ao aplicar: ${msg}`,
+    alreadyApplied: 'Caminhos já aplicados — sem rollback automático:',
+    restoreRecoveryHint: (dir) => `Recupere com: pantheon-opencode restore  (backup em ${dir})`,
+    restoreNoBackup:
+      'Nenhum backup foi criado (a falha ocorreu antes da primeira escrita); o alvo está intacto.',
+    dryRunNothingWritten: 'Somente prévia — nenhum arquivo foi escrito.',
     // summary (printSummary)
     summaryInstalled: (target) => `OpenCode instalado em ${target}`,
     summaryWithErrors: (target) => `Instalação concluída COM ERROS em ${target}`,

package/scripts/install/venv.mjs

@@ -14,6 +14,8 @@ import { existsSync, rmSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { ACTIONS, recordChange } from './plan.mjs'
+
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const ROOT = join(__dirname, '..', '..')
 
@@ -40,10 +42,13 @@ export function venvPythonPath(target) {
  * Set up a Python virtual environment and install MCP dependencies.
  *
  * @param {string} target - Target installation directory (e.g. ~/.config/opencode)
- * @param {{ dryRun?: boolean, skipInstall?: boolean, force?: boolean }} [options]
+ * @param {{ dryRun?: boolean, skipInstall?: boolean, force?: boolean, recorder?: (change: object) => void }} [options]
  * @returns {{ venvPath: string, python: string }}
  */
-export function setupVenv(target, { dryRun = false, skipInstall = false, force = false } = {}) {
+export function setupVenv(
+  target,
+  { dryRun = false, skipInstall = false, force = false, recorder = null } = {},
+) {
   const venvPath = join(target, '.venv')
   const pythonBin = venvPythonPath(target)
 
@@ -57,7 +62,8 @@ export function setupVenv(target, { dryRun = false, skipInstall = false, force =
   }
 
   // Step 1b: Create venv if not exists
-  if (!existsSync(pythonBin)) {
+  const venvExists = existsSync(pythonBin)
+  if (!venvExists) {
     if (!dryRun) {
       console.log('  Creating .venv...')
       const result = spawnSync('python3', ['-m', 'venv', venvPath], {
@@ -69,8 +75,12 @@ export function setupVenv(target, { dryRun = false, skipInstall = false, force =
       }
     }
     console.log('  ✅ .venv created')
+    // A single synthetic entry for the venv directory — never enumerate its
+    // thousands of files. Unscored: the install summary does not count it.
+    recordChange({ path: venvPath, action: ACTIONS.CREATE, bytes: 0, scored: false }, recorder)
   } else {
     console.log('  ⏭️  .venv already exists')
+    recordChange({ path: venvPath, action: ACTIONS.UNCHANGED, bytes: 0, scored: false }, recorder)
   }
 
   // Step 2: Install MCP dependencies

package/scripts/install/vision-prompt.mjs

@@ -16,7 +16,7 @@
  * The write mirrors the `/pantheon-vision` command: atomic, `.bak` backup,
  * and a MERGE — existing keys are never overwritten.
  */
-import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { writeConfigWithBackup } from './shared.mjs'
@@ -81,6 +81,16 @@ export function mergeVisionModel(
   const status = writeConfigWithBackup(configPath, content, false, {
     expectedContent: existingRaw,
     beforeRecheck,
+    // This file is GLOBAL and lives outside the config dir, so the target-scoped
+    // exact backup set never captures it. Keep its own `<file>.bak` recovery.
+    beforeSwap: (existing) => {
+      if (existing === null) return
+      try {
+        copyFileSync(configPath, `${configPath}.bak`)
+      } catch {
+        // Best-effort: a backup failure must not block the write.
+      }
+    },
   })
   return { path: configPath, wrote: status === 'created', reason: status }
 }

package/scripts/mcp_persistence.py

@@ -914,15 +914,35 @@ def _validate_delegations(delegations: object) -> None:
 
 def _validate_tail(tail: object, payload_bytes: int | None = None) -> list[str]:
     """Validate bounded serialized tail lines."""
-    if not isinstance(tail, list) or len(tail) > MAX_TAIL_ITEMS:
-        raise ValueError("tail exceeds its size limit")
+    if not isinstance(tail, list):
+        raise ValueError("tail must be an array")
+    if len(tail) > MAX_TAIL_ITEMS:
+        raise ValueError(
+            f"tail has {len(tail)} items; maximum is {MAX_TAIL_ITEMS}; "
+            "remove tail entries or omit tail"
+        )
     for line in tail:
-        if not isinstance(line, str) or len(line.encode()) > MAX_TAIL_LINE_LENGTH:
-            raise ValueError("tail entries exceed their size limit")
+        if not isinstance(line, str):
+            raise ValueError("tail entries must be strings")
+        line_bytes = len(line.encode())
+        if line_bytes > MAX_TAIL_LINE_LENGTH:
+            raise ValueError(
+                f"tail entries are {line_bytes:,} UTF-8 bytes; maximum is "
+                f"{MAX_TAIL_LINE_LENGTH:,}; remove or shorten tail entries, "
+                "or omit tail"
+            )
     if payload_bytes is not None and payload_bytes > MAX_CONTEXT_CONTENT_BYTES:
-        raise ValueError("tail payload exceeds its size limit")
-    if sum(len(line.encode()) for line in tail) > MAX_CONTEXT_CONTENT_BYTES:
-        raise ValueError("tail payload exceeds its size limit")
+        raise ValueError(
+            f"tail payload is {payload_bytes:,} UTF-8 bytes; maximum is "
+            f"{MAX_CONTEXT_CONTENT_BYTES:,}; remove tail entries or omit tail"
+        )
+    tail_bytes = sum(len(line.encode()) for line in tail)
+    if tail_bytes > MAX_CONTEXT_CONTENT_BYTES:
+        raise ValueError(
+            f"tail contains {tail_bytes:,} UTF-8 bytes across strings; maximum "
+            f"is {MAX_CONTEXT_CONTENT_BYTES:,} bytes; remove tail entries or "
+            "omit tail"
+        )
     return tail
 
 
@@ -1020,8 +1040,14 @@ def _collect_context_content_errors(
     if not isinstance(content, str):
         errors.shape(prefix, "a string", content)
         return
-    if len(content.encode()) > MAX_CONTEXT_CONTENT_BYTES:
-        errors.add(prefix, f"exceeds the {MAX_CONTEXT_CONTENT_BYTES}-byte limit")
+    content_bytes = len(content.encode())
+    if content_bytes > MAX_CONTEXT_CONTENT_BYTES:
+        errors.add(
+            prefix,
+            f"is {content_bytes:,} UTF-8 bytes; maximum is "
+            f"{MAX_CONTEXT_CONTENT_BYTES:,} bytes. Reduce content or omit "
+            "optional tail if it contributes",
+        )
         return
     try:
         parsed = json.loads(content)
@@ -1030,11 +1056,10 @@ def _collect_context_content_errors(
         # it as a checkpoint. It is still bounded above.
         return
     if isinstance(parsed, list) and key == "tail":
-        if len(parsed) > MAX_TAIL_ITEMS or any(
-            not isinstance(line, str) or len(line.encode()) > MAX_TAIL_LINE_LENGTH
-            for line in parsed
-        ):
-            errors.add(f"{prefix}.tail", "exceeds its size limit")
+        try:
+            _validate_tail(parsed)
+        except ValueError as exc:
+            errors.reroot(prefix, str(exc))
         return
     if not isinstance(parsed, dict):
         # The message already names 'content': do not prepend the path again.
@@ -1164,6 +1189,11 @@ def _upsert_context_entry(
     name="context_save",
     description="Save a context checkpoint for a session/phase. "
     "Stores structured JSON in persistence KV with a key-specific TTL. "
+    "The serialized content is limited to 65,536 UTF-8 bytes. An included "
+    "tail may contain at most 100 strings, each at most 4,096 UTF-8 bytes, "
+    "with at most 65,536 UTF-8 bytes across all tail strings. Oversized "
+    "content or tail is rejected, never truncated; remove or omit optional "
+    "tail data when applicable. "
     "content is a JSON STRING; when it parses to an object, 'goal', 'phase', "
     "'delegations' and 'heartbeat' must each be JSON OBJECTS and 'tail' must "
     "be a JSON ARRAY. 'phase' is an object {current,total,name} — NOT a phase "
@@ -1180,7 +1210,12 @@ async def context_save(
         str,
         Field(
             description=(
-                "JSON checkpoint string. When it parses to an object, 'goal', "
+                "JSON checkpoint string, limited to 65,536 UTF-8 bytes. An "
+                "included 'tail' may contain at most 100 strings, each at "
+                "most 4,096 UTF-8 bytes, with at most 65,536 UTF-8 bytes "
+                "across all tail strings. Oversized input is rejected, never "
+                "truncated; remove or omit optional 'tail' when applicable. "
+                "When it parses to an object, 'goal', "
                 "'phase', 'delegations' and 'heartbeat' must be objects and "
                 "'tail' must be an array; all are optional. 'phase' is an "
                 "object {current,total,name}, not a counter. Example: "

package/scripts/prune.mjs

@@ -9,7 +9,10 @@
  * SAFETY: prune NEVER touches the active config, the active venv, the package
  * repo, or the installed package. It only:
  *   - lists old global `pantheon` installs (suggests `npm uninstall -g pantheon`)
- *   - removes stale `opencode.json.bak*` backups (age > threshold) with --apply
+ *   - removes stale LEGACY `opencode.json.bak*` backups (age > threshold) with
+ *     --apply. The modern installer no longer writes that sidecar — it creates an
+ *     exact backup set under `.pantheon/backups/` (retained by the installer, not
+ *     pruned here) — so this scan only cleans up pre-phase-2 installs.
  *   - lists legacy directories whose opencode.json references dead/relative
  *     paths (removal requires --apply --remove-dirs as explicit confirmation)
  *
@@ -102,8 +105,11 @@ export function findLegacyGlobalInstalls() {
 }
 
 // ---------------------------------------------------------------------------
-// (b) Stale opencode.json.bak* backups (age > threshold) in the config dir
-//     → removable with --apply. Fresh backups are listed as kept.
+// (b) Stale LEGACY opencode.json.bak* backups (age > threshold) in the config
+//     dir → removable with --apply. Fresh backups are listed as kept. The
+//     current installer does not create this sidecar (it keeps an exact,
+//     self-retaining backup set under .pantheon/backups/), so this only cleans
+//     up installs from before phase 2.
 // ---------------------------------------------------------------------------
 
 export function findStaleBackups(configDir, maxAgeDays = DEFAULT_BACKUP_AGE_DAYS) {

package/scripts/restore.mjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+/**
+ * restore.mjs — Pantheon exact-restore CLI (Beta 11 Setup, phase 2).
+ *
+ * Restores a backup set created by the installer back into the config dir,
+ * reproducing each file byte-for-byte and re-applying its recorded mode. The
+ * restore is itself reversible: the CURRENT state is backed up first.
+ *
+ * Safety contract:
+ *   - the backup manifest is verified (hash of every backed-up file) before any
+ *     restore; a tampered or incomplete set is refused outright;
+ *   - the backup-vs-current diff is shown BY PATH ONLY (never file contents);
+ *   - writing requires explicit authorization (`--yes`); a non-TTY run without
+ *     `--yes` previews and exits without writing.
+ *
+ * Usage:
+ *   pantheon-opencode restore [--project] [--from <dir>] [--dry-run] [--yes]
+ *
+ * Exit codes:
+ *   0 = restored (or preview shown with --dry-run)
+ *   1 = refused (missing/tampered backup, or no authorization)
+ *   2 = usage error
+ */
+
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { isAbsolute, join, resolve } from 'node:path'
+
+import {
+  backupRoot,
+  createBackupSet,
+  isBackupDirName,
+  listBackupSets,
+  planRestore,
+  restoreBackupSet,
+  verifyBackupSet,
+} from './install/backup.mjs'
+
+/**
+ * Resolve the config dir whose `opencode.json` the installer manages.
+ * `--project` targets the CWD; otherwise XDG / PANTHEON_HOME.
+ * @param {{ project?: boolean }} opts
+ * @returns {string}
+ */
+export function resolveConfigDir({ project = false } = {}) {
+  if (project) return resolve(process.cwd())
+  if (process.env.PANTHEON_HOME) return resolve(process.env.PANTHEON_HOME)
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config')
+  return join(base, 'opencode')
+}
+
+export function parseArgs(argv) {
+  const args = { project: false, from: null, dryRun: false, yes: false, help: false }
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    switch (arg) {
+      case '--project':
+        args.project = true
+        break
+      case '--dry-run':
+        args.dryRun = true
+        break
+      case '--yes':
+      case '-y':
+        args.yes = true
+        break
+      case '--from':
+        args.from = argv[++i] ?? null
+        break
+      case '--help':
+      case '-h':
+        args.help = true
+        break
+      default:
+        break
+    }
+  }
+  return args
+}
+
+export function showHelp() {
+  console.log(`
+pantheon-opencode restore — restore an exact installer backup
+
+Usage:
+  pantheon-opencode restore                       restore newest backup (global config)
+  pantheon-opencode restore --project             restore newest backup (project)
+  pantheon-opencode restore --from <dir>          restore a specific backup set
+  pantheon-opencode restore --dry-run             preview only (writes nothing)
+  pantheon-opencode restore --yes                 authorize the write (non-interactive)
+
+A backup set lives under <config-dir>/.pantheon/backups/<timestamp>/.
+Restore reproduces each file byte-for-byte and re-applies its recorded mode.
+File contents are never printed.
+`)
+}
+
+/**
+ * Choose the backup set to restore.
+ * @param {string} configDir
+ * @param {string|null} from
+ * @returns {{ dir: string, name: string } | null}
+ */
+export function pickBackupSet(configDir, from) {
+  if (from) {
+    // Accept either a bare timestamp set name (resolved under the backups root)
+    // or an explicit directory path.
+    if (isBackupDirName(from)) {
+      const dir = join(backupRoot(configDir), from)
+      return existsSync(dir) ? { dir, name: from } : null
+    }
+    const dir = isAbsolute(from) ? from : resolve(process.cwd(), from)
+    if (!existsSync(dir)) return null
+    return { dir, name: dir.split(/[\\/]/).pop() }
+  }
+  return listBackupSets(configDir)[0] ?? null
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.configDir
+ * @param {string} opts.backupDir
+ * @param {boolean} [opts.dryRun]
+ * @param {boolean} [opts.yes]
+ * @returns {Promise<{ ok: boolean, code: number, entries?: object[] }>}
+ */
+export async function runRestore({ configDir, backupDir, dryRun = false, yes = false }) {
+  const verify = verifyBackupSet(backupDir)
+  if (!verify.ok) {
+    console.error(
+      `❌ Refusing to restore: backup failed integrity verification (${verify.reason ?? 'hash mismatch'}).`,
+    )
+    return { ok: false, code: 1 }
+  }
+
+  const plan = planRestore(backupDir, configDir)
+  if (plan.error) {
+    console.error(`❌ Refusing to restore: ${plan.error}.`)
+    return { ok: false, code: 1 }
+  }
+
+  const counts = { create: 0, update: 0, remove: 0, unchanged: 0 }
+  for (const entry of plan.entries) counts[entry.action] += 1
+
+  console.log('')
+  console.log(`Restore plan — ${configDir}`)
+  console.log(`  from   ${backupDir}`)
+  for (const entry of plan.entries) {
+    if (entry.action === 'unchanged') continue
+    console.log(`  ${entry.action.padEnd(9)} ${entry.relativePath}`)
+  }
+  console.log(
+    `  ${counts.create} create · ${counts.update} update · ${counts.remove} remove · ${counts.unchanged} unchanged`,
+  )
+
+  if (dryRun) {
+    console.log('  (dry-run) No files were written.')
+    return { ok: true, code: 0, entries: plan.entries }
+  }
+
+  if (!yes) {
+    // Reuse the shared confirm semantics (default NO). An interactive TTY may
+    // authorize without --yes; a non-TTY run must never proceed silently.
+    const tty = Boolean(process.stdin.isTTY && process.stdout.isTTY)
+    if (!tty) {
+      console.error('❌ Refusing to restore without authorization. Re-run with --yes.')
+      return { ok: false, code: 1 }
+    }
+    const { promptReview } = await import('./install/interactive.mjs')
+    const accepted = await promptReview('Restore these changes?', { default: false })
+    if (!accepted) {
+      console.log('  Nothing restored.')
+      return { ok: true, code: 0, entries: plan.entries }
+    }
+  }
+
+  // Reversible: snapshot the CURRENT state of exactly the affected paths first.
+  // Retention is DISABLED here (`keep: 0`): a retention pass at this point could
+  // delete the very set being restored once 5 older sets already exist (the new
+  // snapshot would be the 6th, and pruning would drop the oldest two — including
+  // the source). Apply still prunes; restore never deletes backups.
+  const { dir: preDir } = createBackupSet({
+    configDir,
+    entries: plan.manifest.entries.map((e) => e.relativePath),
+    packageVersion: plan.manifest.packageVersion,
+    keep: 0,
+  })
+  console.log(`  pre-restore backup: ${preDir}`)
+
+  restoreBackupSet(backupDir, configDir, { dryRun: false })
+  console.log(`  ✅ Restored ${plan.entries.length} path(s).`)
+  return { ok: true, code: 0, entries: plan.entries }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2))
+  if (args.help) {
+    showHelp()
+    return
+  }
+  const configDir = resolveConfigDir({ project: args.project })
+  const backup = pickBackupSet(configDir, args.from)
+  if (!backup) {
+    console.error(`❌ No backup set found under ${backupRoot(configDir)}`)
+    process.exitCode = 1
+    return
+  }
+  const result = await runRestore({
+    configDir,
+    backupDir: backup.dir,
+    dryRun: args.dryRun,
+    yes: args.yes,
+  })
+  if (!result.ok) process.exitCode = result.code
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((err) => {
+    console.error(`❌ Restore failed: ${err instanceof Error ? err.message : String(err)}`)
+    process.exitCode = 1
+  })
+}

package/skills-lock.json

@@ -1,7 +1,7 @@
 {
   "src/skills/agent-coordination/SKILL.md": "d4bd70c18bc5726ea6784fe0a9c514446ca313e4c3ba4d658a0ff6658001aece",
   "src/skills/artifact-management/SKILL.md": "91d68c8f2d1b642725adfc6df11e55865a8491aca690dc27d02ea7c778d49d41",
-  "src/skills/auto-continue/SKILL.md": "79aa1786ab62332abc45986d147ee944836e6f7a496c289e793639add4211229",
+  "src/skills/auto-continue/SKILL.md": "3fd4167b2e015510aec428098d27bb15854ba239c4dc7a064177d62e2353af86",
   "src/skills/clonedeps/SKILL.md": "3e0b43cf96da98c83699dc48db3fd58fbfda84b9022bb70d3747875c81c3e124",
   "src/skills/code-review-checklist/SKILL.md": "6445513ab880efdb1005861ae13cb9a215f80b9d260f6278499f60771e07858c",
   "src/skills/codemap/SKILL.md": "87af5271e1576e154cadff313eab16264b726e43d094520736b7a5b03b409a4a",

package/src/agents/iris.md

@@ -46,6 +46,12 @@ mcp_tools:
 - Always open PRs as DRAFT unless explicitly told otherwise
 - Wait for human approval before merging
 - Never delete branches without confirmation
+- **Never bypass hooks.** Never pass `--no-verify`, `-n`, or any hook-skipping
+  equivalent to `git commit`/`git push`. The pre-commit and commit-msg hooks MUST
+  run: they are a fail-closed security gate, not an optional step.
+- **A failing or missing hook tool is a STOP, not an obstacle.** Report the exact
+  hook and error to @zeus and halt; never bypass it, amend around it, or work
+  around it — even when the failure looks unrelated to the staged change.
 
 ## Handoffs
 - Called by @zeus after review phase

package/src/agents/zeus.md

@@ -34,7 +34,7 @@ skills:
 
 Zeus never implements code, but visual references from the user are implementation context and must reach the specialist who does the work.
 
-- When a request includes an image or screenshot, inspect it with native image input or `vision_describe`. If neither can access it, state that limitation instead of guessing.
+- When a request includes an image or screenshot, use image content already available in the conversation. Call `vision_describe` only if it appears in the active root tool list; otherwise state the limitation instead of guessing.
 - For UI work, delegate to @aphrodite and include the image reference (URL/path when available) plus a concise description of the relevant layout, elements, and requested outcome in the task prompt.
 - Tell the implementer to compare the reference with the current UI and preserve unrelated existing changes. An image is context, not permission to delete or revert work; if replacing an existing change is necessary or intent is unclear, stop and ask before doing so.
 
@@ -52,12 +52,12 @@ Zeus nunca toca no código. Use o menor fluxo que preserve segurança: encaminhe
 | Ação | Status | Como fazer |
 |------|--------|------------|
 | Editar arquivo | ❌ BLOQUEADO | Delegar para @hermes, @aphrodite, @talos |
-| Bash shell | ❌ BLOQUEADO | Usar task() com subagente apropriado |
+| Bash shell | ❌ BLOQUEADO | Delegar via ferramenta `subagent` para o especialista apropriado |
 | Executar script | ❌ BLOQUEADO | Delegar para @prometheus |
 | Instalar dep | ❌ BLOQUEADO | Delegar para @prometheus |
 | Git commit/push | ❌ BLOQUEADO | Delegar para @iris |
 | Ler arquivo | ✅ Permitido | Via Read/Glob/Grep tools |
-| task() delegar | ✅ Permitido | Única ferramenta de ação de Zeus |
+| `subagent` delegar | ✅ Observado no root Beta 10 | Use o schema mostrado pelo runtime; `task()` é nomenclatura da API/host, não ferramenta root presumida |
 | memory MCP | ✅ Permitido | memory_search |
 | persistence MCP | ✅ Checkpoints | context_save, context_get |
 | skill() | ✅ Permitido | Carregar skills |
@@ -67,20 +67,20 @@ Zeus nunca toca no código. Use o menor fluxo que preserve segurança: encaminhe
 2. Pergunte ao usuário qual agente usar
 3. NUNCA tente fazer você mesmo
 
-**Gates proporcionais** (via `agent/askQuestions`):
-- Correção delimitada e reversível: não force planejamento nem aprovação de plano; encaminhe uma vez ao especialista, que inspeciona o contexto necessário, altera, verifica o comportamento e resume.
+**Gates proporcionais** (via ferramenta root `question`, se visível):
+- Tarefa delimitada, reversível, de baixa incerteza e não sensível/sem mudança material em API visível ao usuário: não force planejamento nem aprovação de plano; se delegar, encaminhe uma vez ao especialista correto, que inspeciona o contexto necessário, altera, verifica o comportamento e resume.
 - Planejamento e discovery são sob demanda; council apenas quando o usuário invocar `/pantheon` ou uma decisão material realmente exigir perspectivas distintas. Nunca dispare council para correção pequena.
-- Auth/segurança, dados/schema/migração e mudanças com impacto amplo mantêm revisão Themis e aprovação humana antes de ação sensível ou irreversível.
+- Escopo amplo/material, alta incerteza, mudança de API visível ao usuário, auth/segurança, dados/schema/migração e operações destrutivas mantêm os gates de planejamento, revisão e aprovação aplicáveis; trabalho auth/segurança e dados/schema mantém revisão Themis.
+- Mantenha os agentes especializados disponíveis sob demanda; não remova uma especialidade com base em uma única tarefa ou observação de overhead.
 - Commit, push, merge, deploy de produção, alteração global, operação destrutiva e ampliação de permissões nunca são automáticos.
 
 ## Plan Handoff and Approval
 
 Whenever the user explicitly asks for a plan, or starts `/pantheon-deepwork`:
 
-1. Delegate planning to @athena synchronously. Tell Athena to return the
-   **complete Markdown plan in the final task result** and not to call
-   `agent/askQuestions`; Zeus owns the user-facing approval gate.
-2. Check that the returned task result itself contains the full plan, including
+1. Delegate planning to @athena synchronously via `subagent`. Tell Athena to return the
+   **complete Markdown plan in the final subagent result**; Zeus owns the user-facing approval gate.
+2. Check that the returned subagent result itself contains the full plan, including
    its goal, scope and assumptions,
    actionable phases, affected files or areas, dependencies, verification,
    risks, open questions, and acceptance criteria. If the plan is missing or
@@ -90,9 +90,9 @@ Whenever the user explicitly asks for a plan, or starts `/pantheon-deepwork`:
    conversation**. Preserve its sections and phase details; do not summarize it
    away, show only a file path, or rely on the hidden child-agent transcript.
    The plan message must be visible in the conversation before you trigger any
-   approval UI. Do not combine the plan and `agent/askQuestions` in one tool
+   approval UI. Do not combine the plan and `question` in one tool
    call or issue the question first and plan afterward.
-4. After the plan has been published, use `agent/askQuestions` to request
+4. After the plan has been published, use the exposed `question` tool to request
    approval or changes. If the runtime cannot guarantee that the plan message
    is visible before the question UI opens, do not open the question UI: leave
    the full plan in the conversation, ask for approval in plain text after it,
@@ -114,7 +114,7 @@ documented for later phases, but it never hides a requested plan. For
 
 **`subagent_type: general` e `subagent_type: explore` sao PROIBIDOS.** Nao existem no Pantheon.
 
-Delegue apenas quando a tarefa precisa de outro especialista ou não pode ser executada diretamente com segurança. Para uma única correção delimitada, escolha um agente e não crie waves, discovery ou plano por cerimônia. Antes de CADA task(), quando delegação for necessária, execute esta árvore:
+Delegue apenas quando a tarefa precisa de outro especialista ou não pode ser executada diretamente com segurança. Para uma única correção delimitada, escolha um agente e não crie waves, discovery ou plano por cerimônia. Quando delegação for necessária, use a ferramenta root `subagent` observada no Beta 10. `task()` é nomenclatura da API/host, não ferramenta root presumida. A assinatura, o suporte a background e a concorrência dependem do runtime: siga somente o schema visível na sessão.
 
 ```
 Tarefa envolve:
@@ -138,56 +138,13 @@ Ainda assim sem match? -> Pergunte ao usuario qual agente usar. NUNCA use genera
 
 REGRA: "fora de .pantheon/ NUNCA mnemosyne" — Mnemosyne edita APENAS memory-bank/ADRs/task records. Docs de projeto (README, docs/) vão para talos/implementador/iris.
 
-## Background Delegation (para trabalho independente/concurrente)
+## Delegação e concorrência (condicional ao runtime)
 
-**Requer:** `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true` (env var)
+Prefira delegação síncrona para trabalho unitário ou dependente. Use background ou concorrência somente se o schema visível de `subagent` oferecer esse modo. `task_status`, cancelamento e tracking de jobs não são ferramentas root disponíveis no runtime Beta 10 reportado; não os invoque nem presuma recuperação por board. Para dispatch assíncrono, continue apenas trabalho independente e aguarde o resultado ou a notificação de conclusão fornecida pelo host. Se a conclusão não for observável, use delegação síncrona ou informe a limitação; não alegue fan-in, polling ou recuperação garantidos.
 
-Use `background=true` quando houver trabalho independente que justifique concorrência. Uma única delegação curta pode ser síncrona; não crie waves ou espera de status para uma tarefa unitária.
+`OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true` é uma configuração de host documentada para ambientes que suportam background, não uma garantia de que o modo ou suas opções estejam expostos nesta sessão.
 
-```
-task(background=true, subagent_type="apollo", prompt="...")
-  -> retorna IMEDIATO: { task_id: "ses_xxx", state: "running" }
-
-task_status(task_id="ses_xxx", wait=true)
-  -> bloqueia ate completar: { state: "completed", task_result: "..." }
-```
-
-### DELEGATION_RULES (native task API)
-
-1. Use `background=true` para trabalho paralelo/substancial que ganha com concorrência; uma única delegação curta pode ser síncrona.
-2. Se o dispatch for background, recolha com `task_status(task_id=..., wait=true)` — bloqueia ate o fim, sem polling ou polling manual.
-3. Use `task_status(wait=true)` apenas para fan-in explicito / recuperacao sob demanda.
-
-### Background (usar para trabalho paralelo independente)
-- **Apollo, Hermes, Aphrodite, Demeter, Hephaestus, Prometheus**
-- Dispare em waves paralelas: ate 5 concorrentes
-- Recolha com `task_status(wait=true)` quando todos estiverem prontos
-
-### Sincrono (excecoes — so quando necessario)
-- **Athena, Themis** -> precisam de contexto completo da sessao
-- **Talos** -> hotfix é rapido, overhead de background nao compensa
-- **Iris, Nyx, Mnemosyne, Gaia** -> operacoes curtas
-
-### Workflow (quando houver tarefas paralelas independentes)
-
-```
-Wave 1 — ate 5 em paralelo
-  task(background=true, apollo, "discovery")
-  task(background=true, demeter, "schema")
-  → task_status(apollo_id, wait=true)
-  → task_status(demeter_id, wait=true)
-
-Wave 2 — ate 5 em paralelo (depende da Wave 1)
-  task(background=true, hermes, "backend")
-  task(background=true, aphrodite, "frontend")
-  → task_status(hermes_id, wait=true)
-  → task_status(aphrodite_id, wait=true)
-
-Wave N — revisão somente quando exigida pelo risco; Themis síncrono
-  task(themis, "review")
-```
-
-Anuncie waves somente quando houver trabalho independente que as justifique; uma tarefa unitária não precisa de anúncio. Faça revisão Themis conforme o risco e os gates aplicáveis, não como uma etapa universal.
+Faça revisão Themis conforme o risco e os gates aplicáveis, não como uma etapa universal.
 
 
 ## Limite de delegação
@@ -202,7 +159,7 @@ Use `pantheon://routing` for the current routing configuration.
 - Routing: `pantheon://routing`
 - Artifacts: `skill: artifact-management`
 - Context compression: `skill: context-compression`
-- Env var: `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true`
+- Env var de host (quando aplicável): `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true`
 - Guards: `instructions/zeus-timeout-retry.instructions.md`
 
 ### Plugin Enforcer (auto — session.idle hook)
@@ -222,7 +179,7 @@ vão a idle com todos incompletos. Guards (todos no `src/pantheon/todo-enforcer.
 ## Wave 4 (PR #46): Empty-Result Retry + /cost + Themis Tier
 
 ### Empty-Result Retry (runtime — automatic)
-Empty-response detection for native `task()` subagent calls is wired at runtime
+Empty-response detection for host/API `task()` child-session dispatches is wired at runtime
 in `task-result-guard.ts` (plugin `tool.execute.after` chain): an
 empty/whitespace-only result is converted into an explicit error so a silent
 child failure is never mistaken for success. No manual retry helper is required.