@mrclrchtr/supi-consulting 11.0.1 → 11.2.0

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

@@ -0,0 +1,260 @@
+import { lstatSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, relative, resolve } from "node:path";
+import {
+  type ConsultingDeniedOperation,
+  type ConsultingFileResource,
+  MAX_FAILURE_RESOURCE_PATH_CHARS,
+  MAX_FAILURE_RESOURCES,
+} from "../../errors.ts";
+import {
+  eventStatus,
+  eventType,
+  extractWorkspacePath,
+  isErrorStatus,
+  isRecord,
+  isSuccessStatus,
+  normalizeToolName,
+  safeString,
+  structuredWorkspacePath,
+  toolInput,
+} from "./event-values.ts";
+
+/** Reduce known tool names to fixed diagnostic categories, without retaining arbitrary names. */
+export function classifyDeniedOperation(name: string | undefined): ConsultingDeniedOperation {
+  switch (name) {
+    case "command":
+    case "run_command":
+    case "run_terminal_command":
+      return "command";
+    case "read_file":
+    case "view_file":
+    case "view_file_outline":
+    case "view_file_item":
+    case "list_dir":
+    case "list_files":
+    case "find_by_name":
+    case "grep_search":
+    case "code_search":
+      return "file-read";
+    case "write_file":
+    case "write_to_file":
+    case "replace_file_content":
+    case "multi_replace_file_content":
+    case "apply_patch":
+      return "file-write";
+    case "search_web":
+    case "read_url_content":
+    case "read_url":
+    case "web_search":
+      return "web-read";
+    case "execute_url":
+    case "browser_subagent":
+      return "browser";
+    default:
+      return name === "mcp" || name?.startsWith("mcp_") ? "mcp" : "other";
+  }
+}
+
+/** Classify result events, preserving their legacy implicit-success default when status is omitted. */
+export function classifyToolResult(event: Record<string, unknown>): {
+  kind: "pending" | "failure" | "success";
+  denied: boolean;
+} {
+  const status = eventStatus(event);
+  const denied = isPermissionDenial(event);
+  if (denied || isErrorStatus(status)) return { kind: "failure", denied };
+  return { kind: isSuccessStatus(status) ? "success" : "pending", denied };
+}
+
+/** Fixed operation minima from terminal summaries, with no inferred call IDs or file targets. */
+export function terminalDeniedOperations(
+  event: Record<string, unknown>,
+): Map<ConsultingDeniedOperation, string> {
+  const operations = new Map<ConsultingDeniedOperation, string>();
+  if (!Array.isArray(event.denied_actions)) return operations;
+  for (const action of event.denied_actions) {
+    const name = isRecord(action) ? safeString(action.action, 80) : undefined;
+    if (!name) continue;
+    const normalizedName = normalizeToolName(name);
+    operations.set(classifyDeniedOperation(normalizedName), normalizedName);
+  }
+  return operations;
+}
+
+/** Extract a file target: undefined means omitted; null means explicitly supplied but unavailable. */
+function requestedFileResource(
+  name: string | undefined,
+  event: Record<string, unknown>,
+): ConsultingFileResource | null | undefined {
+  const operation = classifyDeniedOperation(name);
+  if (operation !== "file-read" && operation !== "file-write") return undefined;
+  const field = structuredWorkspacePath(toolInput(event) ?? event);
+  if (!field) return undefined;
+  const path = field.value;
+  return typeof path === "string" &&
+    path.length > 0 &&
+    path.length <= MAX_FAILURE_RESOURCE_PATH_CHARS
+    ? { operation, requestedPath: path }
+    : null;
+}
+
+/** Bounded, deduplicated requested targets for one category of file observations. */
+export class FileResources {
+  #resources: ConsultingFileResource[] = [];
+  #omitted = 0;
+  #unavailable = 0;
+
+  /** Record an observation, counting absent targets and capacity omissions without guessing. */
+  record(operation: ConsultingDeniedOperation, resource?: ConsultingFileResource | null): void {
+    if (operation !== "file-read" && operation !== "file-write") return;
+    if (!resource || resource.operation !== operation) {
+      this.#unavailable += 1;
+      return;
+    }
+    if (
+      this.#resources.some(
+        (item) => item.operation === operation && item.requestedPath === resource.requestedPath,
+      )
+    )
+      return;
+    if (this.#resources.length === MAX_FAILURE_RESOURCES) {
+      this.#omitted += 1;
+      return;
+    }
+    this.#resources.push({ ...resource });
+  }
+
+  /** Copy metadata only; neither raw payloads nor inferred outcomes are exposed. */
+  get snapshot() {
+    return {
+      resources: this.#resources.map((resource) => ({ ...resource })),
+      omitted: this.#omitted,
+      unavailable: this.#unavailable,
+    };
+  }
+}
+
+/** Recognize denial observations without retaining the raw error or tool output. */
+export function isPermissionDenial(event: Record<string, unknown>): boolean {
+  const status = eventStatus(event);
+  if (["denied", "permission_denied", "forbidden", "blocked"].includes(status ?? "")) return true;
+  const type = eventType(event);
+  if (type.includes("permission") || type.includes("denied") || type.includes("blocked"))
+    return true;
+  const hasExplicitFailure =
+    event.is_error === true ||
+    event.isError === true ||
+    isErrorStatus(status) ||
+    event.error !== undefined ||
+    event.reason !== undefined;
+  if (!hasExplicitFailure) return false;
+  const message = [event.error, event.reason, event.message, event.content]
+    .map((value) => safeDenialText(value))
+    .join(" ")
+    .toLowerCase();
+  return message.includes("permission") || message.includes("denied");
+}
+
+function safeDenialText(value: unknown, depth = 0): string {
+  if (depth > 3) return "";
+  if (typeof value === "string") return value.slice(0, 4_000);
+  if (Array.isArray(value)) {
+    return value
+      .slice(0, 20)
+      .map((item) => safeDenialText(item, depth + 1))
+      .join(" ");
+  }
+  if (!isRecord(value)) return "";
+  return ["text", "message", "content", "error", "reason"]
+    .map((key) => safeDenialText(value[key], depth + 1))
+    .join(" ");
+}
+
+/** Approved filesystem roots for diagnostic location classification, not permission enforcement. */
+export interface DiagnosticReadScope {
+  workspaceDirectory?: string;
+  additionalReadOnlyDirectories?: readonly string[];
+}
+
+/** Correlated target facts; null invalidates an earlier resource instead of reviving a stale path. */
+export interface FileTargetObservation {
+  requestedResource?: ConsultingFileResource | null;
+  outsideReadRoots?: boolean;
+}
+
+/** Preserve earlier facts only when a path is omitted; explicit replacements supersede both facts. */
+export function fileTargetUpdate(
+  name: string | undefined,
+  event: Record<string, unknown>,
+  scope: DiagnosticReadScope,
+  previous?: FileTargetObservation,
+): FileTargetObservation {
+  const operation = classifyDeniedOperation(name);
+  if (operation !== "file-read" && operation !== "file-write") return {};
+  const resource = requestedFileResource(name, event);
+  return resource === undefined
+    ? {
+        requestedResource: previous?.requestedResource,
+        outsideReadRoots: previous?.outsideReadRoots,
+      }
+    : {
+        requestedResource: resource,
+        outsideReadRoots: fileAccessOutsideReadRoots(name, event, scope),
+      };
+}
+
+/**
+ * Classify the requested file location independently of the denial cause. Resolve
+ * aliases (including missing targets' existing parents); inaccessible paths and
+ * parent traversal stay unknown rather than relying on lexical symlink semantics.
+ */
+export function fileAccessOutsideReadRoots(
+  name: string | undefined,
+  event: Record<string, unknown>,
+  scope: DiagnosticReadScope,
+): boolean | undefined {
+  const operation = classifyDeniedOperation(name);
+  if (operation !== "file-read" && operation !== "file-write") return undefined;
+  const path = extractWorkspacePath(toolInput(event) ?? event, { preserveWhitespace: true });
+  if (!path || !scope.workspaceDirectory) return undefined;
+  // Resolving '..' lexically can erase a symlink before its destination is inspected.
+  if (path.split(/[\\/]/).includes("..")) return undefined;
+  const target = canonicalDiagnosticPath(resolve(scope.workspaceDirectory, path));
+  const roots = [scope.workspaceDirectory, ...(scope.additionalReadOnlyDirectories ?? [])].map(
+    canonicalDiagnosticPath,
+  );
+  if (!target || roots.some((root) => root === undefined)) return undefined;
+  return !roots.some((root) => {
+    if (!root) return false;
+    const distance = relative(root, target);
+    return (
+      distance === "" || (!isAbsolute(distance) && distance !== ".." && !distance.startsWith("../"))
+    );
+  });
+}
+
+function canonicalDiagnosticPath(path: string): string | undefined {
+  let candidate = path;
+  const suffix: string[] = [];
+  while (true) {
+    try {
+      return resolve(realpathSync(candidate), ...suffix.reverse());
+    } catch (error) {
+      if (!canResolveParent(candidate, error)) return undefined;
+      const parent = dirname(candidate);
+      if (parent === candidate) return undefined;
+      suffix.push(basename(candidate));
+      candidate = parent;
+    }
+  }
+}
+
+function canResolveParent(path: string, error: unknown): boolean {
+  if (!isRecord(error) || !["ENOENT", "ENOTDIR"].includes(String(error.code))) return false;
+  try {
+    // A dangling symlink is not a lexical child of its containing directory.
+    return !lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}

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

@@ -1,4 +1,60 @@
-import { ERROR_STATES, eventType, isRecord, SUCCESS_STATES, safeString } from "./event-values.ts";
+import {
+  ERROR_STATES,
+  eventStatus,
+  eventType,
+  isErrorStatus,
+  isRecord,
+  isSuccessStatus,
+  isToolResultEvent,
+  isToolStartEvent,
+  SUCCESS_STATES,
+  safeString,
+  toolName,
+} from "./event-values.ts";
+
+/** Terminal results need explicit success; the absence of an error is not enough. */
+export function hasExplicitSuccess(
+  event: Record<string, unknown>,
+  status: string | undefined,
+): boolean {
+  return status !== undefined
+    ? isSuccessStatus(status)
+    : event.is_error === false || event.isError === false || event.success === true;
+}
+
+/** Only explicit successful activity can establish observed evidence or complete a pending call. */
+export function isSuccessfulActivity(event: Record<string, unknown>): boolean {
+  const status = eventStatus(event);
+  return (
+    !isErrorStatus(status) &&
+    isSuccessStatus(status) &&
+    (status !== undefined || event.success === true || event.ok === true)
+  );
+}
+
+/** Exclude planning/assistant steps even when their index matches a pending tool call. */
+export function isNonToolStepUpdate(event: Record<string, unknown>): boolean {
+  const type = eventType(event);
+  if (!["assistant", "step_update"].includes(type)) return false;
+  const declaredType = safeString(event.step_type ?? event.stepType, 40)?.toLowerCase();
+  if (declaredType) return declaredType !== "tool";
+  return toolName(event) === undefined && !isRecord(event.tool_info) && !isRecord(event.toolInfo);
+}
+
+/** Extract normalized tool activity from assistant content without treating answer text as evidence. */
+export function nestedToolEvents(event: Record<string, unknown>): Record<string, unknown>[] {
+  const content = isRecord(event.message) ? event.message.content : undefined;
+  if (!Array.isArray(content)) return [];
+  return content.filter(isRecord).map(normalizeProtocolEvent).filter(isToolActivityBlock);
+}
+
+function isToolActivityBlock(event: Record<string, unknown>): boolean {
+  return (
+    isToolStartEvent(event) ||
+    isToolResultEvent(event) ||
+    (eventType(event) === "step_update" && !isNonToolStepUpdate(event))
+  );
+}
 
 /** Adapt an agy event envelope to the small event vocabulary used by the reducer. */
 export function normalizeProtocolEvent(event: Record<string, unknown>): Record<string, unknown> {

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

@@ -1,9 +1,10 @@
+import { randomUUID } from "node:crypto";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { type IsolatedAntigravityPaths, prepareIsolatedAntigravityHome } from "../isolated-home.ts";
 import type { AntigravityExecutionFacts, AntigravityProgressCallback } from "../types.ts";
-import { eventType, toolName } from "./event-values.ts";
+import { eventType, isRecord, toolName } from "./event-values.ts";
 import { AntigravityEventAccumulator } from "./events.ts";
 import { MAX_STREAM_EVENTS, parseNdjsonLine, StreamLimitError } from "./ndjson.ts";
 import { AntigravityResponseError } from "./response-error.ts";
@@ -16,28 +17,37 @@ const DEFAULT_PROBE_TIMEOUT_MS = 15 * 1_000;
 export type { AntigravityProbeResult } from "./subprocess.ts";
 export { AntigravityProcessError } from "./subprocess.ts";
 
-/** Build the fixed paid-run argument list. */
-export function buildAntigravityRunArguments(
-  schemaPath: string,
-  model: string,
-  conversationId?: string,
-  workspaceDirectory?: string,
-): string[] {
+/**
+ * Register extra roots per process, never in the shared profile. The enforced
+ * write_file(*) and command(*) denials keep these additional roots inspection-only.
+ */
+export function buildAntigravityRunArguments(options: {
+  schemaPath: string;
+  model: string;
+  conversationId?: string;
+  workspaceDirectory?: string;
+  additionalReadOnlyDirectories?: readonly string[];
+}): string[] {
   return [
     "--input-format",
     "stream-json",
     "--output-format",
     "stream-json",
     "--json-schema",
-    schemaPath,
+    options.schemaPath,
     "--model",
-    model,
+    options.model,
     "--print-timeout",
     "5m",
     "--sandbox",
-    ...(workspaceDirectory ? ["--add-dir", workspaceDirectory] : []),
+    ...[
+      ...new Set([
+        ...(options.workspaceDirectory ? [options.workspaceDirectory] : []),
+        ...(options.additionalReadOnlyDirectories ?? []),
+      ]),
+    ].flatMap((directory) => ["--add-dir", directory]),
     "--disable-slash-commands",
-    ...(conversationId ? ["--conversation", conversationId] : []),
+    ...(options.conversationId ? ["--conversation", options.conversationId] : []),
   ];
 }
 
@@ -60,6 +70,8 @@ export async function runAntigravityConversation(options: {
   conversationId?: string;
   /** Add the selected project directory to agy's sandbox workspace. */
   workspaceDirectory?: string;
+  /** Canonical inspection roots; fixed profile rules still deny writes and commands. */
+  additionalReadOnlyDirectories?: readonly string[];
   schema: Record<string, unknown>;
   signal?: AbortSignal;
   timeoutMs?: number;
@@ -73,16 +85,35 @@ export async function runAntigravityConversation(options: {
     join(options.schemaDirectoryParent ?? tmpdir(), "supi-consulting-schema-"),
   );
   const schemaPath = join(schemaDirectory, "answer.json");
-  const accumulator = new AntigravityEventAccumulator({ workspaceDirectory: options.cwd });
+  const responseToken = randomUUID();
+  const accumulator = new AntigravityEventAccumulator({
+    expectedResponseToken: responseToken,
+    workspaceDirectory: options.cwd,
+    additionalReadOnlyDirectories: options.additionalReadOnlyDirectories,
+  });
   let eventCount = 0;
   try {
-    await writeFile(schemaPath, `${JSON.stringify(options.schema)}\n`, { mode: 0o600 });
-    const args = buildAntigravityRunArguments(
+    // 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 = {
+      ...options.schema,
+      properties: {
+        ...(isRecord(options.schema.properties) ? options.schema.properties : {}),
+        responseToken: { type: "string", enum: [responseToken] },
+      },
+      required: [
+        ...(Array.isArray(options.schema.required) ? options.schema.required : []),
+        "responseToken",
+      ],
+    };
+    await writeFile(schemaPath, `${JSON.stringify(schema)}\n`, { mode: 0o600 });
+    const args = buildAntigravityRunArguments({
       schemaPath,
-      options.model,
-      options.conversationId,
-      options.workspaceDirectory,
-    );
+      model: options.model,
+      conversationId: options.conversationId,
+      workspaceDirectory: options.workspaceDirectory,
+      additionalReadOnlyDirectories: options.additionalReadOnlyDirectories,
+    });
     await runBoundedChildProcess({
       args,
       cwd: options.cwd,

package/src/agents/errors.ts

@@ -15,6 +15,8 @@ const FAILURE_REASON_MESSAGES = {
   "missing-answer": "The Consulting Agent did not return a final structured answer.",
   "invalid-answer":
     "The Consulting Agent returned an answer that does not match the required schema.",
+  "unbound-answer":
+    "The Consulting Agent's structured answer could not be verified for the current request. Start a new Consultation.",
   "missing-conversation": "The Consulting Agent did not return a conversation identifier.",
   "events-after-terminal": "The Consulting Agent sent data after its final result.",
   "malformed-json": "The Consulting Agent returned malformed JSON.",
@@ -27,9 +29,49 @@ const FAILURE_REASON_MESSAGES = {
 /** Fixed failure reasons that do not contain agent output. */
 export type ConsultingFailureReason = keyof typeof FAILURE_REASON_MESSAGES;
 
-/** Execution facts that can leave the adapter on failure. No resource names or raw output. */
+const DENIED_OPERATIONS = [
+  "command",
+  "file-read",
+  "file-write",
+  "web-read",
+  "browser",
+  "mcp",
+  "other",
+] as const;
+
+/** Fixed operation categories; raw agent tool names never leave the adapter on failure. */
+export type ConsultingDeniedOperation = (typeof DENIED_OPERATIONS)[number];
+
+/** Maximum distinct requested file targets in each failure resource list. */
+export const MAX_FAILURE_RESOURCES = 8;
+/** Longer paths are unavailable, never silently truncated into a different target. */
+export const MAX_FAILURE_RESOURCE_PATH_CHARS = 1_024;
+
+/** Structured requested file target, not a canonical path, rule decision, or outcome. */
+export interface ConsultingFileResource {
+  operation: "file-read" | "file-write";
+  requestedPath: string;
+}
+
+/** Failure facts plus bounded requested file targets; never raw tool payloads or output. */
 export interface ConsultingFailureDiagnostics {
   permissionDenials?: number;
+  /** Deduplicated denial counts, classified into fixed operation categories. */
+  permissionDenialsByOperation?: Partial<Record<ConsultingDeniedOperation, number>>;
+  /** Denied file operations targeting outside approved roots; not a claim about denial cause. */
+  deniedFileAccessOutsideReadRoots?: number;
+  /** Distinct requested file targets extracted from correlated structured tool parameters. */
+  deniedResources?: readonly ConsultingFileResource[];
+  /** File-denial observations whose known targets were omitted because the list is full. */
+  deniedResourcesOmitted?: number;
+  /** Known file-denial observations without an available, bounded structured target. */
+  deniedResourcePathsUnavailable?: number;
+  /** Requested file targets of calls without a terminal outcome; not attributed to denials. */
+  unfinishedResources?: readonly ConsultingFileResource[];
+  /** Unfinished file observations omitted because their target list is full. */
+  unfinishedResourcesOmitted?: number;
+  /** Unfinished file observations lacking a usable structured target. */
+  unfinishedResourcePathsUnavailable?: number;
   eventCount?: number;
   terminalSeen?: boolean;
   terminalSucceeded?: boolean;
@@ -40,7 +82,7 @@ export interface ConsultingFailureDiagnostics {
 export type ConsultingAgentFailureKind = keyof typeof FAILURE_MESSAGES;
 
 /**
- * A bounded failure with fixed messages and safe execution facts, but no raw cause.
+ * A bounded failure with fixed reason text and extracted execution metadata, but no raw cause.
  * Permission denials are observations, not a claim about the cause of failure.
  */
 export class ConsultingAgentError extends Error {
@@ -55,22 +97,160 @@ export class ConsultingAgentError extends Error {
     const message = options.reason
       ? FAILURE_REASON_MESSAGES[options.reason]
       : FAILURE_MESSAGES[kind];
-    const denial = (options.diagnostics?.permissionDenials ?? 0) > 0;
-    super(
-      `${message}${denial ? " A tool permission denial was observed. Check the requested resources and the Consulting Agent permissions." : ""}`,
-    );
-    this.name = "ConsultingAgentError";
-    this.kind = kind;
-    this.reason = options.reason;
     const facts = options.diagnostics;
-    this.diagnostics = facts
+    const diagnostics: ConsultingFailureDiagnostics | undefined = facts
       ? {
           permissionDenials: facts.permissionDenials,
+          ...(facts.permissionDenialsByOperation
+            ? {
+                permissionDenialsByOperation: sanitizeOperationCounts(
+                  facts.permissionDenialsByOperation,
+                ),
+              }
+            : {}),
+          ...(facts.deniedFileAccessOutsideReadRoots === undefined
+            ? {}
+            : { deniedFileAccessOutsideReadRoots: facts.deniedFileAccessOutsideReadRoots }),
+          ...(facts.deniedResources
+            ? { deniedResources: sanitizeFileResources(facts.deniedResources) }
+            : {}),
+          deniedResourcesOmitted: facts.deniedResourcesOmitted,
+          deniedResourcePathsUnavailable: facts.deniedResourcePathsUnavailable,
+          ...(facts.unfinishedResources
+            ? { unfinishedResources: sanitizeFileResources(facts.unfinishedResources) }
+            : {}),
+          unfinishedResourcesOmitted: facts.unfinishedResourcesOmitted,
+          unfinishedResourcePathsUnavailable: facts.unfinishedResourcePathsUnavailable,
           eventCount: facts.eventCount,
           terminalSeen: facts.terminalSeen,
           terminalSucceeded: facts.terminalSucceeded,
           exitCode: facts.exitCode,
         }
       : undefined;
+    super(`${message}${formatFailureContext(diagnostics)}`);
+    this.name = "ConsultingAgentError";
+    this.kind = kind;
+    this.reason = options.reason;
+    this.diagnostics = diagnostics;
+  }
+}
+
+function sanitizeFileResources(
+  resources: readonly ConsultingFileResource[],
+): ConsultingFileResource[] {
+  return resources
+    .slice(0, MAX_FAILURE_RESOURCES)
+    .flatMap((resource) =>
+      (resource.operation === "file-read" || resource.operation === "file-write") &&
+      typeof resource.requestedPath === "string" &&
+      resource.requestedPath.length > 0 &&
+      resource.requestedPath.length <= MAX_FAILURE_RESOURCE_PATH_CHARS
+        ? [{ operation: resource.operation, requestedPath: resource.requestedPath }]
+        : [],
+    );
+}
+
+function sanitizeOperationCounts(
+  counts: Partial<Record<ConsultingDeniedOperation, number>>,
+): Partial<Record<ConsultingDeniedOperation, number>> {
+  const result: Partial<Record<ConsultingDeniedOperation, number>> = {};
+  for (const operation of DENIED_OPERATIONS) {
+    const count = counts[operation];
+    if (typeof count === "number" && Number.isSafeInteger(count) && count > 0) {
+      result[operation] = count;
+    }
+  }
+  return result;
+}
+
+function formatFailureContext(facts: ConsultingFailureDiagnostics | undefined): string {
+  if (!facts) return "";
+  const parts: string[] = [];
+  if (facts.terminalSeen !== undefined) {
+    const status = facts.terminalSeen
+      ? facts.terminalSucceeded
+        ? "success"
+        : "unsuccessful"
+      : "not observed";
+    parts.push(`Agent terminal status: ${status}.`);
+  }
+  const denial = formatPermissionDenials(facts);
+  if (denial) parts.push(denial);
+  const unfinished = formatUnfinishedResources(facts);
+  if (unfinished) parts.push(unfinished);
+  return parts.length > 0 ? ` ${parts.join(" ")}` : "";
+}
+
+function formatPermissionDenials(facts: ConsultingFailureDiagnostics): string {
+  if ((facts.permissionDenials ?? 0) === 0) return "";
+  const parts = [`Observed permission denials: ${facts.permissionDenials}.`];
+  const counts = Object.entries(facts.permissionDenialsByOperation ?? {});
+  if (counts.length > 0) {
+    parts.push(
+      `Permission denials by operation: ${counts.map(([operation, count]) => `${operation}=${count}`).join(", ")}.`,
+    );
+  }
+  if ((facts.deniedFileAccessOutsideReadRoots ?? 0) > 0) {
+    parts.push(
+      `Denied file access outside approved read roots: ${facts.deniedFileAccessOutsideReadRoots}.`,
+    );
+  }
+  const resources = formatDeniedResources(facts);
+  if (resources) parts.push(resources);
+  parts.push("Permission denials are observations, not proof of the failure cause.");
+  if (facts.permissionDenialsByOperation?.command) {
+    parts.push("Workspace access does not grant command execution.");
+  }
+  parts.push(
+    "Do not retry denied actions unchanged. Use permitted inspection tools and artifacts in approved read roots, or request a limited/blocked report.",
+  );
+  return parts.join(" ");
+}
+
+function quoteFileResources(resources: readonly ConsultingFileResource[]): string {
+  return JSON.stringify(resources).replace(
+    /[\u007f-\u009f\u2028\u2029]/g,
+    (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+}
+
+function formatUnfinishedResources(facts: ConsultingFailureDiagnostics): string {
+  const parts: string[] = [];
+  if (facts.unfinishedResources?.length) {
+    parts.push(
+      `Requested file targets of unfinished actions: ${quoteFileResources(facts.unfinishedResources)}.`,
+    );
+  }
+  if ((facts.unfinishedResourcesOmitted ?? 0) > 0) {
+    parts.push(
+      `Additional unfinished file observations omitted: ${facts.unfinishedResourcesOmitted}.`,
+    );
+  }
+  if ((facts.unfinishedResourcePathsUnavailable ?? 0) > 0) {
+    parts.push(
+      `Unfinished file observations with unavailable structured targets: ${facts.unfinishedResourcePathsUnavailable}.`,
+    );
+  }
+  if (parts.length)
+    parts.push("Unfinished file operations have unknown outcomes; they are not confirmed denials.");
+  return parts.join(" ");
+}
+
+function formatDeniedResources(facts: ConsultingFailureDiagnostics): string {
+  const parts: string[] = [];
+  if (facts.deniedResources?.length) {
+    const targets = quoteFileResources(facts.deniedResources);
+    parts.push(`Requested file targets of denied actions: ${targets}.`);
+  }
+  if ((facts.deniedResourcesOmitted ?? 0) > 0) {
+    parts.push(
+      `Additional file-denial observations omitted from target list: ${facts.deniedResourcesOmitted}.`,
+    );
+  }
+  if ((facts.deniedResourcePathsUnavailable ?? 0) > 0) {
+    parts.push(
+      `File-denial observations with unavailable structured targets: ${facts.deniedResourcePathsUnavailable}.`,
+    );
   }
+  return parts.join(" ");
 }

package/src/agents/types.ts

@@ -25,6 +25,8 @@ export interface ConsultingAgentExecutionOptions {
   model: ConsultingModel;
   canonicalWorkingDirectory: string;
   workspaceAccess: boolean;
+  /** Canonical extra directory roots for inspection; writes and commands remain denied. */
+  additionalReadOnlyDirectories?: readonly string[];
   continuation?: string;
   signal?: AbortSignal;
   onProgress?: (activity: string) => void;