pantheon-opencode 1.6.0-beta.2 → 1.6.0-beta.4

package/src/plugin-v2.ts

@@ -2,26 +2,68 @@
  * Pantheon V2 Plugin — full orchestration plugin for OpenCode V2.
  *
  * Registers:
- * - 6 orchestration tools via V2 tool.transform (with V1 bridge fallback)
+ * - 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)
- * - 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.
+ * - 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, registered as
+ *   registration points with no V2-side behaviour
+ *
+ * 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 four 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 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.
@@ -29,7 +71,8 @@
  * @module plugin-v2
  */
 
-import { appendFileSync } from 'node:fs'
+import { appendFileSync, mkdirSync } from 'node:fs'
+import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import type {
   AgentDraft,
@@ -38,11 +81,20 @@ 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 {
   getV2BridgeFromContext,
   type PantheonV2Bridge,
   type V2ContextLike,
 } from './pantheon/v2-bridge.ts'
+import { createV2ToolDefinitions, type V2ToolResult } from './pantheon/v2-tools.ts'
+import { type HookPayload, runHook } from './plugins/hook-runner.ts'
 
 // ─── Unsupported Features Registry ───────────────────────────────────────
 
@@ -53,16 +105,34 @@ import {
  */
 export const V2_UNSUPPORTED_FEATURES: string[] = [
   'legacy-hooks',
-  // `catalog` alone was absent in the OpenCode 2.0.18 runtime probe.
+  // `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',
-  // 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.
+  // 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 for adding a
-  // directory source. This is narrower than (and distinct from) ctx.skill's
-  // host availability or callable 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: 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',
 ]
 
 // ─── Constants ───────────────────────────────────────────────────────────
@@ -146,6 +216,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 ──────────────────────────────────────────────
 
 /**
@@ -283,32 +415,44 @@ 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
+  const toolCtx = hostDomains(context).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 toolDefs = createV2ToolDefinitions()
 
     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,
         })
       }
@@ -330,9 +474,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
@@ -377,20 +519,35 @@ 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.
+ *
+ * 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".
+ */
 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.
   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.
+  // 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 +560,23 @@ 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-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> {}
 
-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-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 +590,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
@@ -487,8 +640,10 @@ 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.
+      // Vision interception. No V2-side implementation: the handler lives in
+      // the V1 path (`vision.chatMessage`), which is not loaded on a V2-only
+      // install. This is a permanent no-op there, not a graceful degradation —
+      // nothing is delegated, because there is nothing here to delegate to.
     })
     registered = true
   } catch {
@@ -498,8 +653,169 @@ 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'
+
+/**
+ * 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
+  }
+}
+
 // ─── 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
+  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`:
+ * 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.
+ */
+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.
  *
@@ -510,11 +826,7 @@ 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
+  const toolCtx = hostDomains(context).tool
 
   if (!toolCtx?.hook) {
     return false
@@ -523,16 +835,60 @@ async function registerV2ToolHooks(context: PluginContext): Promise<boolean> {
   let registered = 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 { input, output, agent } = adaptV2ExecuteBeforeEvent(event)
+      // 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 2 → block. exit 1 (low-confidence header/KEY names) → advisory,
+      // logged only. A scanner failure (missing script, timeout) is fail-OPEN:
+      // runHook never rejects, and an infrastructure error must not deny
+      // unrelated tool calls.
+      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 runHook('scan-secrets.sh', payload)
+        if (scan.code === 2) {
+          appendV2HookLog(SECRET_BLOCK_MESSAGE)
+          appendV2HookLog(scan.stderr)
+          blockError = new Error(SECRET_BLOCK_MESSAGE)
+        } else if (scan.code === 1) {
+          // Advisory: log only, never block.
+          appendV2HookLog(scan.stderr)
+        }
+      } catch {
+        // Never let the scanner take down the session — runHook resolves a
+        // structured result instead of rejecting, so this is belt-and-braces.
       }
+      if (blockError !== null) throw blockError
     })
     registered = true
   } catch {
@@ -540,13 +896,14 @@ async function registerV2ToolHooks(context: PluginContext): Promise<boolean> {
   }
 
   try {
-    // "execute.after" — hashline read enhance + context sandbox
+    // "execute.after" — hashline read enhance + context sandbox.
+    //
+    // Registration point only: there is no V2-side behaviour here. The
+    // enhancer/sandbox live in the V1 path (`pantheon-hooks.ts` +
+    // `context-sandbox.ts`), a separate plugin instance that is not loaded when
+    // only `plugin-v2` is configured.
     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.
-      }
+      // Intentionally empty.
     })
     registered = true
   } catch {
@@ -567,11 +924,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')
@@ -580,8 +933,11 @@ 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.
+      // Registration point only — no V2-side permission logic. Read-only
+      // enforcement does NOT run here: it runs in the `execute.before` handler
+      // above, which is the hook the host consults before a tool executes. Do
+      // not read this as "the V1 guards cover it": V1 is a different plugin
+      // instance and is not loaded when only `plugin-v2` is configured.
     })
     return true
   } catch {
@@ -593,7 +949,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 +965,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 ───────────────────────────────────────────────────
 
@@ -713,10 +998,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) },
       {
@@ -769,14 +1056,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
@@ -786,7 +1066,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