pantheon-opencode 1.6.0-beta.6 → 1.6.0-beta.8

package/CHANGELOG.md

@@ -18,6 +18,59 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## ✅ Closed Issues
 
+## [v1.6.0-beta.8] - 2026-10-11
+
+<!-- Add new changes here. Running `node scripts/versioning.mjs apply` will
+     move this section to a versioned entry and reset the template below. -->
+
+## 🐞 Fixed
+
+- **opencode-v2** — repair session lookup and beta sandbox reuse
+- **scripts** — isolate beta background service port
+## [v1.6.0-beta.7] - 2026-10-10
+
+<!-- Add new changes here. Running `node scripts/versioning.mjs apply` will
+     move this section to a versioned entry and reset the template below. -->
+
+## 🆕 What's New
+
+- **Permissões MCP nativas por agente no OpenCode V1 e V2.** O instalador
+  converte a allowlist `mcp_tools` de cada agente em regras nativas: nega por
+  padrão os servidores Pantheon omitidos, libera apenas as ferramentas
+  declaradas e preserva MCPs de terceiros. O V2 mantém os servidores
+  conectados; as regras limitam quais ferramentas cada agente vê.
+- **Guarda V2 de delegação alinhada ao contrato de permissões.** Os hooks de
+  permissão e de sessão aplicam as restrições de sessão somente-leitura e a
+  matriz caller→target sem conceder acesso além do configurado pelo host.
+- **Menos chamadas automáticas de memória e compressão.** A busca de contexto
+  do Zeus reutiliza o resultado de início de tarefa, e o protocolo de
+  compressão deixa de recomendar pipelines automáticos extensos.
+- **Prova de identidade da instalação do sandbox.** O teste global compara a
+  versão e arquivos do pacote instalado com este checkout e rejeita referências
+  npm antigas nas configurações ativas antes de validar o runtime.
+- O `--prepare` agora gera `start-pantheon.sh` para abrir o TUI interativo com o
+  beta instalado e HOME, configuração XDG, projeto e banco de dados isolados do
+  sandbox. O launcher fixa a porta do serviço gerenciado em `49376` e falha sem
+  parar serviços existentes se a porta dedicada já estiver ocupada.
+
+## 🐞 Fixed
+
+- Referências versionadas/alias do pacote Pantheon que sobravam na lista
+  `plugins` agora são reconhecidas pelo instalador e substituídas pelo caminho
+  do plugin local correto, sem afetar plugins de terceiros com nomes parecidos.
+- A suíte CI foi separada do caminho crítico de instalação/empacotamento para
+  reduzir o tempo até o resultado das verificações do pacote.
+- O `run-test.sh` gerado agora define seu timeout do `mcp list` antes do uso
+  sob `set -u`; antes, a variável ausente interrompia o teste antes de chamar
+  o CLI. A saída do comando também fica disponível quando o gate falha.
+
+## ⚠️ Known Issues
+
+- **A delegação real ainda precisa de confirmação nesta beta.** O teste manual
+  anterior de `HERMES-PONG` foi negado com
+  `Pantheon delegation denied: authoritative caller session is unavailable`;
+  a correção de permissões e a instalação isolada precisam ser verificadas no
+  TUI OpenCode V2 antes de considerar a delegação validada.
 ## [v1.6.0-beta.6] - 2026-10-05
 
 <!-- Add new changes here. Running `node scripts/versioning.mjs apply` will

package/README.md

@@ -54,6 +54,9 @@ project-local installation, or non-interactive setup, see the
 [installation guide](docs/INSTALLATION.md).
 The bundled Python MCP servers use the pinned MCP SDK 2.2.0 and standalone
 FastMCP 4.0.10 runtime; see the [MCP guide](docs/MCP.md).
+The installer also turns each agent's `mcp_tools` allowlist into native
+per-agent permissions for OpenCode V1 and V2; see the
+[agent MCP reference](docs/AGENT-MCP.md).
 
 ## A simple example
 
@@ -80,6 +83,13 @@ clear handoff between stages of work.
 - Project memory that helps preserve relevant context between sessions.
 - Optional integrations for common development tasks.
 
+Memory is used selectively: the coordinator searches once only when project
+history could affect a task, then passes relevant results to specialists. Store
+one concise, reusable outcome at task completion when it will matter later;
+routine child summaries and phase updates stay in the current handoff. The
+session-checkpoint tools are separate, optional persistence APIs and are not
+called automatically by compaction hooks. See [Memory usage](docs/MEMORY.md).
+
 ## Status
 
 Candidate version: the manifests in this checkout express the version being
@@ -131,10 +141,15 @@ host is an unsupported mixed/wrong-generation configuration, not a supported mod
 **Not inert.** The V2 path (`src/plugin-v2`, registered as a directory because
 the V2 loader rejects bare file paths) registers real tools with real
 `input`/`output` schemas via `ctx.tool.transform()`, 5 event subscriptions,
-session hooks and a tool `execute.before` hook that enforces read-only sessions.
-It is a smaller surface than V1 by design, not a stub: the 3 goal tools and the
-V1 caller→target delegation matrix are absent, and `getUnsupportedFeatures()`
-reports that as `goal-tools` and `delegation-matrix`.
+session hooks and tool/permission hooks that enforce read-only sessions and the
+caller→target delegation matrix. The matrix applies only to Pantheon-managed
+targets: Zeus may delegate to any registered agent; Athena and Hermes may target
+Apollo only; other Pantheon callers and unknown callers are denied. Child
+sessions cannot delegate to Pantheon agents. Calls between native/custom agents
+remain under host permissions. The V2 path never adds an allow grant or
+overrides an explicit host deny; missing or mismatched identity fails closed
+for the attempted Pantheon delegation. The 3 goal tools remain unsupported and
+are reported as `goal-tools`.
 
 **Not complete either, and the V2 support claim is currently narrowed.** Two
 facts, both recorded in this repository rather than smoothed over:
@@ -175,6 +190,28 @@ there is no Pantheon-specific delegation tool surface to configure. See
 [ADR-0011](.pantheon/memory-bank/adr/0011-delegation-engine-contract.md) for the
 historical engine contract.
 
+This beta.8 candidate combines native per-agent MCP permissions for OpenCode V1
+and V2, V2 delegation-permission alignment, simpler memory/compression
+instructions, and a sandbox check that proves the installed package matches
+this checkout instead of silently accepting stale npm-cached code. The isolated
+sandbox launcher also pins the OpenCode background service to its dedicated
+loopback port, rather than colliding with another OpenCode installation. The Zeus
+prompt reuses one task-start memory-search result for context and routing;
+runtime call counts and latency have not been measured. A beta.7 V2 dispatch
+failed because the permission hook passed a bare string to `ctx.session.get`
+instead of the V2 input object `{ sessionID }`; beta.8 corrects the call and
+adds contract tests for the success and failure cases. The user subsequently
+reported a successful Hermes liveness delegation in the active session, but
+freshly restarting and testing the beta.8 sandbox remains the end-to-end gate.
+The original report also included a separate `GET /api/session/{id}/permission`
+404; the session ID exists in the beta7-candidate database but not the default
+global database. Both OpenCode services were running, so the 404 in the global
+log may come from the other instance; this remains an end-to-end verification
+item.
+
+Delegated tasks get at most one retry after an initial timeout or failure. If
+that retry fails, the configured fallback or escalation chain applies.
+
 ## Cost tool backend
 
 `pantheon_cost` prefers a read-only `node:sqlite` backend against the selected
@@ -285,10 +322,16 @@ surface: the host includes the active agent on the event, a read-only agent
 `createEnforcementGuard` throws to deny `edit`, `write`, `bash`, `task`,
 `hashline_edit` and `pantheon_model`. It does **not** rely on the V1
 `tool.execute.before` hook, which lives in `src/plugin.ts` and is not loaded
-when only `plugin-v2` is configured. The companion `execute.after` hook and the
-`permission.evaluate` hook are registration points with no V2-side behaviour,
-and the V1 caller/target delegation matrix for native `task()` is not enforced
-on V2.
+when only `plugin-v2` is configured. The `permission.evaluate` hook enforces
+the V2 caller/target matrix for Pantheon-managed targets across every entry in
+the host's `resources` array. Native-only resources pass through unchanged to
+OpenCode's permission policy; mixed native/Pantheon requests and multi-target
+requests are denied unless every Pantheon target is explicitly allowed for the
+authoritative caller. Explicit host denies remain final, and missing or
+unknown resource data fails closed. If a denied evaluation has no mutable host
+output argument, the hook throws to fail closed rather than silently omitting
+the denial. V2 `execute.after` runs the completed-result chain:
+`task-result-guard` → `context-sandbox` → `read-enhancer`.
 
 Every V2 tool declares an `output` schema. OpenCode 2.0.x requires the
 declaration and the resolved result to agree in both directions, so an
@@ -473,6 +516,10 @@ Release validation keeps each manifest with its lockfile: the root
 SHA-256 of that same artifact, and binds the tarball and GitHub release to the
 full `TARGET_SHA`; a second pack is not interchangeable.
 
+CI also rebuilds the TUI with `npm run build --prefix src/plugins/tui` and
+checks every packaged `dist` artifact byte-for-byte against its checked-in
+version, including final newlines.
+
 ## Sandbox validation (V2)
 
 `scripts/test-opencode-v2-sandbox.sh` validates the globally installed
@@ -484,6 +531,11 @@ agent delegation. The gate is fail-closed: every required check must return an
 explicit PASS; timeouts, auth/network/provider failures and missing
 prerequisites block the run.
 
+The runner defaults to the current stable `@opencode/cli` package and its
+`opencode2` alias; set `OPENCODE_V2_SPEC` only when a test needs a different
+host build. This keeps Pantheon beta testing separate from the OpenCode CLI
+release channel.
+
 "V2" here refers only to the hook canary observed against an OpenCode v2.0.18
 host, where at least one tested hook callback fired; it does not establish
 compatibility with the stable `@opencode/plugin@2.0.18` SDK or full 2.x
@@ -495,6 +547,7 @@ single leg.
 
 ```bash
 scripts/test-opencode-v2-sandbox.sh --prepare     # tarball + install + init in the sandbox
+~/pantheon-sandbox/start-pantheon.sh              # interactive TUI in that isolated beta sandbox
 scripts/test-opencode-v2-sandbox.sh --run v2      # base validation only
 scripts/test-opencode-v2-sandbox.sh --prompts     # base validation + prompt battery
 scripts/test-opencode-v2-sandbox.sh --rehydrate   # offline context rehydration/session-summary probe
@@ -533,7 +586,7 @@ Env overrides:
 |----------|---------|---------|
 | `PANTHEON_SANDBOX_ROOT` | `~/pantheon-sandbox` | Sandbox root (refused if unsafe for `--reset`) |
 | `OPENCODE_V1_SPEC` | `opencode-ai@1.18.18` | Configures the V1 plugin only; the V2-only sandbox runner does not consume or support it |
-| `OPENCODE_V2_SPEC` | `@opencode-ai/cli@beta` | npm spec providing the `opencode2` binary |
+| `OPENCODE_V2_SPEC` | `@opencode/cli@latest` | npm spec providing the `opencode2` binary |
 | `PANTHEON_SANDBOX_MODEL` | `opencode-go/mimo-v2.5` | Model used by init and prompts |
 | `PANTHEON_PROMPT_TIMEOUT` | `300` | Per-prompt timeout in seconds |
 
@@ -591,6 +644,22 @@ Ideas, bug reports, documentation improvements, and code contributions are
 welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue
 or pull request.
 
+### Reproducible benchmark evidence
+
+The beta2 benchmark records reported token usage separately from its
+character-based fallback estimate; source bytes and logical line counts remain
+provenance data and are never converted into tokens. Cross-report comparisons
+require matching model/config provenance and reported OpenCode usage. Offline
+fixture responses are mocked: their reported values are labeled separately,
+excluded from `actual` usage, and blocked from comparative metrics and GEPA.
+Fixture quality outcomes test the offline contract; they are not evaluation
+evidence.
+Reproduce the
+checked-in AGENTS.md history manifest with
+`python3 -m benchmarks.beta2.provenance --output benchmarks/beta2/fixtures/agent-baseline-provenance.json`.
+For OpenCode benchmark runs, provide `--model` and `--config-sha256` so reports
+can be compared safely.
+
 ### Project-level `opencode.json`
 
 The published package carries no `opencode.json` template. `init` still writes

package/README.pt-BR.md

@@ -141,10 +141,16 @@ dessa superfície: o host inclui o agente ativo no evento, um agente somente-lei
 compartilhado lança para negar `edit`, `write`, `bash`, `task`,
 `hashline_edit` e `pantheon_model`. Ele **não** depende do hook
 `tool.execute.before` do V1, que vive em `src/plugin.ts` e não é carregado
-quando apenas `plugin-v2` está configurado. Os hooks companheiros
-`execute.after` e `permission.evaluate` são pontos de registro sem comportamento
-do lado V2, e a matriz de delegação caller/target da V1 para o `task()` nativo
-não é imposta no V2.
+quando apenas `plugin-v2` está configurado. O hook `permission.evaluate`
+aplica no V2 a matriz caller/target para destinos gerenciados pelo Pantheon,
+considerando todos os itens do array `resources` do host. Recursos
+exclusivamente nativos são repassados sem alteração à política de permissões do
+OpenCode; pedidos mistos (nativos/Pantheon) e com vários destinos são negados,
+a menos que todos os destinos Pantheon sejam explicitamente permitidos para o
+chamador autoritativo. Uma negação explícita do host é final, e dados de
+recursos ausentes ou desconhecidos são negados por padrão. O `execute.after` do
+V2 executa a cadeia de resultados concluídos `task-result-guard` →
+`context-sandbox` → `read-enhancer`; eventos de erro permanecem inalterados.
 
 Toda ferramenta V2 declara um schema `output`. O OpenCode 2.0.x exige que a
 declaração e o resultado resolvido concordem nos dois sentidos, então uma

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pantheon-opencode",
-  "version": "1.6.0-beta.6",
+  "version": "1.6.0-beta.8",
   "description": "Multi-agent orchestration for OpenCode — 14 specialized agents, TDD, Themis review gates.",
   "type": "module",
   "workspaces": [
@@ -112,8 +112,12 @@
     "typescript": "7.0.2"
   },
   "overrides": {
+    "@babel/core": "7.29.7",
+    "seroval": "1.6.8",
+    "solid-js": "1.9.12",
     "rolldown": "1.2.7"
   },
+  "//overrides": "TUI production advisory fixes: Babel >=7.29.6 and Seroval >=1.6.3; Solid stays at 1.9.12 to satisfy OpenTUI's exact peer. Remove only after upstream ranges include fixed versions; Seroval compatibility is covered by the Solid serializer regression test.",
   "repository": {
     "type": "git",
     "url": "https://github.com/ils15/pantheon-opencode.git"

package/plugin.json

@@ -1,9 +1,9 @@
 {
   "name": "pantheon",
   "publisher": "ils15",
-  "version": "1.6.0-beta.6",
+  "version": "1.6.0-beta.8",
   "displayName": "Pantheon",
-  "description": "Conductor-Delegate orchestration platform with 14 specialized agents, 21 skills, and OpenCode support.",
+  "description": "Conductor-Delegate orchestration platform with 14 specialized agents, 20 skills, and OpenCode support.",
   "agents": "./src/agents",
   "skills": "./src/skills",
   "instructions": "./src/instructions",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.backends._legacy:_Backend"
 
 [project]
 name = "pantheon"
-version = "1.6.0-beta.6"
+version = "1.6.0-beta.8"
 description = "Multi-agent orchestration framework"
 requires-python = ">=3.11"
 dependencies = []
@@ -16,6 +16,7 @@ dependencies = []
 testpaths = [
     "tests",
     "benchmarks/beta2/test_beta2.py",
+    "benchmarks/beta2/test_t1.py",
 ]
 asyncio_mode = "auto"
 addopts = "-v --tb=short"
@@ -48,6 +49,7 @@ select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "PL", "RUF", "C901"]
 "tests/test_code_mode_frontmatter.py" = ["PLR2004"]
 "tests/test_eval.py" = ["PLR2004"]
 "tests/test_mcp_persistence_server.py" = ["PLR2004"]
+"benchmarks/beta2/test_t1.py" = ["PLR2004"]
 
 [tool.mypy]
 python_version = "3.11"

package/scripts/build-agents-md.mjs

@@ -8,11 +8,11 @@
  * across both versions without duplication, this script consolidates:
  *
  *   (a) a static header (project description + agent table + setup notes)
- *   (b) every src/instructions/*.instructions.md body, embedded under a
- *       `## <name>` section marker (name taken from frontmatter)
+ *   (b) shared instruction bodies embedded under a `## <name>` section marker;
+ *       agent-scoped bodies are rendered into only their matching agent prompt
  *
- * into one generated AGENTS.md. src/instructions/*.instructions.md remains
- * the source of truth — AGENTS.md is a committed build artifact, never
+ * into AGENTS.md plus selective agent prompt content. The instruction files
+ * remain the source of truth; AGENTS.md is a committed build artifact, never
  * hand-edited.
  *
  * Usage:
@@ -22,8 +22,8 @@
  * No runtime dependencies (Node >= 18, stdlib only). Idempotent: running it
  * twice produces byte-identical output.
  */
-import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -44,19 +44,19 @@ This project uses the Pantheon multi-agent framework with 14 specialized agents.
 
 | Agent | Role |
 |-------|------|
-| @aphrodite | Frontend specialist — React 19, TypeScript strict, WCAG accessibility, responsive design, TDD, modern API patterns, deprecated npm detection. Calls apollo for discovery, sends to themis for review. |
+| @aphrodite | Frontend specialist — React 19, TypeScript strict, WCAG accessibility, responsive design, TDD, modern API patterns, deprecated npm detection. Uses discovery/review proportionally to scope and risk. |
 | @apollo | Read-only investigation scout — 3–10 parallel searches across codebase, external docs, and GitHub. Called by: athena, zeus, hermes, aphrodite, demeter. No edits, no commands. |
 | @athena | Strategic planner & architect — research-first, plan-only, never implements. Plans include quality gates (ruff/Biome, dep detection, LTS policy). Calls apollo for discovery. |
-| @demeter | Database specialist — SQLAlchemy 2.0, Alembic, query optimization, N+1 prevention, TDD migrations, modern DB libs. Calls apollo for discovery, sends to themis. |
+| @demeter | Database specialist — SQLAlchemy 2.0, Alembic, query optimization, N+1 prevention, TDD migrations, modern DB libs. Preserves review gates for schema/data changes. |
 | @gaia | Remote sensing domain specialist — satellite image processing, spectral analysis, SAR, change detection, time series, ML/DL classification. Read-only analysis of geospatial data. |
 | @hephaestus | AI tooling & pipelines specialist — LangChain/LangGraph chains, RAG architecture, vector stores, embedding strategies. Forges AI infrastructure. Calls apollo, sends to themis. |
-| @hermes | Backend specialist — FastAPI, Python, async, TDD (RED→GREEN→REFACTOR), modern Python stdlib, obsolete lib detection. Calls apollo for discovery, sends to themis. |
+| @hermes | Backend specialist — FastAPI, Python, async, TDD (RED→GREEN→REFACTOR), modern Python stdlib, obsolete lib detection. Uses discovery/review proportionally to scope and risk. |
 | @iris | GitHub operations specialist — branches, pull requests, issues, releases, tags. Called by zeus after review. Never pushes or merges without explicit human approval. Integrates with VS Code GitHub Pull Requests extension. |
 | @mnemosyne | Memory bank quality owner — initializes .pantheon/memory-bank/, writes ADRs and task records on explicit request. Called by zeus. Never invoked automatically after phases. |
 | @nyx | Observability & monitoring specialist — OpenTelemetry tracing, token/cost tracking, agent performance analytics, LangSmith integration. Calls apollo for discovery, sends to themis. |
 | @prometheus | Infrastructure + model provider specialist — Docker, CI/CD, multi-model routing, cost optimization, provider abstraction |
 | @talos | Hotfix express lane — direct fixes for small bugs, CSS, typos, minor logic. No TDD ceremony, no orchestration overhead. Standalone, no subagents. Escalates complex issues to zeus. |
-| @themis | Quality & security gate — ruff/Biome linting, dead/legacy code detection, OWASP Top 10, coverage >80%, correctness, deprecation audit. Called by implementers; escalates blockers to zeus. |
+| @themis | Quality & security gate — ruff/Biome linting, dead/legacy code detection, OWASP Top 10, applicable coverage requirements, correctness, deprecation audit. Reviews material/sensitive changes. |
 | @zeus | Central orchestrator — never implements. Delegates to: athena, apollo, hermes, aphrodite, demeter, prometheus, themis, iris, mnemosyne, talos, hephaestus, nyx |
 
 ## OpenCode Setup
@@ -78,8 +78,8 @@ Para validar a instalação global do pacote pantheon-opencode COMO UM USUÁRIO
 
 ## Conventions
 
-- TDD: Write failing test first, then implement
-- Coverage minimum: 80%
+- TDD: RED→GREEN→REFACTOR for testable behavior; use focused checks for micro-edits
+- Honor repository coverage thresholds when relevant; preserve stronger auth/security/data-integrity gates
 - 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.
@@ -92,20 +92,41 @@ Para validar a instalação global do pacote pantheon-opencode COMO UM USUÁRIO
 /**
  * Parse YAML-ish frontmatter from an instruction file.
  *
- * Only the `name` field is extracted (single-line scalar). The frontmatter
- * block itself is stripped from the embedded body.
+ * Preserve the file-scope `applyTo` glob separately from the explicit
+ * `agents` selectors. In particular, a Python workspace glob is never
+ * interpreted as an agent name. The frontmatter block is stripped from
+ * the embedded body.
  *
  * @param {string} content - Raw file content
- * @returns {{ name: string, body: string } | null}
+ * @returns {{ name: string, body: string, applyTo: string | null,
+ *   agents: string[], fallback: string | null, appliesToAgent: (name: string) => boolean } | null}
  */
-function parseInstruction(content) {
+export function parseInstruction(content) {
   const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/)
   if (!match) return null
   const fm = match[1]
   const nameMatch = fm.match(/^name:\s*["']?([^"'\r\n]+)["']?\s*$/m)
   if (!nameMatch) return null
+  const applyToMatch = fm.match(/^applyTo:\s*["']?([^"'\r\n]+)["']?\s*$/m)
+  const agentsMatch = fm.match(/^agents:\s*\[([^\]\r\n]*)\]\s*$/m)
+  const agents = agentsMatch
+    ? agentsMatch[1]
+        .split(',')
+        .map((agent) => agent.trim().replace(/^(["'])(.*)\1$/, '$2'))
+        .filter(Boolean)
+    : fm.match(/^agents:/m)
+      ? [] // Malformed explicit selector: fail closed; never make it global.
+      : applyToMatch
+        ? [] // File-scoped instructions need an explicit agent association.
+        : ['*'] // Legacy instructions without selectors remain shared.
+  const fallbackMatch = fm.match(/^fallback:\s*["']?([^"'\r\n]+)["']?\s*$/m)
+  const appliesToAgent = (agent) => agents.includes('*') || agents.includes(agent)
   return {
     name: nameMatch[1].trim(),
+    applyTo: applyToMatch?.[1].trim() ?? null,
+    agents,
+    fallback: fallbackMatch?.[1].trim() ?? null,
+    appliesToAgent,
     body: `${content.slice(match[0].length).trimEnd()}\n`,
   }
 }
@@ -114,7 +135,8 @@ function parseInstruction(content) {
  * Read all src/instructions/*.instructions.md files, sorted by filename for
  * deterministic output.
  *
- * @returns {Array<{ file: string, name: string, body: string }>}
+ * @returns {Array<{ file: string, name: string, body: string, applyTo: string | null,
+ *   agents: string[], fallback: string | null, appliesToAgent: (name: string) => boolean }>}
  */
 export function readInstructions() {
   if (!existsSync(INSTRUCTIONS_DIR)) return []
@@ -137,10 +159,13 @@ export function readInstructions() {
 /**
  * Generate the full AGENTS.md content.
  *
- * @param {Array<{ file: string, name: string, body: string }>} instructions
+ * @param {Array<{ file: string, name: string, body: string, agents?: string[] }>} instructions
  * @returns {string}
  */
 export function generateAgentsMd(instructions) {
+  const sharedInstructions = instructions.filter(
+    (instr) => !instr.agents || instr.agents.includes('*'),
+  )
   const sections = [
     '<!-- Generated by scripts/build-agents-md.mjs — do not edit directly. -->',
     '<!-- Source of truth: src/instructions/*.instructions.md (AGENTS.md is a committed build artifact). -->',
@@ -153,10 +178,11 @@ export function generateAgentsMd(instructions) {
     '',
     'The following sections are consolidated from `src/instructions/*.instructions.md`',
     'so both OpenCode V1 (auto-loads AGENTS.md) and V2 (loads AGENTS.md, ignores the',
-    '`instructions` config key) receive identical instruction content.',
+    '`instructions` config key) receive identical shared rules. Agent-scoped rules',
+    'are rendered into only the matching installed agent prompts.',
     '',
   ]
-  for (const instr of instructions) {
+  for (const instr of sharedInstructions) {
     sections.push(
       `<!-- Source: src/instructions/${instr.file} -->`,
       `## ${instr.name}`,
@@ -168,6 +194,110 @@ export function generateAgentsMd(instructions) {
   return `${sections.join('\n').trimEnd()}\n`
 }
 
+const GENERATED_AGENT_BLOCK =
+  /\n?<!-- Pantheon selective instructions: generated -->[\s\S]*?<!-- \/Pantheon selective instructions -->\n?/g
+
+/**
+ * Render the agent-specific instruction set into the supported agent prompt.
+ * The shared rules remain in AGENTS.md; file globs are retained as scope
+ * guidance and are never used as agent selectors.
+ *
+ * @param {string} agentName - Canonical agent name from the prompt filename
+ * @param {string} prompt - Canonical source agent prompt
+ * @param {Array<{ file: string, name: string, body: string, applyTo?: string | null,
+ *   agents?: string[], fallback?: string | null }>} instructions
+ * @returns {string}
+ */
+export function generateAgentPrompt(agentName, prompt, instructions = readInstructions()) {
+  const basePrompt = prompt.replace(GENERATED_AGENT_BLOCK, '').trimEnd()
+  const selected = instructions.filter(
+    (instr) => instr.agents && !instr.agents.includes('*') && instr.agents.includes(agentName),
+  )
+  if (selected.length === 0) {
+    return [
+      basePrompt,
+      '',
+      '<!-- Pantheon selective instructions: generated -->',
+      'No agent-specific instructions are assigned; follow the shared rules in AGENTS.md.',
+      '<!-- /Pantheon selective instructions -->',
+      '',
+    ].join('\n')
+  }
+
+  const sections = selected.map((instr) => {
+    const scope = instr.applyTo
+      ? `\n\n> Apply only when a target workspace file matches \`${instr.applyTo}\`.`
+      : ''
+    const fallback =
+      instr.fallback === 'shared'
+        ? '\n\n> For work outside this scope, use the shared rules in AGENTS.md.'
+        : ''
+    return [
+      `<!-- Source: src/instructions/${instr.file} -->`,
+      `## ${instr.name}${scope}`,
+      '',
+      `${instr.body.trimEnd()}${fallback}`,
+    ].join('\n')
+  })
+  return [
+    basePrompt,
+    '',
+    '<!-- Pantheon selective instructions: generated -->',
+    sections.join('\n\n'),
+    '<!-- /Pantheon selective instructions -->',
+    '',
+  ].join('\n')
+}
+
+/**
+ * Copy agent prompts with scoped instructions embedded in each actual prompt.
+ * Used by both init and postinstall sync so the installed runtime receives the
+ * same selection without a per-turn injection hook.
+ *
+ * @param {string} sourceDir - Canonical src/agents directory
+ * @param {string} targetDir - OpenCode agents directory
+ * @param {boolean} dryRun - Do not write when true
+ * @param {boolean} existingOnly - Refresh installed prompts without adding missing agents
+ * @returns {{ created: number, skipped: number }}
+ */
+export function copyAgentPrompts(sourceDir, targetDir, dryRun = false, existingOnly = false) {
+  const instructions = readInstructions()
+  if (!dryRun && !existingOnly) mkdirSync(targetDir, { recursive: true })
+  let created = 0
+  let skipped = 0
+  for (const file of readdirSync(sourceDir)
+    .filter((entry) => entry.endsWith('.md'))
+    .sort()) {
+    if (file.toLowerCase() === 'readme.md') continue
+    const sourcePath = join(sourceDir, file)
+    if (!statSync(sourcePath).isFile()) continue
+    const agentName = file.replace(/\.md$/, '')
+    const output = generateAgentPrompt(agentName, readFileSync(sourcePath, 'utf8'), instructions)
+    const targetPath = join(targetDir, file)
+    if (existingOnly && !existsSync(targetPath)) continue
+    const existing = existsSync(targetPath) ? readFileSync(targetPath, 'utf8') : null
+    if (existing === output) {
+      skipped++
+    } else {
+      if (!dryRun) writeFileSync(targetPath, output, 'utf8')
+      created++
+    }
+  }
+  return { created, skipped }
+}
+
+/**
+ * Count LF-delimited logical lines without assuming a trailing newline.
+ *
+ * @param {string} content - File content
+ * @returns {number}
+ */
+export function logicalLineCount(content) {
+  if (content.length === 0) return 0
+  const separators = content.match(/\n/g)?.length ?? 0
+  return separators + (content.endsWith('\n') ? 0 : 1)
+}
+
 // ---------------------------------------------------------------------------
 // CLI entry point
 // ---------------------------------------------------------------------------
@@ -175,6 +305,9 @@ export function generateAgentsMd(instructions) {
 function main() {
   const checkOnly = process.argv.includes('--check')
   const instructions = readInstructions()
+  const sharedCount = instructions.filter(
+    (instr) => !instr.agents || instr.agents.includes('*'),
+  ).length
   const content = generateAgentsMd(instructions)
 
   if (checkOnly) {
@@ -183,15 +316,15 @@ function main() {
       console.error(`❌ AGENTS.md is stale — run: node scripts/build-agents-md.mjs`)
       process.exit(1)
     }
-    console.log(`✅ AGENTS.md is up to date (${instructions.length} instruction sections)`)
+    console.log(`✅ AGENTS.md is up to date (${sharedCount} shared instruction sections)`)
     return
   }
 
   writeFileSync(AGENTS_MD_PATH, content, 'utf8')
-  const lines = content.split('\n').length
-  console.log(
-    `✅ Generated AGENTS.md (${instructions.length} instruction sections, ${lines} lines)`,
-  )
+  const lines = logicalLineCount(content)
+  console.log(`✅ Generated AGENTS.md (${sharedCount} shared instruction sections, ${lines} lines)`)
 }
 
-main()
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main()
+}

package/scripts/install/agents-md.mjs

@@ -2,7 +2,7 @@
 /**
  * agents-md.mjs — Dynamic AGENTS.md generator from canonical agent frontmatter
  *
- * Reads all agents/*.agent.md files, extracts name + description from frontmatter,
+ * Reads all canonical src/agents/*.md files, extracts name + description from frontmatter,
  * and generates AGENTS.md content dynamically. Eliminates hardcoded agent tables
  * in platform installers (claude.mjs, cursor.mjs, windsurf.mjs, cline.mjs, etc.).
  *
@@ -64,7 +64,7 @@ function parseAgentFrontmatter(content) {
 // ---------------------------------------------------------------------------
 
 /**
- * Read all canonical agents/*.agent.md files, parse frontmatter,
+ * Read all canonical src/agents/*.md files, parse frontmatter,
  * and return an array of agent metadata objects sorted alphabetically by name.
  *
  * Skips files that don't match the `*.agent.md` pattern, files without