rea-agents 3.0.0 → 3.1.0

package/README.md

@@ -4,7 +4,7 @@
 
 # REA: Reverse Engineer Anything
 
-### One CLI and MCP server for agents to reverse engineer anything
+### Reverse engineer anything with agents, from app behavior down to native binaries.
 
 **See a feature you like. Understand how it works, down to the binary level.**
 
@@ -89,13 +89,13 @@ REA shows how it reached its conclusions. It does not claim to recover original
 ### Run setup — recommended
 
 ```bash
-npx rea-agents setup
+npx --yes rea-agents@latest setup
 ```
 
 The npm package-runner prompt, when shown, approves downloading REA for this
 invocation; it does not approve any setup changes. The REA wizard separately
 shows its complete plan and asks before applying it. Setup does not update
-Homebrew, Node.js, or npm. `npx rea-agents setup` opens with the work it
+Homebrew, Node.js, or npm. The setup command opens with the work it
 enables: investigate local apps from an agent, recover evidence through a
 deep-analysis provider, and reuse REA's guided workflow. It summarizes the
 detected agents, then asks which capabilities to set up: agent integration
@@ -103,12 +103,10 @@ detected agents, then asks which capabilities to set up: agent integration
 Nothing is preselected. Choosing agent integration opens a second empty
 checklist for the specific detected agents that should receive a registration.
 
-If bare `npx` finds a project-local REA package, its dispatcher restarts setup
-through `rea-agents@latest` before planning any changes. This prevents an older
-local dependency from silently writing stale integration state. An already
-published older release cannot contain that dispatcher protection; run
-`npx -y rea-agents@latest setup` once to repair registrations created by one.
-Intentional rollbacks remain available through an exact package request.
+`@latest` makes the requested release explicit and asks npm for the release
+currently published under that tag. REA does not silently replace the package
+version npm selected. Intentional rollbacks therefore remain available through
+an exact package request.
 
 REA keeps the journey inline so its history remains in the terminal. Selecting
 a capability does not select every detected target or authorize a change.
@@ -139,7 +137,7 @@ Pass installer options after `bash -s --`, for example `--dry-run`, `--no-setup`
 ### With an agent — recommended
 
 ```bash
-npx rea-agents setup
+npx --yes rea-agents@latest setup
 ```
 
 Choose Agent Integration in the reviewed setup plan. REA installs the pinned MCP
@@ -151,7 +149,7 @@ Review the setup plan, approve it if appropriate, then describe the app or featu
 ### From Terminal — no installation
 
 ```bash
-npx rea-agents setup
+npx --yes rea-agents@latest setup
 npx -y rea-agents@latest doctor
 npx -y rea-agents@latest analyze /Applications/Notes.app
 ```
@@ -386,10 +384,10 @@ REA handles the app analysis in steps 1–5. The agent performs step 6 with its
 | Artifact graph            |     3 | bounded provider-neutral inspection, deterministic directory/ZIP/APK/IPA/MSIX/AppX/ASAR inventory, and explicitly selected extraction into an absent owned tree                                                                                                                                                                  |
 | Managed PE/CLI            |     8 | PE/CLI identity, metadata members, CIL hashes, P/Invoke/native-boundary declarations and verification, application-graph projection, decompiler reconstruction import, token remapping, runtime-correlation plans, and version comparison                                                                                        |
 | Browser observation       |     9 | exact-origin passive CDP capture, bundle and source-map analysis, WebMCP discovery, session timelines, capture diff, visual evidence, and bounded Playwright scenarios                                                                                                                                                           |
-| Electron analysis         |     4 | passive root-confined observation, bounded static application mapping, and evidence-backed static/runtime reconciliation                                                                                                                                                                                                         |
+| Electron analysis         |     5 | passive root-confined observation, bounded static application mapping, evidence-backed static/runtime reconciliation, and separately approved provider-owned click/wait scenarios                                                                                                                                                |
 | JavaScript runtime        |     2 | approved attach-only Node/Electron Inspector target discovery plus bounded script and execution-context observation without evaluation or instrumentation                                                                                                                                                                        |
 | Application workflows     |    12 | bounded cross-layer traces, unique-only version matching, historical-source to bundle mapping, static export return-shape comparison, approved Linux-isolated extracted-module replay, managed-runtime characterization, reconstruction coverage closure, deterministic obligation ledgers, and end-to-end readiness conformance |
-| Workspace and observation |    22 | target lifecycle, Evidence v2 bundle snapshots, aggregate navigation/address context, direct finite replay-machine evaluation, process/artifact/function comparison, evidence-linked residual-unknown lifecycle                                                                                                                  |
+| Workspace and observation |    23 | target lifecycle, Evidence v2 bundle snapshots, retained-bundle release, aggregate navigation/address context, direct finite replay-machine evaluation, process/artifact/function comparison, evidence-linked residual-unknown lifecycle                                                                                         |
 
 The public interface describes what the agent is trying to learn. Providers decide how to answer. macOS utilities handle common semantic inspection without launching Hopper; Hopper handles deeper native analysis; the process harness implements controlled behavioral capture.
 
@@ -509,14 +507,14 @@ REA is growing into a toolkit for understanding software across static artifacts
 
 ### Next
 
-1. **Controlled replay conformance growth** — extend the shipped Linux extracted-module sandbox with more source-owned hostile fixtures and cross-kernel conformance; browser or Electron interaction remains a different future authority.
+1. **Controlled replay conformance growth** — extend the shipped Linux extracted-module sandbox with more source-owned hostile fixtures and cross-kernel conformance; browser and Electron scenarios remain separately permissioned authorities.
 2. **Broader application graph evidence** — extend authenticated cross-layer traces with additional static extractors and separately approved runtime authorities.
 3. **Professional managed-code analysis** — extend shipped PE/CLI triage, CIL evidence, managed/native declaration inventory, source-owned conformance, and obfuscation-resistant comparisons toward verified native-provider composition under the accepted [managed-code boundary](docs/managed-code-analysis.md).
 4. **Deterministic behavior harnesses** — extend process ownership, protocol fixtures, filesystem observation, reconnects, and cross-version behavioral comparison.
 
 ### Later
 
-1. **Controlled application interaction** — evaluate separately authorized full-application driving without widening passive browser, Electron, or extracted-module replay authority.
+1. **Broader controlled application interaction** — extend the separately authorized browser and Electron scenario surfaces beyond the current bounded click/wait actions without widening passive observation or extracted-module replay authority.
 2. **Native runtime observation** — approval-gated LLDB, Frida, system logs, process/filesystem observers, and native API tracing.
 3. **Additional providers and targets** — evaluate IDA/Hex-Rays, Binary Ninja, Rizin, LIEF, Windows-native providers, mobile artifacts, firmware, document formats, and other software-defined systems.
 
@@ -537,7 +535,7 @@ Setup detects Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf,
   "mcpServers": {
     "rea": {
       "command": "npx",
-      "args": ["-y", "rea-agents@3.0.0", "mcp"]
+      "args": ["-y", "rea-agents@3.1.0", "mcp"]
     }
   }
 }

package/dist/application/AnalysisContextQueries.js

@@ -69,10 +69,7 @@ export const inspectAddressContext = async (analysis, input, signal) => {
         comment,
         inline_comment: inlineComment,
         bookmarks: bookmarks.state === "available"
-            ? {
-                state: "available",
-                value: matchingBookmarks(bookmarks.value, resolvedAddress(results[1], input.address)),
-            }
+            ? matchingBookmarks(bookmarks.value, resolvedAddress(results[1], input.address))
             : bookmarks,
     });
 };
@@ -122,9 +119,24 @@ const resolvedAddress = (result, fallback) => {
 };
 const matchingBookmarks = (value, address) => {
     if (!Array.isArray(value))
-        return [];
-    return value.filter((bookmark) => typeof bookmark === "object" &&
-        bookmark !== null &&
-        !Array.isArray(bookmark) &&
-        bookmark.address === address);
+        return {
+            state: "unavailable",
+            reason: "list_bookmarks returned malformed output; expected an array.",
+            remediation: "Retry list_bookmarks directly and report the provider output shape if it remains malformed.",
+        };
+    if (!value.every(isBookmark))
+        return {
+            state: "unavailable",
+            reason: "list_bookmarks returned malformed entries; expected address and name strings.",
+            remediation: "Retry list_bookmarks directly and report the provider output shape if it remains malformed.",
+        };
+    return {
+        state: "available",
+        value: value.filter((bookmark) => bookmark.address === address),
+    };
 };
+const isBookmark = (value) => typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    typeof value.address === "string" &&
+    typeof value.name === "string";

package/dist/application/ApplicationWorkflowEvidenceResolver.js

@@ -36,7 +36,7 @@ export const resolveTraceApplicationFeatureRequest = (input, lookup) => {
 };
 /** Resolve a trace request already parsed by the caller-facing contract. */
 export const resolveTraceApplicationFeatureRequestValidated = (input, lookup) => {
-    const application = graphEvidence(input.application, input.application_evidence_id, lookup);
+    const application = graphEvidence(input, lookup);
     if (!application.ok)
         return application;
     const native = resolveEvidenceReferences(lookup, input.native_observation_evidence_ids);
@@ -63,7 +63,7 @@ export const resolveTraceJavaScriptSemanticsRequest = (input, lookup) => {
 };
 /** Resolve a semantic trace request already parsed by its public contract. */
 export const resolveTraceJavaScriptSemanticsRequestValidated = (input, lookup) => {
-    const application = graphEvidence(input.application, input.application_evidence_id, lookup);
+    const application = graphEvidence(input, lookup);
     if (!application.ok)
         return application;
     const raw = { application: application.value, query: input.query };
@@ -81,10 +81,14 @@ export const resolveCompareApplicationVersionsRequest = (input, lookup) => {
 };
 /** Resolve a comparison request parsed by the caller-facing contract. */
 export const resolveCompareApplicationVersionsRequestValidated = (input, lookup) => {
-    const left = graphEvidence(input.left, input.left_evidence_id, lookup);
+    const left = graphEvidence("left" in input
+        ? { application: input.left }
+        : { application_evidence_id: input.left_evidence_id }, lookup);
     if (!left.ok)
         return left;
-    const right = graphEvidence(input.right, input.right_evidence_id, lookup);
+    const right = graphEvidence("right" in input
+        ? { application: input.right }
+        : { application_evidence_id: input.right_evidence_id }, lookup);
     if (!right.ok)
         return right;
     const leftNative = resolveEvidenceReferences(lookup, input.left_native_observation_evidence_ids);
@@ -123,7 +127,7 @@ export const resolveCompareSourceToBundleRequest = (input, lookup) => {
 };
 /** Resolve a historical-source comparison request parsed by its public contract. */
 export const resolveCompareSourceToBundleRequestValidated = (input, lookup) => {
-    const application = graphEvidence(input.application, input.application_evidence_id, lookup);
+    const application = graphEvidence(input, lookup);
     if (!application.ok)
         return application;
     const raw = {
@@ -148,10 +152,14 @@ export const resolveCompareJavaScriptExportShapesRequest = (input, lookup) => {
 };
 /** Resolve an export-shape request already parsed by the adapter contract. */
 export const resolveCompareJavaScriptExportShapesRequestValidated = (input, lookup) => {
-    const left = graphEvidence(input.left, input.left_evidence_id, lookup);
+    const left = graphEvidence("left" in input
+        ? { application: input.left }
+        : { application_evidence_id: input.left_evidence_id }, lookup);
     if (!left.ok)
         return left;
-    const right = graphEvidence(input.right, input.right_evidence_id, lookup);
+    const right = graphEvidence("right" in input
+        ? { application: input.right }
+        : { application_evidence_id: input.right_evidence_id }, lookup);
     if (!right.ok)
         return right;
     const raw = {
@@ -171,10 +179,10 @@ export const resolveCompareJavaScriptExportShapesRequestValidated = (input, look
         ? ok(parsed.data)
         : invalid("compare_javascript_export_shapes", parsed.error, raw);
 };
-const graphEvidence = (evidence, evidenceId, lookup) => {
-    if (evidence !== undefined)
-        return ok(evidence);
-    const resolved = resolveEvidenceReferences(lookup, evidenceId === undefined ? [] : [evidenceId], APPLICATION_GRAPH_IDENTITIES);
+const graphEvidence = (source, lookup) => {
+    if ("application" in source)
+        return ok(source.application);
+    const resolved = resolveEvidenceReferences(lookup, [source.application_evidence_id], APPLICATION_GRAPH_IDENTITIES);
     return resolved.ok ? ok(resolved.value[0]) : resolved;
 };
 const invalid = (operation, cause, input) => err(new AnalysisInputError(operation, undefined, projectInputIssues(cause.issues, input)));

package/dist/application/ArtifactInventory/policy.js

@@ -0,0 +1,17 @@
+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+/** Resolve caller approval and operator policy before native reader selection. */
+export const resolveNativeMountPolicy = (approved, enabled) => {
+    if (!approved)
+        return { status: "disabled" };
+    if (!enabled)
+        throw new ArtifactReaderFailure("unavailable", "Native DMG mounting is disabled by operator policy");
+    return { status: "approved" };
+};
+/** Resolve parsed caller intent and operator policy before artifact scanning. */
+export const resolveArtifactIntegrityPolicy = (intent, enabled) => {
+    if (intent.mode === "fail")
+        return intent;
+    if (!enabled)
+        throw new ArtifactReaderFailure("policy", "Integrity continuation requires explicit approval and operator policy");
+    return intent;
+};

package/dist/application/ArtifactInventory/reader.js

@@ -1,5 +1,4 @@
 import { AsarArtifactReader } from "../../artifacts/AsarArtifactReader.js";
-import { ArtifactReaderFailure, } from "../../artifacts/ArtifactReader.js";
 import { DirectoryArtifactReader } from "../../artifacts/DirectoryArtifactReader.js";
 import { MachOSliceArtifactReader } from "../../artifacts/MachOSliceArtifactReader.js";
 import { NativeDmgArtifactReader } from "../../artifacts/NativeDmgArtifactReader.js";
@@ -21,10 +20,8 @@ export const createReader = async (path, format, nativeMount, signal) => {
                 ? new MachOSliceArtifactReader(path)
                 : undefined;
         case "dmg":
-            if (!nativeMount.nativeMountApproved)
+            if (nativeMount.status === "disabled")
                 return undefined;
-            if (!nativeMount.nativeMountEnabled)
-                throw new ArtifactReaderFailure("unavailable", "Native DMG mounting is disabled by operator policy");
             return NativeDmgArtifactReader.create(path, signal);
         default:
             return undefined;

package/dist/application/ArtifactInventory/scanCanonical.js

@@ -10,9 +10,6 @@ import { scanReader, } from "./scanReader.js";
 import { NATIVE_MOUNT_DISABLED, STRICT_INTEGRITY_POLICY, } from "./types.js";
 export const scanCanonicalArtifactInventory = async (path, limits, options = {}) => {
     const integrity = options.integrity ?? STRICT_INTEGRITY_POLICY;
-    if (integrity.mode === "record-and-continue" &&
-        (!integrity.approved || !integrity.enabled))
-        throw new ArtifactReaderFailure("policy", "Integrity continuation requires explicit approval and operator policy");
     const metadata = await lstat(path);
     const rootFormat = await classifyRoot(path, metadata.isDirectory());
     const rootDigest = metadata.isDirectory()

package/dist/application/ArtifactInventory/scanReader.js

@@ -69,14 +69,14 @@ const digestArtifactEntry = async (context, currentReader, entry, logicalPath) =
     const digest = await hashReadable(await currentReader.open(entry, context.signal), Math.min(context.limits.maxEntryBytes, remainingBytes), context.signal);
     context.totalBytes += digest.bytes;
     const mismatched = entry.declaredSha256 !== null && entry.declaredSha256 !== digest.sha256;
-    if (mismatched && context.integrity.mode === "fail")
-        throw new ArtifactReaderFailure("integrity", `Artifact integrity metadata disagrees with content: ${logicalPath}`, undefined, {
-            logicalPath,
-            declaredSha256: entry.declaredSha256,
-            calculatedSha256: digest.sha256,
-            unpacked: entry.unpacked,
-        });
     if (mismatched && entry.declaredSha256 !== null) {
+        if (context.integrity.mode === "fail")
+            throw new ArtifactReaderFailure("integrity", `Artifact integrity metadata disagrees with content: ${logicalPath}`, undefined, {
+                logicalPath,
+                declaredSha256: entry.declaredSha256,
+                calculatedSha256: digest.sha256,
+                unpacked: entry.unpacked,
+            });
         if (context.pendingContradictions.length >= context.integrity.maxMismatches)
             throw new ArtifactReaderFailure("limit", "Artifact integrity mismatch limit exceeded");
         context.pendingContradictions.push({

package/dist/application/ArtifactInventory/types.js

@@ -1,10 +1,6 @@
 export const NATIVE_MOUNT_DISABLED = {
-    nativeMountApproved: false,
-    nativeMountEnabled: false,
+    status: "disabled",
 };
 export const STRICT_INTEGRITY_POLICY = {
     mode: "fail",
-    approved: false,
-    enabled: false,
-    maxMismatches: 1,
 };

package/dist/application/BinarySession.js

@@ -24,7 +24,7 @@ export class BinarySession extends BinarySessionRecords {
     #transition = Promise.resolve();
     #calls = new Set();
     #providerRouter;
-    #runtimeAvailability = new Map();
+    #runtimeUnavailability = new Map();
     #availabilityListeners = new Set();
     constructor(provider, options = {}) {
         super();
@@ -185,7 +185,7 @@ export class BinarySession extends BinarySessionRecords {
             target: this.#active?.target,
             route: this.#currentRoute(),
             router: this.#providerRouter,
-            runtimeAvailability: this.#runtimeAvailability,
+            runtimeUnavailability: this.#runtimeUnavailability,
             runId: this.#active?.runId,
             runtimeLineageSnapshots: this.#active?.client.runtimeLineageSnapshots?.() ?? [],
             requestActivitySnapshots: this.#active?.client.requestActivitySnapshots?.() ?? [],
@@ -246,12 +246,12 @@ export class BinarySession extends BinarySessionRecords {
     }
     #observeRuntimeAvailability(operation, result) {
         if (result.ok) {
-            if (this.#setRuntimeAvailability(operation, true, null))
+            if (this.#markRuntimeAvailable(operation))
                 this.#emitAvailabilityChanged();
             return;
         }
         if (result.error._tag === "AnalysisCapabilityUnavailableError") {
-            if (this.#setRuntimeAvailability(operation, false, result.error.message))
+            if (this.#markRuntimeUnavailable(operation, result.error.message))
                 this.#emitAvailabilityChanged();
             return;
         }
@@ -267,27 +267,25 @@ export class BinarySession extends BinarySessionRecords {
             for (const descriptor of capabilities?.values() ?? [])
                 if (providerId !== undefined && descriptor.provider.id === providerId)
                     changed =
-                        this.#setRuntimeAvailability(descriptor.operation, false, "Provider became unavailable during this session.") || changed;
+                        this.#markRuntimeUnavailable(descriptor.operation, "Provider became unavailable during this session.") || changed;
             if (changed)
                 this.#emitAvailabilityChanged();
         }
     }
-    #setRuntimeAvailability(operation, available, reason) {
-        const current = this.#runtimeAvailability.get(operation);
-        if (current?.available === available && current.reason === reason)
-            return false;
-        if (available && current === undefined)
+    #markRuntimeAvailable(operation) {
+        return this.#runtimeUnavailability.delete(operation);
+    }
+    #markRuntimeUnavailable(operation, reason) {
+        const current = this.#runtimeUnavailability.get(operation);
+        if (current?.reason === reason)
             return false;
-        if (available)
-            this.#runtimeAvailability.delete(operation);
-        else
-            this.#runtimeAvailability.set(operation, { available, reason });
+        this.#runtimeUnavailability.set(operation, { reason });
         return true;
     }
     #clearRuntimeAvailability() {
-        if (this.#runtimeAvailability.size === 0)
+        if (this.#runtimeUnavailability.size === 0)
             return;
-        this.#runtimeAvailability.clear();
+        this.#runtimeUnavailability.clear();
         this.#emitAvailabilityChanged();
     }
     #emitAvailabilityChanged() {

package/dist/application/BinarySessionRecords.js

@@ -63,17 +63,31 @@ export class BinarySessionRecords {
             bytes: Buffer.byteLength(existing ?? encoded),
             records: bundle.records.length,
             unknowns: bundle.unknowns.length,
+            scope: "session",
+            survivesSession: false,
             uri: `rea://evidence-bundle/${digest}`,
         });
     }
     retainedEvidenceBundle(digest) {
         return this.#retainedBundles.get(digest);
     }
+    /** Release one immutable bundle so bounded retention has an explicit recovery path. */
+    releaseEvidenceBundle(bundleDigest) {
+        const encoded = this.#retainedBundles.get(bundleDigest);
+        if (encoded === undefined)
+            return false;
+        this.#retainedBundles.delete(bundleDigest);
+        this.#retainedBundleBytes -= Buffer.byteLength(encoded);
+        this.#emitSnapshotChanged();
+        return true;
+    }
     importEvidenceBundle(bundle) {
         const imported = this.#evidence.import(bundle);
-        if (imported.ok && imported.value > 0)
+        if (!imported.ok)
+            return imported;
+        if (imported.value.changed)
             this.#emitSnapshotChanged();
-        return imported;
+        return ok(imported.value.recordsAdded);
     }
     exportAnalysisSnapshot() {
         const active = this.activeAnalysisBinding();
@@ -93,7 +107,10 @@ export class BinarySessionRecords {
             return err(new EvidenceIntegrityError("Analysis snapshot profile_mismatch: the active target has no concrete analysis profile"));
         const imported = this.#snapshot.import(snapshot, active === undefined
             ? undefined
-            : { target: active.target, profile: active.profile }, (bundle) => this.#evidence.import(bundle));
+            : { target: active.target, profile: active.profile }, (bundle) => {
+            const imported = this.#evidence.import(bundle);
+            return imported.ok ? ok(imported.value.recordsAdded) : imported;
+        });
         if (imported.ok)
             this.#emitSnapshotChanged();
         return imported;
@@ -136,8 +153,17 @@ export class BinarySessionRecords {
         this.#emitSnapshotChanged();
     }
     #emitSnapshotChanged() {
-        for (const listener of this.#snapshotListeners)
-            void listener();
+        for (const listener of this.#snapshotListeners) {
+            try {
+                const notification = listener();
+                if (notification !== undefined)
+                    void notification.catch(() => undefined);
+            }
+            catch {
+                // External resource observers are best-effort; one callback must not
+                // make a committed evidence mutation appear to fail.
+            }
+        }
     }
     retainInvestigationWorkspace(workspace) {
         const parsed = parseInvestigationWorkspace(workspace);

package/dist/application/BinarySessionStatus.js

@@ -1,14 +1,20 @@
 /** Project internal provider routing state into the caller-visible session status. */
-export const binarySessionStatus = ({ target, route, router, runtimeAvailability, runId, runtimeLineageSnapshots, requestActivitySnapshots, }) => {
+export const binarySessionStatus = ({ target, route, router, runtimeUnavailability, runId, runtimeLineageSnapshots, requestActivitySnapshots, }) => {
     const configuredProvider = router.configuredIdentity();
     const provider = providerSummary(configuredProvider);
     const providers = router.providerIdentities(route).map(providerSummary);
     const capabilities = [...(route.capabilities?.values() ?? [])]
         .sort((left, right) => left.operation.localeCompare(right.operation))
-        .map((descriptor) => ({
-        ...descriptor,
-        ...runtimeAvailability.get(descriptor.operation),
-    }))
+        .map((descriptor) => {
+        const unavailable = runtimeUnavailability.get(descriptor.operation);
+        return unavailable === undefined
+            ? descriptor
+            : {
+                ...descriptor,
+                available: false,
+                reason: unavailable.reason,
+            };
+    })
         .map(capabilityStatus);
     const analysisProviderBinding = route.binding === null
         ? null

package/dist/application/BrowserEvidence.js

@@ -21,9 +21,7 @@ export const createBrowserEvidence = (operation, input, result, provider) => cre
 });
 const browserParameters = (input) => {
     if (!("cdp_endpoint" in input)) {
-        if ("before_scenario" in input &&
-            input.before_scenario !== undefined &&
-            input.after_scenario !== undefined)
+        if ("before_scenario" in input)
             return {
                 comparison_kind: "browser_scenario",
                 before_browser: input.before_scenario.browser,
@@ -89,9 +87,9 @@ const browserParameters = (input) => {
         include_storage_keys: input.include_storage_keys,
         include_storage_fingerprints: input.include_storage_fingerprints,
         limits: input.limits,
-        ...(input.include_script_sources && "source_capture_approved" in input
+        source_capture_approved: input.source_capture_approved,
+        ...(input.include_script_sources && "analysis_limits" in input
             ? {
-                source_capture_approved: input.source_capture_approved,
                 fetch_source_maps: input.fetch_source_maps,
                 source_map_fetch_approved: input.source_map_fetch_approved,
                 analysis_limits: input.analysis_limits,

package/dist/application/CapabilityClientRequirements.js

@@ -0,0 +1,26 @@
+/** Empty MCP client feature declaration used when the caller supplies none. */
+export const NO_CLIENT_FEATURES = {
+    elicitation_form: false,
+    elicitation_url: false,
+    roots: false,
+    sampling: false,
+};
+const CLIENT_FEATURE_REQUIREMENTS = {
+    capture_process_scenario: {
+        required: [],
+        optional: ["elicitation_form"],
+    },
+};
+/** Project a tool's client requirements against the negotiated feature set. */
+export const clientRequirementsFor = (name, clientFeatures) => {
+    const requirements = CLIENT_FEATURE_REQUIREMENTS[name] ?? {
+        required: [],
+        optional: [],
+    };
+    return {
+        required: [...requirements.required],
+        optional: [...requirements.optional],
+        missing_required: requirements.required.filter((feature) => !clientFeatures[feature]),
+        missing_optional: requirements.optional.filter((feature) => !clientFeatures[feature]),
+    };
+};