Skip to content

fix(contracts): mark foreign execution and device mutation destructive - #1904

Merged
morluto merged 1 commit into
morluto:mainfrom
larinyo:pr/honest-destructive-hints
Oct 11, 2026
Merged

morluto merged 1 commit into
morluto:mainfrom
larinyo:pr/honest-destructive-hints

Conversation

@larinyo

@larinyo larinyo commented Oct 11, 2026

Copy link
Copy Markdown
Contributor

Summary

MCP destructiveHint was derived only from mayDiscardData. As a result, tools that run the analysis target or an executable the caller selected (capture_process_scenario, observe_native_calls) and tools that change an attached Android device (install_adb_package, uninstall_adb_package, push_adb_file, start_adb_app, start_adb_activity, stop_adb_app) advertised destructiveHint: false. Clients use that hint to decide whether to prompt, so these tools could be auto-approved as "safe".

Problem and expected behavior

  • Smallest trigger: tools/list reports capture_process_scenario with destructiveHint: false, even though it runs a caller-chosen program.
  • Violated invariant: annotations should describe effects honestly (docs/mcp-contracts.md, "Tool annotations describe effects").
  • New behavior: destructiveHint = mayDiscardData || executesForeignCode || mutatesDevice. readOnlyHint semantics are unchanged.

Change and scope

  • ToolEffects gains executesForeignCode and mutatesDevice, both documented in code. All 170 tool effect records were audited.
  • Tools now declaring executesForeignCode:
    • capture_process_scenario, observe_native_calls;
    • capture_browser_scenario, capture_electron_scenario, capture_native_ui_scenario. These three were already destructive through mayDiscardData.
  • Tools now declaring mutatesDevice: the six ADB tools listed above.
  • Separate, droppable change: set_address_name, set_addresses_names, set_bookmark, set_comment, set_inline_comment and annotate_native_function now declare mayDiscardData: true. They can replace or clear existing analyst names and comments in the Hopper/Ghidra session database, which is data the caller cannot recover from REA. This flips their destructiveHint to true and is a judgment call separate from the execution/device fix. If maintainers prefer to keep metadata writers non-destructive, these six hunks can be dropped without affecting the rest. Those tools are not in the drift test's pinned set, so dropping them needs only a catalog regeneration.
  • New src/contracts/toolEffects.test.ts:
    • every public tool is audited exactly once;
    • every tool whose description mentions running, launching, executing, starting, installing or uninstalling declares one of the new flags or appears in a reasoned exception list. Stale exceptions also fail, so wording and effects cannot drift apart silently;
    • the set of foreign-execution and device-mutating tools is pinned;
    • destructiveHint must follow from each flag on its own;
    • advertised annotations must equal the derived ones.
  • The binary_session effects output schema carries the new flags, and docs/mcp-contracts.md documents them.
  • Not included: writesCallerPath, or any execution or approval policy.

Contract and boundary impact

  • Semantic owner and earliest changed stage: src/contracts/toolEffects.ts.
  • CLI and MCP/tool-catalog contract: annotations change from destructiveHint: false to true for 14 tools (8 through the new flags, 6 through mayDiscardData). The binary_session effects record gains two boolean fields.
  • Provider, bridge, target-format, or platform compatibility: none.
  • Evidence, artifact, provenance, or reconstruction contract: none.
  • Process execution, authorization, cleanup, or containment impact: these are hints only, not enforcement. Clients that honour destructiveHint will now prompt for these tools.
  • Generated metadata, package, or installation impact: the MCP tool catalog was regenerated (.cache/, untracked). The product catalog check passed.

Evidence and regression coverage

  • Tests added or updated: src/contracts/toolEffects.test.ts (new), tests/boundary/mcp/toolResult.test.ts, tests/boundary/mcp/toolSchemaValidity.test.ts.
  • Base reproduction or other evidence: on the base, the generated catalog shows destructiveHint: false for the tools listed above.

Validation performed

  • npx vitest run src/contracts tests/boundary/mcp (after npm run build and npm run mcp-catalog:generate): 103 files, 414 passed, 5 skipped.
  • npm run test:fast: 378 files, 4338 passed, 6 skipped.
  • npm run docs:check: passed.
  • npx tsc --noEmit: clean. npx oxlint: 0 errors. npm run verify:module-boundaries: passed. npm run format: no changes.

Compatibility, safety, and release

  • Breaking changes or migration steps: not marked breaking. Annotations are hints, and the effects record only gains fields. Clients that auto-approve on destructiveHint: false will now prompt for these 14 tools, which is the purpose of the change.
  • Real Hopper/Ghidra, browser, or OS coverage: not applicable (metadata only).
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: this makes client approval prompts more accurate.

Limits / not verified

  • Not checked against a specific client's approval UI (Claude Code, Codex, and others).

MCP annotations derived destructiveHint only from mayDiscardData, so tools
that run the analysis target or a caller-selected executable
(capture_process_scenario, observe_native_calls) and tools that change an
attached Android device (install/uninstall/push/start/stop) advertised
destructiveHint: false.

Add explicit executesForeignCode and mutatesDevice effect flags, audit them
across all 170 tool effect records, and derive
destructiveHint = mayDiscardData || executesForeignCode || mutatesDevice.
readOnlyHint semantics are unchanged.

Hopper/Ghidra metadata writers (set_address_name, set_addresses_names,
set_bookmark, set_comment, set_inline_comment, annotate_native_function)
can replace or clear existing analyst names and comments, so they now
declare mayDiscardData as well.

A contract test pins the destructive set and requires every tool whose
description mentions running, launching, executing, starting, installing or
uninstalling to declare one of the new flags or carry a reasoned exception,
so wording and effects cannot silently drift. The binary_session effects
output schema carries the new flags.
@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-11T16:46:25.896565Z caa5af5 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@morluto
morluto merged commit 0b7fc40 into morluto:main Oct 11, 2026
2 checks passed
@github-actions github-actions Bot mentioned this pull request Oct 11, 2026
3 tasks done
@morluto

morluto commented Oct 11, 2026

Copy link
Copy Markdown
Owner

Welcome to REA, @larinyo. Your ToolEffects change makes MCP’s destructive hint account for running caller-selected code and changing an attached Android device, and the catalog tests pin those cases. Thanks for making the effects explicit; clients can use the hint when deciding whether to prompt.

@morluto morluto added the bug Something isn't working label Oct 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants