@mrclrchtr/supi-consulting 11.0.1 → 11.2.0

package/README.md

@@ -65,7 +65,7 @@ A new Consultation requires the agent, an available model, and Workspace Access:
 
 The Model Catalogue is the intersection of the curated Antigravity models and the models available to the signed-in account. It stays fixed until the next session start or reload. There is no default model or automatic agent fallback.
 
-Set `workspace` to `true` only when the Consultation needs repository evidence. This exposes the current PI workspace. Set it to `false` to use the empty Consultation Workspace.
+Set `workspace` to `true` only when the Consultation needs repository evidence. This exposes the current PI workspace. Set it to `false` to use the empty Consultation Workspace. Explicitly configured additional read-only directories remain accessible with either selection.
 
 A follow-up supplies only a returned Conversation Handle:
 
@@ -82,16 +82,43 @@ Results report web use, workspace use, observed and claimed references, warnings
 
 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
+
+Use `/supi-settings` → **Consulting** → **Additional read-only directories** to enter comma-separated absolute directory paths. The default is an empty list. No shell expansion or glob matching is performed. For paths containing commas, edit the JSON configuration instead.
+
+Global configuration lives at `~/.pi/agent/supi/config.json`; project configuration lives at `.pi/supi/config.json`:
+
+```json
+{
+  "consulting": {
+    "additionalReadOnlyDirectories": ["/tmp/octalog-filter-previews"]
+  }
+}
+```
+
+- Project values replace the global list, rather than extending it. An explicit `[]` removes inherited grants; Inherit/Reset deletes the scoped key. Untrusted project configuration cannot grant access; global grants still apply.
+- Directories must exist and be accessible when a Consultation starts. Symlinks are resolved and duplicate roots are removed, so `/tmp` resolves to `/private/tmp` on macOS without needing both entries.
+- Settings are read from the current Pi workspace before each new Consultation and follow-up. Changes apply to the next invocation without reloading. They do not modify an already-running process.
+- The directories are registered with Antigravity per process using `--add-dir`, not persisted as permission grants in the shared profile. The fixed write, command, MCP, and URL-execution denials remain in force; `allowNonWorkspaceAccess` stays `false`.
+- Configured directories are available even with `workspace: false`. Prefer task-specific artifact folders over all of `/tmp`, which may contain unrelated sensitive files. This setting does not authorize shell-based browser automation.
+- Reads from extra directories can contribute inspection activity, but references outside the selected workspace are not reported as validated workspace-relative evidence.
+
+Directory registration and deny-rule precedence follow Antigravity's [CLI reference](https://antigravity.google/docs/cli/reference/) and [permissions reference](https://antigravity.google/docs/permissions/). These are Antigravity policy restrictions, not a new operating-system security boundary.
+
 ## Failure diagnostics
 
 Execution failures report a fixed reason when the adapter can identify it:
 
-- Missing final result, missing structured answer, or answer schema mismatch.
+- Missing final result, missing structured answer, answer schema mismatch, or an answer not bound to the current request.
 - Unsuccessful final result or data received after the final result.
 - Malformed JSON, a non-object event, or an output limit exceeded.
 - Missing conversation identifier, process failure, timeout, or cancellation.
 
-An observed tool permission denial is reported separately. It does not prove the cause of a later failure. A denial does not fail a Consultation that returns a valid answer. Workspace Access does not grant access to files outside the selected workspace.
+Each invocation adds a unique response token to its private answer schema and validates the returned token locally before accepting the answer. The token is removed from public results and excluded from failure diagnostics. This prevents a resumed Antigravity conversation's previous structured answer from being accepted as the current result. Missing or mismatched tokens fail with `unbound-answer`; plain-text answers are not substituted for the structured contract. A started follow-up that fails retires its Conversation Handle; start a new Consultation.
+
+An observed tool permission denial is reported separately. It does not prove the cause of a later failure. A denial does not fail a Consultation that returns a valid answer. Workspace Access alone does not grant access to files outside the selected workspace; configure additional read-only directories explicitly.
+
+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:
 
@@ -101,13 +128,26 @@ When SuPi Debug is enabled, failed executions emit one `consulting/consultation.
 
 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.
 
-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. They exclude prompts, answers, resource paths, conversation IDs, raw stdout, stderr, tool payloads, and error causes, even when raw Debug access is enabled. The event's `cwd` identifies the selected working directory. Failure messages remain specific when Debug is disabled.
+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.
+
+Antigravity's terminal `denied_actions` summary can establish a denial even when its detailed tool-error update is absent. It establishes a minimum of one observation per operation category, not additional calls on top of already-correlated denials. Summary entries have no tool-call IDs or file parameters, so the adapter does not attribute them to nearby or unfinished file requests.
+
+Failures also include bounded requested file-target metadata in both Debug and caller-visible feedback:
+
+- `deniedResources` lists at most eight distinct `{ operation, requestedPath }` references for known file operations observed as denied. Targets come from structured parameters on the denied event or earlier updates correlated by tool-call ID, never from error text, command parsing, nearby calls, or transcripts.
+- `requestedPath` preserves the supplied path, including significant whitespace. It is not a canonical filesystem path or the permission checker's resolved target, and does not identify a permanent path blacklist or the denying rule. Paths are limited to 1,024 UTF-16 characters; longer paths are unavailable rather than silently shortened.
+- `deniedResourcesOmitted` counts file-denial observations whose known targets were omitted because the list was full, not unique omitted paths. Repeated denials for listed targets do not duplicate entries.
+- `deniedResourcePathsUnavailable` counts known file-denial observations without an available, bounded structured target. Missing correlation or parameters remain unknown; the adapter does not infer a path from prose. Explicit replacement targets supersede earlier metadata, including when the replacement is invalid or overlong; only omitted path parameters preserve an earlier target.
+- `unfinishedResources` separately lists at most eight distinct requested targets from ID-correlated file calls with no observed terminal outcome. These are **unknown outcomes, not confirmed denials**, even if a terminal summary reports the same operation category. Successful and already-denied calls are excluded. `unfinishedResourcesOmitted` counts capacity-omitted observations; `unfinishedResourcePathsUnavailable` counts observations lacking a usable target. The same path limits, replacement semantics, and deduplication rules apply as for denied resources.
+- Caller-visible references are JSON-quoted, with terminal control characters and line separators escaped. **Denied and unfinished requested paths can contain sensitive metadata and are exposed to the calling agent and persisted with enabled Debug events.**
+
+Events otherwise exclude prompts, answers, arbitrary tool names, raw stdout, stderr, complete tool payloads, and error causes, even when raw Debug access is enabled. The event's `cwd` identifies the selected working directory. Successful Consultations do not gain a failure event merely because an action was denied.
 
 ## Security limits
 
-The Antigravity adapter enforces its Inspection Permission Set in the Isolated Antigravity Home. It allows `read_url(*)` and denies known file writes, commands, unsandboxed actions, MCP, and URL execution. These rules are **not an operating-system sandbox**.
+The Antigravity adapter enforces its Inspection Permission Set in the Isolated Antigravity Home. It allows `read_url(*)` and denies known file writes, commands, MCP, and URL execution. The `command(*)` rule covers commands inside and outside Antigravity's terminal sandbox; the obsolete, ignored `unsandboxed(*)` rule is not emitted. These rules are **not an operating-system sandbox**.
 
-For workspace Consultations, project-local hooks can run commands, read the Antigravity transcript, and cause side effects outside these permission rules. The adapter probes hook state before the paid process and warns when hooks are active or unknown.
+For Consultations with Workspace Access or additional read-only directories, project-local hooks can run commands, read the Antigravity transcript, and cause side effects outside these permission rules. The adapter probes hook state with the additional roots before the paid process and warns when hooks are active or unknown. Directory grants are intended for inspection artifacts, not untrusted project customizations.
 
 `read_url(*)` can reach local, private-network, and link-local endpoints that Antigravity accepts. It does not enforce public-internet-only access.
 

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

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

package/node_modules/@mrclrchtr/supi-core/src/debug-registry.ts

@@ -14,6 +14,8 @@ export interface DebugRegistryConfig {
   enabled: boolean;
   /** What the agent-callable debug tool may return. */
   agentAccess: DebugAgentAccess;
+  /** Whether Agent Run retrospective capture is explicitly enabled. */
+  agentRunRetrospectivesEnabled: boolean;
   /** Maximum number of session-local events to keep in memory. */
   maxEvents: number;
 }
@@ -21,6 +23,7 @@ export interface DebugRegistryConfig {
 export const DEBUG_REGISTRY_DEFAULTS: DebugRegistryConfig = {
   enabled: false,
   agentAccess: "sanitized",
+  agentRunRetrospectivesEnabled: false,
   maxEvents: 100,
 };
 
@@ -75,6 +78,9 @@ export interface DebugEventQueryResult {
 /** Receives a sanitized event whenever the registry records one. */
 export type DebugEventListener = (event: DebugEventView) => void;
 
+/** Receives sanitized events for persistence; separate from ordinary event subscriptions. */
+export type DebugPersistenceSink = (event: DebugEventView) => void;
+
 export interface DebugSummary {
   total: number;
   byLevel: Partial<Record<DebugLevel, number>>;
@@ -85,6 +91,7 @@ interface DebugRegistryState {
   config: DebugRegistryConfig;
   events: DebugEvent[];
   listeners: Set<DebugEventListener>;
+  persistenceSinks: Set<DebugPersistenceSink>;
   nextId: number;
 }
 
@@ -111,13 +118,15 @@ function getState(): DebugRegistryState {
       config: cloneConfig(DEBUG_REGISTRY_DEFAULTS),
       events: [],
       listeners: new Set(),
+      persistenceSinks: new Set(),
       nextId: 1,
     };
     (globalThis as Record<symbol, unknown>)[REGISTRY_KEY] = state;
   }
   // Keep the shared registry compatible with extension reloads that reuse an
-  // instance created before listeners existed.
+  // instance created before listener sets existed.
   if (!state.listeners) state.listeners = new Set();
+  if (!state.persistenceSinks) state.persistenceSinks = new Set();
   return state;
 }
 
@@ -200,6 +209,19 @@ export function isDebugRegistryEnabled(): boolean {
   return getState().config.enabled;
 }
 
+/**
+ * Return whether a retrospective can be captured: Debug and its explicit opt-in
+ * must be enabled, and at least one persistence sink must be registered.
+ */
+export function canRecordAgentRunRetrospective(): boolean {
+  const state = getState();
+  return (
+    state.config.enabled &&
+    state.config.agentRunRetrospectivesEnabled &&
+    state.persistenceSinks.size > 0
+  );
+}
+
 /** Best-effort redaction helper for data exposed through sanitized debug views. */
 export function redactDebugData<T>(value: T): T {
   return redactValue(value, 8) as T;
@@ -226,6 +248,16 @@ export function subscribeDebugEvents(listener: DebugEventListener): () => void {
   return () => state.listeners.delete(listener);
 }
 
+/**
+ * Register a sanitized event persistence sink. Sinks are tracked separately from
+ * ordinary listeners so eligibility checks only succeed when logging is active.
+ */
+export function subscribeDebugPersistence(sink: DebugPersistenceSink): () => void {
+  const state = getState();
+  state.persistenceSinks.add(sink);
+  return () => state.persistenceSinks.delete(sink);
+}
+
 /** Record a session-local debug event if debugging is enabled. */
 export function recordDebugEvent(input: DebugEventInput): DebugEvent | null {
   const state = getState();
@@ -251,6 +283,13 @@ export function recordDebugEvent(input: DebugEventInput): DebugEvent | null {
       // Debug-event consumers must not alter producer behavior.
     }
   }
+  for (const sink of state.persistenceSinks) {
+    try {
+      sink(toSanitizedView(event));
+    } catch {
+      // Persistence failures must not alter producer behavior.
+    }
+  }
   return {
     ...event,
     data: event.data === undefined ? undefined : redactDebugData(event.data),
@@ -309,5 +348,6 @@ export function resetDebugRegistry(): void {
   state.config = cloneConfig(DEBUG_REGISTRY_DEFAULTS);
   state.events = [];
   state.listeners.clear();
+  state.persistenceSinks.clear();
   state.nextId = 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-consulting",
-  "version": "11.0.1",
+  "version": "11.2.0",
   "description": "Bounded consultations with explicit agent and workspace selection and observed evidence",
   "license": "MIT",
   "repository": {
@@ -37,7 +37,7 @@
     "docs/adr/*.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "11.0.1"
+    "@mrclrchtr/supi-core": "11.2.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/scripts/live-probe.ts

@@ -30,14 +30,17 @@ async function main(): Promise<void> {
   requireWebEvidence(first);
 
   const second = await adapter.execute({
-    prompt: `What exact context token did I give you? Answer in one sentence and include ${CONTEXT_TOKEN}.`,
+    prompt:
+      "Without using tools, return only the exact context token I gave you in the preceding request.",
     model: MODEL,
     canonicalWorkingDirectory: consultationWorkspace,
     workspaceAccess: false,
     continuation: first.continuation,
   });
-  if (!second.answer.answer.includes(CONTEXT_TOKEN)) {
-    throw new Error("The follow-up did not retain the Conversation Handle context.");
+  if (second.answer.answer.trim() !== CONTEXT_TOKEN) {
+    throw new Error(
+      "The follow-up did not return the requested current-turn answer from conversation context.",
+    );
   }
 
   const fixture = await realpath(await mkdtemp(join(tmpdir(), "supi-consulting-live-")));

package/src/agents/antigravity/adapter.ts

@@ -111,8 +111,10 @@ class AntigravityAdapter implements ConsultingAgentAdapter {
       ? decodeContinuation(options.continuation)
       : undefined;
     await prepareIsolatedAntigravityHome(this.#paths);
-    if (options.workspaceAccess) onPhase("hook-probe");
-    const hookWarning = options.workspaceAccess
+    const inspectHooks =
+      options.workspaceAccess || (options.additionalReadOnlyDirectories?.length ?? 0) > 0;
+    if (inspectHooks) onPhase("hook-probe");
+    const hookWarning = inspectHooks
       ? await inspectProjectHooks(this.#paths, options, options.onWarning)
       : undefined;
     onPhase("conversation");
@@ -123,6 +125,7 @@ class AntigravityAdapter implements ConsultingAgentAdapter {
       model: options.model,
       ...(expectedConversationId ? { conversationId: expectedConversationId } : {}),
       ...(options.workspaceAccess ? { workspaceDirectory: options.canonicalWorkingDirectory } : {}),
+      additionalReadOnlyDirectories: options.additionalReadOnlyDirectories,
       schema: ANTIGRAVITY_ANSWER_SCHEMA as Record<string, unknown>,
       signal: options.signal,
       onActivity: options.onProgress,
@@ -161,6 +164,7 @@ async function inspectProjectHooks(
   const probe = await probeProjectHooks({
     paths,
     cwd: options.canonicalWorkingDirectory,
+    additionalReadOnlyDirectories: options.additionalReadOnlyDirectories,
     signal: options.signal,
     onProcessStart: options.onProcessStart,
   });

package/src/agents/antigravity/isolated-home.ts

@@ -67,13 +67,7 @@ export const INSPECTION_PERMISSION_SET = Object.freeze({
   allowNonWorkspaceAccess: false,
   permissions: Object.freeze({
     allow: Object.freeze(["read_url(*)"]),
-    deny: Object.freeze([
-      "write_file(*)",
-      "command(*)",
-      "unsandboxed(*)",
-      "mcp(*)",
-      "execute_url(*)",
-    ]),
+    deny: Object.freeze(["write_file(*)", "command(*)", "mcp(*)", "execute_url(*)"]),
   }),
 });
 

package/src/agents/antigravity/process/event-values.ts

@@ -171,24 +171,42 @@ export function extractUrl(value: unknown): string | undefined {
   );
 }
 
-export function extractWorkspacePath(value: unknown): string | undefined {
-  return readBoundedField(value, [
-    "path",
-    "file",
-    "file_path",
-    "relative_path",
-    "directory_path",
-    "search_path",
-    "search_directory",
-    "absolute_path",
-    "directory",
-  ]);
+const WORKSPACE_PATH_FIELDS = [
+  "path",
+  "file",
+  "file_path",
+  "relative_path",
+  "directory_path",
+  "search_path",
+  "search_directory",
+  "absolute_path",
+  "directory",
+] as const;
+
+/** Distinguish an omitted path parameter from an explicitly supplied but invalid target. */
+export function structuredWorkspacePath(value: unknown): { value: unknown } | undefined {
+  if (!isRecord(value)) return undefined;
+  for (const name of WORKSPACE_PATH_FIELDS) {
+    for (const [key, field] of Object.entries(value)) {
+      if (normalizeFieldName(key) === normalizeFieldName(name)) return { value: field };
+    }
+  }
+  return undefined;
+}
+
+/** Read a structured path; requested-target diagnostics preserve significant filename whitespace. */
+export function extractWorkspacePath(
+  value: unknown,
+  options: { preserveWhitespace?: boolean } = {},
+): string | undefined {
+  return readBoundedField(value, WORKSPACE_PATH_FIELDS, () => true, options.preserveWhitespace);
 }
 
 function readBoundedField(
   value: unknown,
   names: readonly string[],
   predicate: (candidate: string) => boolean = () => true,
+  preserveWhitespace = false,
 ): string | undefined {
   if (!isRecord(value)) return undefined;
   const fields = Object.entries(value);
@@ -196,13 +214,20 @@ function readBoundedField(
     const normalizedName = normalizeFieldName(name);
     for (const [key, field] of fields) {
       if (normalizeFieldName(key) !== normalizedName) continue;
-      const candidate = safeString(field, 4_096);
+      const candidate = boundedFieldText(field, preserveWhitespace);
       if (candidate && predicate(candidate)) return candidate;
     }
   }
   return undefined;
 }
 
+function boundedFieldText(value: unknown, preserveWhitespace: boolean): string | undefined {
+  if (preserveWhitespace && typeof value === "string") {
+    return value.length > 0 && value.length <= 4_096 ? value : undefined;
+  }
+  return safeString(value, 4_096);
+}
+
 function normalizeFieldName(value: string): string {
   return value.toLowerCase().replace(/[-_]/g, "");
 }
@@ -246,6 +271,7 @@ function selectAnswerFields(value: Record<string, unknown>): Record<string, unkn
     answer: value.answer,
     sources: value.sources,
     workspaceEvidence: value.workspaceEvidence,
+    ...(Object.hasOwn(value, "responseToken") ? { responseToken: value.responseToken } : {}),
   };
 }