feat: safe-by-default tool curation — write-capable tools opt-in for autonomous principals

[chubes4]

Summary

Addresses #408. Part of #412.

Makes write-capable / mutating ability categories opt-in (not ambient) for autonomous principals (no human in the loop), while leaving human-backed (interactive) principals unchanged. This is tool-surface CURATION (defense-in-depth) — it reduces prompt surface and stops an autonomous agent from even trying a write tool. It is NOT the security boundary: the real boundary is capability-ceiling ENFORCEMENT at ability/tool execution, tracked separately in #412.

Production incident this prevents: a pipeline agent silently published 224 junk posts by calling a generic publish ability it was never meant to reach. (Consumer-side emergency fix: Extra-Chill/data-machine#2853; this PR is the durable substrate curation layer.)

Update (this push) — repositioned onto principal autonomy

The gate now keys off the execution principal's autonomy, which the substrate already models precisely, instead of a mode/interactive string (a weaker proxy). Per the deeper analysis in #412, the gate is also now explicitly documented as curation, not enforcement.

• Deleted WP_Agent_Tool_Policy::INTERACTIVE_MODES (the chat/interactive/rest mode-marker list) and the is_non_interactive_context() mode check entirely. The write-gate now names zero consumer modes.
• Replaced is_non_interactive_context($context) with is_autonomous_principal_context($context), keyed off the principal.
• Kept RUNTIME_CHAT = 'chat' — it is still the default value for the generic tool mode filter (filter_by_mode(), a substrate-native interactive surface that lets tools declare the modes they are available in). The write-gate no longer touches it.
• Documented the gate as tool-surface CURATION (defense-in-depth); capability enforcement is Enforce capability ceiling at ability/tool execution — the Core-worthy boundary for autonomous writes (beneath #408/#411) #412.

How autonomy is determined

A principal is autonomous when EITHER:

• its auth_source is an automation source (system / runtime / agent_token), OR
• it has no human backing it (acting_user_id === 0).

The principal is resolved, in order, from:

1. a principal entry on the context — a WP_Agent_Execution_Principal instance or its array shape (to_array()), or
2. flat auth_source / acting_user_id fields on the context root (mirrors how WP_Agent_Action_Policy_Resolver already reads acting_user_id).

When no principal information is present at all, the gate falls back safe: autonomy is assumed and the gate engages. Prefer the principal at the call site; the fallback exists so an unannotated context cannot silently expose write tools.

The system / runtime / agent_token strings here are the principal's authentication source identifiers (substrate primitive constants on WP_Agent_Execution_Principal::AUTH_SOURCE_*), not consumer orchestration mode names. The gate contains zero consumer mode-name vocabulary.

Why autonomy, not mode

The substrate already models who/what is driving the run via the principal. A mode string only describes the runtime surface (chat/rest/cli/…), not whether a human is accountable for the loop. Two examples the old mode-based gate got wrong:

• An agent-token principal driving an unattended loop is autonomous even though it may carry an acting_user_id — a mode-based gate that treats rest as "interactive" would surface write tools to it.
• A user-session principal in an opaque consumer mode is not autonomous — but the old gate gated them because the mode wasn't a recognized interactive marker.

Keying off autonomy fixes both. git grep -nE "INTERACTIVE_MODES|'pipeline'|'system'|RUNTIME_PIPELINE|RUNTIME_SYSTEM|NON_INTERACTIVE" src/Tools/ now returns only the auth_source allow-list ('system', 'runtime', 'agent_token').

What's excluded by default (for autonomous principals)

Tools classified as write-capable are removed unless preserved or explicitly opted in. A tool is write-capable when either:

1. It declares a per-tool flag — 'write' => true or 'mutating' => true on the tool/ability-tool definition. (Layer-pure: the tool declares its own nature, the policy enforces the default. Mirrors the existing action_policy per-tool declaration precedent.)
2. One of its categories matches a write-capable category — built-in set is ['write', 'publishing', 'mutating', 'destructive'], all generic classification vocabulary (not consumer tool names).

The substrate never hardcodes consumer tool slugs (e.g. publish-wordpress) and never enumerates consumer mode names. Classification is by declared nature or generic category.

What's exempt (unchanged behavior)

Path	Effect
Human-backed principal (auth_source user/application_password with acting_user_id > 0)	Gate not applied. Request-user-scoped and already access-gated.
Mandatory tools/categories	$preserve_tool closure still exempts them — mandatory plumbing survives.
Declared-mandatory tools ('mandatory' => true)	Preserved.
allow_only	Names the write tool explicitly → kept.
runtime_tools	Names the write tool explicitly → kept.
runtime_categories	Category match → kept.
ALLOW-mode named policy (mode: allow, tools: [...])	Named tool/category → kept.

The gate reuses the existing collect_runtime_tool_opt_in() aggregate, so every opt-in path works uniformly — no parallel opt-in path was built.

Escape hatches

Mechanism	Effect
Context key 'allow_write_tools' => true	Disables the curation gate entirely for that resolution.
Policy fragment 'allow_write_tools' => true	Same, via agent config / tool_policy / provider.
Filter agents_api_write_capable_categories	Extend or replace the built-in category set (Core/consumer).

The final agents_api_resolved_tools filter still runs after the write gate, so host-level overrides compose on top.

Where it sits in resolve()

filter_by_mode → access_checker → named policies → categories
→ allow_only → runtime opt-in → [WRITE-CAPABLE CURATION GATE] → deny → final filter

The gate runs after the runtime opt-in gate (so it can reuse the aggregated opt-in set) and before deny (so explicit deny always wins) and before the final filter (so hosts can still override the result).

Smoke test

tests/write-capable-default-smoke.php (37 assertions) proves the gate keys off principal autonomy, not a mode string:

1. Curation contracts + mode-name neutrality → INTERACTIVE_MODES / NON_INTERACTIVE_MODES / RUNTIME_PIPELINE / RUNTIME_SYSTEM are gone; RUNTIME_CHAT retained (as the generic mode-filter default); filter methods present.
2. Autonomous runtime principal → every write-capable tool gated (category or flag); read + mandatory survive.
3. Declared write/mutating flags gated exactly like category-classified tools.
4. Both autonomy signals independently engage the gate → agent_token auth_source (even with an acting user) and acting_user_id=0 (even for a non-automation auth source).
5. Human-backed principals keep write tools → user-session and application-password principals.
6. The gate keys off the principal, NOT the mode (decisive contract) → autonomous principal gated even in chat mode; user principal keeps write tools even in pipeline mode.
7. Principal supplied as array shape OR flat context fields → both supported.
8. Safe fallback → no principal in context → treated as autonomous (gate engages).
9. allow_only / runtime_categories / ALLOW policy / runtime_tools → write tool restored for an autonomous principal.
10. mandatory_tools → write tool preserved even for an autonomous principal.
11. allow_write_tools (context + policy) → ambient write tools restored.
12. agents_api_write_capable_categories filter → extended category gated for autonomous principal, visible for user principal.
13. agents_api_resolved_tools final filter still runs after the gate.

tests/tool-policy-contracts-smoke.php section [5] was updated to model an interactive user principal so the generic runtime-tool opt-in behavior stays in focus without the write curation gate interfering.

All 37 Write-capable default assertions passed.

Full suite: composer smoke (all existing tests still green) and composer phpstan (clean).

Consumer impact: Data Machine needs zero changes

Data Machine (the primary consumer) requires no code changes for this repositioning. The curation gate is a no-op for DM's tools: every DM ability category is datamachine-* namespaced (datamachine-publishing, datamachine-content, …) and no DM tool sets a write/mutating flag. None of DM's tools match the substrate's generic write-capable set (write/publishing/mutating/destructive). DM's own pipeline write-gating (filterPipelineWriteOptInTools, which targets requires_pipeline_opt_in + datamachine-publishing) continues to own product-specific gating exactly as before. The substrate gate simply composes as defense-in-depth without dropping anything DM currently exposes.

When DM (or any consumer) wants the substrate to engage for an autonomous principal, it passes the execution principal into the resolver context — the substrate no longer guesses from a mode string.

Relationship to #412

• This PR (feat: safe-by-default tool curation — write-capable tools opt-in for autonomous principals #411) is tool-list curation: don't even offer write tools to an autonomous agent. Defense-in-depth only.
• Enforce capability ceiling at ability/tool execution — the Core-worthy boundary for autonomous writes (beneath #408/#411) #412 is the actual enforcement boundary beneath it: enforce the capability ceiling at ability/tool execution so an autonomous principal cannot perform a write it isn't granted — even if a write tool is somehow offered or the acting user is privileged.

Shipping curation as if it were the security boundary would give Core sites a false sense of safety. This PR is explicitly scoped as curation, with enforcement tracked in #412.

Notes

• No backward-compatibility shim is needed — INTERACTIVE_MODES was private and never imported by consumers; the only behavioral change is that the gate now engages on principal autonomy (with a safe no-principal fallback) instead of on a mode-string heuristic.
• The consumer-side emergency fix was fix: make generic content-publishing tools opt-in for pipeline AI steps Extra-Chill/data-machine#2853.