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

package/src/plugin-v2.ts

@@ -12,8 +12,8 @@
  *   session, and the shared `createEnforcementGuard` throws to deny
  *   `hashline_edit` / `pantheon_model` / `edit` / `write` / `bash` / `task`.
  *   See `registerV2ToolHooks`.
- * - The SAME `execute.before` hook scans serialized tool input in-process and
- *   throws on a high-confidence token match. This is the
+ * - 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
@@ -88,7 +88,6 @@ import {
   type ToolExecuteBeforeInput,
   type ToolExecuteBeforeOutput,
 } from './pantheon/delegation-enforce.ts'
-import { scanSecretPayload } from './pantheon/secret-scanner.ts'
 import {
   getV2BridgeFromContext,
   type PantheonV2Bridge,
@@ -104,6 +103,7 @@ import {
 import { createV2ExecuteAfter, resolveV2SandboxConfig } from './pantheon/v2-execute-after.ts'
 import { createV2ToolDefinitions, type V2ToolResult } from './pantheon/v2-tools.ts'
 import { V2_UNSUPPORTED_FEATURE_SEED } from './pantheon/v2-unsupported.mjs'
+import { type HookPayload, type HookResult, runHook } from './plugins/hook-runner.ts'
 
 // ─── Unsupported Features Registry ───────────────────────────────────────
 
@@ -240,15 +240,14 @@ interface V2PermissionDomain {
 }
 
 /**
- * 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.
+ * 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?: (sessionID: string) => Promise<unknown>
+  get?: (input: { sessionID: string }) => Promise<unknown>
 }
 
 /** `PluginContext` plus the four domains 1.18.x omits. See the module header. */
@@ -731,12 +730,15 @@ async function registerV2SessionHooks(context: PluginContext): Promise<boolean>
 // ─── V2 Secret Scan ─────────────────────────────────────────────────────
 
 /**
- * High-confidence secret token formats used to redact unrelated runtime logs.
- * Detection itself is shared with V1 in `pantheon/secret-scanner.ts`.
+ * 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.
  *
- * This separate log-redaction expression is not the runtime detector. It is
- * kept local because it masks arbitrary log strings, while the shared scanner
- * returns masked findings and never returns raw payload content.
+ * 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,
@@ -751,7 +753,7 @@ function maskSecret(text: string): string {
 }
 
 /**
- * Message thrown when a high-confidence token match is detected.
+ * 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
@@ -770,8 +772,17 @@ const SECRET_BLOCK_MESSAGE =
   '[plugin-v2] Blocked: high-confidence secret detected in tool input — see .pantheon/logs/hooks.log'
 
 /**
- * Message thrown when the scanner cannot validate or serialize the tool input.
- * Invalid scanner input is a deliberate fail-CLOSED denial.
+ * 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
@@ -780,80 +791,6 @@ const SECRET_BLOCK_MESSAGE =
 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'
 
-const SECRET_SCAN_MARKER = '[SECRET SCAN]'
-
-type SecretScanPayload = {
-  tool_name?: string
-  tool_input?: unknown
-  agent_id?: string
-  session_id?: string
-}
-
-type SecretScanHookResult = {
-  code: number
-  stdout: string
-  stderr: string
-  signal: NodeJS.Signals | null
-  timedOut: boolean
-}
-
-type SecretScanFailureReason = 'scanner-malformed-output' | 'scanner-unexpected-exit'
-
-type SecretScanDecision =
-  | { action: 'allow' }
-  | { action: 'advisory' }
-  | { action: 'block' }
-  | { action: 'fail-closed'; reason: SecretScanFailureReason }
-
-function evaluateSecretScanResult(scan: SecretScanHookResult): SecretScanDecision {
-  if (scan.timedOut || scan.signal !== null) {
-    return { action: 'fail-closed', reason: 'scanner-unexpected-exit' }
-  }
-  if (!Number.isInteger(scan.code)) {
-    return { action: 'fail-closed', reason: 'scanner-malformed-output' }
-  }
-  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' }
-}
-
-/** Convert the pure scanner result into the existing fail-closed verdict shape. */
-async function scanSecretInProcess(payload: SecretScanPayload): Promise<SecretScanHookResult> {
-  const result = scanSecretPayload(payload)
-  const reports =
-    result.status === 'block' || result.status === 'advisory'
-      ? result.findings.map(
-          (finding) =>
-            `[SECRET SCAN] ${finding.confidence}-confidence match: ${finding.masked} (pattern: ${finding.pattern})`,
-        )
-      : []
-  const code = result.status === 'clean' ? 0 : result.status === 'block' ? 2 : 1
-  const stderr =
-    result.status === 'invalid'
-      ? 'scanner input validation failed'
-      : result.status === 'block'
-        ? `${reports.join('\n')}\n[SECRET SCAN] High-confidence hardcoded secret detected. Tool call will be BLOCKED.`
-        : result.status === 'advisory'
-          ? `${reports.join('\n')}\n[SECRET SCAN] Possible secret detected. Remove it and use environment variables or a vault.`
-          : ''
-  return { code, stdout: '', stderr, signal: null, timedOut: false }
-}
-
-let secretScanRunner: (payload: SecretScanPayload) => Promise<SecretScanHookResult> =
-  scanSecretInProcess
-
-/** Test-only seam for exercising malformed scanner verdicts without a host. */
-export function setV2SecretScanRunnerForTests(
-  runner: ((payload: SecretScanPayload) => Promise<SecretScanHookResult>) | null,
-): void {
-  secretScanRunner = runner ?? scanSecretInProcess
-}
-
 /**
  * Append one masked, ISO-stamped line to .pantheon/logs/hooks.log under the
  * working directory, and return whether it landed.
@@ -889,6 +826,98 @@ function appendV2HookLog(line: string): boolean {
   }
 }
 
+// ─── 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 ──────────────────────────────────────────────────────
 
 /**
@@ -925,11 +954,41 @@ interface V2ToolExecuteBeforeEvent {
  * tool — `hashline_edit` and `pantheon_model` are denied here for exactly the
  * reason they are denied in V1.
  *
- * Caller/target delegation authorization is separate: V2's
- * `permission.evaluate` hook resolves the authoritative caller from the host
- * session and applies the matrix in `v2-delegation-enforce.ts`. Keeping the
- * responsibilities separate avoids treating this mutating-tool deny list as
- * the delegation policy.
+ * 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(),
@@ -976,9 +1035,7 @@ function adaptV2ExecuteBeforeEvent(event: unknown): {
  *   ctx.tool.hook("execute.before", handler) — pre-execution guard
  *   ctx.tool.hook("execute.after", handler)  — post-execution augment
  *
- * Returns true only if the security-critical `execute.before` hook registered.
- * The post-execution hook is optional and cannot make an unprotected tool
- * surface ready.
+ * Returns true if any hooks were registered.
  */
 async function registerV2ToolHooks(context: PluginContext): Promise<boolean> {
   const toolCtx = hostDomains(context).tool
@@ -987,6 +1044,8 @@ async function registerV2ToolHooks(context: PluginContext): Promise<boolean> {
     return false
   }
 
+  let registered = false
+
   try {
     // "execute.before" — read-only enforcement. Throwing from this handler
     // DENIES the tool call and the host surfaces the message to the session,
@@ -1009,20 +1068,25 @@ async function registerV2ToolHooks(context: PluginContext): Promise<boolean> {
       // propagating to the host, not be swallowed as a scanner failure.
       await v2EnforcementGuard(input, output)
 
-      // In-process high-confidence secret scan. This is the
+      // 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`. Both V1 and V2 import the same
-      // scanner module so this remains active on either install surface.
+      // `plugins` declares only `src/plugin-v2`. V1's scan-secrets block was
+      // therefore inert by construction, not by misconfiguration.
       //
-      // Clean → allow. Low-confidence match → advisory. High-confidence match
-      // or malformed/non-serializable input → deny this tool call.
+      // 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: SecretScanPayload = {
+        const payload: HookPayload = {
           tool_name: input.tool,
-          tool_input: output.args,
+          tool_input: output.args ?? {},
           agent_id: typeof agent === 'string' ? agent : '',
           session_id: input.sessionID,
         }
@@ -1033,25 +1097,28 @@ async function registerV2ToolHooks(context: PluginContext): Promise<boolean> {
           appendV2HookLog(scan.stderr)
           blockError = new Error(SECRET_BLOCK_MESSAGE)
         } else if (decision.action === 'advisory') {
-          // The pure scanner reports masked matches only.
+          // Advisory: log only, never block.
           appendV2HookLog(scan.stderr)
         } else if (decision.action === 'fail-closed') {
-          // Never persist scanner output from an invalid verdict.
+          // 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 {
-        // Keep the enforcement fail-closed if the scanner unexpectedly throws.
+        // 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
     })
+    registered = true
   } catch {
-    // Never proceed to Pantheon tool registration without this guard. The host
-    // may still expose its own built-in tools; this marker does not claim to
-    // block or scan native host tool paths.
-    return false
+    // Tool before-hook not supported
   }
 
   try {
@@ -1068,11 +1135,12 @@ async function registerV2ToolHooks(context: PluginContext): Promise<boolean> {
       sandbox: resolveV2SandboxConfig(context.options),
     })
     await toolCtx.hook('execute.after', (event: unknown) => v2ExecuteAfter(event))
+    registered = true
   } catch {
-    markUnsupported('tool-execute-after-hook')
+    // Tool after-hook not supported
   }
 
-  return true
+  return registered
 }
 
 // ─── V2 Permission Hook ─────────────────────────────────────────────────
@@ -1082,6 +1150,8 @@ async function registerV2ToolHooks(context: PluginContext): Promise<boolean> {
  *
  * The V2 permission.hook API (when available) provides:
  *   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.
  */
@@ -1095,14 +1165,10 @@ async function registerV2PermissionHook(context: PluginContext): Promise<boolean
   }
 
   try {
-    await permCtx.hook('evaluate', async (rawEvent: unknown, rawOutput?: unknown) => {
+    await permCtx.hook('evaluate', async (rawEvent: unknown) => {
       const event = rawEvent as V2PermissionEvent | null
-      const output =
-        rawOutput !== null && typeof rawOutput === 'object'
-          ? (rawOutput as { status?: unknown })
-          : undefined
-      const statusBefore = output?.status
-      const writeProof = (statusAfter: unknown): void => {
+      const effectBefore = event?.effect
+      const writeProof = (): void => {
         const proofPath = process.env.PANTHEON_HOOK_CANARY_PERMISSION_PROOF
         if (!proofPath || !event || !Array.isArray(event.resources)) return
         try {
@@ -1113,61 +1179,89 @@ async function registerV2PermissionHook(context: PluginContext): Promise<boolean
               agent: event.agent,
               sessionID: event.sessionID,
               effect: event.effect,
+              message: event.message,
               eventFields: ['resources', 'agent', 'sessionID', 'effect'].filter((key) =>
                 Object.hasOwn(event, key),
               ),
-              outputPresent: output !== undefined,
-              statusBefore: statusBefore ?? null,
-              statusAfter: statusAfter ?? null,
+              effectBefore: effectBefore ?? null,
+              effectAfter: event.effect ?? null,
             })}\n`,
           )
         } catch {
           // Instrumentation is best-effort and must not affect permission flow.
         }
       }
-      const deny = (): void => {
-        if (!output) {
-          writeProof(undefined)
-          throw new Error('permission output is unavailable; denying V2 permission evaluation')
+      const deny = (reason: string): void => {
+        if (event === null || typeof event !== 'object') {
+          throw new Error(
+            `permission event is unavailable; denying V2 permission evaluation (${reason})`,
+          )
         }
-        output.status = 'deny'
-        writeProof(output.status)
+        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 (output?.status === 'deny') {
-        writeProof(output.status)
+      if (event?.effect === 'deny') {
+        writeProof()
         return // explicit host deny is final
       }
-      if (event == null || !Array.isArray(event.resources)) {
-        deny()
+      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()
+        deny('permission resource target is malformed')
         return
       }
       const hasPantheonTarget = targets.some((target) => PANTHEON_AGENTS.has(target ?? ''))
       let session: AuthoritativeSession | undefined
       if (hasPantheonTarget) {
+        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 {
-          const sessionID = typeof event.sessionID === 'string' ? event.sessionID : ''
-          if (!sessionID || !domains.session?.get) throw new Error('session lookup unavailable')
-          const retrieved = await domains.session.get(sessionID)
-          if (retrieved === null || typeof retrieved !== 'object')
-            throw new Error('invalid session')
-          session = retrieved as AuthoritativeSession
+          retrieved = await sessionDomain.get({ sessionID })
         } catch {
-          deny()
+          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
       }
 
       // Native-only resources remain under host policy. If a Pantheon target
       // appears anywhere, the shared policy evaluates the complete resource set.
-      const decision = evaluateV2Delegation(event, session, output?.status)
-      if (decision === 'deny') deny()
-      else writeProof(output?.status)
+      const decision = evaluateV2Delegation(event, session, event.effect)
+      if (decision === 'deny') deny('caller or target is not allowed by delegation policy')
+      else writeProof()
     })
     return true
   } catch {
@@ -1256,30 +1350,13 @@ export const plugin = define({
       }
     })
 
-    // ─── Phase 2: Required V2 execute.before enforcement ──────────────
-    // Register the scanner/read-only gate before any Pantheon V2 tools can be
-    // added. A missing/rejected hook disables the custom Pantheon tool surface;
-    // native host built-ins may still remain available and are not claimed to
-    // be covered by this plugin guard.
-    const toolHooksRegistered = await registerV2ToolHooks(context).catch(() => false)
-    if (!toolHooksRegistered) {
-      markUnsupported('tool-execute-hooks')
-      markUnsupported('secret-scan-hook')
-      markUnsupported('pantheon-tools-disabled')
-      console.error(
-        '[Pantheon V2] Secret-scanning enforcement is unavailable; Pantheon V2 tools were not registered. Native host tools may remain available and are not covered by this guard.',
-      )
-    }
-
-    // ─── Phase 3: V2 Tool Registration (guarded) ─────────────────────
-    const toolsRegistered = toolHooksRegistered
-      ? await registerV2Tools(context).catch(() => false)
-      : false
-    if (!toolsRegistered && toolHooksRegistered) {
+    // ─── Phase 2: V2 Tool Registration (best-effort) ─────────────────
+    const toolsRegistered = await registerV2Tools(context).catch(() => false)
+    if (!toolsRegistered) {
       markUnsupported('tool-transform')
     }
 
-    // ─── Phase 4: V2 Event Subscription (best-effort) ────────────────
+    // ─── Phase 3: V2 Event Subscription (best-effort) ────────────────
     const eventCleanup = subscribeV2Events(context)
     if (eventCleanup) {
       activeCleanups.push(eventCleanup)
@@ -1287,12 +1364,18 @@ export const plugin = define({
       markUnsupported('event-stream')
     }
 
-    // ─── Phase 5: V2 Session Hooks (best-effort) ─────────────────────
+    // ─── Phase 4: 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) {
+      markUnsupported('tool-execute-hooks')
+    }
+
     // ─── Phase 6: V2 Permission Hook (best-effort) ───────────────────
     await registerV2PermissionHook(context).catch(() => false)