pantheon-opencode 1.6.0-beta.1 → 1.6.0-beta.11

package/src/plugin-v2.ts

@@ -2,26 +2,70 @@
  * Pantheon V2 Plugin — full orchestration plugin for OpenCode V2.
  *
  * Registers:
- * - 6 orchestration tools via V2 tool.transform (with V1 bridge fallback)
- * - 4 event subscriptions (session.created, idle, error, compacted)
- * - Session hooks (prompt, context, compaction) and tool hooks (execute.before/after)
- * - Permission hooks for custom authorization
- *
- * 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
- *
- * 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.
+ * - 3 self-sufficient tools via V2 tool.transform (hashline_edit,
+ *   pantheon_cost, pantheon_model) plus native `vision_describe` when the host
+ *   exposes the V2 model catalog; Vision resolves OpenCode Zen auth and sends
+ *   images directly to the selected multimodal model.
+ *   The goal tools need V1 infrastructure and are absent from this surface.
+ * - 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
+ *   session, and the shared `createEnforcementGuard` throws to deny
+ *   `hashline_edit` / `pantheon_model` / `edit` / `write` / `bash` / `task`.
+ *   See `registerV2ToolHooks`.
+ * - The SAME `execute.before` hook runs scripts/hooks/scan-secrets.sh over the
+ *   tool input and throws on exit 2 (high-confidence token match). This is the
+ *   ONLY hard security block on the V2 surface. It is wired HERE, not delegated
+ *   to `src/plugins/pantheon-hooks.ts`: opencode.json declares only
+ *   `src/plugin-v2` in `plugins`, so the V1 plugin never loads on a V2-only
+ *   install and V1's identical block was inert by construction.
+
+ * - A tool `execute.after` hook and a permission hook, with permission
+ *   evaluation enforcing the caller/target matrix for Pantheon agents
+ *
+ * Every tool registered through `draft.add` MUST declare `output`, and its
+ * `execute` MUST resolve to a value carrying `output`. The host enforces the
+ * two as a pair — see `V2ToolDraft` for the exact contract.
+ *
+ * ## The host domains the SDK types do not carry
+ *
+ * `@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 these domains, 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 host domains, 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.
@@ -29,7 +73,9 @@
  * @module plugin-v2
  */
 
-import { appendFileSync } from 'node:fs'
+import { appendFileSync, mkdirSync } from 'node:fs'
+import { realpath as realpathAsync } from 'node:fs/promises'
+import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import type {
   AgentDraft,
@@ -38,11 +84,37 @@ import type {
   ReferenceDraft,
 } from '@opencode-ai/plugin/v2/promise'
 import { define } from '@opencode-ai/plugin/v2/promise'
+import {
+  createEnforcementGuard,
+  readOnlyRegistry,
+  syncReadOnlySession,
+  type ToolExecuteBeforeInput,
+  type ToolExecuteBeforeOutput,
+} from './pantheon/delegation-enforce.ts'
+import {
+  BOUNDED_READ_TOOL,
+  createV2BoundedReadTool,
+  type V2BoundedReadOriginRegistry,
+} from './pantheon/v2-bounded-read.ts'
 import {
   getV2BridgeFromContext,
   type PantheonV2Bridge,
   type V2ContextLike,
 } from './pantheon/v2-bridge.ts'
+import {
+  type AuthoritativeSession,
+  evaluateV2Delegation,
+  PANTHEON_AGENTS,
+  type V2PermissionEvent,
+  V2SubagentOriginRegistry,
+  v2ResourceTarget,
+} from './pantheon/v2-delegation-enforce.ts'
+import { createV2ExecuteAfter, resolveV2SandboxConfig } from './pantheon/v2-execute-after.ts'
+import { applyV2ModelOverrides, readV2ModelConfiguration } from './pantheon/v2-model-overrides.ts'
+import { createV2ToolDefinitions, type V2ToolResult } from './pantheon/v2-tools.ts'
+import { V2_UNSUPPORTED_FEATURE_SEED } from './pantheon/v2-unsupported.mjs'
+import { buildV2VisionPromptContext, type V2VisionRuntime } from './pantheon/v2-vision.ts'
+import { type HookPayload, type HookResult, runHook } from './plugins/hook-runner.ts'
 
 // ─── Unsupported Features Registry ───────────────────────────────────────
 
@@ -51,19 +123,18 @@ import {
  * 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',
-]
+/**
+ * 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 ───────────────────────────────────────────────────────────
 
@@ -146,6 +217,88 @@ 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`.
+ *
+ * The V2.0.25 live contract supplies an `evaluate` event with `resources`;
+ * runtime validation remains defensive because SDK declarations omit this
+ * domain and the host may evolve independently.
+ */
+interface V2PermissionDomain {
+  assert?: (input: Record<string, unknown>) => Promise<unknown>
+  hook?: (
+    name: string,
+    handler: (event: unknown, output?: unknown) => void | Promise<void>,
+  ) => Promise<unknown>
+}
+
+/**
+ * The minimal shape of `ctx.session` used by this module. `get` follows the V2
+ * Promise API's object input (`{ sessionID }`); session hooks accept any string
+ * and silently drop an unknown one, which is why the host-backed hook canary
+ * exists.
+ */
+interface V2SessionDomain {
+  hook?: (name: string, handler: (event: unknown) => void | Promise<void>) => Promise<unknown>
+  get?: (input: { sessionID: string }) => Promise<unknown>
+}
+
+interface V2LocationDomain {
+  directory?: string
+  project?: { id?: string }
+}
+
+interface V2ModelDomain {
+  list?: V2VisionRuntime['model']['list']
+}
+
+interface V2GenerateDomain {
+  text?: (input: { model: { providerID: string; id: string }; prompt: string }) => Promise<unknown>
+}
+
+/** `PluginContext` plus the host domains 1.18.x omits. See the module header. */
+interface HostPluginContext extends PluginContext {
+  tool?: V2ToolDomain
+  event?: V2EventDomain
+  permission?: V2PermissionDomain
+  session?: V2SessionDomain
+  model?: V2ModelDomain
+  generate?: V2GenerateDomain
+  location?: V2LocationDomain
+}
+
+/**
+ * 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 ──────────────────────────────────────────────
 
 /**
@@ -199,6 +352,18 @@ function transformAgents(draft: AgentDraft): void {
     markUnsupported('agent-transform-list')
     return
   }
+  try {
+    const modelConfiguration = readV2ModelConfiguration()
+    if (modelConfiguration.warnings.length > 0) {
+      // The V2 server PluginContext has no documented user-visible notification
+      // or logging channel; preserve the degradation for status diagnostics.
+      markUnsupported('agent-model-overrides')
+    }
+    applyV2ModelOverrides(draft, modelConfiguration.overrides)
+  } catch {
+    // Model configuration is optional. Preserve host models if it cannot be read.
+    markUnsupported('agent-model-overrides')
+  }
   try {
     for (const agent of agents) {
       draft.update(agent.id, (current) => {
@@ -283,32 +448,53 @@ function transformReferences(draft: ReferenceDraft): void {
  *
  * The V2 tool.transform API (when available) provides:
  *   draft.namespace({ name: "pantheon", description: "..." })
- *   draft.add({ name, description, input, execute })
+ *   draft.add({ name, description, input, output, execute })
+ *
+ * `output` is part of the required shape, not an optional extra: see
+ * `V2ToolDraft` for the host contract that makes it mandatory.
  *
  * 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
+async function registerV2Tools(
+  context: PluginContext,
+  boundedRead?: ReturnType<typeof createV2BoundedReadTool>['definition'],
+): Promise<boolean> {
+  const host = hostDomains(context)
+  const toolCtx = host.tool
 
   if (!toolCtx?.transform) {
     return false
   }
 
   try {
-    // Tool definitions require infrastructure instances — when available via
-    // V2 context, they are passed through; otherwise the factory returns
-    // definitions with lazy execute wrappers.
-    const toolDefs = createV2ToolDefinitionsFromContext(context)
+    // Tool definitions carry their own `output` declaration; the draft requires
+    // it, and the host rejects a definition whose result shape cannot satisfy
+    // the declaration it makes.
+    const model = host.model
+    const visionReady = typeof model?.list === 'function'
+    if (!visionReady) markUnsupported('vision-tool')
+    const visionRuntime = visionReady ? ({ model } as V2VisionRuntime) : undefined
+    const toolDefs = createV2ToolDefinitions(visionRuntime)
+    if (boundedRead !== undefined) toolDefs.push(boundedRead)
 
     await toolCtx.transform((draft: V2ToolDraft) => {
+      // Catalog grouping only. The host computes a tool's registration id as
+      // `options.namespace === undefined ? name : `${namespace}_${name}``, and
+      // `draft.namespace()` does NOT set `options.namespace` on later `add`
+      // calls — so the tools stay `hashline_edit` / `pantheon_cost` /
+      // `pantheon_model`, not `pantheon_*`. That bare name is what the
+      // enforcement guard's blocked-tool list matches on; see
+      // `adaptV2ExecuteBeforeEvent`.
       draft.namespace({ name: 'pantheon', description: 'Pantheon orchestration tools' })
       for (const def of toolDefs) {
         draft.add({
           name: def.name,
           description: def.description,
           input: def.input,
+          // Required by the host contract: without this the tool fails on
+          // every call with "Tool result declared output without an output
+          // schema". Must stay paired with def.execute resolving to `output`.
+          output: def.output,
           execute: def.execute,
         })
       }
@@ -329,10 +515,11 @@ 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
+function subscribeV2Events(
+  context: PluginContext,
+  onTurnEnd?: (sessionID: string) => void,
+): (() => void) | undefined {
+  const eventCtx = hostDomains(context).event
 
   if (!eventCtx?.subscribe) {
     return undefined
@@ -344,6 +531,19 @@ function subscribeV2Events(context: PluginContext): (() => void) | undefined {
       // biome-ignore lint/style/noNonNullAssertion: subscribe guaranteed by guard above
       for await (const event of eventCtx.subscribe!({ signal: controller.signal })) {
         await handleV2SessionEvent(event)
+        if (event.type === 'session.idle' || event.type === 'session.deleted') {
+          const properties = event.properties ?? {}
+          const info = properties.info
+          const infoID =
+            info !== null && typeof info === 'object' ? (info as { id?: unknown }).id : undefined
+          const sessionID =
+            typeof properties.sessionID === 'string'
+              ? properties.sessionID
+              : typeof infoID === 'string'
+                ? infoID
+                : undefined
+          if (sessionID) onTurnEnd?.(sessionID)
+        }
       }
     } catch (err: unknown) {
       if (err instanceof Error && err.name === 'AbortError') return
@@ -366,6 +566,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
@@ -377,20 +580,68 @@ async function handleV2SessionEvent(event: V2SessionEvent): Promise<void> {
   }
 }
 
-async function onSessionCreated(_event: V2SessionEvent): Promise<void> {
-  // Seed session state — handled by V1 bridge or direct registration.
-  // The V2 event doesn't carry enough context for full hierarchy setup;
-  // bridge.board is used when available for root-session registration.
+/**
+ * Record the v2.0.29 lifecycle event in the opt-in F4A canary. Runtime events
+ * use a `{ id, created, type, data }` envelope; the child data carries
+ * `sessionID`, `parentID` and `agent`. Admission itself does not depend on this
+ * subscription: it checks the current permission source and `ctx.session.get`
+ * synchronously, so resumed roots and children use the same path.
+ */
+async function onSessionCreated(event: V2SessionEvent): Promise<void> {
+  const payload = event as V2SessionEvent & Record<string, unknown>
+  const properties = event.properties ?? {}
+  const data =
+    event.data !== null && typeof event.data === 'object'
+      ? (event.data as Record<string, unknown>)
+      : {}
+  const info = properties.info ?? data.info
+  const sessionInfo =
+    info !== null && typeof info === 'object' ? (info as Record<string, unknown>) : {}
+  writeV2AdmissionProof('session.created', {
+    eventKeys: Object.keys(payload),
+    propertyKeys: Object.keys(properties),
+    dataKeys: Object.keys(data),
+    infoKeys: Object.keys(sessionInfo),
+    id:
+      sessionInfo.id ??
+      sessionInfo.sessionID ??
+      data.id ??
+      data.sessionID ??
+      properties.id ??
+      properties.sessionID ??
+      payload.sessionID ??
+      null,
+    parentID: sessionInfo.parentID ?? data.parentID ?? properties.parentID ?? null,
+    agent: sessionInfo.agent ?? data.agent ?? properties.agent ?? null,
+  })
   const _bridge = resolveBridge()
   if (_bridge?.board != null) {
-    // Bridge available: board will register root sessions via the V1 event hook.
-    // This is a no-op here — V1 handles hierarchy setup.
+    // Bridge present ⇒ this process also loaded V1, whose own event hook owns
+    // root-session registration. Intentionally nothing to do on the V2 side.
   }
 }
 
 async function onSessionIdle(_event: V2SessionEvent): Promise<void> {
-  // Idle continuation — goal loop / todo enforcer dispatch.
-  // Bridge provides the full V1 infrastructure when available.
+  // Temp-image sweep on the V2-only path: DELIBERATELY DEFERRED.
+  //
+  // V1 unlinks a session's temp images on `session.idle`/`session.deleted`
+  // (`cleanupSessionTempImages`, grace-guarded and refcounted). V2 cannot reuse
+  // it: `saveDataUrlImageSync` (the V2 materialization path) receives no session
+  // id, so there is no per-session `path → createdAt` map to sweep, and the
+  // content-hash temp dir is refcounted ONLY on the V1 path. The one reusable
+  // piece, `enforceTempFileCap`, is already invoked off every V2 save
+  // (`saveDataUrlImageSync`), so disk usage is bounded without an idle pass —
+  // re-running it here would be redundant, and a GLOBAL age-based unlink fired
+  // by one session's idle could delete a file another live session still
+  // references. Delivery is also best-effort: with no `ctx.event.subscribe`
+  // the stream is unsupported (`markUnsupported('event-stream')`) and no idle
+  // ever arrives. Implementing this safely needs V2-side session threading
+  // first; until then it stays deferred rather than approximated.
+  //
+  // Idle continuation — goal loop / todo enforcer dispatch. This one really
+  // does delegate: `bridge.todoEnforcer` is the V1 enforcer instance, reached
+  // only in a process that also loaded V1. On a V2-only install the bridge
+  // resolves to null and idle continuation does not run.
   const sessionID = _event.properties?.sessionID as string | undefined
   if (!sessionID) return
   const bridge = resolveBridge()
@@ -403,23 +654,75 @@ async function onSessionIdle(_event: V2SessionEvent): Promise<void> {
   }
 }
 
-async function onSessionError(_event: V2SessionEvent): Promise<void> {
-  // Error handling — board transition to error.
-  const bridge = resolveBridge()
-  if (bridge?.board != null) {
-    // Bridge available: error handling is done by the V1 event hook.
-    // V2 only logs — V1 owns the board transition.
+/**
+ * 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)
 }
 
-async function onSessionCompacted(_event: V2SessionEvent): Promise<void> {
-  // Compaction restore — todo preserve / context rebuild.
-  const bridge = resolveBridge()
-  if (bridge?.todoEnforcer != null) {
-    // Bridge available: todo preservation is done by V1 compaction hook.
-    // V2 only logs — V1 handles full compaction context build.
-  }
-}
+/**
+ * Session-error handler: no V2-side implementation.
+ *
+ * The board error transition lives in V1's event hook, which is not loaded on
+ * a V2-only install. There is nothing to do here — deliberately, rather than
+ * describing behaviour this handler does not have.
+ */
+async function onSessionError(_event: V2SessionEvent): Promise<void> {}
+
+/**
+ * Session-compacted handler: no V2-side implementation.
+ *
+ * Todo preservation and compaction context build live in the V1 path
+ * (`todo-preserve.ts`, driven by V1's compaction hook), which is not loaded on
+ * a V2-only install.
+ */
+async function onSessionCompacted(_event: V2SessionEvent): Promise<void> {}
 
 // ─── V2 Session Hooks ───────────────────────────────────────────────────
 
@@ -433,11 +736,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
@@ -485,10 +784,31 @@ async function registerV2SessionHooks(context: PluginContext): Promise<boolean>
   }
 
   try {
-    // "prompt" hook — vision message interception
-    await sessionCtx.hook('prompt', (_event: unknown) => {
-      // Vision interception delegates to the V1 vision handler.
-      // Without V1 client access, this is a graceful no-op.
+    // "prompt" hook — preserve attached image references and add model-visible
+    // instructions so Zeus can inspect visual context and pass it to the
+    // implementation specialist before editing.
+    await sessionCtx.hook('prompt', (event: unknown) => {
+      try {
+        // 2.0.29 host payload: `{ sessionID, messageID, prompt: { text,
+        // files, agents, skills }, metadata, delivery }`. The session id is
+        // top-level (verified against the host's `SessionPrompt.prepare`), so a
+        // data: attachment's panic-free moment also relays it to the MCP.
+        const admission = event as {
+          sessionID?: unknown
+          prompt?: { text?: unknown; files?: unknown }
+        } | null
+        const prompt = admission?.prompt
+        if (!prompt || typeof prompt.text !== 'string') return
+        if (prompt.text.includes('<!-- pantheon-v2-visual-context -->')) return
+        const sessionID =
+          typeof admission?.sessionID === 'string' && admission.sessionID.trim() !== ''
+            ? admission.sessionID
+            : undefined
+        const visualContext = buildV2VisionPromptContext(prompt.files, prompt.text, sessionID)
+        if (visualContext) prompt.text = `${prompt.text}\n\n${visualContext}`
+      } catch {
+        // Fail-open: malformed/unsupported prompt shapes must not block input.
+      }
     })
     registered = true
   } catch {
@@ -498,8 +818,395 @@ async function registerV2SessionHooks(context: PluginContext): Promise<boolean>
   return registered
 }
 
+// ─── V2 Secret Scan ─────────────────────────────────────────────────────
+
+/**
+ * High-confidence secret token formats — MIRRORS `SECRET_MASK_RE` in
+ * src/plugins/pantheon-hooks.ts (V1) and `HIGH_CONFIDENCE_PATTERNS` in
+ * scripts/hooks/scan-secrets.sh.
+ *
+ * Duplicated rather than imported because the V1 module is a separate plugin
+ * that is NOT loaded on a V2-only install (see the module header), and pulling
+ * it in for one regex would resurrect exactly the V1-hook coupling V2 exists to
+ * remove. The drift risk is real and is asserted by a test in
+ * tests/pantheon/plugin-v2-contract.test.ts.
+ *
+ * Applied to every log line this module writes, so a hook trail can never
+ * contain a raw credential. Header/KEY names (the Bifrost header alone,
+ * `api_key=...`) are deliberately NOT matched: they are not secret values.
+ */
+const SECRET_MASK_RE =
+  /(sk-bf-[A-Za-z0-9_-]{8,}|AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9_]{36,}|glpat-[A-Za-z0-9_-]{20}|sk-[a-zA-Z0-9]{20,}|sk_live_[a-zA-Z0-9]{20,}|sk_test_[a-zA-Z0-9]{20,}|xox[baprs]-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24}|bearer\s+[a-zA-Z0-9_.-]{20,}|eyJ[A-Za-z0-9_-]*\.eyJ[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*)/gi
+
+/** Replace every high-confidence secret match with '****'. */
+function maskSecret(text: string): string {
+  return text.replace(SECRET_MASK_RE, '****')
+}
+
+/**
+ * Message thrown when scan-secrets.sh exits 2 (a high-confidence token match).
+ *
+ * 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 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] Blocked: high-confidence secret detected in tool input — see .pantheon/logs/hooks.log'
+
+/**
+ * Message thrown when the secret scanner cannot produce a trustworthy verdict —
+ * the script is missing/unexecutable, the child timed out or was killed, the
+ * payload could not be serialized, the report was malformed, or the exit status
+ * was unexpected.
+ *
+ * This is a deliberate fail-CLOSED denial. The previous handler blocked only
+ * `code === 2` and treated every other outcome as advisory — but the runner
+ * reports a missing script, a spawn failure and a payload-serialization failure
+ * as `code: 1` too (src/plugins/hook-runner.ts), so a broken scanner read as a
+ * clean advisory and the tool ran, silently disabling the only hard secret block
+ * on the V2 surface.
+ *
+ * English and user-facing, like {@link SECRET_BLOCK_MESSAGE}. It carries no
+ * scanner output on purpose: a scan that failed mid-flight may still be holding
+ * the raw payload, and the denial must not become the leak it exists to prevent.
+ */
+const SECRET_SCAN_UNAVAILABLE_MESSAGE =
+  '[plugin-v2] Blocked: the secret scanner could not complete, so this tool call was denied (fail-closed) — see .pantheon/logs/hooks.log'
+
+/**
+ * Append one masked, ISO-stamped line to .pantheon/logs/hooks.log under the
+ * working directory, and return whether it landed.
+ *
+ * V1's `reportFailure` also writes to `client.app.log` and shows a TUI toast.
+ * The V2 `PluginContext` exposes NEITHER (it is
+ * `{options, agent, aisdk, catalog, command, integration, plugin, reference,
+ * skill}` — no `client`, no `directory`), so this module has only the file
+ * channel. That is a real reduction in observability versus V1, stated here
+ * rather than implied. Best-effort by contract: a logging failure must never
+ * take down the session.
+ */
+function appendV2HookLog(line: string): boolean {
+  const masked = maskSecret(line)
+  if (masked === '') return false
+  const stamp = new Date().toISOString()
+  // Multi-line scanner stderr would otherwise produce continuation lines with
+  // no timestamp (V1's P0-5 fix) — one message becomes N timestamped lines.
+  const body = masked
+    .split('\n')
+    .map((part) => part.trim())
+    .filter((part) => part !== '')
+    .map((part) => `[${stamp}] ${part}`)
+    .join('\n')
+  if (body === '') return false
+  try {
+    const dir = path.join(process.cwd(), '.pantheon', 'logs')
+    mkdirSync(dir, { recursive: true })
+    appendFileSync(path.join(dir, 'hooks.log'), `${body}\n`, 'utf8')
+    return true
+  } catch {
+    return false
+  }
+}
+
+// ─── BENCH Hook Timing (beta-10 latency slice, Phase 0) ────────────────
+
+/**
+ * BENCH INSTRUMENTATION — observation only, zero behavior change.
+ *
+ * The beta-10 latency slice measures the V2 tool hook chain. These helpers
+ * record the start/end of `execute.before` and `execute.after` per tool call
+ * and append one single-line `[bench]` entry per hook end to the EXISTING
+ * hooks.log channel (same appendV2HookLog path as every other line: masked,
+ * stamped, best-effort, never throwing). The lines are consumed by
+ * bench/lib/hooklog.mjs.
+ *
+ * Deliberate properties:
+ *   - the log call happens in `finally`, so denied calls (read-only guard,
+ *     secret block) are timed too, and the denial still propagates unchanged
+ *   - the join key is the host callID (`event.id`); a TTL-bounded map prunes
+ *     stale entries so a background/never-after call cannot leak memory
+ *   - `since_before_ms=unavailable` when no before record exists — the bench
+ *     contract never lets "unavailable" be encoded as 0
+ */
+
+/** Entries older than this are pruned (a task tool result may never fire after). */
+const BENCH_TIMING_TTL_MS = 5 * 60_000
+/** Hard cap — mirrors the V1 delegationStarts bound. */
+const BENCH_TIMING_MAX = 256
+
+const benchTimings = new Map<string, number>()
+
+function pruneBenchTimings(now: number): void {
+  for (const [callID, startedAt] of benchTimings) {
+    if (now - startedAt > BENCH_TIMING_TTL_MS) benchTimings.delete(callID)
+  }
+  while (benchTimings.size >= BENCH_TIMING_MAX) {
+    let oldestID: string | null = null
+    let oldestAt = Number.POSITIVE_INFINITY
+    for (const [id, at] of benchTimings) {
+      if (at < oldestAt) {
+        oldestAt = at
+        oldestID = id
+      }
+    }
+    if (oldestID === null) break
+    benchTimings.delete(oldestID)
+  }
+}
+
+/** Read `{tool, id}` off a V2 tool event without assuming its exact shape. */
+function benchEventIdentity(event: unknown): { tool: string; callID: string } {
+  if (event === null || typeof event !== 'object') return { tool: '', callID: '' }
+  const payload = event as { tool?: unknown; id?: unknown }
+  return {
+    tool: typeof payload.tool === 'string' ? payload.tool : '',
+    callID: typeof payload.id === 'string' ? payload.id : '',
+  }
+}
+
+/**
+ * Append one `[bench]` timing line for a finished hook phase. Best-effort and
+ * exception-free by construction (appendV2HookLog never throws).
+ */
+function logBenchHookTiming(phase: 'before' | 'after', event: unknown, startedAt: number): void {
+  try {
+    const { tool, callID } = benchEventIdentity(event)
+    const endedAt = Date.now()
+    if (phase === 'before') {
+      if (callID !== '') {
+        benchTimings.set(callID, startedAt)
+        pruneBenchTimings(startedAt)
+      }
+      appendV2HookLog(
+        `[bench] tool.execute.before end tool=${tool} callID=${callID} ` +
+          `started_at=${new Date(startedAt).toISOString()} duration_ms=${endedAt - startedAt}`,
+      )
+      return
+    }
+    const beforeAt = callID !== '' ? benchTimings.get(callID) : undefined
+    if (beforeAt !== undefined) benchTimings.delete(callID)
+    const sinceBefore = beforeAt === undefined ? 'unavailable' : String(endedAt - beforeAt)
+    appendV2HookLog(
+      `[bench] tool.execute.after end tool=${tool} callID=${callID} ` +
+        `duration_ms=${endedAt - startedAt} since_before_ms=${sinceBefore}`,
+    )
+  } catch {
+    // Instrumentation must never affect the hook chain.
+  }
+}
+
+// ─── V2 Secret-Scan Verdict ─────────────────────────────────────────────
+
+/**
+ * The scanner's own report marker, written to stderr on every non-clean run
+ * (exit 1 advisory, exit 2 block). It is the discriminator between a genuine
+ * low-confidence advisory and a runner infrastructure failure, BOTH of which
+ * surface as `code === 1`: the runner's own failures (missing/unexecutable
+ * script, spawn error, payload-serialization error) resolve a structured
+ * `HookResult` with `code: 1` and no scan report, while the real scanner's
+ * advisory always carries this marker. Requiring it means a scanner that stops
+ * reporting fails toward a denial, never toward a silent allow.
+ */
+const SECRET_SCAN_MARKER = '[SECRET SCAN]'
+
+/** Sanitized failure classes — logged in place of raw scanner output. */
+type SecretScanFailureReason =
+  | 'scanner-timeout'
+  | 'scanner-signal'
+  | 'scanner-spawn-failure'
+  | 'scanner-serialization-failure'
+  | 'scanner-malformed-output'
+  | 'scanner-unexpected-exit'
+
+type SecretScanDecision =
+  | { action: 'allow' }
+  | { action: 'advisory' }
+  | { action: 'block' }
+  | { action: 'fail-closed'; reason: SecretScanFailureReason }
+
+/**
+ * The runner's own infrastructure-failure messages (see hook-runner.ts), matched
+ * at the start of stderr where the runner is the only writer. Matching a prefix
+ * rather than a substring keeps a scan report that merely happens to quote one
+ * of these phrases from flipping a valid advisory into a denial.
+ */
+const SCANNER_INFRA_FAILURES: ReadonlyArray<[string, SecretScanFailureReason]> = [
+  ['payload serialization failed:', 'scanner-serialization-failure'],
+  ['spawn failed:', 'scanner-spawn-failure'],
+  ['hook script failed to spawn:', 'scanner-spawn-failure'],
+]
+
+/**
+ * Classify one secret-scan {@link HookResult} into an enforcement decision.
+ *
+ * fail-closed by construction: `allow` and `advisory` are reachable only from a
+ * result that is unambiguously a completed scanner run. Everything else —
+ * timeout, signal, spawn/serialization failure, missing report, unknown or
+ * unexpected exit status — denies. `advisory` additionally requires the
+ * scanner's own report marker, which is what separates an exit-1 advisory from
+ * the runner's exit-1 infrastructure failure.
+ *
+ * `block` covers the high-confidence match (exit 2); the caller turns it into
+ * the user-facing block.
+ */
+function evaluateSecretScanResult(scan: HookResult): SecretScanDecision {
+  if (scan.timedOut) return { action: 'fail-closed', reason: 'scanner-timeout' }
+  if (scan.signal !== null) return { action: 'fail-closed', reason: 'scanner-signal' }
+  if (!Number.isInteger(scan.code)) {
+    return { action: 'fail-closed', reason: 'scanner-malformed-output' }
+  }
+  for (const [signature, reason] of SCANNER_INFRA_FAILURES) {
+    if (scan.stderr.startsWith(signature)) return { action: 'fail-closed', reason }
+  }
+  if (scan.code === 0) return { action: 'allow' }
+  if (scan.code === 2) return { action: 'block' }
+  if (scan.code === 1) {
+    return scan.stderr.includes(SECRET_SCAN_MARKER)
+      ? { action: 'advisory' }
+      : { action: 'fail-closed', reason: 'scanner-malformed-output' }
+  }
+  return { action: 'fail-closed', reason: 'scanner-unexpected-exit' }
+}
+
+/** Invocation of scripts/hooks/scan-secrets.sh used by the tool guard. */
+type SecretScanRunner = (payload: HookPayload) => Promise<HookResult>
+
+const defaultSecretScanRunner: SecretScanRunner = (payload) => runHook('scan-secrets.sh', payload)
+
+let secretScanRunner: SecretScanRunner = defaultSecretScanRunner
+
+/**
+ * Test seam — override (or, with `null`, restore) the V2 secret-scan runner.
+ *
+ * Exported only for tests/pantheon/plugin-v2-contract.test.ts, which injects
+ * structured {@link HookResult}s (missing scanner, timeout, malformed output)
+ * that the real script cannot be made to produce on demand. There is no
+ * production caller; the shipped handler always uses `defaultSecretScanRunner`.
+ */
+export function setV2SecretScanRunnerForTests(runner: SecretScanRunner | null): void {
+  secretScanRunner = runner ?? defaultSecretScanRunner
+}
+
 // ─── V2 Tool Hooks ──────────────────────────────────────────────────────
 
+/**
+ * The `tool.execute.before` event as the host dispatches it (opencode 2.0.22).
+ *
+ * Transcribed from the host's tool service:
+ *
+ *   trigger("tool", "execute.before", { tool, sessionID, agent, messageID, id, input })
+ *
+ * Two shape differences from V1's positional `(input, output)` pair, both
+ * handled by {@link adaptV2ExecuteBeforeEvent}: the host passes ONE payload
+ * object, and the tool arguments live on `input` where V1 called them
+ * `output.args`.
+ *
+ * `agent` is a required field of the host's tool context
+ * (`ToolInvocation.context = { sessionID, agent, messageID, id }`), so the
+ * active agent arrives on the very event the enforcement guard needs. V1 had to
+ * learn it from a separate `chat.params` hook and keep a session→agent map; V2
+ * does not have to, and neither does this module.
+ */
+interface V2ToolExecuteBeforeEvent {
+  tool?: unknown
+  sessionID?: unknown
+  messageID?: unknown
+  agent?: unknown
+  id?: unknown
+  input?: unknown
+}
+
+/**
+ * Read-only enforcement for the V2 tool surface.
+ *
+ * The same factory, the same `DEFAULT_BLOCKED_TOOLS` and the same read-only set
+ * that V1 uses, so the two surfaces cannot drift on what counts as a mutating
+ * tool — `hashline_edit` and `pantheon_model` are denied here for exactly the
+ * reason they are denied in V1.
+ *
+ * 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(),
+})
+
+/**
+ * Project a V2 `execute.before` event onto the two-argument shape
+ * `createEnforcementGuard` was built for.
+ *
+ * `tool` is the host's registration id, computed as
+ * `options.namespace === undefined ? name : `${namespace}_${name}``. Pantheon
+ * declares a namespace for catalog grouping but sets `options.namespace` on no
+ * tool, so the id is the bare name (`hashline_edit`) and the blocked-tool match
+ * fires. A tool that opted into `options.namespace` would gain a prefix and stop
+ * matching — the integration test in tests/pantheon/plugin-v2-contract.test.ts
+ * drives the real registration path and asserts on the registered names, so
+ * that drift fails a test instead of silently disabling enforcement.
+ *
+ * A missing `sessionID` maps to the empty key: the registry lookup then matches
+ * the event's own (absent) identity, so a blocked tool in a read-only session is
+ * still denied. Fail-closed on the one axis that matters.
+ */
+function adaptV2ExecuteBeforeEvent(event: unknown): {
+  input: ToolExecuteBeforeInput
+  output: ToolExecuteBeforeOutput
+  agent: unknown
+} {
+  const payload = (event ?? {}) as V2ToolExecuteBeforeEvent
+  return {
+    input: {
+      tool: typeof payload.tool === 'string' ? payload.tool : '',
+      sessionID: typeof payload.sessionID === 'string' ? payload.sessionID : '',
+      callID: typeof payload.id === 'string' ? payload.id : '',
+    },
+    output: { args: payload.input },
+    agent: payload.agent,
+  }
+}
+
 /**
  * Register tool execution hooks via V2 ctx.tool.hook.
  *
@@ -509,43 +1216,142 @@ async function registerV2SessionHooks(context: PluginContext): Promise<boolean>
  *
  * 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
+async function registerV2ToolHooks(
+  context: PluginContext,
+  subagentOrigins: V2SubagentOriginRegistry,
+  boundedReadOrigins?: V2BoundedReadOriginRegistry,
+): Promise<{ registered: boolean; beforeRegistered: boolean }> {
+  const toolCtx = hostDomains(context).tool
 
   if (!toolCtx?.hook) {
-    return false
+    return { registered: false, beforeRegistered: false }
   }
 
   let registered = false
+  let beforeRegistered = false
 
   try {
-    // "execute.before" — read-only enforcement + command normalization
-    await toolCtx.hook('execute.before', (_event: unknown) => {
-      // Enforcement guard runs via V1 bridge when infrastructure is available.
-      // The V2 hook is a registration point; actual enforcement is wired
-      // through the V1 tool.execute.before hook.
-      const bridge = resolveBridge()
-      if (bridge?.board != null) {
-        // Bridge available: V1 enforcement guard handles read-only + command normalization.
-        // No additional V2-side enforcement needed.
+    // "execute.before" — read-only enforcement. Throwing from this handler
+    // DENIES the tool call and the host surfaces the message to the session,
+    // which is how the guard blocks a mutating tool in a read-only session.
+    //
+    // This is the enforcement point for the V2 surface, not a delegation to
+    // V1: `src/plugin.ts` is not loaded when only `plugin-v2` is configured
+    // (opencode.json `plugins`), so the V1 `tool.execute.before` hook does not
+    // exist in that process. The guard below is instantiated here and consulted
+    // here; without it the tools registered by registerV2Tools would be a live
+    // write path in every session, including read-only ones.
+    await toolCtx.hook('execute.before', async (event: unknown) => {
+      const benchStartedAt = Date.now()
+      const { input, output, agent } = adaptV2ExecuteBeforeEvent(event)
+      try {
+        // V2's equivalent of V1's `chat.params` trigger: the host puts the active
+        // agent on the event itself, so registering here needs no separate hook
+        // and no session→agent map. A non-read-only (or absent) agent revokes the
+        // registration, which also covers an in-session agent switch.
+        syncReadOnlySession(readOnlyRegistry, input.sessionID, agent)
+        // Deliberately OUTSIDE the try/catch below: a read-only denial must keep
+        // propagating to the host, not be swallowed as a scanner failure.
+        await v2EnforcementGuard(input, output)
+
+        // High-confidence secret scan (scripts/hooks/scan-secrets.sh). This is the
+        // ONLY hard block on the V2 surface, and it exists here — rather than via
+        // `src/plugins/pantheon-hooks.ts` — because that module is a separate
+        // plugin that is never loaded on a V2-only install: opencode.json
+        // `plugins` declares only `src/plugin-v2`. V1's scan-secrets block was
+        // therefore inert by construction, not by misconfiguration.
+        //
+        // exit 0 → allow. exit 1 with a valid scanner report → advisory, logged
+        // only. exit 2 (high-confidence match) → deny. A scanner that does NOT
+        // produce a trustworthy verdict — missing/unexecutable script, timeout,
+        // killed child, spawn/serialization failure, malformed or unexpected
+        // output — is fail-CLOSED: this pending tool call is denied, the session
+        // is not. (runHook resolves a structured result instead of rejecting, so
+        // the exit-code-only reading below cannot lean on an exception.)
+        let blockError: Error | null = null
+        try {
+          const payload: HookPayload = {
+            tool_name: input.tool,
+            tool_input: output.args ?? {},
+            agent_id: typeof agent === 'string' ? agent : '',
+            session_id: input.sessionID,
+          }
+          const scan = await secretScanRunner(payload)
+          const decision = evaluateSecretScanResult(scan)
+          if (decision.action === 'block') {
+            appendV2HookLog(SECRET_BLOCK_MESSAGE)
+            appendV2HookLog(scan.stderr)
+            blockError = new Error(SECRET_BLOCK_MESSAGE)
+          } else if (decision.action === 'advisory') {
+            // Advisory: log only, never block.
+            appendV2HookLog(scan.stderr)
+          } else if (decision.action === 'fail-closed') {
+            // Sanitized failure category only — never the scanner's raw stderr,
+            // which on a failure path is unverified and may carry the very
+            // payload the scan exists to keep out of logs.
+            appendV2HookLog(`${SECRET_SCAN_UNAVAILABLE_MESSAGE} (${decision.reason})`)
+            blockError = new Error(SECRET_SCAN_UNAVAILABLE_MESSAGE)
+          }
+        } catch {
+          // The runner is contracted to resolve a structured result, so this only
+          // guards an unexpected throw (including a future change to the runner).
+          // A scanner that cannot run is fail-CLOSED: deny this call rather than
+          // let it through with no scan at all.
+          appendV2HookLog(SECRET_SCAN_UNAVAILABLE_MESSAGE)
+          blockError = new Error(SECRET_SCAN_UNAVAILABLE_MESSAGE)
+        }
+        if (blockError !== null) throw blockError
+        const boundedReadOrigin = boundedReadOrigins?.capture(event)
+        const eventTool = (event as V2ToolExecuteBeforeEvent | null)?.tool
+        if (eventTool === BOUNDED_READ_TOOL && boundedReadOrigin === undefined) {
+          throw new Error('BOUND_READ_UNAUTHORIZED')
+        }
+        if (boundedReadOrigin !== undefined) {
+          writeV2AdmissionProof('tool.execute.before bounded-read', {
+            sessionID: boundedReadOrigin.sessionID,
+            messageID: boundedReadOrigin.messageID,
+            callID: boundedReadOrigin.callID,
+            agent: boundedReadOrigin.agent,
+          })
+        }
+        const origin = subagentOrigins.capture(event)
+        if (origin !== undefined) {
+          writeV2AdmissionProof('tool.execute.before', { ...origin })
+        }
+      } finally {
+        // BENCH instrumentation — observation only; runs on the deny paths too.
+        logBenchHookTiming('before', event, benchStartedAt)
       }
     })
     registered = true
+    beforeRegistered = true
   } catch {
     // Tool before-hook not supported
   }
 
   try {
-    // "execute.after" — hashline read enhance + context sandbox
-    await toolCtx.hook('execute.after', (_event: unknown) => {
-      // Read enhancer + sandbox run via V1 bridge.
-      const bridge = resolveBridge()
-      if (bridge?.visionHandler != null) {
-        // Bridge available: V1 vision handler + read enhancer handle post-execution.
+    // "execute.after" — the V1 parity chain (task-result-guard →
+    // context-sandbox → read-enhancer) rebuilt on the V2 event shape.
+    //
+    // This IS behaviour, not a registration point: on a V2-only install the V1
+    // `pantheon-hooks` plugin is not loaded, so this handler is the only thing
+    // that truncates oversized output and tags `read` with hashline refs.
+    // The sandbox config comes from `ctx.options.context_sandbox` (the V2 copy
+    // the installer writes — V2.0.25 drops the V1 top-level key), resolved with
+    // the same resolver V1 uses.
+    const v2ExecuteAfter = createV2ExecuteAfter({
+      sandbox: resolveV2SandboxConfig(context.options),
+    })
+    await toolCtx.hook('execute.after', async (event: unknown) => {
+      const benchStartedAt = Date.now()
+      try {
+        subagentOrigins.forget(event)
+        boundedReadOrigins?.forget(event)
+        await v2ExecuteAfter(event)
+      } finally {
+        // BENCH instrumentation — observation only; the awaited call means the
+        // duration covers the whole parity chain, not just its dispatch.
+        logBenchHookTiming('after', event, benchStartedAt)
       }
     })
     registered = true
@@ -553,7 +1359,7 @@ async function registerV2ToolHooks(context: PluginContext): Promise<boolean> {
     // Tool after-hook not supported
   }
 
-  return registered
+  return { registered, beforeRegistered }
 }
 
 // ─── V2 Permission Hook ─────────────────────────────────────────────────
@@ -562,16 +1368,18 @@ async function registerV2ToolHooks(context: PluginContext): Promise<boolean> {
  * Register permission hook via V2 ctx.permission.hook.
  *
  * The V2 permission.hook API (when available) provides:
- *   ctx.permission.hook("evaluate", handler) — custom permission logic
+ *   ctx.permission.hook("evaluate", handler) — host permission evaluation
+ * The handler receives one mutable PermissionEvaluation event; decisions are
+ * written to event.effect/event.message (there is no separate V1-style output).
  *
  * 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
+async function registerV2PermissionHook(
+  context: PluginContext,
+  subagentOrigins: V2SubagentOriginRegistry,
+): Promise<boolean> {
+  const domains = hostDomains(context)
+  const permCtx = domains.permission
 
   if (!permCtx?.hook) {
     markUnsupported('permission-hook')
@@ -579,9 +1387,117 @@ async function registerV2PermissionHook(context: PluginContext): Promise<boolean
   }
 
   try {
-    await permCtx.hook('evaluate', (_event: unknown) => {
-      // Custom permission logic — Zeus read guard + read-only enforcement.
-      // Wired through V1 tool.execute.before when infrastructure is available.
+    await permCtx.hook('evaluate', async (rawEvent: unknown) => {
+      const event = rawEvent as V2PermissionEvent | null
+      const effectBefore = event?.effect
+      let origin: ReturnType<V2SubagentOriginRegistry['consume']>
+      let decision: string | null = null
+      let callerSessionParentID: unknown
+      const writeProof = (): void => {
+        const proofPath = process.env.PANTHEON_HOOK_CANARY_PERMISSION_PROOF
+        if (!proofPath || !event || !Array.isArray(event.resources)) return
+        try {
+          appendFileSync(
+            proofPath,
+            `permission.evaluate ${JSON.stringify({
+              action: event.action,
+              resources: event.resources,
+              agent: event.agent,
+              sessionID: event.sessionID,
+              callerSessionParentID: callerSessionParentID ?? null,
+              source: event.source,
+              matchedOrigin: origin ?? null,
+              decision,
+              effect: event.effect,
+              message: event.message,
+              eventFields: ['action', 'resources', 'agent', 'sessionID', 'source', 'effect'].filter(
+                (key) => Object.hasOwn(event, key),
+              ),
+              effectBefore: effectBefore ?? null,
+              effectAfter: event.effect ?? null,
+            })}\n`,
+          )
+        } catch {
+          // Instrumentation is best-effort and must not affect permission flow.
+        }
+      }
+      const deny = (reason: string): void => {
+        if (event === null || typeof event !== 'object') {
+          throw new Error(
+            `permission event is unavailable; denying V2 permission evaluation (${reason})`,
+          )
+        }
+        event.effect = 'deny'
+        event.message = `Pantheon delegation denied: ${reason}`
+        if (event.effect !== 'deny') {
+          throw new Error(
+            `permission event is not mutable; denying V2 permission evaluation (${reason})`,
+          )
+        }
+        writeProof()
+      }
+
+      if (event?.effect === 'deny') {
+        writeProof()
+        return // explicit host deny is final
+      }
+      if (event == null) {
+        deny('permission event is missing')
+        return
+      }
+      if (!Array.isArray(event.resources) || event.resources.length === 0) {
+        deny('permission resources are missing or malformed')
+        return
+      }
+      const targets = event.resources.map(v2ResourceTarget)
+      if (targets.some((target) => target === undefined)) {
+        deny('permission resource target is malformed')
+        return
+      }
+      const hasPantheonTarget = targets.some((target) => PANTHEON_AGENTS.has(target ?? ''))
+      let session: AuthoritativeSession | undefined
+      if (hasPantheonTarget) {
+        origin = subagentOrigins.consume(event)
+        if (origin === undefined) {
+          deny('matching host subagent tool origin is missing or stale')
+          return
+        }
+        const sessionID = typeof event.sessionID === 'string' ? event.sessionID.trim() : ''
+        if (!sessionID) {
+          deny('caller session ID is missing')
+          return
+        }
+
+        const sessionDomain = domains.session
+        if (!sessionDomain || typeof sessionDomain.get !== 'function') {
+          deny('session lookup API is unavailable')
+          return
+        }
+
+        let retrieved: unknown
+        try {
+          retrieved = await sessionDomain.get({ sessionID })
+        } catch {
+          deny('caller session lookup failed')
+          return
+        }
+        if (retrieved === null || retrieved === undefined) {
+          deny('caller session was not found')
+          return
+        }
+        if (typeof retrieved !== 'object' || Array.isArray(retrieved)) {
+          deny('caller session lookup returned invalid data')
+          return
+        }
+        session = retrieved as AuthoritativeSession
+        callerSessionParentID = session.parentID
+      }
+
+      // Native-only resources remain under host policy. If a Pantheon target
+      // appears anywhere, the shared policy evaluates the complete resource set.
+      decision = evaluateV2Delegation(event, session, event.effect, origin)
+      if (decision === 'deny') deny('caller or target is not allowed by delegation policy')
+      else writeProof()
     })
     return true
   } catch {
@@ -593,7 +1509,15 @@ async function registerV2PermissionHook(context: PluginContext): Promise<boolean
 // ─── Tool Definition Factory ─────────────────────────────────────────────
 
 /**
- * Internal types for V2 tool draft.
+ * Minimal structural view of the V2 tool draft.
+ *
+ * `output` is REQUIRED. The host (opencode 2.0.22) enforces a biconditional on
+ * a tool's declared `output` and the value its `execute` resolves to:
+ * `def.output === undefined` together with `'output' in result` throws
+ * "Tool result declared output without an output schema", and a declared
+ * `output` whose result omits the key throws "Tool did not return its
+ * declared output". A missing declaration therefore fails every call, so the
+ * field is mandatory here rather than optional.
  */
 interface V2ToolDraft {
   namespace(config: { name: string; description: string }): void
@@ -601,91 +1525,12 @@ interface V2ToolDraft {
     name: string
     description: string
     input: Record<string, unknown>
+    output: Record<string, unknown>
     execute: (input: Record<string, unknown>, context: unknown) => Promise<V2ToolResult>
   }): void
 }
 
-/**
- * V2 tool result shape.
- *
- * The V1 SDK types `ToolResult` as `string | { output: string, ... }`, but
- * the V2 beta host reads a field off the resolved value (minified `Ce`) and
- * throws `Ce is not an Object` when a tool resolves to a bare string. Our
- * handlers are fail-open, so that host-side TypeError escapes instead of
- * being contained. Always resolve to the object shape — it satisfies both
- * the SDK union and the beta host.
- */
-export interface V2ToolResult {
-  output: string
-}
-
-/**
- * A V2 tool definition ready for registration.
- */
-interface V2ToolDef {
-  name: string
-  description: string
-  input: Record<string, unknown>
-  execute: (input: Record<string, unknown>, context: unknown) => Promise<V2ToolResult>
-}
-
-/**
- * Create V2 tool definitions from the plugin context.
- *
- * When V1 infrastructure (BackgroundJobBoard, delegation client, etc.) is
- * available through the V2 context, tools are wired directly. Otherwise,
- * each tool returns an error message explaining the limitation.
- */
-function createV2ToolDefinitionsFromContext(_context: PluginContext): V2ToolDef[] {
-  // Tool definitions are created lazily. When the full V1 infrastructure
-  // is bridged through the V2 context, these can be wired to real implementations.
-  // For now, they are structural definitions with placeholder execute functions
-  // that explain the V2 limitation.
-  const v2UnavailableMessage =
-    'This tool requires V1 infrastructure (BackgroundJobBoard, SDK client). ' +
-    'Use the V1 plugin (src/plugin.ts) for full tool support, or wire V1 ' +
-    'infrastructure through the V2 bridge (src/pantheon/v2-bridge.ts).'
-
-  const toolNames = [
-    'hashline_edit',
-    'pantheon_goal_create',
-    'pantheon_goal_get',
-    'pantheon_goal_update',
-    'pantheon_cost',
-    'pantheon_model',
-  ]
-
-  const toolDescriptions: Record<string, string> = {
-    hashline_edit:
-      'Edit a file anchored by hashline refs (LINE#TAG) instead of raw line numbers. ' +
-      'Ops: replace, append, prepend, delete. ALL refs validated against ORIGINAL file first.',
-    pantheon_goal_create:
-      'Create the single active goal for this session. The goal loop then continues the ' +
-      'session automatically on idle until the goal is marked done.',
-    pantheon_goal_get:
-      'Return the active goal for this session (status, objective, continuations).',
-    pantheon_goal_update:
-      'Update the active goal: set status (pending/in_progress/done) and/or rewrite the objective. ' +
-      'Setting status to done stops all further continuations.',
-    pantheon_cost:
-      'Report delegation cost + token usage by agent over the last N days, read from opencode.db.',
-    pantheon_model:
-      'Show, set, or reset per-agent model overrides in active-preset.json (project or global).',
-  }
-
-  return toolNames.map((name) => ({
-    name,
-    description: toolDescriptions[name] ?? `Pantheon tool: ${name}`,
-    input: { type: 'object' as const, properties: {} },
-    // FOLLOW-UP: wire the real tool wrappers (costCommand/goalTools) once V1
-    // infrastructure is resolvable in the V2 standalone context. Until then,
-    // placeholders resolve to the object shape so the beta host never sees a
-    // bare string.
-    execute: async (_input: Record<string, unknown>, _context: unknown): Promise<V2ToolResult> => {
-      return { output: `${name}: ${v2UnavailableMessage}` }
-    },
-  }))
-}
+export type { V2ToolDef, V2ToolResult } from './pantheon/v2-tools.ts'
 
 // ─── Plugin Definition ───────────────────────────────────────────────────
 
@@ -693,6 +1538,83 @@ function createV2ToolDefinitionsFromContext(_context: PluginContext): V2ToolDef[
 interface V2SessionEvent {
   type: string
   properties?: Record<string, unknown>
+  data?: unknown
+}
+
+/** Opt-in trace used by the isolated F4A canary; never logs prompts or inputs. */
+function writeV2AdmissionProof(label: string, detail: Record<string, unknown>): void {
+  const proofPath = process.env.PANTHEON_HOOK_CANARY_PERMISSION_PROOF
+  if (!proofPath) return
+  try {
+    appendFileSync(proofPath, `${label} ${JSON.stringify(detail)}\n`)
+  } catch {
+    // Proof is best-effort and must not affect admission behavior.
+  }
+}
+
+async function prepareV2BoundedRead(
+  context: PluginContext,
+): Promise<ReturnType<typeof createV2BoundedReadTool> | undefined> {
+  const host = hostDomains(context)
+  const directory = host.location?.directory
+  const projectID = host.location?.project?.id
+  const session = host.session
+  const permission = host.permission
+  if (
+    typeof directory !== 'string' ||
+    directory.trim() === '' ||
+    typeof projectID !== 'string' ||
+    projectID.trim() === '' ||
+    typeof session?.get !== 'function' ||
+    typeof permission?.assert !== 'function' ||
+    typeof host.event?.subscribe !== 'function' ||
+    typeof host.tool?.transform !== 'function' ||
+    typeof host.tool?.hook !== 'function'
+  ) {
+    markUnsupported('bounded-read')
+    return undefined
+  }
+
+  const rootDirectory = await realpathAsync(directory).catch(() => undefined)
+  if (rootDirectory === undefined) {
+    markUnsupported('bounded-read')
+    return undefined
+  }
+
+  return createV2BoundedReadTool({
+    rootDirectory,
+    projectID,
+    getSession: (sessionID) => {
+      if (typeof session.get !== 'function') throw new Error('session lookup unavailable')
+      return session.get.call(session, { sessionID })
+    },
+    assertPermission: (request) => {
+      if (typeof permission.assert !== 'function') throw new Error('permission API unavailable')
+      return permission.assert.call(permission, request)
+    },
+    scanContent: async ({ content, agent, sessionID, callID }) => {
+      try {
+        const scan = await secretScanRunner({
+          tool_name: BOUNDED_READ_TOOL,
+          tool_input: { content },
+          agent_id: agent,
+          session_id: sessionID,
+        })
+        const decision = evaluateSecretScanResult(scan)
+        if (decision.action === 'allow') return 'allow'
+        const reason = decision.action === 'fail-closed' ? decision.reason : 'content-match'
+        appendV2HookLog(
+          `[SECRET SCAN] bounded read withheld session=${sessionID} callID=${callID} reason=${reason}`,
+        )
+        return decision.action === 'fail-closed' ? 'unavailable' : 'deny'
+      } catch {
+        appendV2HookLog(
+          `[SECRET SCAN] bounded read withheld session=${sessionID} callID=${callID} reason=scanner-failure`,
+        )
+        return 'unavailable'
+      }
+    },
+  })
 }
 
 /** Cleanup function type. */
@@ -713,10 +1635,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 host 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) },
       {
@@ -739,44 +1663,49 @@ export const plugin = define({
       }
     })
 
-    // ─── Phase 2: V2 Tool Registration (best-effort) ─────────────────
-    const toolsRegistered = await registerV2Tools(context).catch(() => false)
-    if (!toolsRegistered) {
-      markUnsupported('tool-transform')
-    }
+    const subagentOrigins = new V2SubagentOriginRegistry()
+    const boundedRead = await prepareV2BoundedRead(context).catch(() => undefined)
+    if (boundedRead === undefined) markUnsupported('bounded-read')
 
-    // ─── Phase 3: V2 Event Subscription (best-effort) ────────────────
-    const eventCleanup = subscribeV2Events(context)
+    // ─── Phase 2: V2 Event Subscription (best-effort) ────────────────
+    const eventCleanup = subscribeV2Events(context, boundedRead?.clearSession)
     if (eventCleanup) {
       activeCleanups.push(eventCleanup)
     } else {
       markUnsupported('event-stream')
     }
 
-    // ─── Phase 4: V2 Session Hooks (best-effort) ─────────────────────
+    // ─── Phase 3: V2 Session Hooks (best-effort) ─────────────────────
     const sessionHooksRegistered = await registerV2SessionHooks(context).catch(() => false)
     if (!sessionHooksRegistered) {
       markUnsupported('session-hooks')
     }
 
-    // ─── Phase 5: V2 Tool Hooks (best-effort) ────────────────────────
-    const toolHooksRegistered = await registerV2ToolHooks(context).catch(() => false)
-    if (!toolHooksRegistered) {
+    // ─── Phase 4: V2 Tool Hooks (best-effort) ────────────────────────
+    const toolHookResult = await registerV2ToolHooks(
+      context,
+      subagentOrigins,
+      boundedRead?.origins,
+    ).catch(() => ({ registered: false, beforeRegistered: false }))
+    if (!toolHookResult.registered) {
       markUnsupported('tool-execute-hooks')
     }
 
+    // ─── Phase 5: V2 Tool Registration (best-effort) ─────────────────
+    const boundedReadDefinition = toolHookResult.beforeRegistered
+      ? boundedRead?.definition
+      : undefined
+    if (boundedRead !== undefined && boundedReadDefinition === undefined) {
+      markUnsupported('bounded-read')
+    }
+    const toolsRegistered = await registerV2Tools(context, boundedReadDefinition).catch(() => false)
+    if (!toolsRegistered) markUnsupported('tool-transform')
+
     // ─── Phase 6: V2 Permission Hook (best-effort) ───────────────────
-    await registerV2PermissionHook(context).catch(() => false)
+    await registerV2PermissionHook(context, subagentOrigins).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
@@ -786,7 +1715,10 @@ export const plugin = define({
         // Proven by the canary's negative control.
         await compactionCtx.hook('compaction', (_event: unknown) => {
           // Compaction context build — injects active goals, pending todos,
-          // and in-flight delegations. Wired through V1 infrastructure.
+          // and in-flight delegations. No V2-side implementation: that build
+          // lives in the V1 path, which is not loaded on a V2-only install.
+          // This registration is a real hook (the canary below proves it
+          // fires) with no V2 behaviour behind it.
           //
           // Opt-in lifetime proof for the host-backed hook canary
           // (tests/pantheon/plugin-v2-hook-canary.test.mjs, MODE=real). It is
@@ -832,7 +1764,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