Files
reverse-engineering-anything/docs/development/tool-design.md
T
morluto 897784042a fix(native)!: report a target-selected plist against the target, not the unsent path input (#10798)
* fix(native): report a target-selected plist against the target, not the unsent path input

inspect_plist resolved a plist that the open target itself selects with the same origin as a caller's path input, so an unreadable target plist was reported as an input issue on path even when the caller never sent path. The selection now records a target origin, and unreadablePlist reports it as a BinaryTargetError for the target. The inspect-plist CLI command is projected from its contract, so its --relative-path issues are named by the CLI key.

* refactor(cli)!: route analyze to the contract its target selects (#10808)

* refactor(cli): route analyze to the contract its target selects

analyze hand-declared both lanes: native open options for binary_overview and the JavaScript integrity policy and source selection for analyze_javascript_application, with its own routing and refusals. registerTargetRoutedCommand now projects each route from its contract, takes the union of their options, runs the first route that owns every given option and takes the target, and refuses options the chosen route does not own by their CLI key. Omitted union fields, including a root discriminator, no longer need an argv projection.

* fix(cli): give a routed command's chosen route its CLI-only option defaults

Routing strips option defaults so an omitted option routes no target. Contract fields regain theirs on admission, but CLI-only options have no later parse, so a defaulted one reached the handler as undefined. The chosen route's omitted CLI-only options now receive their defaults before the handler runs.

* refactor(cli): deliver decompile and inspect-macho Evidence by the contract's detail (#10813)

* refactor(cli): deliver decompile and inspect-macho Evidence by the contract's detail

decompile and inspect-macho omitted the contract's detail field and always printed complete Evidence. Both now declare evidenceDelivery, adding --detail and --evidence_output from the contract. Publishing a result never used the provider id it required, so publication takes no provider and runOnSessionTarget no longer needs one to deliver.

* refactor(cli): project managed artifact and native-boundary inspectors from their contracts (#10816)

inspect-managed-artifact and inspect-managed-native-boundaries re-declared the managed budget fields by hand. Both now register from their contracts on a session target, and inspect-managed-artifact gains --detail and --evidence_output from its detail field.

* fix(cli): name every contract command's input issues by their CLI key

Commands applied their CLI field binding only where a session-target or
direct handler returned an undelivered result. With evidenceDelivery,
decompile publishes through the shared delivery, which returned a
provider failure unprojected, so an issue about the procedure would be
reported at ["procedure"] instead of the advertised positional
"address". Handlers that run a service or publish themselves never
applied it: inspect-il2cpp-metadata reported ["generic_instances"],
inspect-go-binary ["max_string_literals"] and inspect-apple-ips
["join_path"] rather than the CLI keys other commands report.

The contract command now projects whatever its handler returns through
the binding it owns, for plain and target-routed commands alike, and
the handler context no longer carries the binding.

* fix(analysis-view): summarize pseudocode that selected an independent fresh decompile

The pseudocode view parsed its parent's parameters with a selection
schema that admitted only procedure and document. A procedure_pseudo_code
observation made with analysis independent_fresh records that field, so
its summary view refused the parent. Through the CLI's new summary
delivery, `decompile --analysis independent_fresh --detail summary
--evidence_output <file>` would fail after a successful decompile and
never save the bundle; an inline inspect_analysis_view of such Evidence
failed the same way.

The selection schema now admits the analysis the contract offers, and
the contract reads that enum from the same owner.

* test(cli): restore the worker's exit status after synthetic contract command runs

logCliCommand sets process.exitCode on a refused or failed command. The
synthetic routed and input-field harnesses ran in the cli-boundary
project's shared workers (isolate: false) and left that status for later
tests. Each invocation now restores the previous status.

* refactor(cli)!: deliver inspect-managed-members Evidence through the shared --evidence_output (#10845)

inspect-managed-members was the last command with its own Evidence
delivery: a hand-written registration passed --detail and
--evidence-bundle to runProviderAnalysis, whose members-only delivery
variant re-checked heap headroom and published through
deliverAnalysisEvidence. Every other producer writes its bundle with
--evidence_output through publishCliAnalysisEvidence, and elsewhere on
the CLI --evidence-bundle names an input bundle to read.

The command now registers from the inspect_managed_members contract on
a session target with evidenceDelivery, like inspect-managed-artifact;
--type is the contract's type_names. runProviderAnalysis loses its
delivery parameter and its two refusals, and deliverAnalysisEvidence,
now unused, is deleted. Its lifecycle tests drive publishEvidenceDelivery
directly or the CLI delivery; the managed-only headroom pre-check tests
are removed, since the shared delivery deliberately does not
re-authenticate immutable Evidence and keeps the writer's check for
mutable sources.

BREAKING CHANGE: `rea inspect-managed-members --evidence-bundle <path>`
is now `--evidence_output <path>`; the old flag is refused as an unknown
flag. With `--detail summary`, stdout is now
`{"summary": <summary Evidence>, "evidence_bundle": {"path", "bytes"}}`
instead of the summary Evidence alone, and a publication failure is the
shared delivery's error projection without the `error` label or
`input_path`. A summary without a destination names `evidence_output`
in its issue path. Migrate by renaming the flag and reading
`.summary`. Compatibility is not kept: one spelling cannot mean "read
this bundle" on view and workflow commands and "write this bundle" on
one producer.

* refactor(cli): project analyze-javascript-application and analyze's JavaScript route from one contract projection

analyze-javascript-application declared its options by hand, mapped
about twelve option names to contract fields itself, parsed its delivery
separately and resolved its own caller path. analyze's JavaScript route,
projected from the same contract, omitted every field but the path,
source selection and integrity policy, so the two commands for one
contract offered different options.

Both now use javaScriptApplicationCliProjection and
runJavaScriptApplicationCommand: the path positional, --artifact-format,
--source-path, and the two options that accept a JSON file
(--source-paths-json, --semantic-precision), with contract delivery.
analyze therefore takes the JavaScript budgets, --artifact-format,
--semantic-precision and --detail/--evidence_output/--view for
JavaScript targets, and refuses them by CLI key for native targets.
javascriptApplicationOptions is deleted.

The command's missing-target refusal now names its CLI key, "path",
as every contract command does.

* refactor(cli): project the apktool commands from their contracts (#10878)

* refactor(cli): project the apktool commands from their contracts

* refactor(cli): project the Flutter commands from their contracts (#10882)

* refactor(cli): project the Flutter commands from their contracts

* refactor(cli): project the JEB commands from their contracts (#10888)

* refactor(cli): project the JEB commands from their contracts

* refactor(cli): project the Android package, class, method and reference commands from their contracts (#10893)

* refactor(cli): compose compare-managed-members from its contract over two inspected targets (#10914)

* refactor(cli): compose compare-managed-members from its contract over two inspected targets

The contract command builder takes Evidence targets: required contract
fields that each take the Evidence a source contract produces for one
positional target, with the source's options admitted for every target.
compare-managed-members now inspects each path through the typed managed
runner, as inspect-managed-members does, and compares the records as MCP
compare_managed_members does. A failing candidate names its argument and
retains the baseline's Evidence; a cancellation as the comparison settles
retains the comparison. The path-only comparison service is removed.

* fix(cli): drain queued interrupts before a composed command settles

Select snapshot faults by file identity, guard real permission denial to
hosts that enforce it, and release retained owners when a test fails.

* refactor(cli): project the ADB commands from their contracts (#10934)

Each ADB command is registered from its ADB_TOOL_CONTRACTS entry through
registerContractCommand, keeping its positionals, flags and kebab-case path
keys. start-adb-activity keeps its repeatable --extra type:key:value option,
which supplies the contract's extras.

* refactor(cli): project Frida discovery from its contracts and share Frida request mapping with MCP (#10951)

list-frida-devices and list-frida-processes are registered from their
contracts, with each remote member as its own option, and admit the request
MCP would send. instrument-with-frida keeps its argv but builds and admits
the instrument_with_frida contract input. One application owner maps Frida
contract inputs to service requests for both adapters.

* refactor(cli): finalize the Evidence-target composition through runOwned

runOnEvidenceTargets turned a completed comparison into a cancellation by reading the abort signal by hand, which main's architecture guard now refuses outside runOwned. The composition now finalizes through runOwned: its close drains queued interrupts (it owns no resource), and a cancellation observed as it settles keeps the completed Evidence as the partial observation, as before.

* fix(errors)!: keep every completed argument's observation beside a composite failure's own partial (#10961)

* fix(errors): keep every completed argument's observation beside a composite failure's own partial

* test(errors): cover argument observations through cleanup composition and the partial-free fallback

* test(errors): settle the cleanup through its owner's release in the argument-observation case

* refactor(cli): project instrument-with-frida through the contract builder (#10962)

* refactor(cli): project instrument-with-frida through the contract builder with CLI-only positionals and handler-filled fields

* fix(cli): keep omitted flattened members omitted so partial capture limits keep their Evidence

* refactor(cli): project the CDP page-target browser commands from their contracts (#10976)

* refactor(cli): project the CDP page-target browser commands from their contracts

* refactor(cli): project inspect-web-page from its contract with a branch-selecting flag

* test(cli): enroll the browser commands in the parity registration check and refuse unenrolled argv fixtures

* refactor(cli): project the V8 Inspector and Electron commands from their contracts (#10977)

* refactor(cli): project the V8 Inspector runtime commands from their contracts

* test(cli): enroll the V8 Inspector runtime commands in the parity registration check

* refactor(cli): project the Electron page observation commands from their contracts (#10987)

* refactor(cli): project the Electron page observation commands from their contracts

* test(cli): enroll the Electron page observation commands in the parity registration check

* refactor(cli): project inspect-electron-fuses from its contract with the shared caller-path rule

The command now registers through registerContractCommand with `path` as a
caller path, so the builder's absoluteCallerPath owns relative-path
anchoring and the command's own absoluteElectronFusePath copy is removed.
inspectWithService records the caller's spelling as caller_input_path.

The named file is unchanged: every `..` is kept for the filesystem, and
Win32 resolves as before. The recorded selected_path drops `.` segments
and repeated separators (`App.app/./` -> `App.app/`), and an empty path is
now refused at argv parsing (VALIDATION_ERROR) like every other
caller-path command.

* test(cli): derive contract-built commands from the builder registries instead of a hand list

Every command named after a public tool contract must register through a contract builder unless it is in a shrinking list of hand registrations, and the renamed contract commands are listed exactly, so an earlier migration that reverts fails instead of dropping out of the parity cases. The JSON-document command hand list is covered by the same check and removed.

* test(cli): drop the empty inspect-electron-fuses path mismatch the CLI now refuses

* refactor(cli): project compare-web-screenshots and analyze-web-bundle from their contracts with builder JSON inputs (#11012)

* refactor(cli): project compare-web-screenshots from its contract with builder JSON inputs read from inline text or a file

The contract command builder gains jsonInputs: structured fields taken as inline JSON or a JSON file path (- reads stdin), read when the command runs and admitted with the contract input before any target is opened. Inline text that is not JSON is refused under its CLI key; a file that cannot be read keeps its own failure. compare-web-screenshots takes both artifacts this way, replacing its hand-written JSON argument parsing.

* refactor(cli): project analyze-web-bundle from its contract

analyze-web-bundle now registers through registerContractCommand with Evidence and view delivery, semantic_precision as a builder JSON input, and source_map_limits flattened onto the existing --source-map-* flags. Page-inspection extras stay omitted, and script sources stay on as the contract default. The superseded javascriptRouteDelivery options, passive browser scope options, observation duration helper and fetched source-map option set are removed.

* refactor(cli): take semantic_precision of JavaScript application analysis as a builder JSON input

analyze-javascript-application and the analyze route read --semantic-precision through the contract builder's jsonInputs instead of a CLI-only option decoded in the handler, so the decoded budgets are admitted with the contract input before analysis.

* refactor(cli): route compare-web-captures to the contract input shape its documents select (#11027)

* refactor(cli): route compare-web-captures to the contract input shape its documents select

* fix(cli): keep routed defaults advertised and reuse the admitted capture parse

* fix(cli): keep explicit routed options distinct from advertised defaults

* refactor(cli): project inspect-ntfs-journal from its contract (#11043)

* refactor(cli): project inspect-ntfs-journal from its contract

* refactor(cli): project the pcap commands from their contracts (#11045)

* refactor(cli): project the pcap commands from their contracts

* refactor(cli): project inspect-playwright-trace, the Cutter commands and execute-rizin-command from their contracts (#11046)

* refactor(cli): project inspect-playwright-trace from its contract

* refactor(cli): project the Cutter commands from their contracts (#11047)

* refactor(cli): project the Cutter commands from their contracts

* refactor(cli): project execute-rizin-command from its contract (#11048)

* fix(cli): refuse a selected page without summary delivery before opening the target

* refactor(cli): project export-web-scripts and trace-web-module-imports from their contracts (#11053)

* refactor(cli): project export-web-scripts and trace-web-module-imports from their contracts

* fix(cli): describe export-web-scripts paths as resolved against the working directory

* refactor(cli): project the web runtime and JavaScript recovery commands from their contracts (#11084)

* refactor(cli): project the web runtime commands from their contracts

* refactor(cli): project recover-javascript-sources from its contract

* refactor(cli): select a contract input branch by its literal field and project guided-workflows (#11085)

* refactor(cli): select a contract input branch by its literal field and project guided-workflows

* fix(cli): refuse delivery options before reading JSON inputs

* fix(cli): keep branch-only defaults to their branch and name admission issues by CLI key

A branch-only field no longer carries its default into the shared options, so another branch never receives it; the selected branch applies the default on parse. Contract admission failures are projected to CLI keys like handler failures. CLI defaults are typed only on top-level fields, the one place that applies them.

* refactor(cli): project compare-process-captures from its contract, checking each capture before reading the next (#11114)

* refactor(cli): project compare-process-captures from its contract, checking each capture before reading the next

The contract builder gains jsonInputChecks: each check runs on a decoded JSON input as soon as it is read, in argv order, so a refused input stops the command before the next is read; the handler receives what each check admitted. compare-process-captures authenticates the left capture before reading the right and the right before the trace specification, then compares the authenticated facts. It now also takes inline JSON, stdin and --max-capture-age-ms like MCP. Empty JSON input text is refused at argv. A JSON input whose final file close fails is reported as cleanup_incomplete naming the file instead of an unclassified failure. compareProcessEvidenceFiles and its trace-spec parser are removed.

* fix(cli): retry a refused JSON input close and keep the read's refusal beside incomplete cleanup

parseCliJsonInput gives the file's owner a resource scope, so a transient close refusal is retried before the command fails. A close that still fails reports cleanup_incomplete composed with the read's own refusal. Routed commands refuse routes that check a shared JSON input differently, since it is checked before the route is chosen.

* refactor(cli): project inspect-web-network-capture from its contract with nested protobuf options

The contract builder flattens a nested optional object member in turn (protobuf.schema), resolves a flattened caller-path member and reports it as spelled under its dotted path in callerInputs, keeps a flattened member's contract default out of argv so an omitted member stays omitted, and takes an array of numbers as repeated decimal tokens within its bounds. inspect-web-network-capture registers from its contract with the same option names; Evidence keeps the capture and descriptor paths as the caller spelled them. CLI input issues name the capturePath argument.

* fix(cli): name a selector field by its own option in admission issues

A selector parameter's positional may share another key (decompile's procedure positional is address), so mapping the field to its positional key renamed selection issues that already name the option, such as a missing or conflicting --procedure. Map a selector field to its option.

* fix(cli): retain a JSON input file whose close fails and keep why its read stopped

parseCliJsonInput dropped its per-read scope after the owner's close retry failed, so the handle lost its owner, and a read or cancellation failure recorded before the close was replaced by the cleanup failure. The read's scope now stays with the CLI process until final CLI cleanup retries it, and the recorded outcome is translated once into the primary failure with the cleanup attached. The module moves into src/cli so it can register with the CLI process owner without a layer cycle.

* refactor(cli): project inspect-with-objdump and inspect-api-contract from their contracts (#11142)

* refactor(cli): project inspect-with-objdump, list-objdump-architectures and inspect-api-contract from their contracts

The contract builder selects input branches by a field that is a literal in
one branch and an enum in another, takes the default of the one branch that
admits omission, and lets a command take a subset of a union's branches by
their discriminating values, fixing the field when one value is selected.

* refactor(cli): project trace-web-source-location from its contract with flattened positional objects (#11167)

* refactor(cli): project trace-web-source-location from its contract with flattened positional objects

The contract builder flattens required objects as well as optional ones; a
flattened field listed in positionals takes its members as positionals in
member order. The hand-written source-map limit options and the separate CLI
delivery schema are removed.

* fix(cli): refuse to flatten a required object without a required member

* fix(cli): refuse a malformed Evidence-input document before reading the selected bundle

runEvidenceInputCommand admits the document with its transport frame before
it reads --evidence-bundle, so every Evidence-input command refuses a
malformed document first, as compare-static-and-observed-endpoints already
did by hand.

* test(cli): expect a selector field to be named by its option in input issues

* fix(cli): report a refused view before the delivery rule it would trip

Refusing delivery options before JSON inputs are read checked --evidence_output before the view's own schema, so a summary view naming an unknown field reported only the missing bundle. Admit the view with the contract's view field first, as full admission does.

* refactor(cli): project inspect-android-jni-bindings from its contract with a grouped --query option (#11196)

* refactor(cli): project inspect-android-jni-bindings from its contract with a grouped --query option

A projection's fieldGroups take several optional top-level contract fields as the members of one JSON object option. The text is decoded when the command runs, refused with the group's message when it is not a JSON object, a member that is not one of the group's fields is refused by its path, and the contract admits each member as its field. inspect-android-jni-bindings keeps its --query selection through a group and now registers through the contract builder, so the hand-registered contract command list is empty; the superseded parseCliAnalysisEvidenceDelivery and androidJniDeliverySchema are removed.

* fix(cli): refuse an object rule that names a grouped field

A grouped field is a JSON member, not an option, so a contract rule such as dependentRequired naming it would be advertised over an option that does not exist. Registration now refuses that combination.

* fix(cli): describe the --view and --maxCaptureAgeMs options of projected commands

A projected view field kept no help because the contract's own description was skipped and none replaced it, and compare-process-captures exposed max_capture_age_ms without help. The canonical CLI catalog test refused both. The view option now takes the same help in both builders.

* refactor(cli): derive the CLI command inventory from the contract registry (#11248)

A contract now declares `cli: true` when the CLI exposes it as the command
named by its kebab-case name. The primary CLI inventory (CLI_COMMAND_NAMES,
now owned by catalogIdentity.ts) is derived from those declarations plus the
commands no contract names, and a contract projection omits `command`: the
builder names the command from the contract and refuses a contract that does
not declare one. CLI_COMMANDS keeps only the 32 commands no contract names;
the 164 contract-named entries and the copied MCP-only list in
cliToolCoverage.test.ts are removed.

* fix(managed): keep decoded members when only their loaded literals exceed capacity

A capacity failure while decoding #US literals discarded the member facts already decoded, because the shared representation budget threw through the whole inspection. Literals carry their own coverage, so the inspection is retried without them and reports user_strings as partial with the capacity issue. compare-managed-members, which now runs full inspections, keeps comparing members it used to read with literals disabled.

* test(cli): expect builder-admitted issues by CLI key and option help with its default

Builder admission of compare-web-captures, compare-web-screenshots and analyze-web-bundle names input issues by the CLI key (beforeJson, afterJson, normalizationJson, endpoint), and --integrity-policy help states its default. Four test files still expected the contract field names and the old help, so they failed on the stack.

* test(cli): read each refused browser input's CLI path directly now that every case names one

Every invalid browser input now carries its CLI key, so the fallback branch narrowed to never and failed the TypeScript compiler's typecheck.

* chore(verify): carry the moved cliJsonInput baseline entry into its per-guard file

Rebased on main after #11316 split the guard baselines and #11181 threaded the launch environment into the web bundle command; the contract-built analyze-web-bundle command now passes that environment to the browser provider.

* refactor(cli): hand whole-input contract handlers the admitted parse instead of parsing again (#11301)

* refactor(cli): hand whole-input contract handlers the admitted parse instead of parsing again

* refactor(cli): parse an argv whole input only when the handler reads it

Admission parsed every argv whole-input command eagerly, so handlers that
hand the raw input to a service (inspectWithService) parsed it twice.
parseWholeInput now parses on the first admittedContractInput call and
reuses the result; run-time JSON and view delivery still parse at
admission. The test counts whole-schema evaluations.

* refactor(cli): hand JSON-document handlers the admitted parse of their document (#11332)

observe-native-calls, capture-electron-scenario and match-native-functions
parsed their resolved document against the contract schema in the handler.
registerContractDocumentCommand now gives each document handler
parseWholeInput, a memoized parse of the resolved document as the whole
contract input whose refusal names the caller's spelling, so
admittedContractInput serves argv and document commands alike. A handler
whose document is not the whole input never calls it, so it adds no parse.

* fix(cli): admit checked JSON inputs through their checks only

compare-process-captures walked and copied both capture records again in
the whole-input parse after their checks had admitted them. Admission now
parses the remaining fields with the contract and hands the handler the
checked documents uncopied. The managed summary example names
--evidence_output.
2026-11-16 03:22:24 +08:00

42 KiB

MCP tool design

Decide whether to add a tool

Design around the analyst question. Inspect the current canonical contracts, provider capabilities, and nearest existing tool before changing the surface. Extend a tool when intent and result contract match; add one for a distinct outcome or materially different authority. Public names and semantics remain provider-neutral, with exact coverage reported per provider.

Keep the discoverable inventory complete within the caller's selected scope; report capability/session availability independently of catalog visibility. An opt-in dynamic catalog must retain canonical named contracts and provide discovery and recovery for clients without refresh. Serialized bytes alone do not establish agent usability.

Choose the tool shape

Shape Use it for Result
inspect Facts about one target, object, or resource Relevant fields, locations, and facet availability
search / list Candidate discovery Stable ordering and context; pagination when the query or format needs it
trace Relationships across evidence Typed edges, supporting facts, and unresolved paths
compare Explicitly paired artifacts or observations Identity, comparable coverage, and supported deltas
workflow A recurring outcome needing composition Inline answer, contributing evidence, and partial facets
observe / capture Runtime behavior Authority, launch/attach effects, lifecycle, and cleanup status

These are task shapes, not mandatory prefixes. Name tools for the action and object callers reason about. Avoid unrelated discovery/execution/mutation modes inside one tool.

Prefer primitives; compose workflows

A primitive reports a reusable fact about an identified object or relationship. A format-specific decoder qualifies; one application's business interpretation belongs outside the general contract. The format owner reports source observations and structural validation; the application or workflow owner applies use-case-specific admission policy without reinterpreting raw fields. For example, DOS MZ structure and Windows-header evidence stay separate, while target resolution decides whether the unresolved header permits admission. Expose provider APIs when they add a useful capability that existing tools cannot express.

Compose a workflow when repeated use demonstrates a multi-source outcome REA can join without hiding caller choices or uncertainty. Batch homogeneous reads when that removes repeated work while preserving per-item outcomes. Keep prompts optional and avoid prescribing call sequences that a direct tool can replace.

Agents can compose experiments with ordinary commands, scripts, and local fixture servers. Custom orchestration languages, replay engines, or separate prepare/execute plans need an observed requirement those primitives cannot satisfy. A plan without execution does not establish runtime behavior.

Exercise the analyst workflow

Before defining a new provider-backed tool, state the analyst's question, what they already have, the intended result and authority, and what must remain unknown. Try the nearest existing REA workflow and the relevant native provider or ordinary script path when available. Identify the specific gap and what a new or extended contract would add; upstream capability alone does not require a new tool or equal support from every provider.

Use the caller's selected target and authority. Follow provider-backed workflow verification for independent observations, boundary controls and reporting unavailable provider coverage. A scripted tool sequence does not establish agent selection; that claim requires an actual agent evaluation.

Audit existing tools

Scope an audit by analyst tasks and the caller's target, providers and authority. Record the source revision and, when used, the running server, catalog and provider versions; a connected server can differ from the current checkout. Inspect the live CLI help or MCP descriptions and schemas alongside the owning contracts and documentation. Choose representative tasks and their nearest REA and native alternatives rather than counting upstream commands.

For those tasks, inspect relevant rendered MCP prompts, guided workflows and packaged skill advice in the versions actually in use. Follow the suggested producer-to-consumer handoff against the live contracts, including source identity, session lifetime and available alternatives. Matching text between two renderers does not establish that their shared advice is correct or that an agent selected the workflow.

Exercise each selected workflow before and after the tool call. Use workflow verification to check returned facts, partial outcomes, recovery and the scope of existing provider evidence.

Report working routes as well as findings. Separate a reproduced contract bug, an intentional limitation, a design opportunity and an unverified hypothesis; include the smallest useful reproduction, impact and coverage limits. Do not claim autonomous-agent selection from a scripted trace. Check related reports before proposing another issue, and avoid treating lack of API parity as a bug.

Write descriptions for selection and a valid first call

Start with the analyst task, selected source and useful result. Put material effects and the deciding boundary between neighboring tools early. Progressive discovery previews the first 240 characters, so those characters should identify the operation without requiring the rest of its reference documentation.

Keep exact call syntax where the advertised schema cannot convey it. The compact input profile strips most annotation prose and can reduce nested controls to {type: "object"}. Moving selectors into parameter descriptions alone does not make them available to those clients. For example, retained pseudocode needs both source.kind: "retained-evidence" and view: {kind: "native", facet: "pseudocode"}; a short exact example can be more useful than many paragraphs. Use the producer's handoff for other supported views rather than maintaining another supposedly exhaustive list in the shared consumer description.

Keep configuration tutorials and detailed matching algorithms with their owning parameter contracts, product guides and actionable failures. Retain applicability, source identity, uncertainty, authority and cleanup facts needed to choose or safely continue the operation. An unresolved symbol lookup is not a completed reference search; an exhausted page does not establish absence in unexamined source. Shorter copy must preserve these distinctions.

For wording changes, use a small set of representative agent tasks at the affected boundaries. Hold schemas, tool order, fixtures and host configuration fixed when comparing copy; add repetitions only for failures or ambiguous outcomes. Score actual arguments, corrective calls and supported final claims separately. A correct eventual answer can conceal malformed-call loops, while a valid call can still produce an overstated answer. Report whole-task usage, including retries and cached input, rather than treating fewer description bytes as proof of lower token cost.

Design recovery around the failure

Distinguish a request that violates its input contract from a valid selection that the current target, provider inventory, or project cannot resolve. The same invalid_request code can represent either. Suggest schema inspection only when the input contract is the problem; for a valid lookup, preserve the caller's exact selector, the observed reason and any candidates, and give a next step that addresses that outcome. An inventory miss does not prove that the artifact lacks the requested item.

For prerequisite failures, identify what the requested operation actually needs. A missing executable, a wrong path, an incompatible host or version, denied permission, and a download timeout need different repairs. Preserve the observed failure instead of calling all of them "not installed".

Derive the required engine from the operation's execution contract. For example, inspect_firmware_regions needs Binwalk; extract_firmware needs Unblob. Configuring the other tool cannot enable the requested operation. An installed JDK outside the selected PATH may need JAVA_HOME, not another installation. Say where a setting must change: a shell export does not change an already running MCP server's environment.

Keep repair instructions with the contract that owns the failure, and preserve them through provider readiness, capability discovery, doctor and CLI/MCP output. An error description is not a repair instruction. Do not make each consumer guess the fix from diagnostic text or invent another list of prerequisites.

Keep recovery within the selected target, provider, project and authority. If another context could help, describe it as an explicit choice and state any relevant loss of state; do not switch or select a candidate automatically. Preserve uncertainty, partial observations, and session or cleanup state. A suggested retry must be safe and explain any required change or wait.

Verify recovery through the public workflow: reproduce the failure, follow the suggested next step when feasible, and check the result and session state. Include a malformed-input control so schema guidance remains available when it is actually needed. Compare CLI and MCP when both expose the operation.

For each confirmed bug, check sibling adapters and other consumers of the same facts. Reproduce suspected matches and retain a working comparison where one exists. Group reports and fixes around the shared cause; similar wording alone does not establish another instance.

Define the contract

  • Use strict inputs with explicit target identity and required fields. Preserve meaningful target, action, capture, and output choices; remove ignored options and repeated permission declarations. One-shot binary CLI analysis retains the caller's verbatim target spelling in Evidence caller_input_path, including a result loaded from a snapshot. The subject keeps the inspected file identity. Provider inspections also retain the established parameters.input_path field for existing consumers. Keep request provenance separate from provider arguments and snapshot queries.
  • Return the requested facts inline with artifact/provider identity, source locations, Evidence references, coverage, and relevant confidence and limitations. Use supported selection, summaries or views when they answer the question; preserve access to complete source Evidence and honor existing contracts and requested detail. Missing coverage is unknown, not absence. Avoid extra lookups solely to understand the answer or its provenance.
  • Keep observed, derived, and inferred relationships distinct. Preserve unresolved edges and partial provider facts instead of requiring every provider to supply the same metadata. When a format constructor changes defaults or flags, retain the source values and use separately derived effective values only for operations whose semantics require them.
  • For caller/callee reads, relationship_coverage describes only the provider-observed direct relationship set. complete means that set was returned without a known read limit; it does not claim every possible runtime edge. Provider and execution caveats stay in limitations and do not imply incomplete relationship coverage. Directional discovery separately describes whether applicable static relationships could have been missed by discovery; missing discovery is unknown. Preserve paths supported by observed edges, and qualify negative and shortest-path claims by discovery scope. Missing relationship coverage remains unknown. Computed candidates and unestablished incoming targets qualify directional discovery; they do not by themselves mean that recorded edges were omitted.
  • Declare process, filesystem, network, UI, and mutation effects truthfully; enforce the requested target and lifecycle.
  • Add limits only for real format, protocol, authority, or measured resource constraints. Report pagination, truncation, cancellation, and partial failure. An assumed agent budget is insufficient justification for a limit. Name the ceiling and its recovery as described in admission limits and recovery.

Compose declared Evidence inputs

Declare each logical Evidence source with the shared evidenceInputSchema: complete inline Evidence or an exact {kind: "retained-evidence", evidence_id} reference. Use that declaration in single, optional, array and nested source fields across domains. Keep complete record schemas for stored Evidence, bundle records and pure semantic inputs; request alternatives do not change those representations. Ordinary IDs in parameters or result data are not implicitly source selectors.

Derive borrowing request validation and source resolution from the canonical request schema with getEvidenceInputContract and resolveEvidenceRequest. The shared application entrypoint selects references for CLI and MCP before the format owner admits, authenticates and interprets their records. Preserve admission before copying large source payloads. Do not maintain a second list of source paths or resolve references only in an adapter. A resolved reference has the same identity, caller-selected observations, provenance, coverage and partial or unknown facts as its complete inline record; it never reruns a producer or upgrades incomplete evidence. Keep Evidence-bearing request unions outside skipping default wrappers; use prefault when a default must pass through branch selection. Catalog conformance rejects unsupported source containers rather than silently losing their references.

Return authenticated source records alongside derived workflow Evidence when the adapter must retain them. Keep links to those exact sources and require the source closure when the workflow follows their links. Missing references and incompatible workflow roles are explicit failures; do not infer a substitute from ledger order, display names or the active target. A summary or inspection page has its own identity: consumers needing complete source facts use its normalized_result.parent_evidence_id, unless their contract explicitly accepts that view.

New provider-owned source observations require a retention owner. Existing caller-owned inputs can also compose on a fixed port without a recorder; when a recorder is available, preserve its acceptance or rejection and retain completed sources through cancellation.

MCP supplies the current ledger lookup. CLI commands that advertise --evidence-bundle use one explicitly selected, authenticated bundle for the command's lifetime. Keep cleanup with that owner. A retained reference does not grant filesystem access: file selectors remain separate, explicit contracts where supported. See retained Evidence inputs and CLI reuse.

Interpret boundary facts once

The format or protocol reader owns interpretation. Pass its parsed facts and explicit uncertainty to consumers; do not make adapters reparse display text, reconstruct omitted values, or infer success from missing diagnostics. Client registration inspections, for example, carry command identity and activation independently of readiness. An owned registration may be disabled or stale; unresolved ownership remains unknown. Consumers use those facts instead of reclassifying the raw command.

Owned provider commands follow the same rule. providerOutcomeOf in src/process/ProviderOutcome.ts reads what the supervisor observed (launch refusal, cancellation, deadline, output or memory limit, resource signal, exit status with the owner's stop state, or stream failure) together with the retained output and whether it was truncated. classifyProviderOutcome maps that outcome to a typed error once; a provider supplies only its settings, recovery text and a dialect for what an exit or launch refusal means. classifyProviderFailure in src/providers/classifyProviderFailure.ts is the one entry for a raw failure: typed analysis errors pass through, command outcomes go to classifyProviderOutcome, selected-file failures go to the shared stable-artifact projections, and only what none of them recognises reaches the provider's unclassified report. A provider supplies a dialect, not a classifier. A phase that armed its own deadline throws that deadline's timeout where it observes the abort; for a read its signal cancelled, it supplies the timeout as the dialect's interruption, so classification never rereads a cancellation's reason as a timeout. A provider whose cleanup report has its own shape supplies readCleanup or commandCleanup; otherwise the unresolved cleanup is attached to the reported failure. The rea/provider-failure-classifier lint rule keeps new (cause: unknown) => AnalysisError functions out of src/ except in that owner; existing ones are counted in a baseline that may only shrink.

A completed read can establish byte identity even when decoding or format validation fails. State which representation a digest identifies, such as file bytes, Fetch response-body bytes, or UTF-8 text. Preserve admitted source values separately from normalized lookup and display values. When the retention contract keeps only a digest and size, state that the bytes or text are unavailable; the digest does not establish format validity.

Comparison needs separate proofs for lookup, correspondence, content, and coverage. A hash cannot supply the proof that two retained values belong to corresponding objects.

Comparison fact What it establishes What remains unknown
Same capture-local frame or request ID Lookup within that capture Cross-capture identity
Same HTTP method, URL, and resource type A repeated-request group Which individual responses correspond
A partial HTTP response multiset is contained in a complete peer Omissions can explain every retained sample Equality or modification
A retained HTTP sample is absent from a complete peer group An observed difference independent of omissions Other unobserved differences
Complete WebSocket connection/frame inventories and matching metadata streams Ordered payload positions can be compared Equality of unavailable payload facts
Unique WebMCP name, owner origin, and frame URL Tool correspondence without transient frame IDs Correspondence between duplicate owners
A complete source digest or decoded storage value Comparable content Missing source bytes or opaque remote objects

Complete traversal or inventory does not make unavailable values equal. A partial aggregate fingerprint difference cannot establish modification when omissions alone explain it; independently proven differences still survive.

A byte-format parser reports failure with ParseFailureError from src/domain/parseFailure.ts: malformed, truncated, unsupported, or limit, with the format and, when known, the offset and field. Read bounded fields through BinaryReader (src/native/metadata/BinaryContainer.ts), which raises that failure instead of a bare RangeError. Providers project the failure with parseFailureAnalysisError rather than their own instanceof ladder; a limit stays with its producer, which knows the budget to name. Do not use RangeError as a failure channel: a stack overflow, a host string or buffer limit, and an unchecked read past the end of a buffer are all RangeErrors. hostRangeErrorKind is the one interpreter of a host RangeError, and parseFailureFromCause admits only a reported parse failure as evidence about the input. Readers report bounds failures at the read site; host error codes alone cannot distinguish a read from a write or allocation. scripts/verify/architecture-guards.mjs counts the remaining raw Buffer and DataView reads, plain Error throws in parser folders, plain JSON.parse of parser input, and direct instanceof RangeError checks against their per-guard baselines in scripts/verify/baselines/. A file may not exceed its count; after removing copies, run node scripts/verify/architecture-guards.mjs --shrink-baselines.

Keep format recognition separate from provider admission. A recognizable header can supply useful observations while later structure remains unresolved or a provider cannot accept the artifact. Report the reason at the affected boundary without erasing earlier observations or labeling unresolved input malformed.

Derive validation from the field's own format and revision. A runtime API's narrower argument range need not constrain a wider on-disk field. A shared layout, magic, or version label need not identify every constructor or equality rule. When supported producer revisions differ, retain what the input establishes and state what it cannot distinguish. Static inspection does not establish that the artifact can execute successfully.

Own the lifecycle

The investigation owns authenticated Evidence and complete Unknown revision history independently of an engine. close_binary drains earlier admitted work, releases engine resources and clears replay/invalidation state; investigation references survive, including target-free closes and cleanup failures. A target switch does not make historical observations current for its new engine.

reset_investigation is the explicit destructive boundary. It drains earlier analysis, imports, exports and Unknown operations, then clears investigation and replay/source bindings while retaining a healthy active engine. Metadata mutation invalidation remains in force until that engine is recreated. Later admitted work waits for the transition; earlier late results cannot repopulate cleared history. Runtime disposal seals new acquisitions and releases records after successful owned engine/file cleanup; failed cleanup keeps the owner available for retry.

Records are retained in memory under a fixed per-owner representation allowance derived from one quarter of initial available V8 heap. Admission accounts for Evidence, Unknown history and indexes before atomic commit; metadata replacement uses its size delta and duplicates do not accumulate. There is no silent eviction. binary_session.investigation reports committed counts, estimated representation bytes and the allowance; these estimates are not process RSS measurements. Live authentication headroom is checked separately. On refusal, export a checkpoint, reset, and import only the required investigation, or start a process with a larger heap. Retention does not promise automatic persistence.

An MCP request retains its original session admission until its handler cleanup and response send settle. A reset queued behind that request therefore cannot invalidate Evidence before its reply is sent. Nested work borrows the same admission. Cancellation before sending releases a suppressed reply after handler cleanup; cancellation after sending starts still waits for transport settlement. Lifecycle tools drain earlier admissions without acquiring one themselves.

reset_investigation(save_path) saves the complete cross-domain canonical bundle once before clearing. It awaits file sync, atomic publication and staging cleanup; failed save, incomplete cleanup or cancellation observed before reset commit preserves all records. Publication can precede cancellation or cleanup failure; the error retains its committed file receipt. Import that bundle to restore original Evidence IDs and all Unknown revisions in a new process. Engine replay snapshots remain a separate target and profile-bound mechanism. This checkpoint contract does not promise recovery from an uncheckpointed process exit or parent-directory loss after a host crash.

SafeOutputTree publishes only after file readback, nested-directory fsync from children to parents, and root-parent fsync on hosts that support directory syncing. Windows skips directory fsync. Failed writes retain a separate pending identity admission only until identity is captured; rollback retries retain unremoved file/directory identities and open handles independently, so confirmed unlink progress cannot be re-admitted through a closed descriptor.

For tools that acquire resources, identify the owner and the observations that establish each transition. Include temporary files and one-shot commands, as well as persistent engine sessions. Use the existing provider contracts; providers need not expose identical state machines.

In multi-stage work, retain each completed, admitted observation before awaiting the next stage. Later reads, validation, cancellation, or finalization can fail without erasing those facts. Carry them through typed failure outcomes with explicit coverage of unperformed work; do not construct a successful result for stages that never ran. For concurrent reads, the batch owner settles every admitted peer before reporting a failure. Retain completed observations together with each failed request's physical, cancellation and cleanup facts.

  • Keep target admission, provider readiness, active work, observed process exit, and resource release separate. A valid process handle, successful launcher, or selected target establishes only its own fact. Publish available identity and exit observations even when launch fails; retain unknown ownership.
  • Process exit does not establish output closure. The shared supervisor owns diagnostic retention and bounded draining through cleanup and retries. Report incomplete output separately from process cleanup. After verified stop and bounded draining, release owned event-loop references even if output closure stays unconfirmed. Keep the output capture owned for retry while process cleanup is unresolved. Borrowed processes and streams retain their own lifetime and reference state; select the matching supervision controls when changing this code.
  • Authenticate and capture identity through the same boundary on initial and recovery handshakes. Bound abandoned unauthenticated listeners where the protocol permits it; that deadline must not expire authenticated idle sessions or long-running native work. Listener expiry does not prove target closure.
  • Readiness observations may await owned prerequisite commands. Status must remain readable during owner finalization without starting replacement work; report readiness as unknown when it cannot be re-observed.
  • Shared startup has one producer and independently cancellable caller waits. Keep it running while any caller still needs it. The final departing caller waits for owned cleanup and retains its failure. Provider closure is distinct from caller cancellation. Retained cleanup capabilities block replacement; derive readiness from the current startup's completion and live connection.
  • Session cleanup_pending includes retained blockers from external mutation owners until those owners confirm release. Closing the analysis session does not release resources owned by an external debugger. Reading a selected analysis snapshot is part of open_binary; cancellation keeps that operation and the caller's reason through the shared JSON reader.
  • For cancellable observations, carry cancellation through result consumption and awaited cleanup. Check the signal after the last awaited finalization step unless the operation has passed its documented commit cutoff. Preserve the owning operation's committed outcome and receipt after that cutoff. Retain collected observations under typed cancellation. Preserve an existing primary failure and let incomplete cleanup retain its own classification. Preserve the caller's abort reason as the typed cancellation error's cause, including when cancellation is observed only after provider completion. The producing boundary records cancellation separately from physical failures and cleanup ownership. A caller's abort reason is opaque: its value, error type, name or cause chain cannot establish failure origin or cleanup authority. Consumers use the owner's parsed facts. An established command timeout keeps its timeout or refusal policy when preparation records a cancellation. Failure wrapping and operation rebinding preserve these facts and already classified secondary failures. Client cancellation alone does not prove native work stopped. For atomic publication, document the cancellation cutoff and preserve any committed output's publication receipt. Queued and retried work must retain the complete accepted execution controls, including non-default lifecycle deadlines and cancellation signals.
  • Release only owned resources. Attaching owns a connection or session unless the provider contract explicitly establishes target ownership. A helper exit, missing reply, or missing PID does not establish target exit.
  • Retain successful child cleanup and retry only unresolved children, including when close options change. Preserve observed child failure or activity when another child's health is unavailable; idle plus missing coverage stays unknown. Bind cleanup failures to their exact resource owner. Resolve current cleanup uncertainty only after that owner confirms release, while preserving the original failure and completed observations. Later failure composition must report only resources whose cleanup remains unresolved. Carry cleanup capabilities explicitly in typed outcomes so consumers can bind returned errors to exact owners without reparsing diagnostic cause chains. A cleanup-status observer does not replace a callable close capability retained by the caller's scope. Bind every caller-visible retry error and aggregate, including an error already produced by the provider. An aggregate remains incomplete until all owners it reports are released; releasing one child cannot clear another child's status.
  • Await one-shot cleanup without discarding the completed result or primary diagnostic. Preserve partial observations, remaining resources, and the cleanup owner's recovery instructions. While cleanup remains unconfirmed, canonical errors keep cleanup_incomplete and live resources while taking category, operation and failure details from the retained typed primary. Nested cleanup composition does not replace that semantic identity. Finalization reports remain attached to their owning envelope while cleanup is pending and after confirmed release. CLI adapters should reuse finishAnalysisCommand where its contract applies rather than duplicate close/finally handling. It projects runOwned, which owns this precedence for owned work: a recorded failure stays primary, cancellation before commit keeps the completed value as a partial observation, cancellation after commit keeps the value, and unconfirmed cleanup reports cleanup_incomplete while keeping the completed value.
  • Give descriptor-backed reads an owner before opening the file. A rejected close must retain the exact handle and preserve any earlier failure. Carry openRegularFile's admitted handle and initial metadata rather than restatting only to rebuild those facts. Keep fresh descriptor and selected-path identity checks after work, comparing against the original baseline instead of replacing it with a later stat. Preserve explicit bigint reads when ordinary admission metadata cannot supply the required size or timestamp precision. Stable file reads expose completed values separately from cancellation so consumers retain acquired identity facts after successful close or cleanup retry. If an abortable caller stops waiting, keep the underlying work in that owner's lifetime so shutdown cannot report release before finalization settles. Admit the entire inspection once, including later reads and finalization. Helpers must borrow that admission or use an operation child scope; re-entering the same draining scope can make cleanup wait for its own caller. Retry retained cleanup before admitting new work and keep admission blocked while it remains unresolved. Link the originating cleanup error to its exact owner so confirmed release resolves its cleanup marker while preserving the earlier diagnostic. Shared CLI/MCP adapters cannot infer that confirmation.
  • Provider profile selection owns every asynchronous candidate through its terminal result and finalization. The registry owns profile-file cleanup, joins all automatic-selection children, and closes those file owners before reporting candidate shutdown. Final caller cancellation joins the selection; an adapter that ignores cancellation remains active and owned until it settles. Block new admission during shutdown and while cleanup remains unresolved; reopen after confirmed retry. Preserve failed results before considering a later signal, and retain every child's attributed cleanup in mixed outcomes.
  • Release child descriptors before removing their containing root. Retain a composite owner when either stage fails so retry preserves that ordering. A Windows command leader's exit does not establish Job Object closure. Keep the process-tree observer and command lock alive through failed cleanup retries until the owned tree's close event.

Exercise the applicable lifecycle regression scenarios through the producing owner and affected CLI/MCP consumers.

Implement and evaluate

Put provider wire-protocol parsing in adapters and shared CLI/MCP workflows in the application layer.

CLI commands register through cliCommandRegistrations.ts: add the registrar to its family there and its module to src/cli.ts. The build records which registrar defines each top-level command, and a one-shot command loads only that registrar's module graph; help, completions, --llms and unknown names load the complete CLI. A registrar's command definitions must not depend on other registrars, and tests/boundary/cli/cliLazyRegistration.test.ts checks that each one registers alone with the definitions the complete CLI gives it. Modules that every registrar imports set the startup cost of every command; load optional heavy services where a command needs them. Reusable format declarations may live in pure domain owners: peOptionalHeader.ts decodes PE structure, while consumers retain machine admission, directory-address interpretation, and file/mapping bounds. Share Evidence provenance, unknown projection, and session retention semantics; matching payloads alone do not establish parity.

Let createEvidence own JSON validation and snapshotting of ordinary observation payloads. EvidenceObservationInput accepts semantically parsed parameters, results, and raw results whose JSON validity still needs admission. Keep format, selection, and identity validation at their producing boundary. Invalid JSON issues are rooted at parameters, normalized_result, or raw_result in the Evidence envelope.

EvidenceObservation retains the stronger JSON contract used by producer helpers and createImmutableEvidenceSteps. The cooperative constructor also requires an authenticated immutable result; preserve that ownership proof. For objects, proof comes from completed sealing by immutableJson.ts; readonly or Object.freeze alone does not establish it. JSON primitives are directly eligible. Seal owned data and complete cooperative sealing before reusing its result.

When a failed or cancelled operation retains completed, valid partial Evidence, use the shared ToolResultDelivery path with the session's Evidence writer. Keep the original failure and the named contract's target-content marking; replace the inline partial with a retained reference only after recording succeeds. An absent writer or a writer returning a failure Result leaves the partial inline, as does a partial that is not valid Evidence. Unexpected recorder exceptions propagate. An evidence_id member alone does not establish Evidence validity or retention.

Measure the resource before choosing a budget and enforce it before the costly step. Account for value alternatives, trace-frame products, retained records, serialization expansion, and temporary-file growth separately. Derive facet completeness from examined records and exhaustiveness, rather than diagnostic prose or an empty failure list. Preserve observations independently of cleanup success.

Price mutually exclusive success and failure representations separately. Replace a reserved failure envelope when pricing success, and release discarded decoding state from retained-output accounting. Retaining additional failed-body text changes the capacity available to later results; treat that as a contract change and cover its effect on later valid items.

For example, if ten applicable records are discovered, eight are examined, and five are returned, the five returned records do not establish complete coverage of the ten. Keep discovered, applicable, examined, and retained scope distinct. A filtered page can be complete for its selection while the parent inventory remains partial. Carry the upstream coverage and unresolved reasons through filtering and paging; an item missing from that page is not proved absent from the target. Structured completeness and absence fields must agree with the stated limitations.

File-error wrappers retain the format owner's specific diagnostic and recovery text. Strict JSON file input, for example, keeps the byte-order-mark explanation and UTF-8 recovery through CLI/MCP projection rather than replacing it with generic invalid-file advice. Consumers do not classify parser message text. When an artifact boundary falls back to an I/O error, retain the original cause on the typed error so provider callers can inspect its filesystem evidence. Keep public error fields under the canonical projector's ownership; retaining a cause does not require exposing it in transport output.

Update canonical contracts, output schemas, examples, generated artifacts, and relevant docs together. Verify converted advertised schemas and success, malformed, unavailable, cancellation, and partial outcomes through affected consumers. Real-engine claims require the matching provider lane; see testing.md.

For fixed tuples in public contracts, use src/domain/fixedTupleSchema.ts: Zod's tuple projection omits implicit length bounds and Draft 2020-12 items, which some clients require even alongside prefixItems. Tuples with a rest schema also need explicit minimum lengths. Check parser/schema parity for empty, short, overlong, and malformed values in both input and output projections.

A CLI command for a tool contract is described by describeContractCommand in contractCliDescription.ts and rendered for the CLI framework by registerContractCommand in contractCommand.ts. A contract with cli: true names its own command, the kebab-case spelling of its name; the CLI command inventory in catalogIdentity.ts is derived from those declarations, and the projection omits command for it. CLI_COMMANDS holds only the commands no contract names. The projection names only what the CLI spells differently: positionals, caller-relative path fields, option renames and short flags, CLI help wording, omitted optional fields with a reason, Evidence delivery options, and whether the contract's cross-field rules refuse at argv parsing or at the service's contract parse. A delivery view is JSON text decoded when the command runs; the contract input then admits the view with its detail before any target is opened, including a detail-discriminated union input. Field schemas and decimal argv tokens are derived, and tests/boundary/cli/cliContractCommandParity.test.ts checks that each projected command admits what its contract admits.

CLI translations must reuse the canonical semantic fields, enum membership and list bounds. Document transport differences such as relative path spelling and JSON text decoding; reject empty selections before path normalization. Preserve required alternatives across positional arguments and options. When the CLI schema format separates those groups and cannot express their relationship, state the required choice in command discovery/help and retain aggregate admission before target access. Test emitted schemas and parser behavior together, including omission, empty strings, alternatives, conflicts and boundary list counts.

Expected input failures must retain caller field/index paths and safe constraints. Internal operation/input envelopes are not caller paths. Reuse the input issue projector at the admission owner; a schema cause alone does not supply correction metadata to either adapter.

When discoverability changes, evaluate representative broad, direct, and negative tasks on the intended host. Record host/model/catalog, selected tools, arguments, errors, retries, and task outcomes. Schema validity and keyword heuristics do not establish successful tool selection. See mcp-contracts.md for shipped runtime behavior.