@ian-pascoe/pi-advisor 0.3.1 → 0.3.3

package/README.md

@@ -2,7 +2,7 @@
 
 `@ian-pascoe/pi-advisor` reviews a Pi agent's completed work and surfaces concise, attributed findings for material problems and worthwhile low-risk cleanup.
 
-Requires Pi `0.87.1` and Node `>=22.19.0`. Other Pi versions pause review with an explicit compatibility error.
+Requires Node `>=22.19.0`. Advisor does not pin a Pi version: at load it checks the Pi SDK exports and methods it uses. If any are missing, it warns, hides `advisor_ask`, and stays unavailable; `/advisor status` names the missing requirements. The observed session keeps working.
 
 ## Install
 
@@ -35,7 +35,7 @@ When Advisor is enabled, the main agent can call `advisor_ask({ message })` for
 
 A Consultation receives only observed context that has not already been supplied to that Advisor. It does not reduce the Review Backlog, create an Intervention, or trigger a Corrective Turn. Its ordinary tool call and result remain in the observed transcript for later Reviews.
 
-The tool is absent while Advisor is disabled. A paused Advisor keeps it visible so the call can report the pause reason and recovery commands. User cancellation stops only that Consultation; an inference, authentication, deadline, or investigative-tool failure pauses Advisor. CodeMode exposure settings continue to decide whether the tool is direct, CodeMode-only, or both.
+The tool is absent while Advisor is disabled. A paused Advisor keeps it visible so the call can report the pause reason and recovery commands. User cancellation stops only that Consultation; an inference, authentication, deadline, or investigative-tool failure pauses Advisor. With Pi's built-in `codemode` active, scripts can call it too; under `codemode.mode: "only"` its declaration is hidden and it is reachable only through `codemode` scripts.
 
 Consultation authorizes analysis and investigation, not implementation or other side effects. The configured Advisor Prompt remains authoritative. Tool Grants still expose each granted tool's full native interface, so exclude mutating tools when a prompt-level boundary is insufficient.
 
@@ -54,13 +54,13 @@ Consultation authorizes analysis and investigation, not implementation or other
 | Findings per Review            | 4                            |
 | Automatic Corrective Turns     | 1 per request/task           |
 
-A Tool Grant names tools; it does not sandbox their full native interfaces. Explicitly granting `lsp`, for example, permits its native operations, including mutations. Unavailable names are ignored and reported. CodeMode-only tools require an explicitly compatible transport grant; Advisor never adds aliases, autogrants missing tools, or changes CodeMode exposure.
+A Tool Grant names tools; it does not sandbox their full native interfaces. Explicitly granting `lsp`, for example, permits its native operations, including mutations. Unavailable names are ignored and reported. Advisor never autogrants missing tools. Granting `codemode` lets the Advisor script its other granted tools; it inherits the observed `codemode.mode`, so under `"only"` the Advisor calls `advisor_report` from a script.
 
 The Advisor inherits each observed agent's model and thinking level independently unless configured otherwise. One root policy can cover current and future Minimal Subagents descendants when enabled.
 
 ## Sessions and Context Management
 
-Each watched agent has a private, persisted native Advisor Session with fresh, session-bound extension resources. Reviews reuse that session until context or configuration changes require rebuilding. Pi 0.87.1's hidden inline `llama.cpp` built-in is recreated from the installed Pi package's shipped extension file, retaining its ordered metadata and fresh provider state. This is a fixed-version compatibility recipe, not general inline-factory support; it requires the shipped file and the built-in's expected registration shape. Other opaque inline or custom extension resources that cannot be safely recreated are reported as unsupported and pause the Advisor; they are not silently reused or omitted. The Advisor's session state remains separate from the observed agent's state.
+Each watched agent has a private, persisted native Advisor Session with fresh, session-bound extension resources. Reviews reuse that session until context or configuration changes require rebuilding. Pi's enabled `builtin:<name>` extensions are recreated in their observed order: `codemode`, `tool-search`, and `mcp` from Pi's exported factories, and `llama.cpp` from the installed Pi package's shipped extension file, retaining their metadata and fresh provider state. Built-ins disabled with `-builtin:<name>` stay absent. If Pi no longer exports a needed factory, the Advisor pauses with that diagnostic. This is a built-in recreation recipe, not general inline-factory support; a host factory registered under a built-in name is rejected. Other opaque inline or custom extension resources that cannot be safely recreated are reported as unsupported and pause the Advisor; they are not silently reused or omitted. The Advisor's session state remains separate from the observed agent's state.
 
 Context Management is optional. If loaded and its tools are granted, `context_notes`, `context_history`, and `context_rollover` operate on the Advisor's private context. If any of those three tools is excluded, the Advisor pauses before reviewing. There is no autogrant or hook bypass.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-advisor",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "private": false,
   "description": "Background review and attributed corrective advice for Pi agent sessions.",
   "keywords": [
@@ -32,7 +32,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@ian-pascoe/pi-utils": "^0.2.0"
+    "@ian-pascoe/pi-utils": "^0.3.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",

package/skills/pi-advisor/SKILL.md

@@ -11,10 +11,10 @@ Use this sequence for a live Advisor problem:
 1. Run `/advisor status`. Record the effective settings, each setting's source, review state, backlog, usage/cost, and last error. Treat unknown cost as unknown, not zero.
 2. If the state is disabled, check the selected session override, trusted-project settings, and global settings in that order. Advisor defaults to disabled. Use `/advisor on`, `/advisor off`, `/advisor inherit`, or `/advisor set <key> <JSON>` at the intended scope; use `/advisor prompt` for the native prompt editor. Confirm the selected branch after resume, fork, or tree navigation.
 3. If the state is paused, read the reported capability, Review, or Consultation error. Correct the setting or unavailable runtime capability, then explicitly re-enable or reload as the diagnostic instructs. A pause leaves the observed agent running.
-4. If `advisor_ask` is missing, confirm Advisor is enabled; disabled Advisors intentionally hide it. A paused Advisor keeps the tool visible for its diagnostic. Check CodeMode exposure when the tool is available only through `codemode_execute`. Consultations wait for the active Review, return plain advice, and leave Review Backlog accounting unchanged. User cancellation does not pause Advisor; runtime failures do.
+4. If `advisor_ask` is missing, confirm Advisor is enabled; disabled Advisors intentionally hide it. A paused Advisor keeps the tool visible for its diagnostic. Under `codemode.mode: "only"` it stays active but undeclared, reachable only through `codemode` scripts. Consultations wait for the active Review, return plain advice, and leave Review Backlog accounting unchanged. User cancellation does not pause Advisor; runtime failures do.
 5. For missing reviews, inspect backlog and catch-up configuration. Backlog counts completed model responses with their tool batches, including work under review. `off` never waits; a positive threshold waits only while backlog is at least that threshold, and each wait is capped at 30 seconds. A Review has its own deadline, investigative-call limit, and `maxFindingsPerReview` limit of 1–32.
 6. If Context Management is loaded, verify that all three private tools—`context_notes`, `context_history`, and `context_rollover`—are explicitly granted. Any missing grant pauses Advisor before review. These tools operate on the Advisor Session's private Notes, History, and Checkpoints; they never grant access to the observed session. Confirm native settlement and checkpoint completion rather than treating an early response or `agent_end` report as completion.
-7. For tool or CodeMode failures, compare the effective `allowedTools` list with the loaded registry. Missing names are reported and ignored. CodeMode-only exposure needs an explicitly compatible transport grant; Advisor does not add aliases, autogrant tools, or change exposure mode. A Tool Grant covers the tool's full native interface and is not a filesystem or operation sandbox.
+7. For tool failures, compare the effective `allowedTools` list with the loaded registry. Missing names are reported and ignored; Advisor does not autogrant tools. Grant `codemode` explicitly for scripts. An inactive advice tool after extension binding pauses the Advisor. A Tool Grant covers the tool's full native interface and is not a filesystem or operation sandbox.
 8. For stale, duplicated, or unsafe advice, check branch/session identity and configuration-generation changes. Advisor Sessions are separate persisted native sessions with fresh extension resources. Unsupported opaque inline/custom resources pause rather than being reused. Nits use non-interrupting context delivery and never start Corrective Turns. Running Concerns and Blockers use Pi's native steering boundary; Blockers after normal interactive completion use only tracked, budgeted Corrective Turns. Deliberately interrupted, aborted, uncertain, and headless-completed work is preserved without restart. Child correction must finish inside Minimal's owned operation.
 9. On shutdown, allow only the bounded headless final drain. Verify that no hidden corrective turn starts after root completion and that native Advisor resources are aborted before disposal.
 

package/src/advisor-observer.ts

@@ -1,18 +1,8 @@
 import { isDeepStrictEqual } from "node:util";
-import {
-  contentText,
-  getCurrentSystemPrompt,
-  getCurrentTools,
-  toToolDeclaration,
-  type Context,
-  type ImageContent,
-} from "@earendil-works/pi-ai";
-import {
-  defineTool,
-  convertToLlm,
-  type AgentSession,
-  type AgentSessionRuntime,
-} from "@earendil-works/pi-coding-agent";
+import * as piAi from "@earendil-works/pi-ai";
+import type { Context, ImageContent } from "@earendil-works/pi-ai";
+import * as piSdk from "@earendil-works/pi-coding-agent";
+import type { AgentSession, AgentSessionRuntime } from "@earendil-works/pi-coding-agent";
 import { Type, type Static } from "typebox";
 import { Value } from "typebox/value";
 import type { AdvisorConfig } from "./advisor-settings.js";
@@ -65,7 +55,7 @@ const pendingQueuesSchema = Type.Object({
   _pendingCustomMessages: Type.Array(Type.Unknown()),
 });
 
-// oxlint-disable-next-line anti-slop/no-unknown-parameters -- SAFETY: Pi 0.87.1 has no selective queue-removal API. Validate its native queue data and remove only exact owned finding identities, never unrelated messages or journal entries.
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- SAFETY: Pi has no selective queue-removal API. Validate its native queue data and remove only exact owned finding identities, never unrelated messages or journal entries.
 function retractFindings(session: unknown, findings: ReadonlySet<Finding>): void {
   if (!findings.size) return;
   if (!Value.Check(pendingQueuesSchema, session))
@@ -168,7 +158,9 @@ function operationFailure(runtime: AgentSessionRuntime, since: number): string |
     .slice(since)
     .find((message) => message.role === "toolResult" && message.isError);
   if (!failedTool || failedTool.role !== "toolResult") return;
-  return contentText(failedTool.content).trim() || `Advisor tool ${failedTool.toolName} failed`;
+  return (
+    piAi.contentText(failedTool.content).trim() || `Advisor tool ${failedTool.toolName} failed`
+  );
 }
 
 /** Coalesced native review work; it never owns the observed tools, prompt, or agent loop. */
@@ -218,9 +210,9 @@ export class AdvisorObserver {
           // Pi carries the prompt and tool deltas as system messages. Replay them into the
           // current state and copy tool declarations, never execute callbacks.
           this.snapshot = structuredClone({
-            systemPrompt: getCurrentSystemPrompt(context.messages),
-            tools: getCurrentTools(context.messages).map((tool) => {
-              const { name, description, parameters } = toToolDeclaration(tool);
+            systemPrompt: piAi.getCurrentSystemPrompt(context.messages),
+            tools: piAi.getCurrentTools(context.messages).map((tool) => {
+              const { name, description, parameters } = piAi.toToolDeclaration(tool);
               return { name, description, parameters };
             }),
             messages: context.messages.filter((message) => message.role !== "system"),
@@ -250,7 +242,7 @@ export class AdvisorObserver {
         ...this.snapshot,
         messages: [
           ...this.snapshot.messages,
-          ...convertToLlm([event.message, ...event.toolResults]),
+          ...piSdk.convertToLlm([event.message, ...event.toolResults]),
         ],
       };
       if (
@@ -469,7 +461,7 @@ export class AdvisorObserver {
         },
         { additionalProperties: false },
       );
-      const adviceTool = defineTool({
+      const adviceTool = piSdk.defineTool({
         name: "advisor_report",
         label: "Advisor report",
         description: `Finish the Review with up to ${this.config.maxFindingsPerReview} concise, actionable findings. Prioritize blockers, then concerns, then worthwhile nits.`,
@@ -729,7 +721,7 @@ export class AdvisorObserver {
         throw new Error("Advisor consultation did not return an answer");
       if (last.stopReason === "error" || last.stopReason === "aborted")
         throw new Error(last.errorMessage ?? "Advisor consultation did not complete");
-      const answer = contentText(last.content).trim();
+      const answer = piAi.contentText(last.content).trim();
       if (!answer) throw new Error("Advisor consultation did not return a text answer");
       this.supplied = snapshot;
       this.suppliedBoundary = consultation.boundary;

package/src/advisor-runtime.ts

@@ -0,0 +1,97 @@
+import * as piAi from "@earendil-works/pi-ai";
+import * as piSdk from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+
+const callable = Type.Function([], Type.Unknown());
+
+/** True when a native SDK member is present and callable. */
+export function isCallable<T>(value: T): boolean {
+  return Value.Check(callable, value);
+}
+
+/** True when `owner` exposes `name` as a callable, including module getters and inherited methods. */
+function hasMember<T extends object>(owner: T | undefined, name: string): boolean {
+  if (!owner) return false;
+  if (Value.Check(Type.Object({ [name]: callable }), owner)) return true;
+  // TypeBox does not treat classes as objects, so read class statics as own data properties.
+  return isCallable(Object.getOwnPropertyDescriptor(owner, name)?.value);
+}
+
+function missingMembers<T extends object>(
+  label: string,
+  owner: T | undefined,
+  names: readonly string[],
+): string[] {
+  return names.filter((name) => !hasMember(owner, name)).map((name) => `${label}${name}`);
+}
+
+/**
+ * Pi capabilities the Advisor needs to observe a session and recreate a private native one.
+ * Modules are read through namespaces so a missing export is reported here instead of failing
+ * extension load. Built-in extension factories are checked only when the observed session uses them.
+ */
+export function advisorRuntimeIssues(
+  ai: Partial<typeof piAi> = piAi,
+  sdk: Partial<typeof piSdk> = piSdk,
+): string[] {
+  return [
+    ...missingMembers("pi-ai ", ai, [
+      "InMemoryCredentialStore",
+      "contentText",
+      "getCurrentSystemPrompt",
+      "getCurrentTools",
+      "toToolDeclaration",
+    ]),
+    ...missingMembers("", sdk, [
+      "AgentSession",
+      "AgentSessionRuntime",
+      "DefaultResourceLoader",
+      "ModelRuntime",
+      "SessionManager",
+      "SettingsManager",
+      "convertToLlm",
+      "createAgentSessionFromServices",
+      "createAgentSessionRuntime",
+      "createAgentSessionServices",
+      "defineTool",
+    ]),
+    ...missingMembers("SessionManager.", sdk.SessionManager, ["create"]),
+    ...missingMembers("SettingsManager.", sdk.SettingsManager, ["fromStorage"]),
+    ...missingMembers("SettingsManager#", sdk.SettingsManager?.prototype, [
+      "applyOverrides",
+      "getGlobalSettings",
+      "getProjectSettings",
+      "isProjectTrusted",
+    ]),
+    ...missingMembers("ModelRuntime.", sdk.ModelRuntime, ["create"]),
+    ...missingMembers("ModelRuntime#", sdk.ModelRuntime?.prototype, [
+      "getAuth",
+      "getModel",
+      "getRegisteredProviderIds",
+      "isUsingOAuth",
+      "listCredentials",
+      "setRuntimeApiKey",
+    ]),
+    ...missingMembers("AgentSession#", sdk.AgentSession?.prototype, [
+      "abort",
+      "bindExtensions",
+      "getActiveToolNames",
+      "getAllTools",
+      "getSessionStats",
+      "prompt",
+      "sendCustomMessage",
+      "subscribe",
+    ]),
+    ...missingMembers("AgentSessionRuntime#", sdk.AgentSessionRuntime?.prototype, [
+      "dispose",
+      "setRebindSession",
+    ]),
+  ];
+}
+
+/** User-facing explanation for unmet requirements, or undefined when the runtime is supported. */
+export function advisorRuntimeWarning(issues = advisorRuntimeIssues()): string | undefined {
+  if (!issues.length) return undefined;
+  return `Advisor is unavailable: this Pi runtime lacks ${issues.join(", ")}`;
+}

package/src/advisor-session.ts

@@ -3,27 +3,23 @@ import { join } from "node:path";
 import { isDeepStrictEqual } from "node:util";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
-import { InMemoryCredentialStore } from "@earendil-works/pi-ai";
-import {
-  createAgentSessionServices,
-  createAgentSessionFromServices,
-  createAgentSessionRuntime,
-  DefaultResourceLoader,
-  getPackageDir,
-  ModelRuntime,
+import * as piAi from "@earendil-works/pi-ai";
+import * as piSdk from "@earendil-works/pi-coding-agent";
+import type {
+  SourceInfo,
+  CreateModelRuntimeOptions,
+  AgentSession,
+  AgentSessionRuntime,
+  CreateAgentSessionRuntimeFactory,
+  CreateAgentSessionFromServicesOptions,
+  Extension,
+  ExtensionFactory,
+  InlineExtension,
   SessionManager,
-  SettingsManager,
-  VERSION,
-  type SourceInfo,
-  type CreateModelRuntimeOptions,
-  type AgentSession,
-  type AgentSessionRuntime,
-  type CreateAgentSessionRuntimeFactory,
-  type CreateAgentSessionFromServicesOptions,
-  type ExtensionFactory,
-  type ToolDefinition,
+  ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import type { AdvisorConfig } from "./advisor-settings.js";
+import { advisorRuntimeWarning, isCallable } from "./advisor-runtime.js";
 
 /** Explicit file-selection recipe supplied by the resource owner, never inferred from opaque loaders. */
 export interface AdvisorResourceInputs {
@@ -51,6 +47,21 @@ const roleSchema = Type.Object({
   observedSessionId: Type.String({ minLength: 1 }),
 });
 
+// Pi exports fresh factories for these `builtin:<name>` extensions, but not llama.cpp.
+const builtinFactories = new Map<
+  string,
+  "createCodemodeExtension" | "createToolSearchExtension" | "createMcpExtension"
+>([
+  ["codemode", "createCodemodeExtension"],
+  ["tool-search", "createToolSearchExtension"],
+  ["mcp", "createMcpExtension"],
+]);
+const registrationNames = ({ tools, commands, flags }: Extension) => [
+  ...[...tools.keys()].map((name) => `tool:${name}`),
+  ...[...commands.keys()].map((name) => `command:${name}`),
+  ...[...flags.keys()].map((name) => `flag:${name}`),
+];
+
 /** Private role is native journal state and is installed before session_start. */
 export function isAdvisorSession(manager: Pick<SessionManager, "getBranch">): boolean {
   return manager
@@ -72,7 +83,7 @@ export async function disposeAdvisorSession(runtime: AgentSessionRuntime): Promi
   }
 }
 
-// Pi 0.87.1 keeps these plain constructor inputs private; public scoped getters omit applyOverrides.
+// Pi keeps these plain constructor inputs private; public scoped getters omit applyOverrides.
 /* oxlint-disable anti-slop/no-unknown-parameters -- SAFETY: Capability-check native SDK data before copying; offline SDK creation tests cover these inputs. */
 function recreationInputs(
   loader: unknown,
@@ -111,7 +122,7 @@ function recreationInputs(
   if (
     Value.Check(fileAuthSchema, store) &&
     store.authPath === store.storage.authPath &&
-    // Pi 0.87.1's bundled CLI names the same native class _AuthStorage.
+    // Pi's bundled CLI names the same native class _AuthStorage.
     ["AuthStorage", "_AuthStorage"].includes(Object.getPrototypeOf(store)?.constructor.name) &&
     Object.getPrototypeOf(store.storage)?.constructor.name === "FileAuthStorageBackend"
   )
@@ -136,10 +147,8 @@ export async function createAdvisorSession(
   observed: AgentSession,
   options: AdvisorSessionOptions,
 ): Promise<AgentSessionRuntime> {
-  if (VERSION !== "0.87.1")
-    throw new Error(
-      `Unsupported Pi ${VERSION}: Advisor's native tool ceiling and session lifecycle are verified on Pi 0.87.1`,
-    );
+  const unsupported = advisorRuntimeWarning();
+  if (unsupported) throw new Error(unsupported);
   options.signal?.throwIfAborted();
   const cancelled = Promise.withResolvers<never>();
   const abort = () =>
@@ -161,7 +170,7 @@ async function buildAdvisorSession(
   const source = observed.resourceLoader;
   if (
     !options.resourceInputs &&
-    Object.getPrototypeOf(source) !== DefaultResourceLoader.prototype
+    Object.getPrototypeOf(source) !== piSdk.DefaultResourceLoader.prototype
   ) {
     throw new Error(
       "Unsupported Advisor resources: custom loaders/transformations require fresh owner-supplied recreation inputs",
@@ -200,38 +209,54 @@ async function buildAdvisorSession(
     )
       throw new Error("Advisor resource owner flags do not match the observed flags");
   }
-  const extensionPaths = source.getExtensions().extensions.map((extension) => {
-    if (extension.resolvedPath && !extension.resolvedPath.startsWith("<"))
-      return extension.resolvedPath;
-    // Pi 0.87.1 injects this built-in inline, but ships a fresh file-backed factory.
-    // Match its registration shape, not arbitrary inline closures or hidden extensions.
-    if (
-      extension.path === "<inline:llama.cpp>" &&
+  // Pi names its built-in extensions `builtin:<name>`; fresh factories must reproduce them.
+  const builtins: InlineExtension[] = [];
+  const recreated = new Set<number>();
+  const extensionPaths = source.getExtensions().extensions.map((extension, index) => {
+    const name = extension.path.slice("builtin:".length);
+    const builtin =
+      extension.path.startsWith("builtin:") &&
       extension.resolvedPath === extension.path &&
-      extension.hidden === true &&
-      extension.commands.size === 1 &&
-      extension.commands.has("llama") &&
-      [
-        extension.handlers,
-        extension.tools,
-        extension.messageRenderers,
-        extension.entryRenderers,
-        extension.flags,
-        extension.shortcuts,
-      ].every((registrations) => !registrations?.size) &&
-      !extension.markdownTransformer
-    ) {
-      const path = join(getPackageDir(), "dist", "extensions", "llama", "index.js");
+      extension.sourceInfo.source === "builtin";
+    if (!builtin && extension.resolvedPath && !extension.resolvedPath.startsWith("<"))
+      return extension.resolvedPath;
+    const factoryExport = builtinFactories.get(name);
+    if (builtin && factoryExport) {
+      const create = piSdk[factoryExport];
+      if (!isCallable(create))
+        throw new Error(
+          `Unsupported Advisor resources: this Pi runtime does not export ${factoryExport} to recreate ${extension.path}`,
+        );
+      recreated.add(index);
+      builtins.push({
+        name,
+        factory: create(),
+        builtin: true,
+        replaceable: extension.replaceable === true,
+      });
+      return extension.path;
+    }
+    // Pi ships a fresh file-backed llama.cpp factory but does not export it.
+    if (builtin && name === "llama.cpp") {
+      if (!isCallable(piSdk.getPackageDir))
+        throw new Error(
+          "Unsupported Advisor resources: this Pi runtime does not export getPackageDir to locate llama.cpp",
+        );
+      const path = join(piSdk.getPackageDir(), "dist", "extensions", "llama", "index.js");
       if (!existsSync(path))
         throw new Error(
           `Unsupported Advisor resources: Pi's built-in llama.cpp file is unavailable (${path})`,
         );
+      recreated.add(index);
       return path;
     }
     throw new Error(
       `Unsupported Advisor resources: inline factories require fresh owner-supplied recreation inputs (${extension.path})`,
     );
   });
+  const registrations = source
+    .getExtensions()
+    .extensions.map((extension) => new Set(registrationNames(extension)));
   const flags = new Map(observed.extensionRunner?.getFlagValues());
   const global = JSON.stringify(observed.settingsManager.getGlobalSettings());
   const project = JSON.stringify(observed.settingsManager.getProjectSettings());
@@ -299,7 +324,7 @@ async function buildAdvisorSession(
       ["global", global],
       ["project", project],
     ]);
-    const settingsManager = SettingsManager.fromStorage(
+    const settingsManager = piSdk.SettingsManager.fromStorage(
       {
         withLock(scope, update) {
           const next = update(scopes.get(scope));
@@ -320,12 +345,12 @@ async function buildAdvisorSession(
     };
     if (constructionSignal) modelInputs.signal = constructionSignal;
     if (authPath) modelInputs.authPath = authPath;
-    else modelInputs.credentials = new InMemoryCredentialStore();
-    const modelRuntime = await ModelRuntime.create(modelInputs);
+    else modelInputs.credentials = new piAi.InMemoryCredentialStore();
+    const modelRuntime = await piSdk.ModelRuntime.create(modelInputs);
     const operation = constructionSignal ? { signal: constructionSignal } : undefined;
     for (const [provider, apiKey] of runtimeApiKeys)
       await modelRuntime.setRuntimeApiKey(provider, apiKey, operation);
-    const services = await createAgentSessionServices({
+    const services = await piSdk.createAgentSessionServices({
       cwd,
       agentDir,
       settingsManager,
@@ -334,9 +359,25 @@ async function buildAdvisorSession(
         noExtensions: true,
         noContextFiles: true,
         additionalExtensionPaths: extensionPaths,
-        extensionFactories: options.controlExtension
-          ? [{ name: "advisor-control", factory: options.controlExtension }]
-          : [],
+        extensionFactories: [
+          ...builtins,
+          ...(options.controlExtension
+            ? [{ name: "advisor-control", factory: options.controlExtension }]
+            : []),
+        ],
+        // CLI paths load built-ins first; restore the observed order before binding.
+        extensionsOverride: (base) => {
+          const rank = (path: string) => {
+            const index = extensionPaths.indexOf(path);
+            return index < 0 ? extensionPaths.length : index;
+          };
+          return {
+            ...base,
+            extensions: base.extensions.toSorted(
+              (left, right) => rank(left.resolvedPath) - rank(right.resolvedPath),
+            ),
+          };
+        },
         systemPromptOverride: () => config.prompt,
         appendSystemPromptOverride: () => [],
       },
@@ -377,6 +418,14 @@ async function buildAdvisorSession(
       inherited.forEach((original, index) => {
         const fresh = loaded.extensions[index];
         if (!fresh) throw new Error("Advisor inherited extension is unavailable");
+        // A host-supplied factory under a built-in name registers what Pi's own does not.
+        if (
+          recreated.has(index) &&
+          registrationNames(fresh).some((name) => !registrations[index]?.has(name))
+        )
+          throw new Error(
+            `Unsupported Advisor resources: ${original.path} does not match Pi's built-in extension`,
+          );
         fresh.path = original.path;
         fresh.resolvedPath = original.resolvedPath;
         if (original.hidden === undefined) delete fresh.hidden;
@@ -402,13 +451,13 @@ async function buildAdvisorSession(
       customTools: [options.adviceTool],
     };
     if (sessionStartEvent) sessionOptions.sessionStartEvent = sessionStartEvent;
-    const created = await createAgentSessionFromServices(sessionOptions);
+    const created = await piSdk.createAgentSessionFromServices(sessionOptions);
     return { ...created, services, diagnostics: services.diagnostics };
   };
-  const runtime = await createAgentSessionRuntime(factory, {
+  const runtime = await piSdk.createAgentSessionRuntime(factory, {
     cwd: observed.sessionManager.getCwd(),
     agentDir,
-    sessionManager: SessionManager.create(
+    sessionManager: piSdk.SessionManager.create(
       observed.sessionManager.getCwd(),
       join(observed.sessionManager.getSessionDir(), "advisors", observed.sessionId),
     ),
@@ -429,23 +478,20 @@ async function buildAdvisorSession(
     options.signal?.throwIfAborted();
     bindingStarted = true;
     await bind(runtime.session);
-    const active = runtime.session.getActiveToolNames();
-    const bridgeAvailable =
-      config.allowedTools.includes("codemode_execute") && active.includes("codemode_execute");
-    const codeModeLoaded = source
-      .getExtensions()
-      .extensions.some((extension) => extension.tools.has("codemode_execute"));
-    const hiddenGrants = runtime.session
+    if (!runtime.session.getActiveToolNames().includes(options.adviceTool.name))
+      throw new Error(
+        `Advisor advice tool is inactive after extension binding: ${options.adviceTool.name}`,
+      );
+    // The native `tools` option is the Advisor's tool ceiling; verify this runtime enforces it.
+    const ceiling = new Set([...config.allowedTools, options.adviceTool.name]);
+    const escaped = runtime.session
       .getAllTools()
-      .filter((tool) => config.allowedTools.includes(tool.name) && !active.includes(tool.name));
-    if (
-      (!active.includes(options.adviceTool.name) || (codeModeLoaded && hiddenGrants.length > 0)) &&
-      !bridgeAvailable
-    ) {
+      .map(({ name }) => name)
+      .filter((name) => !ceiling.has(name));
+    if (escaped.length)
       throw new Error(
-        "Advisor tools are hidden by inherited exposure policy; grant the CodeMode execution tool explicitly or configure direct exposure",
+        `Unsupported Pi runtime: the Advisor tool ceiling admitted ungranted tools (${escaped.join(", ")})`,
       );
-    }
     options.signal?.throwIfAborted();
     const failure = runtime.diagnostics.find((item) => item.type === "error");
     if (failure) throw new Error(failure.message);

package/src/advisor-settings.ts

@@ -171,7 +171,7 @@ const storageSchema = Type.Object({
   ),
 });
 
-/** Use Pi's actual backend: its generic storage API is not exported in 0.87.1. */
+/** Use Pi's actual backend: its generic storage API is not exported. */
 export async function writeAdvisorSettings(
   manager: SettingsManager,
   scope: "global" | "project",

package/src/index.ts

@@ -1,8 +1,5 @@
-import {
-  AgentSession,
-  type ExtensionAPI,
-  type ExtensionContext,
-} from "@earendil-works/pi-coding-agent";
+import * as piSdk from "@earendil-works/pi-coding-agent";
+import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isDeepStrictEqual } from "node:util";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
@@ -21,6 +18,7 @@ import {
 import { completeAdvisorCommandArguments, parseAdvisorCommand } from "./advisor-command.js";
 import { AdvisorObserver } from "./advisor-observer.js";
 import { isAdvisorSession, type AdvisorResourceInputs } from "./advisor-session.js";
+import { advisorRuntimeWarning } from "./advisor-runtime.js";
 
 interface WatchedChild {
   agentId: string;
@@ -28,7 +26,6 @@ interface WatchedChild {
   observer: AdvisorObserver | undefined;
 }
 const askToolName = "advisor_ask";
-const codeModeToolAvailabilityEvent = "pi-codemode:request-tool-availability";
 const askToolParameters = Type.Object(
   { message: Type.String({ minLength: 1 }) },
   { additionalProperties: false },
@@ -47,6 +44,9 @@ const childRequestSchema = Type.Object({
 
 /** Review an observed session without changing its tools or standing instructions. */
 export default function advisor(pi: ExtensionAPI): void {
+  // Capability checks, not version pins: an unmet requirement warns and leaves the Advisor unavailable.
+  const unsupported = advisorRuntimeWarning();
+  let warn: (message: string) => void = () => {};
   let observed: AgentSession | undefined;
   let error: string | undefined;
   let layers: AdvisorLayers = { global: {}, project: {} };
@@ -89,17 +89,6 @@ export default function advisor(pi: ExtensionAPI): void {
       return;
     }
     if (!askToolRegistered) return;
-    let handled = false;
-    if (rootSessionId)
-      pi.events.emit(codeModeToolAvailabilityEvent, {
-        sessionId: rootSessionId,
-        toolName: askToolName,
-        available,
-        handled: () => {
-          handled = true;
-        },
-      });
-    if (handled) return;
     const active = pi.getActiveTools();
     if (available === active.includes(askToolName)) return;
     pi.setActiveTools(
@@ -141,7 +130,21 @@ export default function advisor(pi: ExtensionAPI): void {
       setAskToolAvailable(false);
       return;
     }
-    const found = discoverPiAgentSession(pi, AgentSession);
+    const { ui } = ctx;
+    warn = (message) => {
+      try {
+        ui.notify(message, "warning");
+      } catch {
+        // A replaced session's UI is stale; the native status entry remains the durable record.
+      }
+    };
+    if (unsupported) {
+      error = unsupported;
+      setAskToolAvailable(false);
+      warn(unsupported);
+      return;
+    }
+    const found = discoverPiAgentSession(pi, piSdk.AgentSession);
     if (found.ok) {
       observed = found.session;
       layers = readAdvisorLayers(observed.settingsManager);
@@ -185,12 +188,13 @@ export default function advisor(pi: ExtensionAPI): void {
       child.observer = new AdvisorObserver(session, config, "owned-child", {
         resourceInputs: child.resourceInputs,
         onError: (message) => {
-          if (children.get(session) === child)
-            pi.appendEntry("pi-advisor-child", {
-              agentId: child.agentId,
-              state: "paused",
-              error: message,
-            });
+          if (children.get(session) !== child) return;
+          pi.appendEntry("pi-advisor-child", {
+            agentId: child.agentId,
+            state: "paused",
+            error: message,
+          });
+          warn(`Advisor for ${child.agentId} paused: ${message}`);
         },
         onIntervention: (finding) => {
           if (children.get(session) === child)
@@ -201,10 +205,14 @@ export default function advisor(pi: ExtensionAPI): void {
 
   // oxlint-disable-next-line anti-slop/no-unknown-parameters -- SAFETY: The native owner bus is a boundary; validate identity, SDK instance, and exact resource metadata before attachment.
   function attachChild(payload: unknown): void {
-    if (!Value.Check(childRequestSchema, payload) || !(payload.session instanceof AgentSession))
+    if (
+      unsupported ||
+      !Value.Check(childRequestSchema, payload) ||
+      !(payload.session instanceof piSdk.AgentSession)
+    )
       return;
     if (!observed) {
-      const found = discoverPiAgentSession(pi, AgentSession);
+      const found = discoverPiAgentSession(pi, piSdk.AgentSession);
       if (!found.ok) return;
       observed = found.session;
       layers = readAdvisorLayers(observed.settingsManager);
@@ -266,8 +274,10 @@ export default function advisor(pi: ExtensionAPI): void {
           settings,
           ctx.hasUI ? "interactive" : "headless-root",
           {
-            onError: (message) =>
-              pi.appendEntry("pi-advisor-status", { state: "paused", error: message }),
+            onError: (message) => {
+              pi.appendEntry("pi-advisor-status", { state: "paused", error: message });
+              warn(`Advisor paused: ${message}`);
+            },
           },
         );
       for (const [session, child] of children) configureChild(session, child, settings);