fix: let a plugin's own readOnlyHint outrank a guess about its name

[hyoshi]

The defect

derive_semantics believes an explicit annotations.readOnlyHint verbatim in both directions — readOnlyHint=False is a plugin author saying "this call moves money", and it arrives as ToolSemantics.mutating=True. _register_plugin_pattern_fallbacks then discarded that declaration whenever the tool NAME happened to look like a read:

if not sem.mutating or is_read_only_tool_name(name):
    continue

Reproduced:

name = "list_and_delete_stale_campaigns"
sem = {name: ToolSemantics(mutating=True)}   # explicit readOnlyHint=False
_register_plugin_pattern_fallbacks(sem)
has_pattern_fallback(name)   # -> False: the guardrail is NOT registered

So a plugin that correctly declared its mutation silently lost its ## Guardrails budget/bid cap enforcement because of a guess about its name. A name shape is a guess; a declaration is evidence.

Found by a post-merge review of #569 and re-confirmed reviewing #585. Pre-existing, and deliberately outside #585's scope.

The fix

The name check now applies only to a tool that declared no hint at all, mirroring the precedence derive_semantics itself uses:

if not sem.mutating:
    continue
# The name is a fallback, not an override: it decides only for a tool
# that declared no readOnlyHint at all.
if sem.read_only_hint is None and is_read_only_tool_name(name):
    continue

The exemption for undeclared tools is untouched — it exists because a manifest snapshot carries no annotations, and a bridged read whose arguments carry a numeric budget-shaped FILTER would otherwise be refused outright (TestReadNameExemption).

ToolSemantics gains read_only_hint: bool | None to carry the raw declaration beside the derived mutating; None means "undeclared, so the name was the only signal". That information did not survive derive_semantics before.

The same inversion in learning_reset

mureo/policy/learning_reset.py::_is_mutation consulted only the name, and was wrong in both directions for a plugin tool:

• read-shaped name + readOnlyHint=False → classified a read → no learning-period notice, no block_learning_resets refusal;
• mutation-shaped name + readOnlyHint=True → classified a mutation → a possible spurious refusal.

It is reachable: register_platform_learning_rules lets a plugin or bridge claim a tool_prefix, so plugin tool names really do reach this classifier.

That layer is pure and must not import the MCP server, so the declarations reach it through a registry in mureo.policy.declarations — same shape, same docstring discipline and the same "populated by mureo.mcp.server at import" contract as the sibling budget/bid registries, re-exported from strategy_gate like they are.

Built-in tools stay immune: is_mutating_builtin_tool and the _BUILTIN_PREFIXES short-circuit both run before the hint lookup, and a test pins that a stray registration cannot reclassify one.

What believing a declaration costs is now stated in _is_mutation's docstring rather than left implicit: a plugin declaring readOnlyHint=True on a real mutation is taken at its word and escapes the refusal. Accepted — refusing to believe a declaration in one direction only is the same name-beats-declaration inversion this ordering removes, and it would hard-refuse honest plugin reads whose names merely look like mutations. These guardrails defend the operator against an agent's mistakes, not against an installed plugin that lies about itself.

mureo/core/tool_names.py is untouched

The two-matcher split from #585 is deliberate and stays: is_read_only_tool_name is the strict matcher for the plugin-facing safety surfaces, reads_as_a_report_only_action the looser one for the rollback planner only. This PR changes when the strict matcher is consulted, never what it matches.

Tests

19 new tests. Applying only the new test files onto pre-change HEAD gives 5 failed / 5 errored — including the end-to-end case through the real StrategyPolicyGate, where list_and_delete_stale_campaigns with readOnlyHint=False and {"dailyBudget": 25_000} against a max_daily_budget_per_campaign: 10000 cap returned allowed=True on the old code.

• test_strategy_gate_pattern_fallback.py::TestDeclarationBeatsNameGuess — all three legs: a declaration is believed in both directions, the name decides only for a tool that declared nothing; plus the end-to-end denial.
• test_mcp_plugin_semantics.py — read_only_hint is True/False when declared and None when undeclared, including annotations that exist but omit the hint (destructiveHint only).
• test_learning_reset_preflight.py::TestDeclaredReadOnlyHintBeatsTheName — both directions, the undeclared name fallback, and built-in immunity. Its fixture saves and restores the process-global registry rather than clearing it destructively.

Two stale docstrings in TestReadNameExemption / _semantics_for are corrected: they claimed derive_semantics defaults an undeclared tool to mutating, which has not been true for read-shaped names since #517. No assertion was weakened.

Checks

• python3 -m pytest → 12 failed, 8741 passed, 8 skipped; the 12 are exactly the known environment baseline (9 × tests/analytics/builtin/test_live_clients.py, test_list_tools_returns_all_tools, test_no_plugins_is_additive_no_op, test_default_discover_is_registry_and_yields_no_op_when_empty).
• mypy mureo/ --ignore-missing-imports → clean (337 files) · ruff check → clean · black --check → clean.

Known, not addressed here

_READ_ONLY_HINTS is keyed by bare tool name with no distribution identity, so two plugins shipping the same generic tool name overwrite each other's declaration. That is the pre-existing shape of _BUDGET_DECLARATIONS and _BID_DECLARATIONS too — the new registry is consistent with its siblings rather than uniquely weak. Worth a follow-up that keys all three by (distribution, tool_name), the way _declares_from_bridged_table already checks the owning distribution.