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.tspantheon_cost—src/pantheon/tools.tspantheon_model—src/pantheon/tools.tspantheon_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 whenctx.model.listis a function (src/plugin.ts; definition atsrc/pantheon/native-vision.ts).pantheon_bounded_read— added only when thetool.execute.beforehook registered and the host exposes the permission and session APIs (src/plugin.ts; definition atsrc/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, neveropencode.jsonc. A host may merge a sibling.jsonc; see Compatibility. - It strips Pantheon references from the legacy singular
pluginkey and the pluralpluginskey 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
reconcilecan 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.