Repository navigation
Description
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:
- 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.)
- 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.
- `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.
- `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.
- 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.
- 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.
Activity
ibrahimhajjaj commentedon May 24, 2026
@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 commentedon May 25, 2026
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:
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:
Thanks again.
lezama commentedon May 26, 2026
and AbilityGuard looks pretty cool :)
ibrahimhajjaj commentedon May 26, 2026
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 commentedon May 26, 2026
More filters landed in WP core:
lezama commentedon May 26, 2026
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:
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 commentedon May 26, 2026
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:
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 commentedon May 26, 2026
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:
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.