pantheon-opencode 1.3.4 → 1.3.5-beta.57.2e03676

package/src/pantheon/cost-command.ts

@@ -10,8 +10,9 @@
  *   - missing/unreadable db → FRIENDLY error string, never a crash (tools
  *     return errors as TEXT).
  *
- * dbPath resolution: explicit option > env PANTHEON_COST_DB > XDG data
- * home > ~/.local/share/opencode/opencode.db. The tool is wired in
+ * dbPath resolution: explicit option > env PANTHEON_COST_DB > the version-aware
+ * default selected by PANTHEON_OPENCODE_VERSION (v1 or v2). An unset version
+ * deliberately preserves V1 behavior. The tool is wired in
  * plugin.ts alongside the delegation toolset (usable by zeus and any agent
  * with tool access — no routing change needed).
  *
@@ -41,6 +42,8 @@ export interface CostCommandOptions {
   dbPath?: string
 }
 
+export type OpenCodeVersion = 'v1' | 'v2'
+
 /** One cost tool: description + zod args shape + execute (delegation.ts shape). */
 export interface CostTool<Args extends z.ZodRawShape = typeof costArgs> {
   description: string
@@ -62,15 +65,32 @@ const costArgs = {
     .describe('Number of days of delegation history to include (default 7).'),
 } satisfies z.ZodRawShape
 
-/** Resolve candidate db paths in priority order (env override first). */
-function dbCandidates(): string[] {
-  const candidates: string[] = []
-  const env = process.env.PANTHEON_COST_DB
-  if (env !== undefined && env !== '') candidates.push(env)
+/** Return the safe, isolated state DB name for an OpenCode version. */
+function defaultDbPath(version: OpenCodeVersion | undefined): string {
   const xdg = process.env.XDG_DATA_HOME
   const dataHome = xdg !== undefined && xdg !== '' ? xdg : join(homedir(), '.local', 'share')
-  candidates.push(join(dataHome, 'opencode', 'opencode.db'))
-  return candidates
+  const filename = version === 'v2' ? 'opencode-v2.db' : 'opencode.db'
+  return join(dataHome, 'opencode', filename)
+}
+
+/**
+ * Resolve the database without probing another version's database.
+ *
+ * Explicit paths always win. A version selector changes exactly one default
+ * filename; it never falls back to V1, which prevents a V2 report from
+ * silently reading V1 history (or vice versa).
+ */
+export function resolveCostDbPath(options?: CostCommandOptions): string {
+  const explicit = options?.dbPath || process.env.PANTHEON_COST_DB
+  if (explicit) return explicit
+
+  const configuredVersion = process.env.PANTHEON_OPENCODE_VERSION
+  if (configuredVersion !== undefined && configuredVersion !== 'v1' && configuredVersion !== 'v2') {
+    throw new Error(
+      `invalid PANTHEON_OPENCODE_VERSION "${configuredVersion}"; expected "v1" or "v2"`,
+    )
+  }
+  return defaultDbPath(configuredVersion as OpenCodeVersion | undefined)
 }
 
 /**
@@ -79,11 +99,28 @@ function dbCandidates(): string[] {
  * to the real opencode.db).
  */
 function findExistingDb(override?: string): string | undefined {
-  const candidates = override !== undefined && override !== '' ? [override] : dbCandidates()
-  for (const candidate of candidates) {
-    if (existsSync(candidate)) return candidate
+  const candidate =
+    override === undefined ? resolveCostDbPath() : resolveCostDbPath({ dbPath: override })
+  return existsSync(candidate) ? candidate : undefined
+}
+
+function assertCompatibleSchema(db: {
+  prepare(sql: string): { get(): unknown; all(...args: unknown[]): unknown[] }
+}): void {
+  const row = db
+    .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'message'")
+    .get()
+  if (row === undefined) {
+    throw new Error('incompatible opencode.db schema: required "message" table is missing')
+  }
+  const columns = db.prepare('PRAGMA table_info(message)').all() as Array<{ name?: unknown }>
+  const names = new Set(columns.map((column) => column.name))
+  const missing = ['data', 'time_created'].filter((name) => !names.has(name))
+  if (missing.length > 0) {
+    throw new Error(
+      `incompatible opencode.db schema: message table is missing ${missing.join(', ')}; select the matching V1/V2 database`,
+    )
   }
-  return undefined
 }
 
 /** Aggregate cost + tokens by agent via node:sqlite (read-only). */
@@ -91,6 +128,7 @@ async function queryWithNodeSqlite(dbPath: string, days: number): Promise<CostRo
   const sqlite = await import('node:sqlite')
   const db = new sqlite.DatabaseSync(dbPath, { readOnly: true })
   try {
+    assertCompatibleSchema(db)
     const since = Date.now() - days * 86_400_000
     const rows = db.prepare('SELECT data FROM message WHERE time_created >= ?').all(since)
     return aggregateMessages(rows.map((row) => String(row.data)))
@@ -180,16 +218,17 @@ export function createCostCommand(options?: CostCommandOptions): CostCommand {
     try {
       const dbPath = findExistingDb(options?.dbPath)
       if (dbPath === undefined) {
-        const expected =
-          options?.dbPath ?? process.env.PANTHEON_COST_DB ?? '~/.local/share/opencode/opencode.db'
+        const expected = resolveCostDbPath(options)
         return (
           `pantheon_cost failed: opencode.db not found (expected at ${expected}). ` +
           `No cost history is available until opencode has stored session data.`
         )
       }
-      const rows = await queryWithNodeSqlite(dbPath, days).catch(async () =>
-        queryWithScript(scriptPath, dbPath, days),
-      )
+      const rows = await queryWithNodeSqlite(dbPath, days).catch(async (err: unknown) => {
+        if (err instanceof Error && err.message.startsWith('incompatible opencode.db schema'))
+          throw err
+        return queryWithScript(scriptPath, dbPath, days)
+      })
       return renderMarkdown(rows, days)
     } catch (err: unknown) {
       const reason = err instanceof Error ? err.message : String(err)

package/src/pantheon/delegation-enforce.ts

@@ -18,9 +18,9 @@
  *   - `task` is blocked too, which hard-enforces depth-2: a read-only agent
  *     cannot spawn its own subagents.
  *
- * Unknown sessions are ALLOWED by default — the guard only denies sessions
- * that are explicitly registered, so normal (non-delegated) agent work is
- * never blocked.
+ * Unknown sessions are allowed for ordinary tools. Delegation tools are
+ * fail-closed when the runtime matrix is wired: missing agent identity or
+ * target metadata is denied rather than inferred.
  *
  * The registry is populated by delegation.ts at delegate time: the CHILD
  * session is registered when the delegate call is read-only.
@@ -47,8 +47,100 @@ export interface ToolExecuteBeforeInput {
   callID: string
 }
 
+/** The output object supplied alongside `tool.execute.before`. */
+export interface ToolExecuteBeforeOutput {
+  args?: unknown
+}
+
 /** The `tool.execute.before` handler shape (throw ⇒ deny). */
-export type ToolExecuteBeforeHandler = (input: ToolExecuteBeforeInput) => Promise<void>
+export type ToolExecuteBeforeHandler = (
+  input: ToolExecuteBeforeInput,
+  output?: ToolExecuteBeforeOutput,
+) => Promise<void>
+
+/** Runtime session hierarchy, populated only from SDK session metadata. */
+export class SessionHierarchyRegistry {
+  private readonly roots = new Set<string>()
+  private readonly children = new Set<string>()
+  private seedState: 'unseeded' | 'pending' | 'seeded' | 'failed' = 'unseeded'
+
+  /** Mark the beginning of an authoritative session snapshot lookup. */
+  beginSeed(): void {
+    this.seedState = 'pending'
+  }
+
+  /** Complete the lookup and register the SDK's authoritative parentID data. */
+  completeSeed(sessions: ReadonlyArray<{ id: string; parentID?: string }>): void {
+    this.registerMany(sessions)
+    this.seedState = 'seeded'
+  }
+
+  /** Record an unavailable snapshot without classifying unknown sessions as children. */
+  failSeed(): void {
+    this.seedState = 'failed'
+  }
+
+  /** Register a session using its SDK parentID (or lack of one). */
+  register(session: { id: string; parentID?: string }): void {
+    if (session.parentID !== undefined) {
+      this.children.add(session.id)
+      this.roots.delete(session.id)
+      return
+    }
+    if (!this.children.has(session.id)) this.roots.add(session.id)
+  }
+
+  /** Register a snapshot returned by session.list(). */
+  registerMany(sessions: ReadonlyArray<{ id: string; parentID?: string }>): void {
+    for (const session of sessions) this.register(session)
+  }
+
+  /** Whether SDK metadata identified this session as a child. */
+  isChild(sessionID: string): boolean {
+    return this.children.has(sessionID)
+  }
+
+  /** Whether SDK metadata identified this session as a root. */
+  isRoot(sessionID: string): boolean {
+    if (this.children.has(sessionID)) return false
+    if (this.roots.has(sessionID)) return true
+    // Until the authoritative snapshot is available, an unknown session is
+    // deliberately unclassified. A valid root resumed after restart must not
+    // be denied merely because session.list() is slow or unavailable.
+    return this.seedState !== 'seeded'
+  }
+
+  /** Snapshot of known root IDs. */
+  rootIDs(): ReadonlySet<string> {
+    return new Set(this.roots)
+  }
+}
+
+/** Normalize an agent identity without guessing from prompts or tool names. */
+export function normalizeDelegationAgent(agent: unknown): string | undefined {
+  if (typeof agent !== 'string') return undefined
+  const normalized = agent.trim().toLowerCase()
+  return normalized === '' ? undefined : normalized
+}
+
+/** Runtime delegation matrix from Fase B2. */
+export function isDelegationAllowed(callerAgent: unknown, targetAgent: unknown): boolean {
+  const caller = normalizeDelegationAgent(callerAgent)
+  const target = normalizeDelegationAgent(targetAgent)
+  if (caller === undefined || target === undefined) return false
+  if (caller === 'zeus') return true
+  return (caller === 'athena' || caller === 'hermes') && target === 'apollo'
+}
+
+function targetFromTool(tool: string, args: unknown): string | undefined {
+  if (args === null || typeof args !== 'object') return undefined
+  const record = args as Record<string, unknown>
+  if (tool === 'pantheon_delegate') return normalizeDelegationAgent(record.agent)
+  if (tool === 'task') {
+    return normalizeDelegationAgent(record.subagent_type ?? record.subagentType)
+  }
+  return undefined
+}
 
 /** Options for createEnforcementGuard(). */
 export interface EnforcementGuardOptions {
@@ -56,6 +148,14 @@ export interface EnforcementGuardOptions {
   blockedTools?: ReadonlySet<string>
   /** Prefix for the denial message. */
   messagePrefix?: string
+  /** Current agent by session, populated by the SDK chat.params hook. */
+  getSessionAgent?: (sessionID: string) => string | undefined
+  /** SDK-backed root check used for the delegation matrix. */
+  isRootSession?: (sessionID: string) => boolean
+  /** SDK-backed child check used to prevent native task() depth escalation. */
+  isChildSession?: (sessionID: string) => boolean
+  /** Audit sink for denied runtime delegation attempts. */
+  logger?: { warn?: (message: string) => void }
 }
 
 // ─── Defaults ──────────────────────────────────────────────────────────
@@ -129,7 +229,41 @@ export function createEnforcementGuard(input: {
   const blockedTools = input.options?.blockedTools ?? DEFAULT_BLOCKED_TOOLS
   const prefix = input.options?.messagePrefix ?? 'pantheon_delegate guard'
 
-  return async (hook: ToolExecuteBeforeInput): Promise<void> => {
+  return async (hook: ToolExecuteBeforeInput, output?: ToolExecuteBeforeOutput): Promise<void> => {
+    const isDelegationTool = hook.tool === 'task' || hook.tool === 'pantheon_delegate'
+    if (isDelegationTool && input.options?.isChildSession?.(hook.sessionID) === true) {
+      throw new Error(
+        `${prefix}: session ${hook.sessionID} is a child session — delegation tools are denied ` +
+          'to prevent nested delegation',
+      )
+    }
+    // pantheon_delegate has the authoritative ToolContext.agent at execution
+    // time, so its matrix check lives in delegation.ts. The hook only has the
+    // session-scoped agent learned from chat.params for native task().
+    if (
+      hook.tool === 'task' &&
+      input.options?.isRootSession !== undefined &&
+      input.options?.isChildSession?.(hook.sessionID) !== true
+    ) {
+      const caller = input.options.getSessionAgent?.(hook.sessionID)
+      const target = targetFromTool(hook.tool, output?.args)
+      if (!input.options.isRootSession(hook.sessionID)) {
+        input.options.logger?.warn?.(
+          `${prefix}: delegation denied for session ${hook.sessionID} — not an authorized root session`,
+        )
+        throw new Error(`${prefix}: session ${hook.sessionID} is not an authorized root session`)
+      }
+      if (!isDelegationAllowed(caller, target)) {
+        const reason =
+          caller === undefined ? 'caller agent is unavailable' : 'agent/target is not allowed'
+        input.options.logger?.warn?.(
+          `${prefix}: delegation denied for session ${hook.sessionID} — ${reason}`,
+        )
+        throw new Error(
+          `${prefix}: delegation denied — ${reason}; target must follow the runtime matrix`,
+        )
+      }
+    }
     if (!blockedTools.has(hook.tool)) return
     if (!input.getReadOnlySessions().has(hook.sessionID)) return
 

package/src/pantheon/delegation-finalize.ts

@@ -65,6 +65,16 @@ export interface DelegationOptions {
   rootSessions?: ReadonlySet<string>
   /** Custom depth-guard predicate — overrides rootSessions and the default. */
   isRootSession?: (sessionID: string) => boolean
+  /** SDK-backed child predicate; authoritative when supplied by the plugin. */
+  isChildSession?: (sessionID: string) => boolean
+  /**
+   * Enforce the runtime B2 delegation matrix; createDelegationTools defaults
+   * this to true. Set false only for an explicitly legacy host that cannot
+   * provide ToolContext.agent.
+   */
+  enforceRuntimeMatrix?: boolean
+  /** Record a child returned by the SDK session.create call. */
+  registerChildSession?: (sessionID: string, parentID: string) => void
   /**
    * Agents whose delegated child sessions are registered as read-only
    * (Phase 4 enforcement). Mirrors routing.yml
@@ -78,6 +88,20 @@ export interface DelegationOptions {
    * from routing.yml agent entries. Higher priority than the active preset.
    */
   agentModels?: Readonly<Record<string, string>>
+  /**
+   * Fase B3: Per-exception delegation budgets. Keys use
+   * `<parent-agent>-><target-agent>` (for example `athena->apollo`). The
+   * count is tracked per parent session for this process. It is intentionally
+   * not persisted across restart because this layer has no reliable store.
+   * An absent key has no budget limit.
+   */
+  delegationBudgets?: ReadonlyMap<string, number>
+  /**
+   * Fase B3: Wall-clock timeout (ms) for individual delegation sessions.
+   * The plugin resolves `PANTHEON_DELEGATION_TIMEOUT_MS` into this option;
+   * direct callers may provide it here instead.
+   */
+  wallClockTimeoutMs?: number
   /**
    * Env override for the active-preset resolution (see resolveActivePreset).
    * Defaults to process.env. Primarily for tests.

package/src/pantheon/delegation.ts

@@ -19,19 +19,13 @@
  * Depth guard (root-session detection): the ToolContext carries NO parentID
  * (spike), so root detection is configurable. Resolution order:
  *   1. `options.isRootSession(sessionID)` custom predicate;
- *   2. `options.rootSessions` explicit allowlist — with a knownChildren
- *      fallback (compaction-134): a session is a sub-session ONLY if WE
- *      created it as a child (`session.create` via pantheon_delegate).
- *      Sessions in neither set are treated as root, so a resumed root can
- *      delegate after a restart even when the allowlist is incomplete
- *      (opencode does not replay `session.created` events for pre-existing
- *      sessions — the plugin seeds the registry from session.list() at
- *      startup, and this fallback covers a failed/incomplete seed);
+ *   2. `options.rootSessions` explicit allowlist, with `options.isChildSession`
+ *      authoritative when supplied by the plugin. SDK session metadata is
+ *      registered from parentID; no prompt/name inference is used.
  *   3. default (no rootSessions): any session WE created via
  *      `session.create` is a sub-session; everything else is treated as
- *      root. Phase 3 should pass the root registry derived from
- *      `session.created` events (Session.parentID undefined ⇒ root) for
- *      authoritative enforcement.
+ *      root for standalone compatibility. The plugin supplies the SDK-backed
+ *      hierarchy at runtime.
  *
  * Read-only enforcement is Phase 4 — `read_only` is exposed on the delegate
  * args and the child session is registered in the read-only registry when the
@@ -44,7 +38,11 @@
 import { z } from 'zod'
 
 import type { BackgroundJobBoard, BackgroundJobRecord } from './background-job-board.ts'
-import { readOnlyRegistry } from './delegation-enforce.ts'
+import {
+  isDelegationAllowed,
+  normalizeDelegationAgent,
+  readOnlyRegistry,
+} from './delegation-enforce.ts'
 import {
   DELEGATION_DEFAULTS,
   type DelegationClient,
@@ -67,6 +65,49 @@ export type {
 } from './delegation-finalize.ts'
 export { DELEGATION_DEFAULTS } from './delegation-finalize.ts'
 
+// Fase B3: these are runtime controls, not routing/frontmatter fields. The
+// plugin reads them from the environment, while tests and embedders can pass
+// the same values through DelegationOptions.
+export const B3_DEFAULT_EXCEPTION_BUDGET = 5
+
+function readIntegerEnv(
+  env: Record<string, string | undefined>,
+  name: string,
+  fallback: number,
+  minimum: number,
+): number {
+  const raw = env[name]?.trim()
+  if (raw === undefined || raw === '') return fallback
+  const value = Number(raw)
+  return Number.isSafeInteger(value) && value >= minimum ? value : fallback
+}
+
+/** Resolve the two supported read-only delegation exception budgets. */
+export function resolveDelegationBudgets(
+  env: Record<string, string | undefined> = process.env,
+): ReadonlyMap<string, number> {
+  return new Map([
+    [
+      'athena->apollo',
+      readIntegerEnv(env, 'PANTHEON_ATHENA_APOLLO_BUDGET', B3_DEFAULT_EXCEPTION_BUDGET, 0),
+    ],
+    [
+      'hermes->apollo',
+      readIntegerEnv(env, 'PANTHEON_HERMES_APOLLO_BUDGET', B3_DEFAULT_EXCEPTION_BUDGET, 0),
+    ],
+  ])
+}
+
+/** Resolve an optional positive wall-clock timeout from the environment. */
+export function resolveDelegationTimeoutMs(
+  env: Record<string, string | undefined> = process.env,
+): number | undefined {
+  const raw = env.PANTHEON_DELEGATION_TIMEOUT_MS?.trim()
+  if (raw === undefined || raw === '') return undefined
+  const value = Number(raw)
+  return Number.isSafeInteger(value) && value > 0 ? value : undefined
+}
+
 // ─── Types ─────────────────────────────────────────────────────────────
 
 // Silence-by-default TUI policy (pantheon-hooks L42-58): console output in a
@@ -79,6 +120,11 @@ export interface ToolContextLike {
   sessionID: string
   directory?: string
   worktree?: string
+  /**
+   * The OpenCode SDK's ToolContext declares this as required. It remains
+   * optional here because the structural test/embedding surface can be
+   * supplied by older hosts; B3 must skip enforcement when it is absent.
+   */
   agent?: string
 }
 
@@ -146,6 +192,9 @@ function stateLabel(state: BackgroundJobRecord['state']): string {
   }
 }
 
+/** Normalize the SDK-provided caller agent without inventing an identity. */
+const normalizeToolAgent = normalizeDelegationAgent
+
 // ─── Agent activity sampling ────────────────────────────────────────────
 //
 // Visibility for `pantheon_delegation_read` / `pantheon_delegation_list`
@@ -478,16 +527,24 @@ export function collectRootSessionIDs(
  */
 export function createDelegationTools(input: CreateDelegationToolsInput): DelegationToolset {
   const { board, client } = input
-  const options: DelegationOptions = input.options ?? {}
+  // Runtime matrix enforcement is the safe default for every host. A legacy
+  // structural embedder must opt out explicitly with `false`; omission must
+  // never silently widen the delegation surface.
+  const options: DelegationOptions = { enforceRuntimeMatrix: true, ...(input.options ?? {}) }
   const deps: DelegationDeps = { board, client, options }
   const outputDir = options.outputDir ?? DELEGATION_DEFAULTS.outputDir
-  const timeoutMs = options.timeoutMs ?? DELEGATION_DEFAULTS.timeoutMs
+  const timeoutMs = options.wallClockTimeoutMs ?? options.timeoutMs ?? DELEGATION_DEFAULTS.timeoutMs
   const readTimeoutMs = options.readTimeoutMs ?? DELEGATION_DEFAULTS.readTimeoutMs
 
   const knownChildren = new Set<string>()
   const timers = new Map<string, NodeJS.Timeout>()
+  // Fase B3: per-parent-session delegation budget tracking, scoped to this
+  // factory/process instance. Keyed by `${parentSessionID}:${parentAgent}->${targetAgent}`;
+  // it is not restart-persistent because the factory has no reliable store.
+  const budgetUsage = new Map<string, number>()
 
   function isRootSession(sessionID: string): boolean {
+    if (options.isChildSession?.(sessionID) === true) return false
     if (options.isRootSession !== undefined) return options.isRootSession(sessionID)
     if (options.rootSessions !== undefined) {
       // compaction-134 (fix layer 2): the allowlist alone is NOT
@@ -540,6 +597,54 @@ export function createDelegationTools(input: CreateDelegationToolsInput): Delega
         )
       }
 
+      // Fase B3: only the two read-only exceptions are budgeted. The official
+      // SDK provides the current agent on ToolContext. If a structural/older
+      // host omits it, do NOT infer identity from prompt, target, or process
+      // state: the budget is explicitly skipped and the delegation continues.
+      const parentAgent = normalizeToolAgent(ctx.agent)
+      const targetAgent = args.agent.toLowerCase()
+      if (options.enforceRuntimeMatrix === true && !isDelegationAllowed(parentAgent, targetAgent)) {
+        const reason =
+          parentAgent === undefined
+            ? 'ToolContext.agent is unavailable'
+            : `${parentAgent}->${targetAgent} is not allowed`
+        options.logger?.warn?.(
+          `[pantheon-delegate] runtime delegation denied for session ${ctx.sessionID}: ${reason}`,
+        )
+        throw new Error(`pantheon_delegate rejected: runtime delegation matrix denied (${reason})`)
+      }
+      if (
+        parentAgent === undefined &&
+        !options.enforceRuntimeMatrix &&
+        (options.delegationBudgets?.size ?? 0) > 0
+      ) {
+        const message =
+          `[pantheon-delegate] B3 budget skipped: current agent unavailable for session ${ctx.sessionID}; ` +
+          `no budget limit applied to ${targetAgent}. Runtime must provide ToolContext.agent ` +
+          '(the official SDK field) to enforce the configured exception budget.'
+        ;(options.logger?.warn ?? ((msg: string) => log.warn(msg)))(message)
+      }
+      const budgetKey =
+        parentAgent === undefined ? undefined : `${ctx.sessionID}:${parentAgent}->${targetAgent}`
+      const budget =
+        parentAgent === undefined
+          ? undefined
+          : options.delegationBudgets?.get(`${parentAgent}->${targetAgent}`)
+      let budgetReserved = false
+      if (budgetKey !== undefined && budget !== undefined) {
+        const used = budgetUsage.get(budgetKey) ?? 0
+        if (used >= budget) {
+          throw new Error(
+            `pantheon_delegate rejected: delegation budget exhausted for ${parentAgent}->${targetAgent} ` +
+              `(${used}/${budget} dispatches used in this session). ` +
+              'Configure the corresponding PANTHEON_*_APOLLO_BUDGET environment variable or DelegationOptions.',
+          )
+        }
+        // Reserve before the first await so concurrent calls cannot overshoot.
+        budgetUsage.set(budgetKey, used + 1)
+        budgetReserved = true
+      }
+
       // session.create failure → return a clear error as TEXT (tools return
       // errors as text, not thrown) and register NO job on the board — an
       // unhandled rejection here would otherwise lose the failure entirely.
@@ -551,7 +656,11 @@ export function createDelegationTools(input: CreateDelegationToolsInput): Delega
       // opencode/deepseek-v4-flash-free; if nothing usable remains the
       // failure is returned as TEXT below — no session, no board job.
       const resolved = resolveUsableChildModel(options, args.agent, args.model)
-      if (resolved.error !== undefined) return resolved.error
+      if (resolved.error !== undefined) {
+        if (budgetReserved && budgetKey !== undefined)
+          budgetUsage.set(budgetKey, (budgetUsage.get(budgetKey) ?? 1) - 1)
+        return resolved.error
+      }
       const childModel = resolved.model
       let created: { id: string }
       try {
@@ -564,10 +673,14 @@ export function createDelegationTools(input: CreateDelegationToolsInput): Delega
         })
       } catch (err: unknown) {
         const reason = err instanceof Error ? err.message : String(err)
+        if (budgetReserved && budgetKey !== undefined) {
+          budgetUsage.set(budgetKey, Math.max(0, (budgetUsage.get(budgetKey) ?? 1) - 1))
+        }
         return `pantheon_delegate failed to create child session: ${reason}`
       }
       const childSessionID = created.id
       knownChildren.add(childSessionID)
+      options.registerChildSession?.(childSessionID, ctx.sessionID)
 
       // Phase 4 read-only enforcement: register the child session in the
       // read-only registry when the delegate is read-only — explicit

package/src/plugin.ts

@@ -7,9 +7,15 @@ import {
   collectRootSessionIDs,
   createDelegationTools,
   type DelegationClient,
+  resolveDelegationBudgets,
+  resolveDelegationTimeoutMs,
 } from './pantheon/delegation.ts'
 import { buildCompactionContext } from './pantheon/delegation-compaction.ts'
-import { createEnforcementGuard, readOnlyRegistry } from './pantheon/delegation-enforce.ts'
+import {
+  createEnforcementGuard,
+  readOnlyRegistry,
+  SessionHierarchyRegistry,
+} from './pantheon/delegation-enforce.ts'
 import { handleDelegationEvent } from './pantheon/delegation-notify.ts'
 import { FilePersistenceAdapter } from './pantheon/file-persistence.ts'
 import { GOAL_LOOP_DEFAULTS, GoalLoop, GoalStore } from './pantheon/goal-loop.ts'
@@ -94,6 +100,12 @@ setInterval(
 // from tool.execute.before; unknown sessions are allowed (safe default).
 const enforcementGuard = createEnforcementGuard({
   getReadOnlySessions: () => readOnlyRegistry.sessionIDs(),
+  options: {
+    getSessionAgent: (sessionID) => sessionAgents.get(sessionID),
+    isRootSession: (sessionID) => rootSessions.has(sessionID) || sessionHierarchy.isRoot(sessionID),
+    isChildSession: (sessionID) => sessionHierarchy.isChild(sessionID),
+    logger: log,
+  },
 })
 
 // Mirrors routing.yml background_delegation.max_compaction_items.
@@ -111,6 +123,8 @@ const COMPACTION_MAX_ITEMS = 10
 // created is a sub-session; unknown sessions are roots") so the depth guard
 // works even when this set is incomplete.
 const rootSessions = new Set<string>()
+const sessionHierarchy = new SessionHierarchyRegistry()
+const sessionAgents = new Map<string, string>()
 
 /**
  * Seed resumed root sessions without making OpenCode startup depend on the
@@ -127,18 +141,23 @@ function seedRootSessionsInBackground(input: PluginInput): void {
   // the seed is always safe.
   const session = input.client.session
   if (typeof session?.list !== 'function') return
+  sessionHierarchy.beginSeed()
   void session
     .list()
     .then((result) => {
       if (!result.error && Array.isArray(result.data)) {
+        sessionHierarchy.completeSeed(result.data)
         const seeded = collectRootSessionIDs(result.data)
         if (seeded.size > 0) {
           for (const id of seeded) rootSessions.add(id)
           log.info(`[Pantheon Plugin] Seeded ${seeded.size} root session(s) from session.list`)
         }
+      } else {
+        sessionHierarchy.failSeed()
       }
     })
     .catch((err) => {
+      sessionHierarchy.failSeed()
       log.warn('[Pantheon Plugin] Root session seed failed (fail-open):', err)
     })
 }
@@ -264,13 +283,26 @@ const plugin: Plugin = async (input: PluginInput) => {
   // Phase 2/3: background delegation toolset + the bound finalize lifecycle
   // hook. Completion is observed through the event hook below
   // (session.idle / session.error on a child) → finalizeDelegation.
+  // Fase B3: runtime controls for the two read-only exceptions and the real
+  // per-child wall-clock timer. No task_budget field is injected into the
+  // plugin/frontmatter; these are enforced by delegation.ts itself.
+  const delegationBudgets = resolveDelegationBudgets()
+  const wallClockTimeoutMs = resolveDelegationTimeoutMs()
+
   const delegation = createDelegationTools({
     board,
     client: adaptDelegationClient(input.client),
     options: {
       rootSessions,
+      isChildSession: (sessionID) => sessionHierarchy.isChild(sessionID),
+      registerChildSession: (sessionID, parentID) => {
+        sessionHierarchy.register({ id: sessionID, parentID })
+      },
+      enforceRuntimeMatrix: true,
       readOnlyAgents: new Set(['apollo', 'gaia']),
       agentModels: routingAgentModels,
+      delegationBudgets,
+      ...(wallClockTimeoutMs !== undefined ? { wallClockTimeoutMs } : {}),
     },
   })
 
@@ -393,12 +425,20 @@ const plugin: Plugin = async (input: PluginInput) => {
       // user-activity gate skips injection for userActivityQuietMs afterwards.
       todoEnforcer.noteUserActivity(hookInput.sessionID)
     },
+    'chat.params': async (hookInput) => {
+      // The SDK exposes the active agent here; tool.execute.before has no
+      // agent field. Never infer identity from a prompt or tool name.
+      sessionAgents.set(hookInput.sessionID, hookInput.agent)
+    },
     'experimental.chat.messages.transform': vision.messagesTransform,
     event: async ({ event: ev }) => {
       // Phase 3: sessions created without a parent are roots for the depth guard.
       if (ev.type === 'session.created') {
         const info = ev.properties.info
-        if (info && info.parentID === undefined) rootSessions.add(info.id)
+        if (info) {
+          sessionHierarchy.register(info)
+          if (info.parentID === undefined) rootSessions.add(info.id)
+        }
       }
       // release-134 Phase 3: activate the todo snapshot captured at
       // compacting time — the first todowrite within the restore window is
@@ -449,7 +489,7 @@ const plugin: Plugin = async (input: PluginInput) => {
       // first post-compaction `todowrite` with the captured todo snapshot.
       // Both are no-ops for non-matching sessions/tools; the preserver is
       // fail-open (only its intentional restore denial throws).
-      await enforcementGuard(input)
+      await enforcementGuard(input, output)
       await todoPreserver.beforeTodoWrite(input, output)
     },
     // Wave 2 (PR #46): augment `read` output with hashline tags. Additive —