Consume Abilities API lifecycle filters (WP core PR #11731) once they land

[lezama]

Context

WordPress core now ships nine execution lifecycle hooks on `WP_Ability` (all `@since 7.1.0`), landed across three PRs by @gziolo:

• PR #11731 — original four: `wp_pre_execute_ability`, `wp_ability_normalize_input`, `wp_ability_permission_result`, `wp_ability_execute_result`. Changeset 62397.
• PR #11852 — new `wp_ability_invoked` action + enriched `$ability` parameter on `wp_before_execute_ability` / `wp_after_execute_ability`. Trac #65248.
• PR #10557 — input/output validation filters: `wp_ability_validate_input`, `wp_ability_validate_output`. Trac #64311.

The substrate adopts these through `WP_Agent_Ability_Lifecycle_Bridge` (in `src/Abilities/`). Each hook is wired as a separate slice / PR.

Hook surface and substrate mapping

Hook	Type	When	Substrate use	Slice
`wp_ability_invoked`	action	Top of `execute()`, every call	universal telemetry — captures all attempts including the failure modes `wp_ability_execute_result` misses	TBD
`wp_pre_execute_ability`	filter	Pre-normalize, sentinel	approval boundary returning `approval_required` envelope with `WP_Agent_Pending_Action` payload	TBD — @ibrahimhajjaj
`wp_ability_normalize_input`	filter	Post-normalize	inject `WP_Agent_Execution_Principal` / `WP_Agent_Caller_Context` into ability input	TBD
`wp_ability_validate_input`	filter	Post-schema validation	agent-aware input validation layering	TBD
`wp_ability_permission_result`	filter	Post-`permission_callback`	route through `WP_Agent_Tool_Access_Policy` + capability ceiling	TBD
`wp_before_execute_ability`	action	Pre-`do_execute` (now with `$ability`)	substrate-level pre-execute audit	TBD
`wp_ability_execute_result`	filter	Post-`execute_callback`	result observation — emits `agents_api_ability_executed` action	#199 (in flight)
`wp_ability_validate_output`	filter	Post-output validation	output-shape audits	TBD
`wp_after_execute_ability`	action	Success path only (now with `$ability`)	success-only commit hooks (transcript, telemetry)	TBD

Design notes carried into slices

These came out of @ibrahimhajjaj's AbilityGuard work (https://github.com/ibrahimhajjaj/abilityguard) and should be observed by every slice that hooks one of the filters:

1. Capability detection cannot key off `$wp_version`. The Abilities API also ships as a standalone repo (`WordPress/abilities-api`) and a Composer package on its own release cadence. A WP 7.0 host can have a recent standalone plugin with the filters; a WP 7.1 host can lack them. Slices that need runtime capability detection should reflect on `WP_Ability::execute()` source for the literal filter name. (Most slices don't need detection because the filter just stays idle when not applied.)
2. Sentinel pass-through is mandatory on `wp_pre_execute_ability`. Core seeds `$pre` with a fresh `WP_Filter_Sentinel` per call. Any handler must `if ( ! ( $pre instanceof WP_Filter_Sentinel ) ) return $pre;` before doing anything, or it clobbers a prior consumer's short-circuit. Smokes should include a multi-consumer coexistence case.
3. `wp_pre_execute_ability` fires before `wp_before_execute_ability`. Anything that opens a pending row or audit record in a before-action never runs on a short-circuit. The pre-execute handler has to do that work inline.
4. `wp_ability_execute_result` only sees the post-callback path — it fires inside `do_execute()` after `execute_callback` returned and before `validate_output()`. It does not fire for pre-execute short-circuit, normalize-input failure, validate-input failure, permission denial, or validate-output failure. A complete failure-aware observer needs `wp_ability_invoked` plus the validation filters.
5. No `duration_ms` at the `wp_ability_execute_result` seam since the outer `execute()` has not returned. Timing belongs in a `wp_after_execute_ability` hook (success path) or a paired `wp_ability_invoked` / `wp_after_execute_ability` measurement.
6. Approval-required envelope inside the loop is the typed `WP_Agent_Pending_Action` returned in a `WP_Agent_Message::approvalRequired(...)` envelope. The `WP_Error` with `status => 202` pattern (used by AbilityGuard) is appropriate at the REST run-controller boundary but is swallowed by `mediate_tool_calls` and cannot carry the typed payload anyway.

Cross-cutting integration: loop-level approval recognition

`mediate_tool_calls` does not currently recognize `approval_required` envelopes returned from ability execution — it treats every executor return as a normal `tool_result`. The `wp_pre_execute_ability` slice depends on the loop learning to detect the envelope and surface it as an approval pause (`status: 'approval_required'`). This is a paired piece of work with the bridge-side approval handler.

Acceptance criteria

• README adoption section documenting `WP_Agent_Ability_Lifecycle_Bridge` and the substrate's observable actions
• Each of the nine hooks wired through a separate PR, sharing the same bridge class
• Smokes per slice; multi-consumer coexistence smoke for `wp_pre_execute_ability`
• `mediate_tool_calls` recognizes `approval_required` envelopes returned from tool execution
• Capability-detection helper that reflects on `WP_Ability::execute()` rather than gating on `$wp_version`

Timing

Hooks are in WP core trunk; `@since 7.1.0`. On WordPress < 7.1 the filters never fire, so registered handlers stay idle — no version gate needed.

AI assistance

• AI assistance: Yes
• Tool(s): Claude Code (Opus 4.7)
• Used for: Mapping the now-nine core filters against this substrate's existing primitives and drafting the adoption plan.

[ibrahimhajjaj]

@lezama

The four filters landed in trunk on May 21 (changeset 62397, commit e8dbd46), so this is unblocked now.

I've been building a consumer of two of them for the last few weeks. AbilityGuard, snapshot/audit/rollback middleware for the Abilities API: https://github.com/ibrahimhajjaj/abilityguard. The feature/wp-7.1-bridge branch hooks wp_pre_execute_ability for an approval short-circuit and wp_ability_execute_result for post-execute capture. Haven't touched normalize_input or permission_result yet.

A few footguns I hit that map onto the adoption plan here:

Capability detection can't key off $wp_version. The abilities-api also ships standalone on its own release cadence, so a 7.0 host can have the filters and a pinned 7.1 host can be without them. I ended up reflecting on WP_Ability::execute() source and checking for the 'wp_pre_execute_ability' literal instead of a version gate. Worth deciding early how agents-api wants to detect the seam.

Sentinel pass-through is mandatory for coexistence. Core seeds $pre with a fresh WP_Filter_Sentinel per call. If two consumers hook wp_pre_execute_ability on one host (agents-api's approval boundary plus something like AbilityGuard), the second one has to bail when $pre is no longer a sentinel, or it clobbers the first short-circuit. if ( ! ( $pre instanceof WP_Filter_Sentinel ) ) return $pre; before doing anything.

The short-circuit fires before wp_before_execute_ability. So anything writing a transcript row in the before-action never runs on an approval short-circuit. I had to open the pending row inline inside the pre-execute handler. Same applies to whatever records the WP_Agent_Pending_Action.

wp_after_execute_ability doesn't fire on WP_Error or output-validation failure. And wp_ability_execute_result only sees the success path (it's inside do_execute() before validate_output()). So for the transcript use case, hooking only those two silently drops failed tool calls, the error path needs its own handling. Also no duration_ms at the execute_result seam since the outer execute() hasn't returned, timing has to come from a later hook.

One design question. For the pending envelope I return a WP_Error with status => 202 so it flows through the REST run-controller as a 202 with no extra plumbing. A typed WP_Agent_Pending_Action reads cleaner but the loop has to tell it apart from a real ability return value, which is the thing you flagged on #11731. Happy to write up the tradeoff if it's useful.

The WP_Agent_* pending-action contracts from #71 give me the shape to target, and #184 looks like the live piece. If the wp_pre_execute_ability approval-boundary slice isn't spoken for, I'd be glad to take it. I've got a working version in AbilityGuard I can adapt to the contracts here.

[lezama]

Hey @ibrahimhajjaj — thanks for this, both the AbilityGuard pointer and the footguns. Every one of those is a thing I'd have learned the painful way.

Quick acks:

• Capability detection via reflection — right call. Folding into the bridge docblock so future slices don't accidentally version-gate on `$wp_version`.
• Sentinel pass-through — noted. The pre-execute handler will start with `if ( ! ( $pre instanceof WP_Filter_Sentinel ) ) return $pre;` and a smoke for co-existing consumers.
• `wp_pre_execute_ability` fires before `wp_before_execute_ability` — whatever opens the pending row has to do it inline in the pre-execute handler.
• `wp_ability_execute_result` only sees the post-callback path — fair catch, my PR Abilities: bridge wp_ability_execute_result onto agents_api_ability_executed #199 description was overclaiming. Updated to "fires when `execute_callback` runs, after permission and input checks pass." Failure modes upstream get their own observer surfaces in follow-up slices.
• No `duration_ms` at the execute_result seam — agreed, timing has to come from a later hook.

The `wp_pre_execute_ability` approval slice is open and I'd love it if you took it. PR #199 is just the post-execute telemetry observer — no envelope work, doesn't touch pre-execute. Your AbilityGuard implementation is exactly the kind of working reference we want.

A couple of things that would help when you send the PR:

• Land it against the same `src/Abilities/class-wp-agent-ability-lifecycle-bridge.php` — new static method + second `add_filter` inside `register()`. Keeps the four lifecycle hooks discoverable in one place.
• The envelope tradeoff (typed `WP_Agent_Pending_Action` vs `WP_Error` with `status => 202`) is the design decision that turns the slice on. If you have a moment, a short writeup of what each unblocks vs rules out would be super useful before you ship. Happy to discuss here first.

Thanks again.

[lezama]

and AbilityGuard looks pretty cool :)

[ibrahimhajjaj]

Thanks @lezama , and glad AbilityGuard's handy as a reference. Happy to take the pre-execute slice.

On the envelope question: I dug through the Approvals module and followed how a pending action moves through things right now, and I think the answer's different depending on where you are.

Inside the agent loop, I'd go with the typed WP_Agent_Pending_Action, returned in the approval_required message envelope. The loop already understands that shape, it accepts approval_required right next to tool_result and input_required, and data-machine already does exactly this: its ToolExecutor calls PendingActionHelper, which builds a pending action and hands it back inside an approval_required envelope as a normal successful result.
So if the pre-execute handler mints a pending action and returns it the same way, nothing in the loop or REST has to change, it just slots into what's already there. And the whole typed payload survives (action_id, kind, summary, preview, apply_input, workspace), so the existing list/get/resolve abilities and the store can pick it up as-is.

The WP_Error with status 202 that AbilityGuard uses is more of a REST thing than a loop thing. It works for AbilityGuard because there's no agent loop underneath it, it sits straight on the ability lifecycle, so a WP_Error comes back out through the REST run controller as a 202 and you're done. But in this loop it just gets eaten: a tool error gets turned into an error result and the run keeps going, the status code thrown away (the result only looks at a success boolean). So the loop would never even notice the 202 unless we taught it to sniff for one and stop, and a WP_Error can't carry the typed pending-action payload anyway.

One gap worth flagging: right now nothing in the module actually creates a pending action during execution, it only stores and resolves ones made elsewhere. So this handler would be the first thing that builds one (via from_array) and stages it through the host store, same store filter data-machine uses. Not a problem, just the first of its kind, so figured I'd mention it.

So here's what I'm picturing, unless you'd rather do it another way: add it to the lifecycle bridge as a new static method and a second add_filter in register(), the handler builds the WP_Agent_Pending_Action, stages it through the host store, and short-circuits with the approval_required envelope, sentinel check up front. Leave the WP_Error 202 as just the REST rendering for people calling the ability directly. Sound right to you?

[gziolo]

More filters landed in WP core:

• Abilities API: Add wp_ability_invoked action for pipeline-entry observers WordPress/wordpress-develop#11852
• Abilities API: add filters for input and output validation WordPress/wordpress-develop#10557

[lezama]

Yes, your direction is right. Typed `WP_Agent_Pending_Action` in an `approval_required` envelope inside the loop, `WP_Error` 202 only at the REST run-controller boundary. The axis you drew is the correct one.

One cross-check before you start, because it changes the slice scope:

I grepped canonical for `approval_required` / `TYPE_APPROVAL_REQUIRED` references in the conversation loop and tool execution layer — there are none. `mediate_tool_calls` records whatever the executor returns as a `tool_result`; it doesn't sniff for the envelope type. data-machine works because its consumer-side ToolExecutor adapter does the recognition before handing the result back to the loop. The substrate itself doesn't.

So the slice is actually two pieces:

1. The pre-execute handler in the bridge — builds the pending action, stages it through the host store, returns the `approval_required` envelope. (Your plan.)
2. Loop-level recognition — `mediate_tool_calls` needs to detect an `approval_required` envelope coming back from the executor and surface it as an approval pause rather than letting it run as a normal tool_result. Probably a new branch that checks `WP_Agent_Message::type($result) === TYPE_APPROVAL_REQUIRED` and returns `status: 'approval_required'` from the loop.

Happy to take #2 in parallel so they land together, or you can do both if you'd rather keep them in one PR. Your call.

The precedent gap (first creator in canonical) is fine — `WP_Agent_Pending_Action::from_array()` is the constructor entry, `WP_Agent_Pending_Action_Store::store()` is the staging entry. Both stable.

One ask: when you write the smoke, please include a coexistence case — two consumers stacked on `wp_pre_execute_ability`, the second one bails on a non-sentinel `$pre`. That's the guarantee your earlier comment flagged and worth pinning in canonical's test surface.

Looking forward to the PR.

[lezama]

Thanks for the heads up @gziolo — that's a significantly richer surface than the original four. The full WP 7.1 Abilities API picture is now nine hooks:

Hook	Type	When	Substrate use
`wp_ability_invoked`	action	top of `execute()`, every call	universal telemetry (catches failures the post-execute filter misses)
`wp_pre_execute_ability`	filter	pre-normalize, sentinel	approval boundary + recording short-circuit
`wp_ability_normalize_input`	filter	post-normalize	inject `WP_Agent_Execution_Principal` / `WP_Agent_Caller_Context`
`wp_ability_validate_input`	filter	post-schema validation	agent-aware input validation layering
`wp_ability_permission_result`	filter	post-`permission_callback`	route through `WP_Agent_Tool_Access_Policy` + capability ceiling
`wp_before_execute_ability`	action	pre-`do_execute` (now with `$ability`)	substrate-level pre-execute audit
`wp_ability_execute_result`	filter	post-`execute_callback`	result observation (#199, in flight)
`wp_ability_validate_output`	filter	post-output validation	output-shape audits
`wp_after_execute_ability`	action	success path only (now with `$ability`)	success-only commit hooks

Updating the #94 body to reflect the full surface. PR #199 stays scoped to `wp_ability_execute_result`; `wp_pre_execute_ability` is being picked up by @ibrahimhajjaj for the approval-boundary slice, and the rest land as separate slices on the same `WP_Agent_Ability_Lifecycle_Bridge`.

One small note from reading the validation-filter patches: when a filter returns literal `false`, the substrate returns a generic `WP_Error( 'ability_invalid_input/output', __( 'Invalid input/output.' ) )`. Fine for the default, but consumers writing custom validators in the wild will probably want to return their own `WP_Error` to preserve specific reason strings. Worth a doc note in the filter description if it isn't already there.

Thanks for the deliberate sentinel choice on `wp_pre_execute_ability` — Ibrahim is working through the multi-consumer coexistence story now and it's only possible because of that design.

[ibrahimhajjaj]

Thanks @lezama for the steer, and good catch, the "no loop changes" bit was wrong. mediate_tool_calls just records whatever the executor returns as a tool_result, it never looks at the message type, so approval_required only does anything today because data-machine's adapter catches it before the result gets back to the loop. The substrate does need the second piece.

I'll do both in one PR, since piece 1 on its own just emits an envelope the loop still treats as a normal tool_result, so they want to land together:

1. the pre-execute handler on the bridge, mints the pending action via from_array, stages it through the host store, returns the approval_required envelope, sentinel bail up front.
2. the mediate_tool_calls branch, when the executor returns a message whose type() is approval_required, surface it as status: approval_required out of the loop instead of recording it as a tool_result. Lines up with how the loop already returns status for budget_exceeded and the like.

Smoke will cover the coexistence case you asked for: two consumers on wp_pre_execute_ability, the second bails on a non-sentinel $pre and the first short-circuit stands.

I also checked the extra hooks from @gziolo lands too, wp_ability_invoked and the validate_input/output filters. Doesn't change this slice, but good to have the full surface for the follow-ups.