pantheon-opencode 1.6.0-beta.3 → 1.6.0-beta.5

package/src/pantheon/v2-unsupported.d.mts

@@ -0,0 +1,11 @@
+/**
+ * Type declarations for v2-unsupported.mjs (the V2 feature-reduction seed).
+ * Consumed by src/plugin-v2.ts via `import ... from './pantheon/v2-unsupported.mjs'`,
+ * and by the plain-`.mjs` install/health scripts at runtime.
+ */
+
+/** Statically-known V2 feature reductions, in report order. */
+export declare const V2_UNSUPPORTED_FEATURE_SEED: readonly string[]
+
+/** A fresh, mutable copy of the seed, so a reporter cannot mutate the shared list. */
+export declare function listV2UnsupportedFeatures(): string[]

package/src/pantheon/v2-unsupported.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * v2-unsupported.mjs — the SEED of V2 feature reductions, in plain ESM.
+ *
+ * WHY A SEPARATE PLAIN-`.mjs` MODULE: these strings must be readable by three
+ * very different consumers, and only one of them can import TypeScript.
+ *
+ *   - `src/plugin-v2.ts` (TypeScript) — owns the LIVE list, appending to it at
+ *     runtime via `markUnsupported()` when a host API turns out to be missing,
+ *     and exposes it through `getUnsupportedFeatures()`.
+ *   - `scripts/install/opencode.mjs` — reports the reduction at install time
+ *     for a V2-generation install.
+ *   - `scripts/doctor.mjs` — reports it in the health gate.
+ *
+ * The scripts are plain Node ESM and must stay that way, and `.mjs` is a
+ * REPO-WIDE INVARIANT rather than a judgement about Node: `tsx` is a
+ * devDependency only, and no plain-Node script in `scripts/` or `bin/` imports
+ * a `.ts` module — every `.ts` path there is a string to copy, stat or read as
+ * text (`scripts/install/opencode.mjs`, `scripts/probe-pantheon-cost.mjs`,
+ * `scripts/package-evidence.mjs`, `scripts/check-plugin-v2-coverage.mjs`).
+ * So a `.mjs` import is the only form all three consumers can share, and it
+ * matches the existing `src/pantheon/presets.mjs` + `.d.mts` precedent.
+ *
+ * NOT the reason: type-stripping. `package.json#engines` admits
+ * `^22.22.2 || ^24.15.0 || >=26.0.0`, every admitted version already defaults to
+ * unflagged type-stripping (it landed in 22.18.0), so that argument would not
+ * have held on any admitted version. The live hazard is that `engines` is not
+ * ENFORCED: a Node 20 user can run `doctor` and would get no type-stripping,
+ * which is an argument for a runtime version check, not for this file's shape.
+ *
+ * The SEED is the statically-known half of `getUnsupportedFeatures()`: what a
+ * migrating user loses by choosing the V2 contract, knowable with no host at
+ * all. Runtime-appended entries (`tool-transform`, `event-stream`, …) are
+ * observations about one live host and are deliberately NOT seeded here — they
+ * are not known until the plugin runs against a real V2 host.
+ *
+ * ONE SOURCE OF TRUTH: install and doctor both read the seed from here, so the
+ * two cannot drift apart, and what they report IS what this file lists. Note the
+ * scope of that claim: it holds between the SEED and the two reporters. The
+ * LIVE list `getUnsupportedFeatures()` returns is this seed PLUS markers appended
+ * at runtime (`tool-transform`, `event-stream`, …), so it is a superset and the
+ * two are expected to differ there. Do not copy these strings into a script;
+ * import them.
+ *
+ * @module v2-unsupported
+ */
+
+/**
+ * Statically-known V2 feature reductions, in the order a reader should meet
+ * them. Frozen: `plugin-v2.ts` copies it into its own mutable live array, and
+ * every other consumer goes through {@link listV2UnsupportedFeatures}.
+ *
+ * @type {readonly string[]}
+ */
+export const V2_UNSUPPORTED_FEATURE_SEED = Object.freeze([
+  'legacy-hooks',
+  // `ctx.catalog` is the one domain a live 2.0.22 host does NOT have: it is
+  // absent from `Object.keys(ctx)`, measured in
+  // tests/canary/plugin-v2-tool-canary.test.mjs. (`catalog` IS in the 1.18.33
+  // SDK's PluginContext, so the SDK types it and the host does not provide it.)
+  'catalog-transform',
+  // Adapter support, NOT host availability: 2.0.22 exposes ctx.integration and
+  // ctx.skill with callable transforms, and Pantheon deliberately registers
+  // neither. These entries record what this plugin does not implement.
+  'integration-transform',
+  // The inspected SkillEditor shape has no `source()` helper — i.e. no
+  // `SkillEditor.source()` — for adding a directory source. This is narrower
+  // than (and distinct from) ctx.skill's host availability or callable
+  // transform, which a live 2.0.22 host does provide.
+  'skill-transform',
+  // Adapter limitation, not a host gap: the goal loop needs a GoalStore, a
+  // GoalLoopClient and a BackgroundJobBoard, none of which the V2
+  // PluginContext exposes, and the V1 bridge resolves to null outside V1.
+  // 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',
+])
+
+/**
+ * A fresh, mutable copy of the seed.
+ *
+ * Callers get a copy so a reporter that sorts, filters or appends cannot reach
+ * back into the shared list — this is what makes "both surfaces report the same
+ * strings" a structural property rather than a convention.
+ *
+ * @returns {string[]}
+ */
+export function listV2UnsupportedFeatures() {
+  return [...V2_UNSUPPORTED_FEATURE_SEED]
+}

package/src/plugin-v2.ts

@@ -5,7 +5,7 @@
  * - 3 self-sufficient tools via V2 tool.transform (hashline_edit,
  *   pantheon_cost, pantheon_model — see ./pantheon/v2-tools.ts; the goal tools
  *   need V1 infrastructure and are absent from this surface)
- * - 4 event subscriptions (session.created, idle, error, compacted)
+ * - 5 event subscriptions (session.created, idle, deleted, error, compacted)
  * - Session hooks (prompt, context, compaction)
  * - A tool `execute.before` hook that ENFORCES read-only sessions: the agent
  *   arrives on the host's event, a read-only agent (apollo/gaia) registers its
@@ -26,21 +26,44 @@
  * `execute` MUST resolve to a value carrying `output`. The host enforces the
  * two as a pair — see `V2ToolDraft` for the exact contract.
  *
- * The transitional SDK types used here expose these domains:
- *   ctx.agent / ctx.command / ctx.model / ctx.reference / ctx.skill /
- *   ctx.tool / ctx.event / ctx.permission / ctx.session
+ * ## The four domains the SDK types do not carry
  *
- * A separate OpenCode 2.0.18 host runtime probe confirmed ctx.integration and
- * ctx.skill have callable `.transform` methods; only ctx.catalog was absent.
- * The probe's callback effects were
- * not observed for any domain. This runtime probe is not an SDK compatibility
- * claim. Pantheon's Phase 1/config transform
- * registrations cover agent, command, and reference; `ctx.tool.transform` is
- * attempted separately in Phase 2. Integration and skill transform callbacks
- * are not registered by Pantheon, so their effects remain unproven. The
- * narrower `SkillEditor.source()` helper is absent from the inspected SDK
- * editor shape, so directory-source registration remains unsupported; that
- * does not imply that `ctx.skill` or its transform is absent.
+ * `@opencode-ai/plugin` 1.18.33 types `PluginContext` as exactly:
+ *   options · agent · aisdk · catalog · command · integration · plugin ·
+ *   reference · skill
+ * — no `tool`, `event`, `permission` or `session`. 1.18.34 (`latest`) is the
+ * same, so following the stable SDK line does not resolve this: it is a
+ * STRUCTURAL DECLARATION task, not a pin reconciliation.
+ *
+ * A live opencode 2.0.22 host DOES have all four, with the shapes this module
+ * uses. Measured by `tests/canary/plugin-v2-tool-canary.test.mjs`, which loads
+ * this file through the real loader and records `Object.keys(ctx)` from inside
+ * the host:
+ *
+ *   agent aisdk app command event experimental generate integration location
+ *   mcp model options permission plugin provider reference rpc session shell
+ *   skill storage tool vcs websearch worktree
+ *
+ *   ctx.tool.transform        function
+ *   ctx.tool.hook             function
+ *   ctx.tool.list             function
+ *   ctx.event.subscribe       function
+ *   ctx.permission.hook       function
+ *   ctx.session.hook          function
+ *   ctx.catalog               absent
+ *
+ * `HostPluginContext` below declares exactly the minimum of that, and
+ * `hostDomains` is the SINGLE documented cast that reaches them — replacing the
+ * six repeated `as unknown as Record<string, unknown>` casts this file carried
+ * (Phases 2, 3, 4, 5, 6 and 7 — every phase except Phase 1, which reads the
+ * SDK-typed domains directly), each of which type-checked nothing at all. The
+ * per-domain definition checks stay: `registerV2Tools` still returns `false`
+ * and marks `tool-transform` when `ctx.tool.transform` is missing, and likewise
+ * for the others. The cast is not a licence to assume: the canary above is what
+ * proves the domains exist on a real host, and it fails if they stop existing.
+ *
+ * If the SDK ever exposes these four, replacing `hostDomains` with the real
+ * type is a one-line change. Do NOT make that change while 1.18.x lacks them.
  *
  * V2_UNSUPPORTED_FEATURES distinguishes adapter limitations from observed
  * host-absent APIs; setup handles optional registrations on a best-effort basis.
@@ -71,6 +94,7 @@ import {
   type V2ContextLike,
 } from './pantheon/v2-bridge.ts'
 import { createV2ToolDefinitions, type V2ToolResult } from './pantheon/v2-tools.ts'
+import { V2_UNSUPPORTED_FEATURE_SEED } from './pantheon/v2-unsupported.mjs'
 import { type HookPayload, runHook } from './plugins/hook-runner.ts'
 
 // ─── Unsupported Features Registry ───────────────────────────────────────
@@ -80,33 +104,18 @@ import { type HookPayload, runHook } from './plugins/hook-runner.ts'
  * the observed host. A listed feature is not necessarily a host-absent API.
  * Additional features are appended during setup when a required API is missing.
  */
-export const V2_UNSUPPORTED_FEATURES: string[] = [
-  'legacy-hooks',
-  // `catalog` alone was absent in the OpenCode 2.0.18 runtime probe.
-  'catalog-transform',
-  // The host exposes callable transforms for integration and skill, but
-  // Pantheon does not register/use them and no host callback effects were
-  // observed. These entries describe adapter support, not host availability.
-  'integration-transform',
-  // The inspected SkillEditor shape has no `source()` helper for adding a
-  // directory source. This is narrower than (and distinct from) ctx.skill's
-  // host availability or callable transform.
-  'skill-transform',
-  // Adapter limitation, not a host gap: the goal loop needs a GoalStore, a
-  // GoalLoopClient and a BackgroundJobBoard, none of which the V2
-  // PluginContext exposes, and the V1 bridge resolves to null outside V1.
-  // 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: the caller/target delegation matrix
-  // needs a session hierarchy seeded from session metadata, and V2 exposes no
-  // seed path for it — SessionHierarchyRegistry.isRoot reports `true` for
-  // unknown sessions while unseeded, which would deny every `task()` call. The
-  // branch is therefore skipped rather than left to deny indiscriminately.
-  // Read-only depth-2 still holds via the blocked-tool list in the guard below,
-  // so this marker records an unenforced matrix, not an unenforced depth limit.
-  'delegation-matrix',
-]
+/**
+ * Live unsupported-feature list: the shared seed plus anything `markUnsupported`
+ * appends while this process talks to a real host.
+ *
+ * The seed lives in `src/pantheon/v2-unsupported.mjs` — a plain-`.mjs` module —
+ * so that the V2 installer and `scripts/doctor.mjs` report the SAME strings
+ * without either of them having to import TypeScript. This array stays a
+ * mutable copy rather than the shared seed itself: `markUnsupported` appends to
+ * it, and the seed must stay frozen. `getUnsupportedFeatures()` still returns
+ * this exact reference.
+ */
+export const V2_UNSUPPORTED_FEATURES: string[] = [...V2_UNSUPPORTED_FEATURE_SEED]
 
 // ─── Constants ───────────────────────────────────────────────────────────
 
@@ -189,6 +198,68 @@ function markUnsupported(feature: string): void {
   }
 }
 
+// ─── Host context domains the SDK types do not carry ────────────────────
+
+/**
+ * The minimal shape of `ctx.tool` this module uses, as a live opencode 2.0.22
+ * host provides it. `transform` registers the Pantheon tools, `hook` installs
+ * the `execute.before`/`execute.after` guards, `list` is the host-built
+ * descriptor dump the canary asserts on.
+ */
+interface V2ToolDomain {
+  transform?: (cb: (draft: V2ToolDraft) => void) => Promise<unknown>
+  hook?: (name: string, handler: (event: unknown) => void | Promise<void>) => Promise<unknown>
+  list?: () => Promise<unknown>
+}
+
+/** The minimal shape of `ctx.event`: one async-iterable subscription. */
+interface V2EventDomain {
+  subscribe?: (opts?: { signal?: AbortSignal }) => AsyncIterable<V2SessionEvent>
+}
+
+/**
+ * The minimal shape of `ctx.permission`.
+ *
+ * Only a hook name and a handler: the plugin registers `evaluate` as a
+ * registration point and deliberately runs no V2-side permission logic, so no
+ * richer payload type is claimed here.
+ */
+interface V2PermissionDomain {
+  hook?: (name: string, handler: (event: unknown) => void | Promise<void>) => Promise<unknown>
+}
+
+/**
+ * The minimal shape of `ctx.session`.
+ *
+ * Only `hook(name, handler)`. The host accepts any string and silently drops an
+ * unknown one — which is why the hook names below were a live defect once and
+ * why the host-backed hook canary exists.
+ */
+interface V2SessionDomain {
+  hook?: (name: string, handler: (event: unknown) => void | Promise<void>) => Promise<unknown>
+}
+
+/** `PluginContext` plus the four domains 1.18.x omits. See the module header. */
+interface HostPluginContext extends PluginContext {
+  tool?: V2ToolDomain
+  event?: V2EventDomain
+  permission?: V2PermissionDomain
+  session?: V2SessionDomain
+}
+
+/**
+ * THE cast to the host's context. Every optional member stays optional and every
+ * caller re-checks before use, so this narrows nothing away: it replaces five
+ * anonymous `Record<string, unknown>` casts with one named, documented,
+ * type-checked boundary.
+ *
+ * When the SDK ships these four domains, delete this function and use
+ * `PluginContext` directly.
+ */
+function hostDomains(context: PluginContext): HostPluginContext {
+  return context as HostPluginContext
+}
+
 // ─── V1 Bridge Integration ──────────────────────────────────────────────
 
 /**
@@ -334,9 +405,7 @@ function transformReferences(draft: ReferenceDraft): void {
  * Returns true if tools were registered, false if the API is unavailable.
  */
 async function registerV2Tools(context: PluginContext): Promise<boolean> {
-  const toolCtx = (context as unknown as Record<string, unknown>).tool as
-    | { transform?: (cb: (draft: V2ToolDraft) => void) => Promise<unknown> }
-    | undefined
+  const toolCtx = hostDomains(context).tool
 
   if (!toolCtx?.transform) {
     return false
@@ -387,9 +456,7 @@ async function registerV2Tools(context: PluginContext): Promise<boolean> {
  * Returns a cleanup function, or undefined if the API is unavailable.
  */
 function subscribeV2Events(context: PluginContext): (() => void) | undefined {
-  const eventCtx = (context as unknown as Record<string, unknown>).event as
-    | { subscribe?: (opts?: { signal?: AbortSignal }) => AsyncIterable<V2SessionEvent> }
-    | undefined
+  const eventCtx = hostDomains(context).event
 
   if (!eventCtx?.subscribe) {
     return undefined
@@ -423,6 +490,9 @@ async function handleV2SessionEvent(event: V2SessionEvent): Promise<void> {
     case 'session.idle':
       await onSessionIdle(event)
       break
+    case 'session.deleted':
+      await onSessionDeleted(event)
+      break
     case 'session.error':
       await onSessionError(event)
       break
@@ -437,18 +507,44 @@ async function handleV2SessionEvent(event: V2SessionEvent): Promise<void> {
 /**
  * Session-created handler: currently a no-op on the V2-only surface.
  *
- * V1 seeds session state here (`sessionHierarchy.register(info)` plus the
- * root-session set) from the full session metadata carried by its own event.
- * The V2 event does not carry that metadata, and — more to the point — V1 is a
- * separate plugin instance that is not loaded when only `plugin-v2` is
- * configured. So nothing runs here on a V2-only install. Do not read the bridge
- * check below as coverage: a non-null bridge means a host process that ALSO
- * loaded V1, and V1 does the seeding itself.
+ * V1 seeds session state here — `sessionHierarchy.register(info)` plus the
+ * root-session set — from the full session metadata carried by its own event.
+ *
+ * THE V2 EVENT CARRIES THE SAME METADATA, so this is an UNWIRED seed, not an
+ * impossible one. The V2 SDK types `session.created` as
+ * `{ sessionID: string; info: Session }`, and `Session` declares
+ * `parentID?: string` (`@opencode-ai/sdk` v2 `gen/types.gen.d.ts`) — a superset
+ * of the two fields V1 reads on this exact event. Seeding here would be a copy
+ * of V1's line. An earlier revision of this comment claimed the metadata was
+ * absent from the V2 event; the SDK types refute that, so do not restore it.
  *
- * The absent hierarchy seed is why the V2 enforcement guard is built without
- * `isRootSession` / `isChildSession`; see `docs/UPGRADING.md`, "Known
- * limitation — V2 enforcement covers the blocked-tool list, not the V1
- * delegation matrix".
+ * WHAT IS NOT MEASURED, in either direction: whether a live 2.0.22 host
+ * populates `info.parentID` on this event. The tool canary records
+ * `Object.keys(ctx)` from inside the host, not event payloads, so host
+ * population is UNVERIFIED. What is proven is only that the type carries the
+ * field and that no code path here reads it.
+ *
+ * The real asymmetry is the OTHER of V1's two seed sources. Besides this event,
+ * V1 runs a fail-open startup seed from `client.session.list()`
+ * (`seedRootSessionsInBackground`, `src/plugin.ts`) to cover sessions that
+ * predate plugin load, because opencode does not replay `session.created` for
+ * them. V2's `PluginContext` exposes no `client` at all — `options`, `agent`,
+ * `aisdk`, `catalog`, `command`, `integration`, `plugin`, `reference`, `skill`,
+ * and nothing else — so that enumeration has NO V2 EQUIVALENT. Wiring this
+ * handler would recover live sessions only, never resumed ones.
+ *
+ * And — more to the point — V1 is a separate plugin instance that is not loaded
+ * when only `plugin-v2` is configured, so on a V2-only install nothing seeds
+ * the hierarchy at all. Do not read the bridge check below as coverage: a
+ * non-null bridge means a host process that ALSO loaded V1, and V1 does the
+ * seeding itself.
+ *
+ * The unwired hierarchy seed is ONE of the two reasons the V2 enforcement guard
+ * is built without `isRootSession` / `isChildSession`; the other — and the one
+ * that would actually deny every `task()` call — is the absent
+ * `getSessionAgent`. See the `v2EnforcementGuard` comment below for both, and
+ * `docs/UPGRADING.md`, "Known limitation — V2 enforcement covers the
+ * blocked-tool list, not the V1 delegation matrix".
  */
 async function onSessionCreated(_event: V2SessionEvent): Promise<void> {
   const _bridge = resolveBridge()
@@ -475,6 +571,58 @@ async function onSessionIdle(_event: V2SessionEvent): Promise<void> {
   }
 }
 
+/**
+ * Session-deleted handler: drop the read-only registration.
+ *
+ * `readOnlyRegistry` is a process-wide singleton and the `execute.before` hook
+ * populates it on every delegated `apollo`/`gaia` call. V1 prunes it on
+ * `session.deleted` (`src/plugin.ts`); V2 did not, so on a long-lived host
+ * every finished investigation session stayed registered for the life of the
+ * process — a slow leak, and a stale entry that would keep denying tools if
+ * the id were ever reused.
+ *
+ * This mirrors V1: unregister the session, which drops its agent entry with it
+ * (the registry stores one `ReadOnlyEntry` per session id). V1 also clears a
+ * `sessionAgents` map here; V2 has no such map and needs no equivalent, since
+ * it reads the active agent off the event instead of caching it.
+ *
+ * The id is read from `properties.sessionID` — the field the sibling
+ * `session.idle` handler already uses — falling back to V1's
+ * `properties.info.id`. Both spellings are accepted because the V2 SDK types
+ * `session.deleted` as `{ sessionID, info }` and a miss here is a silent leak,
+ * which is precisely the bug this handler exists to close.
+ *
+ * A payload with NEITHER spelling is fail-open, and unavoidably so: unregistering
+ * is what needs the id, so an id that cannot be resolved cannot be cleaned up
+ * and the entry survives. The docstring used to leave that as a documented
+ * silent branch; it now warns on the way out, because the only other symptom of
+ * a renamed field is a registry that grows for the life of the process.
+ */
+async function onSessionDeleted(event: V2SessionEvent): Promise<void> {
+  const properties = event.properties
+  if (properties === undefined) return
+  const info = properties.info
+  const sessionID =
+    typeof properties.sessionID === 'string'
+      ? properties.sessionID
+      : info !== null && typeof info === 'object'
+        ? (info as { id?: unknown }).id
+        : undefined
+  if (typeof sessionID !== 'string' || sessionID === '') {
+    // Fail-open by necessity, loud by choice: the entry for this session (if
+    // any) cannot be identified, so it stays registered. Same `console.warn`
+    // channel as the event-subscription error above — this module has no
+    // logger, and a diagnostic nobody reads on stderr is still a silent leak.
+    console.warn(
+      '[Pantheon V2] session.deleted carried no session id ' +
+        '(neither properties.sessionID nor properties.info.id); ' +
+        'its read-only registration cannot be pruned and will persist.',
+    )
+    return
+  }
+  readOnlyRegistry.unregister(sessionID)
+}
+
 /**
  * Session-error handler: no V2-side implementation.
  *
@@ -505,11 +653,7 @@ async function onSessionCompacted(_event: V2SessionEvent): Promise<void> {}
  * Returns true if any hooks were registered.
  */
 async function registerV2SessionHooks(context: PluginContext): Promise<boolean> {
-  const sessionCtx = (context as unknown as Record<string, unknown>).session as
-    | {
-        hook?: (name: string, handler: (event: unknown) => void | Promise<void>) => Promise<unknown>
-      }
-    | undefined
+  const sessionCtx = hostDomains(context).session
 
   if (!sessionCtx?.hook) {
     return false
@@ -600,16 +744,21 @@ function maskSecret(text: string): string {
 /**
  * Message thrown when scan-secrets.sh exits 2 (a high-confidence token match).
  *
- * This is the only deliberate throw on the V2 surface, and it mirrors the V1
- * message (src/plugins/pantheon-hooks.ts `SECRET_BLOCK_MESSAGE`). opencode's
+ * This is the only deliberate throw on the V2 surface. opencode's
  * Plugin.trigger has no catch around hook invocations, so the rejection
  * propagates and fails the tool's execute promise BEFORE the tool body runs —
- * the same hard block V1 had, which was inert on a V2-only install because
+ * the same hard block V1 has (src/plugins/pantheon-hooks.ts
+ * `SECRET_BLOCK_MESSAGE`), which was inert on a V2-only install because
  * pantheon-hooks.ts is never loaded there (opencode.json `plugins` declares only
  * `src/plugin-v2`).
+ *
+ * English, like every other message this module emits: this string surfaces in
+ * the user's session as the tool error, so it is read by whoever hit the block,
+ * not by the code that raised it. A Portuguese release note elsewhere in the
+ * repo is not a reason for the runtime message to be Portuguese too.
  */
 const SECRET_BLOCK_MESSAGE =
-  '[plugin-v2] Bloqueado: segredo de alta confiança detectado no tool input — consulte .pantheon/logs/hooks.log'
+  '[plugin-v2] Blocked: high-confidence secret detected in tool input — see .pantheon/logs/hooks.log'
 
 /**
  * Append one masked, ISO-stamped line to .pantheon/logs/hooks.log under the
@@ -682,15 +831,41 @@ interface V2ToolExecuteBeforeEvent {
  * tool — `hashline_edit` and `pantheon_model` are denied here for exactly the
  * reason they are denied in V1.
  *
- * Deliberately NOT passed `getSessionAgent` / `isRootSession` / `isChildSession`:
- * those drive V1's native-`task()` delegation matrix, which needs a session
- * hierarchy seeded from session metadata. `SessionHierarchyRegistry.isRoot`
- * reports `true` for unknown sessions while unseeded, so passing an unseeded
- * predicate here would DENY every `task()` call in every session. Leaving them
- * out skips that branch (the guard tests `options?.isRootSession !== undefined`).
- * `task` is still denied inside a read-only session via the blocked-tool list,
- * so depth-2 holds for apollo/gaia; the caller/target matrix itself is NOT
- * enforced on V2. That is a known gap, not a covered case.
+ * Deliberately NOT passed `getSessionAgent` / `isRootSession` / `isChildSession`.
+ * There are TWO distinct reasons, and conflating them is what produced a wrong
+ * causal chain here once already — keep them apart:
+ *
+ * 1. MISSING `getSessionAgent` (wiring). This is what would deny every
+ *    `task()` call. V2 learns the active agent from the `execute.before` event
+ *    itself and keeps no session→agent map, so there is no lookup to hand the
+ *    guard. The guard would call `isDelegationAllowed(undefined, target)`,
+ *    which returns `false`, and throw "caller agent is unavailable" — for
+ *    every caller, including Zeus. Note what is NOT happening: an unseeded
+ *    `isRootSession` would *pass* the root gate (`isRoot` reports `true` for an
+ *    unknown session), so the hierarchy is not what denies here.
+ *
+ * 2. UNWIRED HIERARCHY (design). `SessionHierarchyRegistry` is what gates
+ *    exactly two things, and nothing else: the depth-2 child deny
+ *    (`isChildSession`) and the root-session gate (`isRootSession`). Left
+ *    unseeded, `isChild` is `false` for every session, so depth-2 would never
+ *    fire on a genuine child — a hierarchy that cannot tell a child from a root
+ *    is not a trustworthy input to either check.
+ *
+ *    "Unwired", not "impossible": the V2 `session.created` event carries
+ *    `properties.info: Session` including `parentID?`, the same field V1 seeds
+ *    from on the same event, so one line in `onSessionCreated` would seed live
+ *    sessions (see its docstring). What has no V2 equivalent is V1's SECOND
+ *    source, the `client.session.list()` startup seed — V2's `PluginContext`
+ *    exposes no `client`. Whether a live 2.0.22 host populates `info.parentID`
+ *    is UNVERIFIED; no canary reads an event payload. So the correct summary is
+ *    "seeded for nothing", not "unseedable", and the guard's omission is right
+ *    today for the weaker reason that nothing seeds it at all.
+ *
+ * Omitting all three skips the branch wholesale: the guard only enters it when
+ * `options?.isRootSession !== undefined`. `task` is still denied inside a
+ * read-only session via the blocked-tool list, so depth-2 holds for
+ * apollo/gaia; the caller/target matrix itself is NOT enforced on V2. That is
+ * a known gap, not a covered case.
  */
 const v2EnforcementGuard = createEnforcementGuard({
   getReadOnlySessions: () => readOnlyRegistry.sessionIDs(),
@@ -740,11 +915,7 @@ function adaptV2ExecuteBeforeEvent(event: unknown): {
  * Returns true if any hooks were registered.
  */
 async function registerV2ToolHooks(context: PluginContext): Promise<boolean> {
-  const toolCtx = (context as unknown as Record<string, unknown>).tool as
-    | {
-        hook?: (name: string, handler: (event: unknown) => void | Promise<void>) => Promise<unknown>
-      }
-    | undefined
+  const toolCtx = hostDomains(context).tool
 
   if (!toolCtx?.hook) {
     return false
@@ -842,11 +1013,7 @@ async function registerV2ToolHooks(context: PluginContext): Promise<boolean> {
  * Returns true if the hook was registered.
  */
 async function registerV2PermissionHook(context: PluginContext): Promise<boolean> {
-  const permCtx = (context as unknown as Record<string, unknown>).permission as
-    | {
-        hook?: (name: string, handler: (event: unknown) => void | Promise<void>) => Promise<unknown>
-      }
-    | undefined
+  const permCtx = hostDomains(context).permission
 
   if (!permCtx?.hook) {
     markUnsupported('permission-hook')
@@ -920,10 +1087,12 @@ export const plugin = define({
     //
     // Pantheon's Phase 1/config transform registrations cover agent, command,
     // and reference; ctx.tool.transform is attempted separately in Phase 2.
-    // The 2.0.18 runtime probe found ctx.integration and ctx.skill with
-    // callable transforms, but no callback effects were observed; neither is
-    // registered here. Only ctx.catalog was absent in that probe.
-    // The hook canary tests hook firing only, not transform callback effects.
+    // ctx.integration and ctx.skill are present on a live 2.0.22 host and neither
+    // is registered here — that is a Pantheon scope choice, not a host gap.
+    // ctx.catalog is the one domain the host does not provide.
+    // Phase 1 registers against the SDK-typed `context.agent` / `.command` /
+    // `.reference` directly; the four domains the SDK omits are reached only
+    // through `hostDomains` (see the module header).
     const phase1Transforms: Array<{ feature: string; register: () => Promise<unknown> }> = [
       { feature: 'agent-transform', register: () => context.agent.transform(transformAgents) },
       {
@@ -976,14 +1145,7 @@ export const plugin = define({
     await registerV2PermissionHook(context).catch(() => false)
 
     // ─── Phase 7: V2 Compaction Hook (best-effort) ───────────────────
-    const compactionCtx = (context as unknown as Record<string, unknown>).session as
-      | {
-          hook?: (
-            name: string,
-            handler: (event: unknown) => void | Promise<void>,
-          ) => Promise<unknown>
-        }
-      | undefined
+    const compactionCtx = hostDomains(context).session
     if (compactionCtx?.hook) {
       try {
         // 2.0.16 `SessionHooks` key is `compaction` (the migration doc maps
@@ -1042,7 +1204,14 @@ export function v2Dispose(): void {
 }
 
 /**
- * Get the current list of unsupported V2 features (for diagnostics).
+ * The current list of unsupported V2 features.
+ *
+ * Read by the installer and by `doctor` (both via the shared seed in
+ * `src/pantheon/v2-unsupported.mjs`) so the markers a user is shown are the
+ * same ones this returns, rather than a hand-copied duplicate.
+ *
+ * This returns the LIVE array: the shared seed plus whatever `markUnsupported`
+ * appended while this process talked to a real host.
  */
 export function getUnsupportedFeatures(): readonly string[] {
   return V2_UNSUPPORTED_FEATURES

package/src/plugins/tui/dist/server.d.ts

@@ -11,7 +11,6 @@
  * This stub satisfies the loader contract; pantheon-tui is TUI-only and has
  * no background server work of its own.
  */
-declare function server(): {};
+export default function server(): {};
 //#endregion
-export { server as default };
 //# sourceMappingURL=server.d.ts.map

package/src/plugins/tui/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","names":[],"sources":["../src/server.ts"],"mappings":";;;;;;;;;;;;;iBAYwB"}
+{"version":3,"file":"server.d.ts","names":[],"sources":["../src/server.ts"],"mappings":";;;;;;;;;;;;;wBAYwB"}