@mrclrchtr/supi-consulting 11.2.0 → 11.3.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [11.3.0]
+
+- Added package-specific release notes for bounded agent consultations.
+- Consultations now use an explicit read-only Antigravity tool selection for web search, direct URL reading, and workspace inspection, with structured completion and observed source evidence.
+- Follow-ups that ask the agent not to use tools no longer fail with an unverifiable answer.
+- Reading cached web pages no longer reports workspace use or a misleading workspace warning.
+- Requires Antigravity CLI `1.4.9` or newer. Start a new Consultation after upgrading: existing default-agent Conversation Handles cannot gain the new tools; they are rejected before process startup, retired, and recorded as `info`-level `consultation.rejected` Debug events instead of errors.

package/CLAUDE.md

@@ -9,7 +9,7 @@
 - Keep agent-specific models, authentication, process code, protocol parsing, and tool-activity classification in `src/agents/antigravity/`. Shared workflow uses the private interface in `src/agents/types.ts`.
 - Keep each Model Catalogue immutable until the next session start or reload. Register `consulting_run` only after agent discovery succeeds.
 - Require explicit agent, model, and Workspace Access for a new Consultation. Keep `new` and `continue` exact-one; follow-ups inherit all selections and their working directory.
-- Acquire a handle before process work. Report process start, including hook probes, through the adapter interface. Reject overlap before startup; retire only after a started follow-up fails or is canceled.
+- Acquire a handle before process work. Report process start, including hook probes, through the adapter interface. Reject overlap before startup; retire after a started follow-up fails or is canceled, or when the adapter rejects incompatible continuation state (which can never succeed).
 - Keep raw conversation IDs opaque to shared policy. Persist only new consulting handle records and results; old Antigravity state has no migration or legacy read path.
 - Use `<PI agent dir>/supi/consulting/antigravity/` for Antigravity state. Leave the old `supi/antigravity/` tree untouched.
 - Use the Isolated Antigravity Home for every `agy` process. On macOS, create and unlock its private keychain, exposed as the login keychain, before startup. Do not copy the normal profile, credentials, or PI provider environment.

package/README.md

@@ -44,7 +44,7 @@ cd "<consultation-workspace>" &&
 HOME="<isolated-home>" AGY_CLI_DISABLE_AUTO_UPDATE=true agy
 ```
 
-On macOS, the adapter creates and unlocks a private keychain inside the Isolated Antigravity Home. It exposes that keychain as the login keychain without prompting for the normal keychain password. Run the displayed command, sign in, exit Antigravity, and reload Pi. The installed `agy` version must be at least `1.1.24`.
+On macOS, the adapter creates and unlocks a private keychain inside the Isolated Antigravity Home. It exposes that keychain as the login keychain without prompting for the normal keychain password. Run the displayed command, sign in, exit Antigravity, and reload Pi. The installed `agy` version must be at least `1.4.9`.
 
 If macOS displays `antigravity.` in a warning, the final `.` is sentence punctuation, not part of a keychain name.
 
@@ -76,10 +76,24 @@ A follow-up supplies only a returned Conversation Handle:
 }
 ```
 
-Supply exactly one of `new` and `continue`. Follow-ups retain the original agent, model, working directory, and Workspace Access. A handle is opaque and branch-aware. It is retired if a follow-up fails or is canceled after process work starts. Overlapping follow-ups on the same handle are rejected.
+Supply exactly one of `new` and `continue`. Follow-ups retain the original agent, model, working directory, and Workspace Access. A handle is opaque and branch-aware. It is retired if a follow-up fails or is canceled after process work starts, or if its continuation state is incompatible. Overlapping follow-ups on the same handle are rejected.
 
 Results report web use, workspace use, observed and claimed references, warnings, token use, and the Conversation Handle. An answer can claim a reference without matching tool activity; SuPi labels that reference as claimed, not observed.
 
+### Inspection tools and existing handles
+
+New Antigravity conversations use a package-owned temporary agent definition with explicit web search (`search_web`), direct URL reading (`read_url_content`), read-only file inspection (`view_file`, `list_dir`, `find_by_name`, `grep_search`), and structured completion (`finish`). The default Antigravity agent's tool selection is not used. A permission such as `read_url(*)` authorizes access; it does not itself make a URL-reading tool available.
+
+The definition lives in the Isolated Antigravity Home under a random name to avoid workspace-agent name collisions. SuPi removes it after the process, including ordinary failures, timeouts, and cancellation. A hard process crash can leave a temporary definition behind. Follow-ups resume the saved conversation without a new agent override; Antigravity retains the original definition even after its file is removed.
+
+**Start a new Consultation after upgrading from the default-agent integration.** Old Conversation Handles cannot acquire the inspection tools by resuming. SuPi rejects legacy or incompatible profile continuations before starting any Antigravity process, retires the handle, and asks for a new Consultation. Profile compatibility is tracked privately; the calling tool's input shape is unchanged.
+
+Follow-up prompts get one fixed line asking the agent to end with `finish` using the current schema. Without it, a follow-up such as "do not use any tools" can skip `finish`, and Antigravity then replays the previous turn's answer, which SuPi rejects as unbound.
+
+Antigravity caches fetched pages inside its own conversation state and may read them back with `view_file`. File activity whose path resolves outside the selected workspace and configured read-only directories is treated as agent-internal: it does not count as workspace use or workspace evidence. File calls without a classifiable path remain counted.
+
+Web activity alone does not prove a cited page was read. For research, the agent is instructed to search for sources and directly read relevant pages before citing them. SuPi still classifies references from observed activity, not from the agent's claims. The CLI's startup tool inventory is not treated as proof that a tool is active for the selected agent.
+
 Use `/supi-settings` → **Consulting** to disable the tool. Disabling it skips availability checks and removes `consulting_run` from the active tool list.
 
 ## Additional read-only directories
@@ -120,13 +134,13 @@ An observed tool permission denial is reported separately. It does not prove the
 
 Failure messages returned to the calling agent include the observed terminal status and denial counts by fixed operation category (`command`, `file-read`, `file-write`, `web-read`, `browser`, `mcp`, or `other`). They distinguish a successful agent terminal status from a usable final answer and recommend permitted inspection or a limited/blocked report rather than repeating denied actions unchanged. This feedback remains available when Debug is disabled.
 
-When SuPi Debug is enabled, failed executions emit one `consulting/consultation.failed` event at `error` level. Cancellations emit `consulting/consultation.cancelled` at `info` level. Use the `debug` tool:
+When SuPi Debug is enabled, failed executions emit one `consulting/consultation.failed` event at `error` level. Cancellations emit `consulting/consultation.cancelled` at `info` level. Rejected incompatible Conversation Handles emit `consulting/consultation.rejected` at `info` level; no process was started for them. Use the `debug` tool:
 
 ```json
 { "source": "consulting", "level": "error", "limit": 10 }
 ```
 
-Omit `level` to include cancellations. Add `sessionFile` to inspect events persisted in a saved PI session. A response aborted before the adapter starts has no Consulting event.
+Omit `level` to include cancellations and rejected handles. Add `sessionFile` to inspect events persisted in a saved PI session. A response aborted before the adapter starts has no Consulting event.
 
 Events contain the execution phase, timing, selected model, workspace-access and follow-up flags, failure category and reason, and available event counts, terminal-state flags, permission-denial count, and exit code. `permissionDenialsByOperation` breaks down deduplicated denials by fixed category; unknown tool names become `other`. `deniedFileAccessOutsideReadRoots` counts denied file operations whose requested paths resolve outside the selected directory and configured additional read-only directories, following symlinks and existing parents of missing targets. Unavailable path information, dangling symlink destinations, and paths containing parent traversal (`..`) remain unclassified rather than risking an incorrect outside-root claim. This location observation does not identify which rule caused a denial.
 
@@ -163,4 +177,4 @@ The live probe requires separate approval and sign-in. It never runs in normal t
 SUPI_CONSULTING_LIVE=1 pnpm exec jiti packages/supi-consulting/scripts/live-probe.ts
 ```
 
-It uses the isolated profile and checks web evidence, follow-up context, workspace evidence, and byte-identical fixture state.
+It uses the isolated profile and requires successful web search and direct URL reading, an observed source matching the fetched URL, and a schema-validated follow-up that retains context and the URL reader after the temporary definition has been removed. It also checks observed workspace evidence and byte-identical fixture state. The direct-reader checks use the private process interface; workspace checks use the Consulting Agent adapter. No paid capability checks run during normal discovery.

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "11.2.0",
+  "version": "11.3.0",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {

package/node_modules/@mrclrchtr/supi-core/src/child-web-tools.ts

@@ -0,0 +1,110 @@
+// Session-provided Web tools for SuPi child sessions (Agent Runs and Reviewer Sessions).
+//
+// The loaded supi-web extension answers a synchronous request on the parent event bus.
+// Consumers never depend on supi-web; when it is absent or provides no tools, the
+// request returns undefined and the child simply lacks Web tools.
+
+import type { ExtensionAPI, ExtensionFactory } from "@earendil-works/pi-coding-agent";
+
+/** Web tools that child sessions may receive when the containing session provides them. */
+export const CHILD_WEB_TOOL_NAMES = [
+  "web_fetch_md",
+  "web_search",
+  "web_docs_search",
+  "web_docs_fetch",
+] as const;
+
+/** One session-provided Web tool name. */
+export type ChildWebToolName = (typeof CHILD_WEB_TOOL_NAMES)[number];
+
+/**
+ * Web tools currently callable in the containing session plus a child-only extension
+ * factory that registers them. The factory must not capture the parent session; it may
+ * capture plain data such as the containing session's configuration directory.
+ */
+export interface ChildWebToolProvision {
+  readonly toolNames: readonly ChildWebToolName[];
+  /** Register the requested subset of `toolNames` in a child session. */
+  readonly createFactory: (toolNames: readonly ChildWebToolName[]) => ExtensionFactory;
+}
+
+/** Plain containing-session data supplied with a child Web tool request. */
+export interface ChildWebToolsRequestContext {
+  /**
+   * Working directory whose SuPi configuration governs Web settings such as Firecrawl.
+   * Children with a different cwd (for example a frozen Review Workspace) keep this policy.
+   */
+  readonly configCwd: string;
+}
+
+type EventBusLike = Pick<ExtensionAPI["events"], "on" | "emit">;
+
+const REQUEST_CHANNEL = "supi:child-web-tools:request";
+const RESPONSE_CHANNEL = "supi:child-web-tools:response";
+
+interface ChildWebToolsRequest extends ChildWebToolsRequestContext {
+  readonly requestId: string;
+}
+
+interface ChildWebToolsResponse {
+  readonly requestId: string;
+  readonly provision: ChildWebToolProvision;
+}
+
+let nextRequestId = 0;
+
+/**
+ * Answer child Web tool requests on the parent event bus. The callback must be synchronous
+ * because Pi's event bus does not await listeners. Returns an unsubscribe function.
+ */
+export function provideChildWebTools(
+  events: EventBusLike,
+  resolve: (context: ChildWebToolsRequestContext) => ChildWebToolProvision | undefined,
+): () => void {
+  return events.on(REQUEST_CHANNEL, (data) => {
+    const request = data as Partial<ChildWebToolsRequest> | undefined;
+    if (typeof request?.requestId !== "string" || typeof request.configCwd !== "string") return;
+    const { requestId, configCwd } = request;
+    const provision = resolve({ configCwd });
+    if (!provision || provision.toolNames.length === 0) return;
+    events.emit(RESPONSE_CHANNEL, { requestId, provision } satisfies ChildWebToolsResponse);
+  });
+}
+
+/** Capture the Web tools the containing session currently provides, if any. */
+export function requestChildWebTools(
+  events: EventBusLike,
+  context: ChildWebToolsRequestContext,
+): ChildWebToolProvision | undefined {
+  const requestId = `child-web-${process.pid}-${++nextRequestId}`;
+  let provision: ChildWebToolProvision | undefined;
+  const unsubscribe = events.on(RESPONSE_CHANNEL, (data) => {
+    const response = data as Partial<ChildWebToolsResponse> | undefined;
+    if (response?.requestId === requestId && response.provision) provision = response.provision;
+  });
+  try {
+    events.emit(REQUEST_CHANNEL, { requestId, ...context } satisfies ChildWebToolsRequest);
+  } finally {
+    unsubscribe();
+  }
+  return provision;
+}
+
+/**
+ * Return the Web tools callable in a session under Pi's exposure rules: active `direct`
+ * tools, plus registered `codemode` and `deferred` tools. `model-only` and `hidden`
+ * tools are not callable.
+ */
+export function callableChildWebToolNames(
+  pi: Pick<ExtensionAPI, "getAllTools" | "getActiveTools">,
+): ChildWebToolName[] {
+  const active = new Set(pi.getActiveTools());
+  const exposures = new Map(
+    pi.getAllTools().map((tool) => [tool.name, tool.exposure ?? "direct"] as const),
+  );
+  return CHILD_WEB_TOOL_NAMES.filter((name) => {
+    const exposure = exposures.get(name);
+    if (exposure === "direct") return active.has(name);
+    return exposure === "codemode" || exposure === "deferred";
+  });
+}

package/node_modules/@mrclrchtr/supi-core/src/session.ts

@@ -1,5 +1,16 @@
 // supi-core session domain — session utilities and registries.
 
+export type {
+  ChildWebToolName,
+  ChildWebToolProvision,
+  ChildWebToolsRequestContext,
+} from "./child-web-tools.ts";
+export {
+  CHILD_WEB_TOOL_NAMES,
+  callableChildWebToolNames,
+  provideChildWebTools,
+  requestChildWebTools,
+} from "./child-web-tools.ts";
 export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
 export type {
   SessionCapabilitySkill,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-consulting",
-  "version": "11.2.0",
+  "version": "11.3.0",
   "description": "Bounded consultations with explicit agent and workspace selection and observed evidence",
   "license": "MIT",
   "repository": {
@@ -29,6 +29,7 @@
   ],
   "type": "module",
   "files": [
+    "CHANGELOG.md",
     "src/**/*.ts",
     "scripts/live-probe.ts",
     "README.md",
@@ -37,7 +38,7 @@
     "docs/adr/*.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "11.2.0"
+    "@mrclrchtr/supi-core": "11.3.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/scripts/live-probe.ts

@@ -4,11 +4,20 @@ import { tmpdir } from "node:os";
 import { join, relative } from "node:path";
 import { createAntigravityAdapter } from "../src/agents/antigravity/adapter.ts";
 import { getIsolatedAntigravityPaths } from "../src/agents/antigravity/isolated-home.ts";
-import { isHttpUrl, isSafeWorkspacePath } from "../src/tool/consulting_run/evidence.ts";
+import { runAntigravityConversation } from "../src/agents/antigravity/process/runner.ts";
+import { ANTIGRAVITY_ANSWER_SCHEMA } from "../src/agents/antigravity/structured-output.ts";
+import type { AntigravityExecutionFacts } from "../src/agents/antigravity/types.ts";
+import {
+  classifyAnswerEvidence,
+  isHttpUrl,
+  isSafeWorkspacePath,
+} from "../src/tool/consulting_run/evidence.ts";
+import type { ConsultationExecutionFacts } from "../src/types.ts";
 
 const LIVE_ENVIRONMENT = "SUPI_CONSULTING_LIVE";
 const MODEL = "gemini-3.8-flash-low";
 const CONTEXT_TOKEN = "supi-consulting-context-token";
+const SOURCE_URL = "https://nodejs.org/api/child_process.html";
 
 async function main(): Promise<void> {
   if (process.env[LIVE_ENVIRONMENT] !== "1") {
@@ -21,22 +30,56 @@ async function main(): Promise<void> {
     throw new Error("The selected model is not available to the isolated Antigravity account.");
   }
   const consultationWorkspace = await realpath(paths.consultationWorkspace);
-  const first = await adapter.execute({
-    prompt: `Remember the exact token ${CONTEXT_TOKEN}. Name one current official Node.js documentation page about subprocess cancellation and cite it.`,
+  // The process interface exposes successful tool names without adding them to the
+  // public Consultation contract. Mere web activity or claimed URLs cannot pass.
+  const processOptions = {
+    paths,
     model: MODEL,
-    canonicalWorkingDirectory: consultationWorkspace,
-    workspaceAccess: false,
+    cwd: consultationWorkspace,
+    schema: ANTIGRAVITY_ANSWER_SCHEMA as Record<string, unknown>,
+  };
+  const first = await runAntigravityConversation({
+    ...processOptions,
+    prompt: `Remember the exact token ${CONTEXT_TOKEN}. Use search_web to find official Node.js subprocess cancellation documentation, then use read_url_content to read ${SOURCE_URL}. Explain cancellation briefly and cite that exact fetched URL.`,
   });
-  requireWebEvidence(first);
+  if (!first.successfulToolNames.includes("search_web")) {
+    throw new Error("The live probe did not observe a successful web search.");
+  }
+  requireDirectRead(first, consultationWorkspace);
 
-  const second = await adapter.execute({
-    prompt:
-      "Without using tools, return only the exact context token I gave you in the preceding request.",
+  // The first run has already removed its temporary profile. Resume only by ID,
+  // proving the CLI retains the reader and finish capability in conversation state.
+  const second = await runAntigravityConversation({
+    ...processOptions,
+    prompt: `Read ${SOURCE_URL} again using read_url_content and cite that exact URL. In the answer field return only the exact context token I gave you in the preceding request.`,
+    conversationId: first.conversationId,
+  });
+  if (second.conversationId !== first.conversationId) {
+    throw new Error("The live probe resumed a different conversation.");
+  }
+  requireDirectRead(second, consultationWorkspace);
+
+  // A tool-free follow-up used to skip finish and replay the previous answer.
+  const toolFree = await adapter.execute({
+    prompt: "Return only the exact context token I gave you earlier. Do not use any tools.",
     model: MODEL,
     canonicalWorkingDirectory: consultationWorkspace,
     workspaceAccess: false,
-    continuation: first.continuation,
+    continuation: (
+      await adapter.execute({
+        prompt: `Remember the exact token ${CONTEXT_TOKEN}. Use read_url_content to read ${SOURCE_URL} and cite it.`,
+        model: MODEL,
+        canonicalWorkingDirectory: consultationWorkspace,
+        workspaceAccess: false,
+      })
+    ).continuation,
   });
+  if (toolFree.answer.answer.trim() !== CONTEXT_TOKEN) {
+    throw new Error("The tool-free follow-up did not return the current context token.");
+  }
+  if (toolFree.workspaceUsed) {
+    throw new Error("Cached page reads were misreported as workspace use.");
+  }
   if (second.answer.answer.trim() !== CONTEXT_TOKEN) {
     throw new Error(
       "The follow-up did not return the requested current-turn answer from conversation context.",
@@ -56,7 +99,7 @@ async function main(): Promise<void> {
       canonicalWorkingDirectory: fixture,
       workspaceAccess: true,
     });
-    requireWebEvidence(workspace);
+    requireWebEvidence(workspace, fixture);
     requireWorkspaceEvidence(workspace, fixture);
     if (!workspace.workspaceUsed) {
       throw new Error("The workspace probe did not observe workspace activity.");
@@ -68,40 +111,42 @@ async function main(): Promise<void> {
   }
 }
 
-function requireWebEvidence(result: { webUsed: boolean; answer: { sources: unknown[] } }): void {
-  if (!result.webUsed || result.answer.sources.length === 0) {
+type EvidenceFacts = Pick<
+  ConsultationExecutionFacts,
+  "answer" | "observedSourceHashes" | "observedWorkspacePathHashes"
+>;
+
+function requireDirectRead(result: AntigravityExecutionFacts, workspace: string): void {
+  if (!result.successfulToolNames.includes("read_url_content")) {
+    throw new Error("The live probe did not observe a successful direct URL read.");
+  }
+  requireWebEvidence(result, workspace);
+  const evidence = classifyAnswerEvidence(result.answer, result, workspace);
+  if (!evidence.observedSources.some((source) => source.url === SOURCE_URL)) {
+    throw new Error("The live probe did not return the fetched URL as observed evidence.");
+  }
+}
+
+function requireWebEvidence(result: EvidenceFacts, workspace: string): void {
+  const evidence = classifyAnswerEvidence(result.answer, result, workspace);
+  if (evidence.observedSources.length === 0) {
     throw new Error("The live probe did not observe web evidence.");
   }
-  if (
-    !result.answer.sources.every(
-      (source) => isRecord(source) && typeof source.url === "string" && isHttpUrl(source.url),
-    )
-  ) {
+  if (!result.answer.sources.every((source) => isHttpUrl(source.url))) {
     throw new Error("The live probe returned an invalid source URL.");
   }
 }
 
-function requireWorkspaceEvidence(
-  result: { answer: { workspaceEvidence: unknown[] } },
-  workspace: string,
-): void {
+function requireWorkspaceEvidence(result: EvidenceFacts, workspace: string): void {
+  const evidence = classifyAnswerEvidence(result.answer, result, workspace);
   if (
-    result.answer.workspaceEvidence.length === 0 ||
-    !result.answer.workspaceEvidence.every(
-      (item) =>
-        isRecord(item) &&
-        typeof item.path === "string" &&
-        isSafeWorkspacePath(item.path, workspace),
-    )
+    evidence.observedWorkspaceEvidence.length === 0 ||
+    !result.answer.workspaceEvidence.every((item) => isSafeWorkspacePath(item.path, workspace))
   ) {
-    throw new Error("The live probe did not return valid workspace evidence.");
+    throw new Error("The live probe did not return observed, valid workspace evidence.");
   }
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 async function digestTree(directory: string): Promise<string> {
   const hash = createHash("sha256");
   await digestDirectory(directory, directory, hash);

package/src/agents/antigravity/adapter.ts

@@ -9,6 +9,7 @@ import type {
 } from "../types.ts";
 import { isWebToolName, isWorkspaceToolName } from "./activity.ts";
 import { discoverAntigravityAvailability } from "./availability.ts";
+import { INSPECTION_AGENT_FINGERPRINT } from "./inspection-agent.ts";
 import {
   getIsolatedAntigravityPaths,
   type IsolatedAntigravityPaths,
@@ -22,7 +23,12 @@ import { ANTIGRAVITY_ANSWER_SCHEMA } from "./structured-output.ts";
 const MAX_RETAINED_REFERENCE_HASHES = 512;
 const MAX_WARNING_COUNT = 24;
 const MAX_WARNING_CHARS = 500;
-const CONTINUATION_PREFIX = "agy1.";
+// A resumed CLI retains its original profile and ignores --agent overrides.
+// Reject pre-profile conversations and changed contracts before any process work.
+const CONTINUATION_PREFIX = `agy2.${INSPECTION_AGENT_FINGERPRINT}.`;
+// Follow-ups saying "do not use any tools" can skip finish; agy then replays the
+// previous turn's structured answer, which the response token rejects. Tested live.
+const FOLLOW_UP_RESPONSE_CONTRACT = "\n\n[Always end with finish using the current schema.]";
 
 type ExecutionPhase = "preparation" | "hook-probe" | "conversation" | "validation";
 
@@ -78,12 +84,12 @@ class AntigravityAdapter implements ConsultingAgentAdapter {
       });
     } catch (error) {
       const failure = safeExecutionFailure(error);
-      const canceled = failure.kind === "cancelled";
+      const outcome = failureOutcome(failure.kind);
       timer.finish(
         () => ({
           source: "consulting",
-          level: canceled ? "info" : "error",
-          category: canceled ? "consultation.cancelled" : "consultation.failed",
+          level: outcome.level,
+          category: outcome.category,
           message: failure.message,
           cwd: options.canonicalWorkingDirectory,
           data: {
@@ -121,7 +127,9 @@ class AntigravityAdapter implements ConsultingAgentAdapter {
     const rawFacts = await runAntigravityConversation({
       paths: this.#paths,
       cwd: options.canonicalWorkingDirectory,
-      prompt: options.prompt,
+      prompt: expectedConversationId
+        ? `${options.prompt}${FOLLOW_UP_RESPONSE_CONTRACT}`
+        : options.prompt,
       model: options.model,
       ...(expectedConversationId ? { conversationId: expectedConversationId } : {}),
       ...(options.workspaceAccess ? { workspaceDirectory: options.canonicalWorkingDirectory } : {}),
@@ -220,6 +228,19 @@ function decodeContinuation(value: string): string {
   return conversationId;
 }
 
+/**
+ * Cancellations and stale handles are expected outcomes, not execution failures:
+ * an incompatible continuation is rejected before any process starts.
+ */
+function failureOutcome(kind: ConsultingAgentFailureKind): {
+  level: "info" | "error";
+  category: string;
+} {
+  if (kind === "cancelled") return { level: "info", category: "consultation.cancelled" };
+  if (kind === "invalid-continuation") return { level: "info", category: "consultation.rejected" };
+  return { level: "error", category: "consultation.failed" };
+}
+
 /** Keep only fixed reasons and safe facts, including preparation and callback failures. */
 function safeExecutionFailure(error: unknown): ConsultingAgentError {
   if (error instanceof ConsultingAgentError) {

package/src/agents/antigravity/availability.ts

@@ -7,8 +7,8 @@ import { CURATED_MODELS, type CuratedModel, isCuratedModel } from "./models.ts";
 import type { AntigravityProbeResult } from "./process/runner.ts";
 import { AntigravityProcessError, runAntigravityProbe } from "./process/runner.ts";
 
-/** Minimum supported Antigravity CLI version. */
-export const MINIMUM_ANTIGRAVITY_VERSION = Object.freeze({ major: 1, minor: 1, patch: 24 });
+/** Minimum CLI qualified for explicit inspection profiles, finish, and profile-free resumes. */
+export const MINIMUM_ANTIGRAVITY_VERSION = Object.freeze({ major: 1, minor: 4, patch: 9 });
 const MAX_DISCOVERY_OUTPUT_BYTES = 128 * 1024;
 
 /** Parsed Antigravity CLI version. */

package/src/agents/antigravity/inspection-agent.ts

@@ -0,0 +1,53 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+// The generated name is deliberately excluded: it prevents workspace-name collisions,
+// but is not part of the saved conversation's behavior or compatibility contract.
+const DEFINITION = `description: Bounded read-only consultations with observed evidence.
+mainAgent: true
+subagent: false
+tools:
+  - search_web
+  - read_url_content
+  - view_file
+  - list_dir
+  - find_by_name
+  - grep_search
+  - finish
+---
+Provide bounded, read-only consultations using the available inspection tools.
+Do not run commands, modify files, automate browsers, or delegate work.
+For web research, use search_web to discover sources and read_url_content to verify relevant pages before citing them. Report limitations instead of claiming unperformed reads.
+Return workspace evidence as workspace-relative paths; omit references outside the selected workspace.
+Complete each request with finish using the current output schema.
+`;
+
+/** Compatibility marker for the static profile, not an attestation from Antigravity. */
+export const INSPECTION_AGENT_FINGERPRINT = createHash("sha256").update(DEFINITION).digest("hex");
+
+/**
+ * Create an exclusively owned profile for a new conversation. Antigravity retains
+ * its definition in conversation state, so callers remove it after the process ends.
+ * Keep this out of general home preparation: discovery and follow-ups need no profile.
+ */
+export async function createInspectionAgent(
+  homeDir: string,
+): Promise<{ name: string; dispose: () => Promise<void> }> {
+  const parent = join(homeDir, ".gemini", "config", "agents");
+  await mkdir(parent, { recursive: true, mode: 0o700 });
+  const name = `supi-consulting-${randomUUID()}`;
+  const directory = join(parent, name);
+  await mkdir(directory, { mode: 0o700 });
+  const dispose = () => rm(directory, { recursive: true, force: true });
+  try {
+    await writeFile(join(directory, "agent.md"), `---\nname: ${name}\n${DEFINITION}`, {
+      mode: 0o600,
+      flag: "wx",
+    });
+  } catch (error) {
+    await dispose();
+    throw error;
+  }
+  return { name, dispose };
+}

package/src/agents/antigravity/process/events.ts

@@ -27,6 +27,7 @@ import {
   FileResources,
   type FileTargetObservation,
   fileTargetUpdate,
+  isAgentInternalFileActivity,
   isPermissionDenial,
   terminalDeniedOperations,
 } from "./permission-diagnostics.ts";
@@ -326,6 +327,7 @@ export class AntigravityEventAccumulator {
 
   #recordSuccessfulTool(name: string, event: Record<string, unknown>, pending?: PendingTool): void {
     if (!pending?.observed) this.#recordObservedTool(name);
+    if (isAgentInternalFileActivity(name, event, this.#readScope, pending)) return;
     this.#successfulToolNames.add(name);
     const input = toolInput(event) ?? event;
     const sourceHash = pending?.urlHash ?? hashValue(extractUrl(input));

package/src/agents/antigravity/process/permission-diagnostics.ts

@@ -203,6 +203,21 @@ export function fileTargetUpdate(
       };
 }
 
+/**
+ * Antigravity caches fetched pages in its own conversation directory and reads them
+ * back with file tools. A successful file call proven outside the approved roots is
+ * agent-internal, not workspace use. Unknown or missing paths stay counted.
+ */
+export function isAgentInternalFileActivity(
+  name: string,
+  event: Record<string, unknown>,
+  scope: DiagnosticReadScope,
+  pending?: FileTargetObservation,
+): boolean {
+  const target = pending?.requestedResource ? pending : fileTargetUpdate(name, event, scope);
+  return target.outsideReadRoots === true;
+}
+
 /**
  * Classify the requested file location independently of the denial cause. Resolve
  * aliases (including missing targets' existing parents); inaccessible paths and

package/src/agents/antigravity/process/runner.ts

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { createInspectionAgent } from "../inspection-agent.ts";
 import { type IsolatedAntigravityPaths, prepareIsolatedAntigravityHome } from "../isolated-home.ts";
 import type { AntigravityExecutionFacts, AntigravityProgressCallback } from "../types.ts";
 import { eventType, isRecord, toolName } from "./event-values.ts";
@@ -24,6 +25,8 @@ export { AntigravityProcessError } from "./subprocess.ts";
 export function buildAntigravityRunArguments(options: {
   schemaPath: string;
   model: string;
+  /** Only new conversations select a profile; resumes retain their saved definition. */
+  agentName?: string;
   conversationId?: string;
   workspaceDirectory?: string;
   additionalReadOnlyDirectories?: readonly string[];
@@ -47,7 +50,11 @@ export function buildAntigravityRunArguments(options: {
       ]),
     ].flatMap((directory) => ["--add-dir", directory]),
     "--disable-slash-commands",
-    ...(options.conversationId ? ["--conversation", options.conversationId] : []),
+    ...(options.conversationId
+      ? ["--conversation", options.conversationId]
+      : options.agentName
+        ? ["--agent", options.agentName]
+        : []),
   ];
 }
 
@@ -81,10 +88,8 @@ export async function runAntigravityConversation(options: {
   onProcessStart?: () => void;
 }): Promise<AntigravityExecutionFacts> {
   await prepareIsolatedAntigravityHome(options.paths);
-  const schemaDirectory = await mkdtemp(
-    join(options.schemaDirectoryParent ?? tmpdir(), "supi-consulting-schema-"),
-  );
-  const schemaPath = join(schemaDirectory, "answer.json");
+  let schemaDirectory: string | undefined;
+  let inspectionAgent: Awaited<ReturnType<typeof createInspectionAgent>> | undefined;
   const responseToken = randomUUID();
   const accumulator = new AntigravityEventAccumulator({
     expectedResponseToken: responseToken,
@@ -93,6 +98,13 @@ export async function runAntigravityConversation(options: {
   });
   let eventCount = 0;
   try {
+    if (!options.conversationId) {
+      inspectionAgent = await createInspectionAgent(options.paths.homeDir);
+    }
+    schemaDirectory = await mkdtemp(
+      join(options.schemaDirectoryParent ?? tmpdir(), "supi-consulting-schema-"),
+    );
+    const schemaPath = join(schemaDirectory, "answer.json");
     // A resumed CLI can replay its previous structured output. Bind and locally
     // validate this invocation rather than trusting terminal success or schema shape.
     const schema = {
@@ -110,6 +122,7 @@ export async function runAntigravityConversation(options: {
     const args = buildAntigravityRunArguments({
       schemaPath,
       model: options.model,
+      agentName: inspectionAgent?.name,
       conversationId: options.conversationId,
       workspaceDirectory: options.workspaceDirectory,
       additionalReadOnlyDirectories: options.additionalReadOnlyDirectories,
@@ -149,7 +162,10 @@ export async function runAntigravityConversation(options: {
       },
     );
   } finally {
-    await rm(schemaDirectory, { recursive: true, force: true });
+    await Promise.all([
+      inspectionAgent?.dispose(),
+      schemaDirectory ? rm(schemaDirectory, { recursive: true, force: true }) : undefined,
+    ]);
   }
 }
 

package/src/agents/errors.ts

@@ -3,7 +3,8 @@ const FAILURE_MESSAGES = {
   timeout: "The Consultation timed out.",
   cancelled: "The Consultation was canceled.",
   "invalid-response": "The Consulting Agent returned an invalid response.",
-  "invalid-continuation": "Invalid Conversation Handle continuation state.",
+  "invalid-continuation":
+    "The Conversation Handle has invalid or incompatible continuation state. Start a new Consultation.",
   "conversation-mismatch":
     "The Consulting Agent returned a different conversation for this handle.",
   execution: "Consultation execution failed.",

package/src/catalogue.ts

@@ -1,12 +1,12 @@
-import { StringEnum } from "@earendil-works/pi-ai";
-import type { TSchema } from "typebox";
+import { type TSchema, Type } from "typebox";
 
 /** Build a provider-facing model enum from one immutable agent catalogue. */
 export function buildModelCatalogueEnum(catalogue: readonly string[]): TSchema {
   if (catalogue.length === 0) {
     throw new Error("Cannot build a model enum from an empty Consulting Agent catalogue.");
   }
-  return StringEnum([...catalogue] as [string, ...string[]], {
+  return Type.Enum([...catalogue] as [string, ...string[]], {
+    type: "string",
     description: "Model available in the current Consulting Agent catalogue.",
   });
 }

package/src/tool/consulting_run/execute.ts

@@ -4,6 +4,7 @@ import type {
   ExtensionAPI,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { ConsultingAgentError } from "../../agents/errors.ts";
 import type { ConsultingAgentAdapter, ConsultingAgentAvailability } from "../../agents/types.ts";
 import { resolveAdditionalReadOnlyDirectories } from "../../config.ts";
 import {
@@ -167,9 +168,19 @@ async function runContinue(
       ...(hookWarning ? { hookWarning } : {}),
     });
   } catch (error) {
-    if (processStarted) {
+    // Incompatible continuation state can never succeed, so retire it even though
+    // the adapter rejected it before any process work.
+    const incompatible =
+      error instanceof ConsultingAgentError && error.kind === "invalid-continuation";
+    if (processStarted || incompatible) {
       const retired = dependencies.handles.retire(record.handle);
-      if (retired) appendHandleRetired(dependencies.pi, retired, "Consultation follow-up failed");
+      if (retired) {
+        appendHandleRetired(
+          dependencies.pi,
+          retired,
+          incompatible ? "Incompatible continuation state" : "Consultation follow-up failed",
+        );
+      }
     }
     throw error;
   } finally {

package/src/tool/consulting_run/input.ts

@@ -1,4 +1,3 @@
-import { StringEnum } from "@earendil-works/pi-ai";
 import { type TSchema, Type } from "typebox";
 import { Value } from "typebox/value";
 import { buildModelCatalogueEnum, isAvailableModel } from "../../catalogue.ts";
@@ -40,7 +39,8 @@ export function buildConsultingRunSchema(agent: string, catalogue: readonly stri
       new: Type.Optional(
         Type.Object(
           {
-            agent: StringEnum([agent], {
+            agent: Type.Enum([agent], {
+              type: "string",
               description: "The Consulting Agent that will perform this Consultation.",
             }),
             model: buildModelCatalogueEnum(catalogue),