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

package/src/instructions/zeus-timeout-retry.instructions.md

@@ -1,7 +1,8 @@
 ---
 description: "Timeout enforcement, retry policies, subtask dispatch, and timeout tracking for Zeus"
 name: "Zeus Timeout & Retry"
-applyTo: "agents/zeus.agent.md"
+agents: [zeus]
+fallback: shared
 ---
 
 # ⏱️ TIMEOUT & RETRY ENFORCEMENT
@@ -10,123 +11,75 @@ When a delegated agent does not respond in time, enforce the timeout policy from
 
 ## Timeout Behavior by Agent Role
 
-| Agent Role | Timeout | Retry Policy | Fallback Chain | Partial Results OK? | Reasoning Effort |
-|------------|---------|-------------|----------|---------------------|------------------|
-| Explorer (@apollo) | 60s | 2 retries, exp backoff | @athena (plan) → @hermes (impl) | ✅ Yes | low |
-| Implementer (@hermes, @aphrodite, @demeter) | 180s | 3 retries, exp backoff | @talos (hotfix) → @athena (replan) | ❌ No | medium |
-| Reviewer (@themis) | 120s | 3 retries, exp backoff | @zeus (escalate) → user | ❌ No | high |
-| Infrastructure (@prometheus) | 300s | 3 retries, exp backoff | @hermes (config) → @zeus (escalate) | ❌ No | medium |
-| Hotfix (@talos) | 30s | 2 retries, no backoff | @hermes (full fix) | ✅ Yes | low |
-| Remote Sensing (@gaia) | 120s | 2 retries, exp backoff | @hermes (generic) | ✅ Yes | high |
+| Agent Role | Timeout | Retry Policy | Partial Results OK? | Reasoning Effort |
+|------------|---------|--------------|---------------------|------------------|
+| Explorer (@apollo) | 60s | 1 retry | ✅ Yes | low |
+| Implementer (@hermes, @aphrodite, @demeter) | 180s | 1 retry | ❌ No | medium |
+| Reviewer (@themis) | 120s | 1 retry | ❌ No | high |
+| Infrastructure (@prometheus) | 300s | 1 retry | ❌ No | medium |
+| Hotfix (@talos) | 30s | 1 retry | ✅ Yes | low |
+| Remote Sensing (@gaia) | 120s | 1 retry | ✅ Yes | high |
 
 ## Retry Flow
 
 ```
-Task dispatch → timeout elapsed → log timeout
-  ├─ retry_count > 0 → retry with exponential backoff → decrement retry_count
-  │    └─ still failing? → retry again (up to retry_count limit)
-  │
-  ├─ retries exhausted → FALLBACK CHAIN:
-  │    ├─ fallback[0] exists? → dispatch to fallback agent
-  │    │    └─ keep original task spec + context; add error context
-  │    ├─ fallback[1] exists? → dispatch to second fallback
-  │    └─ all fallbacks failed? → ESCALATE
-  │
-  ├─ no fallbacks defined → return TIMEOUT error to user
-  │
-  └─ ESCALATE: "Agent X failed after N retries. Fallbacks Y, Z also failed.
-                 Options: (a) try different agent, (b) simplify scope, (c) manual"
+Initial attempt → timeout/failure → log it → make at most one retry
+  └─ retry fails → try fallback agents left-to-right with original task/context
+       └─ all fallbacks fail (or none exist) → report the chain and escalate
 ```
+`background_delegation.retry_count: 1` means one retry after the initial attempt, not one total attempt. Never restart an exhausted chain automatically.
 
-
+Apply the retry only to a transient dispatch failure (timeout, crash, or empty response). A failed test, validation, or migration is a result to diagnose, not a reason to repeat the same command or agent blindly. Track agents already tried: each agent may be retried at most once and each listed fallback may be tried at most once. For auth/security/data/schema work, a fallback must preserve specialist competence, Themis review, and human approval; otherwise stop and escalate. Never let full-auto bypass these gates.
+An agent refusal or scope-boundary response is not a transient failure: do not retry it with a rephrased prompt. Correct the route once if the right specialist is clear; otherwise stop and ask.
 
 ## Fallback Chain Definitions
 
-Each fallback chain is evaluated left-to-right: if the first fallback fails, try the second, etc.
-
-| Agent | Fallback[0] | Fallback[1] | Escalate To |
-|-------|------------|------------|-------------|
-| @apollo | @athena (plan scoped task) | @hermes (implement search) | @zeus |
-| @hermes | @talos (minimal fix) | @athena (replan + simplify) | @zeus |
-| @aphrodite | @talos (CSS/UX fix) | @hermes (generic fallback) | @zeus |
-| @demeter | @hermes (generic backend) | @athena (replan schema) | @zeus |
-| @themis | @zeus (direct escalation) | — | user |
-| @prometheus | @hermes (config/deploy) | @zeus | user |
-| @talos | @hermes (full implementation) | — | @zeus |
-| @hephaestus | @nyx (observability debug) | @hermes (generic) | @zeus |
-| @nyx | @hermes (generic) | — | @zeus |
-| @iris | @zeus (manual override) | — | user |
-| @mnemosyne | @zeus (manual) | — | user |
+`routing.yml` → `fallback_chains` is the canonical agent-by-agent mapping. Evaluate
+the configured chain left-to-right; if an agent has no configured chain, stop
+and escalate rather than guessing a fallback. Each listed fallback may be tried
+at most once, and an exhausted chain is never restarted automatically.
 
-### Escalation Protocol
-When ALL fallbacks fail:
-1. Log the full failure chain: which agents were tried, what error each returned
-2. Report to user: "Task [X] failed. Tried: [agent list]. Error: [summary]."
-3. Offer options: (a) try different approach, (b) simplify scope, (c) manual fix
-4. NEVER retry the same chain automatically — break the cycle
+### Refusal Is a Routing Error
 
-### Session Reuse Check
-Before dispatching a task, check if a reusable session exists:
+For a domain/scope refusal, do not retry with a rephrased prompt. Correct the
+route once only when the right specialist is clear; otherwise stop and ask.
+Record one `DelegationCacheDecision` telemetry item for the corrected route,
+including `reroute_from`, `reroute_to`, and `delegation_id` when available.
 
-```
-@hermes — continuing from previous session.
-Files already explored: backend/routers/auth.py, backend/services/auth_service.py.
-New task: add refresh token rotation.
-```
+### Escalation Protocol
+When all fallbacks fail, report the tried agents and errors, offer a different approach/simpler scope/manual fix, and stop. Never retry the same chain automatically.
 
-Use `session_max` from routing.yml to determine how many sessions to keep per agent.
+### Session Reuse Check
+Check for a reusable session before dispatch and obey `session_max` in `routing.yml`.
 
 ---
 
 # 📦 SUBTASK DISPATCH (Lightweight Delegation)
 
-Subtask is a bounded, low-risk delegation mode that **skips** the standard artifact lifecycle. Use it for focused work that doesn't need Themis review.
+Subtask is a bounded, low-risk delegation mode that **skips** the standard artifact lifecycle. Choose it by risk and need for review, not by a fixed file/line count.
 
 ## When to Use Subtask vs Full Task
 
-> **REGRA DE OURO:** Quando em dúvida, use full task. Subtask é para o que você tem 100% de certeza que é seguro pular revisão.
+Use the lightest path that safely meets the request. A multi-file but bounded low-risk change does not automatically need a plan/artifact phase.
 
 ### Subtask Decision Tree (run BEFORE every delegation)
 
 ```
-□ Scope: ≤2 files AND ≤10 lines changed?         [YES→continue | NO→full task]
-□ Risk: No schema change, no security impact?      [YES→continue | NO→full task]
-□ Auth: No authentication/authorization logic?      [YES→continue | NO→full task]
-□ Data: No data loss risk, no migration?            [YES→continue | NO→full task]
-□ Review: Output does NOT feed into Themis review?  [YES→continue | NO→full task]
-
-ALL YES → subtask (skip artifact + Themis)
-ANY NO  → full task (IMPL artifact + Themis review mandatory)
-```
-
-### Comparison Table
+□ Is the scope clear, bounded, and reversible?                 [YES→continue | NO→clarify/plan]
+□ Does it avoid auth/security, data/schema, and destructive risk? [YES→continue | NO→full review/gates]
+□ Is there no required Themis/audit handoff for this change?     [YES→continue | NO→preserve that review]
 
-| Aspect | Subtask | Full Task |
-|--------|---------|-----------|
-| Scope | Single file, <10 lines, read-only | Feature, multi-file, schema change |
-| Risk | Low (no security/data implications) | Any risk level |
-| Artifact | ❌ No IMPL artifact | ✅ IMPL artifact required |
-| Themis review | ❌ None | ✅ Mandatory |
-| Use case | Apollo discovery, Talos hotfix, bounded fix | Feature implementation, migration, API change |
-
-### Concrete Examples
-
-| Task | Scope | Risk | Subtask? | Why |
-|------|-------|------|----------|-----|
-| Fix typo in CSS class | 1 file, 1 line | None | ✅ | Bounded, no security impact |
-| Add error handling to existing endpoint | 1 file, 5 lines | Low | ✅ | No schema change |
-| Implement login endpoint | 2+ files, 50+ lines | High (auth) | ❌ | Security-critical, needs Themis |
-| Database migration | 1 file, 15 lines | High (data) | ❌ | Data loss risk, needs rollback |
-| Apollo codebase search | 0 files | None | ✅ | Read-only investigation |
-| Update README | 1 file, 3 lines | None | ✅ | Documentation only |
+ALL YES → direct/lightweight execution; no routine plan or artifact
+ANY NO  → add only the planning, artifact, specialist review, and approval gates the risk requires
+```
 
 ### Safety Rules
-1. **Bounded scope** — single file or read-only investigation
+1. **Bounded scope** — can be a small multi-file change or a read-only investigation
 2. **Low risk** — no security implications, no data loss, no breaking changes
-3. **No Themis dependency** — output doesn't feed into a phase that requires review
+3. **No required Themis dependency** — sensitive/material output retains its review gate
 
 ## Subtask Return Format
-Return the standard `## subtask_summary` defined in `## Agent Return Format` (files_changed, summary, tests, coverage, tokens, status, blockers).
+Return the required `## subtask_summary` fields defined in `## Agent Return Format`; include `memory_context` when memory was used.
 
 ## Timeout Parcial (Partial Results)
 

package/src/pantheon/v2-delegation-enforce.ts

@@ -0,0 +1,87 @@
+/** Caller/target policy for V2's permission.evaluate hook. */
+
+export const PANTHEON_AGENTS: ReadonlySet<string> = new Set([
+  'zeus',
+  'athena',
+  'apollo',
+  'hermes',
+  'aphrodite',
+  'demeter',
+  'themis',
+  'prometheus',
+  'hephaestus',
+  'nyx',
+  'gaia',
+  'iris',
+  'mnemosyne',
+  'talos',
+])
+
+export interface V2PermissionEvent {
+  sessionID?: unknown
+  resources?: unknown
+  /** Optional event identity is checked but never used as authority. */
+  agent?: unknown
+  /** Mutable decision fields exposed by OpenCode V2's evaluate hook. */
+  effect?: unknown
+  message?: unknown
+}
+
+export interface AuthoritativeSession {
+  id?: unknown
+  agent?: unknown
+  parentID?: unknown
+}
+
+export type V2DelegationDecision = 'allow' | 'deny' | 'passthrough' | 'preserve-deny'
+
+function agentName(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const valueNormalized = value.trim().toLowerCase()
+  return valueNormalized.length === 0 ? undefined : valueNormalized
+}
+
+/** Extract the target from the host's resource string or `{ target }` entry. */
+export function v2ResourceTarget(resource: unknown): string | undefined {
+  if (typeof resource === 'string') return agentName(resource)
+  if (resource === null || typeof resource !== 'object' || Array.isArray(resource)) return undefined
+  return agentName((resource as { target?: unknown }).target)
+}
+
+/**
+ * Decide whether a permission evaluation is a Pantheon-managed delegation.
+ * Native/custom-to-native/custom calls are left entirely to host permissions.
+ */
+export function evaluateV2Delegation(
+  event: V2PermissionEvent,
+  session: AuthoritativeSession | undefined,
+  existingStatus?: unknown,
+): V2DelegationDecision {
+  if (existingStatus === 'deny') return 'preserve-deny'
+
+  if (!Array.isArray(event.resources) || event.resources.length === 0) return 'deny'
+  const rawTargets = event.resources.map(v2ResourceTarget)
+  if (rawTargets.some((target) => target === undefined)) return 'deny'
+  const targets = rawTargets.filter((target): target is string => target !== undefined)
+  const pantheonTargets = targets.filter((target) => PANTHEON_AGENTS.has(target))
+  if (pantheonTargets.length === 0) return 'passthrough'
+  const sessionID = typeof event.sessionID === 'string' ? event.sessionID : undefined
+  const caller = agentName(session?.agent)
+  if (
+    sessionID === undefined ||
+    session === undefined ||
+    session.id !== sessionID ||
+    caller === undefined
+  ) {
+    return 'deny'
+  }
+  const eventCaller = agentName(event.agent)
+  if (eventCaller !== undefined && eventCaller !== caller) return 'deny'
+  if (session.parentID !== undefined && session.parentID !== null && session.parentID !== '') {
+    return 'deny'
+  }
+
+  const callerMayTarget = (target: string): boolean =>
+    caller === 'zeus' || ((caller === 'athena' || caller === 'hermes') && target === 'apollo')
+  return pantheonTargets.every(callerMayTarget) ? 'allow' : 'deny'
+}

package/src/pantheon/v2-execute-after.ts

@@ -0,0 +1,186 @@
+/**
+ * V2 `execute.after` parity adapter — reproduces the V1 post-tool chain on the
+ * V2 tool-event surface.
+ *
+ * V1 (`src/plugin.ts`) wires a single `tool.execute.after` handler that runs,
+ * in order:
+ *   1. task-result-guard — an empty native `task()` result becomes an explicit
+ *      error so the parent LLM cannot read silence as success;
+ *   2. context-sandbox   — oversized read/grep/glob/webfetch output is truncated
+ *      with a marker + metadata;
+ *   3. read-enhancer     — a `read` result gains per-line hashline tags
+ *      (`N#TAG|content`) so `hashline_edit` refs resolve.
+ *
+ * On a V2-only install (`opencode.json` `plugins` declares only `plugin-v2`),
+ * `src/plugin.ts` is NOT loaded, so that chain does not exist. `plugin-v2.ts`
+ * registered an `execute.after` hook but with an empty body, so the chain was
+ * dead on V2. This module rebuilds it against the REAL V2 event shape.
+ *
+ * The V2 event (opencode 2.0.x `ToolHooks["execute.after"]`) is ONE object:
+ *
+ *   { tool, sessionID, agent, messageID, id, input } & (
+ *       { status: 'completed'; result: Tool.Result } |
+ *       { status: 'error'; error: Tool.Error } )
+ *
+ * where `Tool.Result = { output?, content?, metadata? }`. This adapter only
+ * acts on `status === 'completed'`; an ERROR event is left untouched — V1's own
+ * behaviour on a tool error was never verified, so this module does not claim
+ * after-on-error semantics.
+ *
+ * Fail-safe: every path is wrapped so an unexpected shape can never break the
+ * tool result the host is about to surface.
+ *
+ * @module pantheon/v2-execute-after
+ */
+
+import {
+  type ContextSandboxConfig,
+  createContextSandbox,
+  resolveSandboxConfig,
+  DEFAULT_CONFIG as SANDBOX_DEFAULT_CONFIG,
+} from './context-sandbox.ts'
+import { createReadEnhancer } from './hashline/read-enhancer.ts'
+import { createTaskResultGuard } from './task-result-guard.ts'
+
+/** The `Tool.Result` fields this adapter reads and writes back. */
+export interface V2ToolResult {
+  output?: unknown
+  content?: unknown
+  metadata?: unknown
+}
+
+/** The completed, non-error `execute.after` event as the 2.0.x host dispatches it. */
+export interface V2ExecuteAfterEvent {
+  tool?: unknown
+  sessionID?: unknown
+  id?: unknown
+  input?: unknown
+  status?: unknown
+  result?: unknown
+}
+
+/** Options for {@link createV2ExecuteAfter}. */
+export interface V2ExecuteAfterOptions {
+  /**
+   * Sandbox config, normally derived from `ctx.options.context_sandbox` via
+   * {@link resolveSandboxConfig}. Defaults to the shared defaults.
+   */
+  sandbox?: ContextSandboxConfig
+}
+
+/** Which `Tool.Result` field carries the (mutable) text this adapter enhances. */
+type TextField = 'output' | 'content' | 'content-array'
+
+/**
+ * Extract the mutable text from a `Tool.Result`.
+ *
+ * Preference order mirrors what a session renders: a declared string `output`
+ * first, then a string `content`, then the concatenation of `content` text
+ * parts. A `content` array containing non-text (file) parts is deliberately NOT
+ * enhanced — replacing it would corrupt the structured payload, so it is
+ * reported as unextractable and the whole event becomes a no-op.
+ *
+ * @returns `{ text, field }` or `null` when there is nothing to enhance.
+ */
+function extractText(result: V2ToolResult): { text: string; field: TextField } | null {
+  if (typeof result.output === 'string') return { text: result.output, field: 'output' }
+  if (typeof result.content === 'string') return { text: result.content, field: 'content' }
+  if (Array.isArray(result.content)) {
+    const parts = result.content
+    const allText = parts.every(
+      (part) => typeof part === 'string' || (part as { type?: unknown })?.type === 'text',
+    )
+    if (!allText || parts.length === 0) return null
+    const text = parts
+      .map((part) => (typeof part === 'string' ? part : ((part as { text?: string }).text ?? '')))
+      .join('\n')
+    return { text, field: 'content-array' }
+  }
+  return null
+}
+
+/**
+ * Write enhanced text back into the SAME field it came from, preserving the
+ * result's other fields.
+ */
+function writeText(result: V2ToolResult, field: TextField, text: string): void {
+  if (field === 'output') {
+    result.output = text
+  } else if (field === 'content') {
+    result.content = text
+  } else {
+    result.content = [{ type: 'text', text }]
+  }
+}
+
+/**
+ * Build the V2 `execute.after` handler that runs the V1 parity chain.
+ *
+ * @param options - see {@link V2ExecuteAfterOptions}
+ * @returns a handler suitable for `ctx.tool.hook('execute.after', …)`
+ */
+export function createV2ExecuteAfter(
+  options: V2ExecuteAfterOptions = {},
+): (event: unknown) => Promise<void> {
+  const taskResultGuard = createTaskResultGuard()
+  const sandbox = createContextSandbox(options.sandbox ?? SANDBOX_DEFAULT_CONFIG)
+  const readEnhancer = createReadEnhancer()
+
+  return async function v2ExecuteAfter(event: unknown): Promise<void> {
+    try {
+      if (event === null || typeof event !== 'object' || Array.isArray(event)) return
+      const payload = event as V2ExecuteAfterEvent
+      // Only a completed result has a result to augment; an error event is left
+      // untouched (no after-on-error semantics are claimed).
+      if (payload.status !== 'completed') return
+
+      const result = payload.result
+      if (result === null || typeof result !== 'object' || Array.isArray(result)) return
+
+      const tool = typeof payload.tool === 'string' ? payload.tool : ''
+      const sessionID = typeof payload.sessionID === 'string' ? payload.sessionID : ''
+      const callID = typeof payload.id === 'string' ? payload.id : ''
+
+      const extracted = extractText(result as V2ToolResult)
+      // A `task` result may carry no text at all — that IS the empty-result
+      // failure the guard exists to surface, so synthesize an empty string and
+      // let the guard replace it. Other tools with no text are a no-op.
+      if (extracted === null && tool !== 'task') return
+      const original = extracted === null ? { text: '', field: 'output' as TextField } : extracted
+
+      const input = { tool, sessionID, callID, args: payload.input }
+      const output: {
+        output: string
+        metadata?: Record<string, unknown>
+      } = { output: original.text }
+
+      await taskResultGuard(input, output)
+      await sandbox(input, output)
+      await readEnhancer(input, output)
+
+      if (output.output !== original.text) {
+        writeText(result as V2ToolResult, original.field, output.output)
+      }
+      // Surface sandbox metadata onto the result (merge, never replace). It is
+      // only present when the sandbox actually truncated something.
+      if (output.metadata && Object.keys(output.metadata).length > 0) {
+        ;(result as V2ToolResult).metadata = {
+          ...((result as V2ToolResult).metadata as Record<string, unknown> | undefined),
+          ...output.metadata,
+        }
+      }
+    } catch {
+      // Fail-safe: an unexpected shape must never break the tool result.
+    }
+  }
+}
+
+/**
+ * Resolve a sandbox config from a V2 plugin's `ctx.options.context_sandbox`.
+ * Exposed so `plugin-v2.ts` resolves it the SAME way V1's config hook does,
+ * rather than silently constructing defaults.
+ */
+export function resolveV2SandboxConfig(options: unknown): ContextSandboxConfig {
+  const raw = (options as { context_sandbox?: unknown } | null | undefined)?.context_sandbox
+  return resolveSandboxConfig(raw)
+}

package/src/pantheon/v2-unsupported.mjs

@@ -74,29 +74,6 @@ export const V2_UNSUPPORTED_FEATURE_SEED = Object.freeze([
   // pantheon_goal_create/get/update are therefore absent from the V2 surface
   // rather than registered as non-functional placeholders.
   'goal-tools',
-  // Adapter limitation, not a host gap — TWO separate reasons, which are easy
-  // to conflate and were once stated wrongly (see the v2EnforcementGuard
-  // comment in src/plugin-v2.ts for the long form):
-  //   - MISSING WIRING: V2 keeps no session→agent map (the host puts the agent
-  //     on the execute.before event), so there is no `getSessionAgent` to pass.
-  //     The guard would then call isDelegationAllowed(undefined, target) → false
-  //     and throw "caller agent is unavailable" on EVERY task() call.
-  //   - UNWIRED HIERARCHY: V2 seeds no session→parent map anywhere, and an
-  //     unseeded SessionHierarchyRegistry gates exactly two things — the depth-2
-  //     child deny and the root-session gate. Unseeded, isChild is always false,
-  //     so neither can be trusted. UNWIRED, not impossible: the V2
-  //     `session.created` event carries `properties.info: Session` with
-  //     `parentID?`, the same field V1 seeds from on the same event, and one
-  //     line in onSessionCreated would seed live sessions. V1's OTHER source —
-  //     the client.session.list() startup seed for sessions predating plugin
-  //     load — has no V2 equivalent at all, because V2's PluginContext exposes
-  //     no `client`. Whether a live 2.0.22 host populates info.parentID on that
-  //     event is UNVERIFIED: the canary records Object.keys(ctx), not payloads.
-  // Note the hierarchy is NOT what would deny: isRoot reports `true` for an
-  // unknown session while unseeded, which PASSES the root gate.
-  // Read-only depth-2 still holds via the blocked-tool list in the guard, so
-  // this marker records an unenforced matrix, not an unenforced depth limit.
-  'delegation-matrix',
 ])
 
 /**