pantheon-opencode 1.5.0-beta.3 → 1.5.0-beta.4

package/README.md

@@ -76,6 +76,57 @@ availability and configuration of OpenCode and any optional services you choose
 to use. Check the [releases](https://github.com/ils15/pantheon-opencode/releases)
 and [changelog](CHANGELOG.md) for the latest published changes.
 
+## Native delegation mode
+
+Set `PANTHEON_DELEGATE_MODE=native` to use OpenCode's native child-session
+delegation. Native mode is strict: it does not use foreground fallback, model
+failover, or retry; it performs a lazy capability probe on the first dispatch,
+and includes the resulting status in the delegation receipt.
+
+## Cost tool backend
+
+`pantheon_cost` has one backend: read-only `node:sqlite` against the selected
+`opencode.db`. On Node versions without `node:sqlite` (Node < 22.5), the tool
+returns `status: UNSUPPORTED`; it has no CLI fallback. Database failures return
+a contract status such as `UNAVAILABLE` or
+`CORRUPT_DATA` and include diagnostic detail, including captured stderr when
+available.
+
+
+## Code-mode execution (explicit opt-in)
+
+Scripts run through the `pantheon-code-mode` MCP server (`execute_code_script`)
+only when they are explicitly approved. Approval is recorded in
+`.pantheon/code-mode/manifest.json` with the SHA-256 of each script:
+
+```json
+{
+  "version": 1,
+  "scripts": {
+    "example-sync.sh": "<sha256>"
+  }
+}
+```
+
+- **No manifest → nothing executes.** A missing manifest returns
+  `INVALID_STATE`; scripts are never run implicitly.
+- **Not listed → `CONFLICT`.** The script must be approved first.
+- **Hash mismatch → `CORRUPT_DATA`.** The SHA-256 of the file on disk must
+  match the manifest entry, so edits after approval are detected.
+
+Approve or re-approve a script with the `approve_code_script` MCP tool:
+
+```
+approve_code_script("checkpoint-session.sh")
+```
+
+The installer seeds the manifest with the SHA-256 of every bundled script, so
+shipped scripts stay approved across installs. Re-run `approve_code_script`
+after intentionally editing a script. Status codes follow the shared nine-code
+contract (`OK`, `UNSUPPORTED`, `UNAVAILABLE`, `INVALID_INPUT`, `INVALID_STATE`,
+`CONFLICT`, `CORRUPT_DATA`, `TIMEOUT`, `ESCALATE`); with `json_output=true`,
+results carry a `status` field.
+
 
 ## What's new in 1.5.0-beta.2
 
@@ -218,6 +269,17 @@ optional codemap schema and `code_index`, `code_query`, and `code_neighbors`.
 The other shared MCP copies remain identical. Do not overwrite one memory copy
 with the other.
 
+### Task-result guard
+
+A `task-result-guard` intercepts calls to the native `task()` tool where the
+child session returns an empty or missing result. Instead of surfacing a silent
+`completed` with no payload (which confuses the orchestrator), the guard now
+raises an explicit error. This catches the common free-tier failure mode where a
+child session exceeds the uncached-prefill token budget (`BackendAdmissionRejected`)
+and returns nothing. For large payloads, prefer `pantheon_delegate` over native
+`task()` — the delegation layer has better timeout and error handling.
+
+
 ## Documentation
 
 - [Installation](docs/INSTALLATION.md) · [Quick start](docs/QUICKSTART.md)

package/README.pt-BR.md

@@ -78,6 +78,23 @@ escolher. Veja as [releases](https://github.com/ils15/pantheon-opencode/releases
 e o [changelog](CHANGELOG.md) para acompanhar as mudanças publicadas.
 
 
+## Execução code-mode (opt-in explícito)
+
+Scripts executados pelo MCP server `pantheon-code-mode` (`execute_code_script`)
+só rodam quando aprovados explicitamente. A aprovação fica em
+`.pantheon/code-mode/manifest.json` com o SHA-256 de cada script.
+
+- **Sem manifest → nada executa** (`INVALID_STATE`); nunca há execução implícita.
+- **Script fora do manifest → `CONFLICT`**; é preciso aprovar antes.
+- **Hash divergente → `CORRUPT_DATA`**; edições após a aprovação são detectadas.
+
+Aprove (ou reaprove) um script com a tool `approve_code_script`. O instalador
+semeia o manifest com o hash de todos os scripts empacotados. Os resultados
+seguem o contrato de nove códigos (`OK`, `UNSUPPORTED`, `UNAVAILABLE`,
+`INVALID_INPUT`, `INVALID_STATE`, `CONFLICT`, `CORRUPT_DATA`, `TIMEOUT`,
+`ESCALATE`) e, com `json_output=true`, incluem o campo `status`.
+
+
 ## Novidades da 1.5.0-beta.2
 
 - Instalador exclusivo para OpenCode: guias de plataformas consolidados em um
@@ -142,7 +159,7 @@ instalador remove referências Pantheon das duas formas de config antes de
 gravar apenas o registro Pantheon selecionado. Entradas de terceiros não são
 convertidas nem reivindicadas por essa regra.
 
-O relatório `pantheon_cost` (apenas V1) pode selecionar o banco com
+O relatório `pantheon_cost`, disponível nos plugins V1 e V2, pode selecionar o banco com
 `PANTHEON_OPENCODE_VERSION=v1` ou `v2` (`opencode.db` ou `opencode-v2.db`).
 `PANTHEON_COST_DB=/caminho/absoluto/para/opencode.db` tem precedência sobre o
 seletor de versão, e um `dbPath` explícito fornecido pelo chamador da

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.5.0-beta.3",
+  "version": "1.5.0-beta.4",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "type": "module",
   "publishConfig": {
@@ -68,6 +68,7 @@
     "!src/agents/README.md",
     "bin/*.mjs",
     "AGENTS.md",
+    "CHANGELOG.md",
     "opencode.json",
     "src/mcp/*.py",
     "src/instructions/*.instructions.md",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pantheon",
   "publisher": "ils15",
-  "version": "1.5.0-beta.3",
+  "version": "1.5.0-beta.4",
   "displayName": "Pantheon",
   "description": "Conductor-Delegate orchestration platform with 14 specialized agents, 21 skills, and OpenCode support.",
   "agents": "./src/agents",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.backends._legacy:_Backend"
 
 [project]
 name = "pantheon"
-version = "1.5.0-beta.3"
+version = "1.5.0-beta.4"
 description = "Multi-agent orchestration framework"
 requires-python = ">=3.11"
 dependencies = []

package/scripts/code_mode_server.py

@@ -16,6 +16,8 @@ Or via MCP client (stdio transport):
 from __future__ import annotations
 
 import asyncio
+import hashlib
+import json
 import logging
 import os
 import shutil
@@ -38,6 +40,30 @@ SCRIPT_TIMEOUT: int = 30
 # executor for longer than 5 minutes.
 MAX_SCRIPT_TIMEOUT: int = 300
 
+# ── Common status contract ────────────────────────────────────────────────────
+# Mirrors the nine-code `NativeTaskStatus` contract introduced in B3-05. Every
+# code-mode result is labelled with one of these statuses so callers can apply
+# the same retry/skip/escalate strategy across the whole platform.
+CONTRACT_STATUSES: frozenset[str] = frozenset(
+    {
+        "OK",
+        "UNSUPPORTED",
+        "UNAVAILABLE",
+        "INVALID_INPUT",
+        "INVALID_STATE",
+        "CONFLICT",
+        "CORRUPT_DATA",
+        "TIMEOUT",
+        "ESCALATE",
+    }
+)
+
+# Explicit installation mode: a script only runs when it is listed in this
+# manifest with a matching SHA-256. No manifest → nothing executes.
+MANIFEST_FILENAME: str = "manifest.json"
+MANIFEST_VERSION: int = 1
+_SHA256_HEX_LEN: int = 64
+
 # ── Env Allowlist ──────────────────────────────────────────────────────────────
 # Only these variables are passed to script subprocesses.  Everything else
 # (secrets, cloud credentials, etc.) is stripped to limit blast radius.
@@ -233,12 +259,19 @@ mcp = FastMCP(
 # ── Helpers ───────────────────────────────────────────────────────────────────
 
 
-def _validate_script_name(script_name: str) -> Path:
+def _validate_script_name(script_name: str, scripts_dir: Path | None = None) -> Path:
     """Validate a script name and return its resolved path.
 
-    Raises ValueError if the name is invalid, traverses paths, or
-    has a disallowed extension.
+    Args:
+        script_name: Bare file name of a script in the code-mode directory.
+        scripts_dir: Directory to resolve against. Defaults to ``SCRIPTS_DIR``.
+
+    Raises:
+        ValueError: If the name is invalid, traverses paths, or has a
+            disallowed extension.
     """
+    scripts_dir = scripts_dir or SCRIPTS_DIR
+
     if not script_name:
         raise ValueError("Script name cannot be empty")
 
@@ -253,12 +286,12 @@ def _validate_script_name(script_name: str) -> Path:
         allowed = ", ".join(sorted(ALLOWED_EXTENSIONS))
         raise ValueError(f"Extension '{ext}' not allowed. Allowed: {allowed}")
 
-    if SCRIPTS_DIR.is_symlink():
+    if scripts_dir.is_symlink():
         raise ValueError(f"Invalid script name: '{script_name}'")
 
     try:
-        scripts_root = SCRIPTS_DIR.resolve(strict=True)
-        script_path = (SCRIPTS_DIR / name).resolve(strict=True)
+        scripts_root = scripts_dir.resolve(strict=True)
+        script_path = (scripts_dir / name).resolve(strict=True)
     except (FileNotFoundError, OSError, RuntimeError):
         raise ValueError(f"Script '{script_name}' not found") from None
 
@@ -272,6 +305,213 @@ def _validate_script_name(script_name: str) -> Path:
     return script_path
 
 
+# ── Installation Mode: Manifest + SHA-256 ─────────────────────────────────────
+# The manifest is the explicit opt-in. A script is executable only when its
+# bare name is present in `manifest.json` AND the SHA-256 of the on-disk file
+# matches the recorded digest. Any deviation fails closed with a contract
+# status instead of executing.
+
+
+class ManifestError(Exception):
+    """Raised when the code-mode manifest cannot authorise execution."""
+
+    def __init__(self, status: str, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.message = message
+
+
+def _manifest_path(scripts_dir: Path | None = None) -> Path:
+    """Return the manifest path for *scripts_dir* (defaults to SCRIPTS_DIR)."""
+    return (scripts_dir or SCRIPTS_DIR) / MANIFEST_FILENAME
+
+
+def _sha256_file(path: Path) -> str:
+    """Return the hex SHA-256 digest of *path* (streamed, binary-safe)."""
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(65536), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _load_manifest(scripts_dir: Path | None = None) -> dict[str, str]:
+    """Load and validate the manifest, returning ``{script_name: sha256}``.
+
+    Raises:
+        ManifestError: With ``INVALID_STATE`` when the manifest is absent (no
+            explicit opt-in), or ``CORRUPT_DATA`` when it is unreadable or
+            malformed.
+    """
+    manifest_file = _manifest_path(scripts_dir)
+    if not manifest_file.is_file():
+        raise ManifestError(
+            "INVALID_STATE",
+            f"Code-mode manifest not found at {manifest_file}. No script executes "
+            "without explicit opt-in — run approve_code_script first.",
+        )
+
+    try:
+        raw = manifest_file.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ManifestError(
+            "CORRUPT_DATA", f"Code-mode manifest unreadable: {exc}"
+        ) from None
+
+    try:
+        data = json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        raise ManifestError(
+            "CORRUPT_DATA",
+            f"Code-mode manifest is malformed JSON: {manifest_file}",
+        ) from None
+
+    if not isinstance(data, dict):
+        raise ManifestError(
+            "CORRUPT_DATA", "Code-mode manifest must be a JSON object."
+        )
+
+    scripts = data.get("scripts")
+    if not isinstance(scripts, dict):
+        raise ManifestError(
+            "CORRUPT_DATA",
+            "Code-mode manifest is malformed: missing 'scripts' object.",
+        )
+
+    approved: dict[str, str] = {}
+    for name, digest in scripts.items():
+        if (
+            not isinstance(name, str)
+            or not isinstance(digest, str)
+            or len(digest) != _SHA256_HEX_LEN
+        ):
+            raise ManifestError(
+                "CORRUPT_DATA",
+                f"Code-mode manifest entry for '{name}' is malformed "
+                "(expected a 64-character SHA-256 hex digest).",
+            )
+        approved[name] = digest.lower()
+    return approved
+
+
+def _verify_approved(script_path: Path, scripts_dir: Path | None = None) -> None:
+    """Authorise *script_path* against the manifest.
+
+    Raises:
+        ManifestError: ``CONFLICT`` when the script is not listed and
+            ``CORRUPT_DATA`` when its hash does not match the recorded digest.
+    """
+    approved = _load_manifest(scripts_dir)
+    name = script_path.name
+    if name not in approved:
+        raise ManifestError(
+            "CONFLICT",
+            f"Script '{name}' is not approved in the code-mode manifest. "
+            "Run approve_code_script to opt in.",
+        )
+    actual = _sha256_file(script_path)
+    if actual != approved[name]:
+        raise ManifestError(
+            "CORRUPT_DATA",
+            f"Script '{name}' hash mismatch (expected {approved[name]}, got "
+            f"{actual}). Re-approve the script after verifying the change.",
+        )
+
+
+def _approve_script(
+    script_name: str, scripts_dir: Path | None = None
+) -> tuple[str, str]:
+    """Add or refresh *script_name* in the manifest with its SHA-256.
+
+    Returns:
+        A ``(status, message)`` tuple; the status is a contract code and is
+        ``OK`` on success.
+    """
+    target_dir = scripts_dir or SCRIPTS_DIR
+    try:
+        script_path = _validate_script_name(script_name, target_dir)
+    except ValueError as exc:
+        return "INVALID_INPUT", str(exc)
+
+    try:
+        approved = _load_manifest(target_dir)
+    except ManifestError as exc:
+        if exc.status == "INVALID_STATE":
+            approved = {}
+        else:
+            return exc.status, exc.message
+
+    approved[script_path.name] = _sha256_file(script_path)
+    payload = {
+        "version": MANIFEST_VERSION,
+        "scripts": dict(sorted(approved.items())),
+    }
+    try:
+        _manifest_path(target_dir).write_text(
+            json.dumps(payload, indent=2) + "\n", encoding="utf-8"
+        )
+    except OSError as exc:
+        return "UNAVAILABLE", f"Failed to write code-mode manifest: {exc}"
+
+    digest = approved[script_path.name]
+    return "OK", f"Approved '{script_path.name}' with SHA-256 {digest}"
+
+
+def _generate_manifest(scripts_dir: Path | None = None) -> int:
+    """Write a manifest covering every valid script in *scripts_dir*.
+
+    Used by the installer to (re)seed the explicit opt-in for bundled scripts.
+
+    Returns:
+        The number of scripts recorded.
+    """
+    target_dir = scripts_dir or SCRIPTS_DIR
+    try:
+        resolved_dir = target_dir.resolve(strict=True)
+    except (OSError, RuntimeError):
+        return 0
+
+    approved: dict[str, str] = {}
+    if resolved_dir.is_dir() and not resolved_dir.is_symlink():
+        for candidate in sorted(resolved_dir.iterdir()):
+            if candidate.name.startswith("."):
+                continue
+            if candidate.suffix.lower() not in ALLOWED_EXTENSIONS:
+                continue
+            try:
+                resolved = candidate.resolve(strict=True)
+            except (OSError, RuntimeError):
+                continue
+            if (
+                resolved.is_file()
+                and resolved.parent == resolved_dir
+                and _is_within(resolved, resolved_dir)
+            ):
+                approved[candidate.name] = _sha256_file(resolved)
+
+    payload = {
+        "version": MANIFEST_VERSION,
+        "scripts": dict(sorted(approved.items())),
+    }
+    try:
+        _manifest_path(target_dir).write_text(
+            json.dumps(payload, indent=2) + "\n", encoding="utf-8"
+        )
+    except OSError:
+        return 0
+    return len(approved)
+
+
+def _contract_result(
+    status: str, message: str, json_output: bool
+) -> str | dict[str, Any]:
+    """Build a contract-labelled error result (text or structured JSON)."""
+    if json_output:
+        return {"status": status, "error": message}
+    return f"[{status}] {message}"
+
+
+
 def _format_output(
     stdout: str,
     stderr: str,
@@ -395,10 +635,12 @@ def _build_result(
     metadata: dict[str, Any],
     json_output: bool,
     timeout_s: int,
+    status: str = "OK",
 ) -> str | dict[str, Any]:
     """Build the tool result in plain-text or structured JSON form."""
     if json_output:
         return {
+            "status": status,
             "stdout": stdout,
             "stderr": stderr,
             "exit_code": exit_code,
@@ -484,12 +726,17 @@ async def execute_code_script(
     try:
         script_path = _validate_script_name(script_name)
     except ValueError as e:
-        return str(e)
+        return _contract_result("INVALID_INPUT", str(e), json_output)
 
     metadata = _parse_frontmatter(script_path)
     denied = _validate_args(script_path, args)
     if denied is not None:
-        return denied
+        return _contract_result("INVALID_INPUT", denied, json_output)
+
+    try:
+        _verify_approved(script_path)
+    except ManifestError as e:
+        return _contract_result(e.status, e.message, json_output)
 
     timeout_s = _script_timeout(script_path)
 
@@ -553,6 +800,7 @@ async def execute_code_script(
                 metadata=metadata,
                 json_output=json_output,
                 timeout_s=timeout_s,
+                status="TIMEOUT",
             )
     except FileNotFoundError:
         return _build_result(
@@ -564,6 +812,7 @@ async def execute_code_script(
             metadata=metadata,
             json_output=json_output,
             timeout_s=timeout_s,
+            status="UNAVAILABLE",
         )
     except OSError as e:
         return _build_result(
@@ -575,10 +824,57 @@ async def execute_code_script(
             metadata=metadata,
             json_output=json_output,
             timeout_s=timeout_s,
+            status="UNAVAILABLE",
         )
 
 
+@mcp.tool(
+    name="approve_code_script",
+    description="Approve a .sh/.py script for execution by adding it to the "
+    "code-mode manifest with its SHA-256. Execution is opt-in: only approved "
+    "scripts with a matching hash run. Set json_output=true for structured JSON.",
+)
+async def approve_code_script(
+    script_name: str,
+    json_output: bool = False,
+) -> str | dict[str, Any]:
+    """Approve (or re-approve) a code-mode script.
+
+    Args:
+        script_name: Name of the script in the code-mode directory.
+        json_output: When True, return ``{"status", "message"}`` instead of a
+            ``[STATUS] message`` string.
+
+    Returns:
+        A contract-labelled result. ``OK`` on success, ``INVALID_INPUT`` when
+        the script name is invalid, or ``CORRUPT_DATA``/``UNAVAILABLE`` when
+        the manifest cannot be read or written.
+    """
+    status, message = _approve_script(script_name)
+    if json_output:
+        return {"status": status, "message": message}
+    return f"[{status}] {message}"
+
+
 # ── Main Entrypoint ───────────────────────────────────────────────────────────
 
-if __name__ == "__main__":
+
+def _cli() -> int:
+    """Handle CLI subcommands used by the installer; fall back to serving MCP."""
+    argv = sys.argv[1:]
+    if "--generate-manifest" in argv:
+        scripts_dir: Path | None = None
+        if "--scripts-dir" in argv:
+            index = argv.index("--scripts-dir")
+            if index + 1 < len(argv):
+                scripts_dir = Path(argv[index + 1])
+        count = _generate_manifest(scripts_dir)
+        print(f"code-mode manifest: {count} script(s) approved")
+        return 0
     mcp.run()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(_cli())
+

package/scripts/install/opencode.mjs

@@ -12,6 +12,7 @@
  * isolation is handled at runtime via OPENCODE_DB.
  */
 
+import { createHash } from 'node:crypto'
 import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, isAbsolute, join, resolve } from 'node:path'
@@ -61,6 +62,34 @@ function deepClone(value) {
   return JSON.parse(JSON.stringify(value))
 }
 
+/**
+ * (Re)generate the code-mode manifest with SHA-256 digests for every bundled
+ * script. This is the explicit installation opt-in: the MCP server only
+ * executes scripts listed here whose on-disk hash matches. Missing or empty
+ * directories approve nothing (0) — execution is never implicit.
+ */
+function writeCodeModeManifest(dir, dryRun) {
+  if (!existsSync(dir)) return 0
+  let names
+  try {
+    names = readdirSync(dir)
+      .filter((name) => /\.(sh|py)$/i.test(name) && !name.startsWith('.'))
+      .sort()
+  } catch {
+    return 0
+  }
+  if (names.length === 0) return 0
+  const scripts = {}
+  for (const name of names) {
+    scripts[name] = createHash('sha256')
+      .update(readFileSync(join(dir, name)))
+      .digest('hex')
+  }
+  const payload = `${JSON.stringify({ version: 1, scripts }, null, 2)}\n`
+  writeIfChanged(join(dir, 'manifest.json'), payload, dryRun)
+  return names.length
+}
+
 function readJsonConfig(filePath) {
   if (!existsSync(filePath)) return {}
 
@@ -665,6 +694,13 @@ export async function installOpenCode(
       stats.created++
     }
 
+    // B3-08: explicit installation mode — seed the manifest with SHA-256
+    // digests so the server never executes a script implicitly.
+    const approvedScripts = writeCodeModeManifest(dstCodeModeDir, dryRun)
+    if (approvedScripts > 0) {
+      info(`Code-mode manifest: ${approvedScripts} script(s) approved`)
+    }
+
     // ── tiers.json ──
     const srcTiers = join(ROOT, '.pantheon', 'tiers.json')
     const dstTiers = join(runtimeTarget, '.pantheon', 'tiers.json')

package/scripts/probe-pantheon-cost.mjs

@@ -28,6 +28,15 @@ function emit(status, detail, checks = []) {
   if (status === 'FAIL') process.exitCode = 1
 }
 
+function diagnostic(error) {
+  const message = error instanceof Error ? error.message : String(error)
+  const stderr =
+    error && typeof error === 'object' && typeof error.stderr === 'string'
+      ? error.stderr.trim()
+      : ''
+  return stderr === '' ? message : `${message}; stderr: ${stderr}`
+}
+
 function ambiental(detail) {
   emit('AMBIENTAL', detail)
 }
@@ -295,7 +304,7 @@ async function main() {
     checks.push('incompatible schema: PASS')
     emit('PASS', 'offline synthetic DB checks passed; no real DB was read', checks)
   } catch (error) {
-    emit('FAIL', error instanceof Error ? error.message : String(error), checks)
+    emit('FAIL', diagnostic(error), checks)
   } finally {
     rmSync(root, { recursive: true, force: true })
   }