Skip to content

Architecture

🇧🇷 Versão em Português disponível: Leia em Português

Audience: developers extending Pantheon and anyone who wants to know how the pieces fit. Setup is in Installation; user-facing 2.x behavior is in OpenCode 2.x.

Agent flow

Pantheon replaces the single-agent coding loop with a conductor and specialists.

flowchart TD
    User(["👤 User Request"]) --> Zeus["⚡ Zeus (Conductor)"]

    Zeus -->|"Planning"| Athena["🏛️ Athena (Plan)"]
    Zeus -->|"Discovery"| Apollo["🔍 Apollo (Discovery)"]
    Zeus -->|"Hotfix (Express)"| Talos["🛡️ Talos (Hotfix)"]
    Zeus -->|"Memory Management"| Mnemosyne["🧠 Mnemosyne (Memory)"]
    Zeus -->|"Git/GitHub PRs"| Iris["🌈 Iris (GitHub)"]

    Athena -.->|"Approved Plan"| Zeus
    Zeus -->|"Implementation"| Specialists

    subgraph Specialists["🛠️ Implementation Specialists"]
        Hermes["✉️ Hermes (Backend)"]
        Aphrodite["🎨 Aphrodite (Frontend)"]
        Demeter["🌾 Demeter (Database)"]
        Prometheus["🔥 Prometheus (Infra)"]
        Hephaestus["🔨 Hephaestus (AI Pipelines)"]
        Nyx["🌙 Nyx (Observability)"]
        Gaia["🌍 Gaia (Remote Sensing)"]
    end

    Specialists -->|"Material & Sensitive Changes"| Themis["⚖️ Themis (Review & Audit)"]
    Themis -->|"PASS Verdict"| Zeus
    Zeus -->|"Delivery & Summary"| User

Zeus orchestrates but never implements. He routes bounded work to one specialist and adds planning, discovery, parallel work, and review when scope and risk call for them. /pantheon-deepwork is the checkpointed workflow for heavy multi-phase work. The canonical agent files live in src/agents/*.md; Agents & Skills indexes them.

The quality gates are qualitative, not file/line thresholds: self-contained work stays inline; one bounded specialist task goes to one agent; independent fronts may use separate root dispatches. Themis reviews material and sensitive changes — auth, security, data/schema, and anything that changes behavior broadly. See Permissions, Gates & Delegation.

Delegation mechanics

Pantheon delegates through the host's native child-session engine. The callable tool is subagent in the reported root runtime; host/API documentation calls the same mechanism task(). Tool availability, background options, and completion observability are properties of the active runtime, not of Pantheon. The former pantheon_delegate tool and its delegation engine were removed.

Every root dispatch carries a concise handoff brief: objective/result, bounded scope and acceptance criteria, only the relevant inputs, constraints and safety gates, expected deliverable and return format, and verification. Do not copy the full conversation or unrelated history.

Return contracts are role-specific:

Caller Return format
Implementation agent ## subtask_summary with files, summary, tests, blockers
Investigation (apollo) Structured findings: bullets, paths with line numbers, snippets ≤3 lines
Planner (athena) The complete Markdown plan, never a summary or a pointer
Council specialist ## specialist_response

Delegated work gets at most one retry after an initial transient failure. When no completion/status tool is exposed, prefer synchronous dispatch or wait for a host notification; do not assume polling, cancellation, job tracking, or board-based recovery.

On OpenCode 2.x, the plugin additionally enforces a caller/target matrix for Pantheon-managed subagent requests when the host exposes ctx.permission.hook. It matches the permission source's session, message, and tool-call ids to a short-lived record from tool.execute.before, then requires the host session to have no parentID. Missing, stale, replayed, or mismatched origins fail closed. If the hook is unavailable, host permissions remain in control. The matrix itself is documented in Permissions, Gates & Delegation.

What the plugin registers

There is a single generation: 2.0 removed the V1 plugin line, and the surface below is the only one.

The plugin is registered under the plural plugins key as the <installed>/src/plugin directory. src/plugin/index.ts re-exports the real entry at src/plugin.ts; the tool-hook registration in src/plugin.ts is fed by the tool definitions in src/pantheon/tools.ts.

Four unconditional tools:

  • hashline_edit — src/pantheon/tools.ts
  • pantheon_cost — src/pantheon/tools.ts
  • pantheon_model — src/pantheon/tools.ts
  • pantheon_local_decision — src/pantheon/tools.ts. The advisory local selector; it rejects execution unless the host tool context identifies the caller as Zeus.

Up to two host-dependent tools:

  • vision_describe — added only when ctx.model.list is a function (src/plugin.ts; definition at src/pantheon/native-vision.ts).
  • pantheon_bounded_read — added only when the tool.execute.before hook registered and the host exposes the permission and session APIs (src/plugin.ts; definition at src/pantheon/bounded-read.ts). Root Zeus sessions only.

The three goal tools are absent because the goal loop needs infrastructure the host's PluginContext does not expose. The gap is reported as goal-tools.

The plugin also wires five event subscriptions (session.created, session.idle, session.deleted, session.error, session.compacted), session hooks (prompt, context, compaction), a read-only-enforcing execute.before hook (the same handler denies the orchestrator read/glob/grep of source, tests and scripts), an execute.after chain (task-result-guard → context-sandbox → read-enhancer → formatter + delegation audit), and a permission.evaluate hook when the host exposes it. The entry constructs the idle todo enforcer itself when the host's session domain exposes what it needs; where it does not, the gap is reported as idle-todo-enforcer.

sequenceDiagram
    autonumber
    participant Host as OpenCode 2.x Host
    participant Plugin as Pantheon Plugin
    participant Guard as Execute Guards
    participant Agent as Specialist Agent

    Host->>Plugin: tool.execute.before
    Plugin->>Guard: Read-only guard (blocks Zeus from direct source/test reads)
    Guard-->>Host: Allow / Deny
    Host->>Agent: Execute tool or subagent
    Agent-->>Host: Return raw tool output
    Host->>Plugin: tool.execute.after
    Plugin->>Guard: task-result-guard → context-sandbox → read-enhancer
    Guard-->>Host: Sanitized, bounded and enriched result

Installer and config model

Canonical sources in src/ are read by the installer and written into the target config. There is no runtime generation step.

  • The installer writes opencode.json, never opencode.jsonc. A host may merge a sibling .jsonc; see Compatibility.
  • It strips Pantheon references from the legacy singular plugin key and the plural plugins key before writing the current registration, so two Pantheon plugins never coexist. Legacy V1-shaped config keys are normalized to the 2.x shapes before the write.
  • Third-party plugin and MCP entries are preserved and never converted.
  • A versioned per-file ownership inventory records what the installer owns, so reconcile can find stale, unchanged installer files.

The package exposes the plugin as the importable export pantheon-opencode/plugin; the pantheon-opencode/local-decision-router subpath is the decision-router TypeScript source. There is no bridge export and no second contract: the plugin works standalone with graceful degradation.

Memory and context stores

Pantheon has three separate stores, documented once in Memory:

  • pantheon-memory — durable SQLite entries with FTS5/BM25 keyword search.
  • pantheon-persistence — session checkpoints and manual session goals.
  • .pantheon/memory-bank/ — human-reviewed project files, read on demand.

They are not synchronized. MCP tool availability depends on the active agent's grants; namespaces are organizational filters, not access-control boundaries.

MCP entrypoints

Five local Python stdio servers, declared in scripts/install-mcp.mjs:74-78 and registered at :196-301:

Server Entrypoint
pantheon-resources scripts/mcp_resources.py
pantheon-code-mode scripts/code_mode.py
pantheon-memory scripts/memory_mcp.py
pantheon-persistence scripts/mcp_persistence.py
pantheon-vision src/mcp/pantheon_vision.py

The entrypoints were renamed away from the shared *_server.py token; the installer heals stale paths using the mapping in scripts/install/config-migration.mjs:521. Setup and allowlists are in MCP.

Design principles

  • One home per fact. The support matrix, installer mechanics, release process, and benchmark evidence each live in exactly one page.
  • Configuration plus a thin runtime. Agent behavior lives in Markdown (src/agents/*.md, src/instructions/*.instructions.md, src/skills/*/SKILL.md); the installed plugin supplies orchestration, tools, and guards.
  • Fail closed on identity and permissions; fail open on presentation. A malformed permission origin denies the delegation. A malformed compaction payload leaves the message array untouched.