Agent Warden
Sign inInstall free
Documentation menu

Hooks reference

Every filter and action Agent Warden offers, generated from the source. Hooks marked "since 1.0.0" are stable.

agentwarden_ability_capabilities#

Filter · src/Capabilities/AbilityCapabilities.php

Filters the primitive capabilities an ability's permission callback checks.

Plugins that register abilities should declare them here so agents allowed to use the ability receive exactly these capabilities, and nothing more, for the request.

  • string[] $caps Capabilities.
  • string $ability_name Ability name.

agentwarden_ability_hard_blocks#

Filter · src/Policy/HardBlockClassifier.php

Filters the hard blocks an ability falls under.

Declare every block that describes what your ability does, for example array( 'settings' ) for an ability that changes options, or array( 'irreversible' ) for one that sends email or moves money. Unknown names are ignored.

  • string[] $blocks Hard block names from Document::HARD_BLOCKS.
  • string $ability_name Ability name.

agentwarden_ability_reversibility#

Filter · src/Policy/Reversibility.php

Filters an ability's reversibility class.

Return array( 'class' => ..., 'caveat' => ... ), where class is one of reversible, reversible_with_caveats, irreversible, or unknown, and the optional caveat is shown to reviewers. Abilities nobody classifies are unknown and treated as irreversible: blocked by the irreversible hard block, or held for approval when it is off.

  • array{class: string, caveat: string, source: string} $classification Classification so far.
  • string $ability_name Ability name.

agentwarden_action_logged#

Action · src/Log/LogWriter.php

Fires after an agent request is written to the action log.

  • int $action_id Action log row ID.
  • string $ability Ability name.
  • mixed $input Input as the ability received it. Not redacted: never store or print it as is.
  • string $decision allow, deny, or hold.
  • RequestContext $context Agent context.

agentwarden_after_execute#

Action · src/Gateway/AbilityGuard.php

Fires just after an allowed ability ran for an agent, whether it succeeded or returned an error.

  • string $name Ability name.
  • mixed $input Input.
  • mixed $result Result or WP_Error.
  • RequestContext $context Agent context.
  • int $duration_ms Execution time in milliseconds.

agentwarden_agent_auto_paused#

Action · src/Safety/AnomalyMonitor.php

Fires after Agent Warden pauses an agent for an anomaly rule.

  • int $agent_id Agent.
  • string $rule anomaly_denials or anomaly_hard_block.
  • int $count Refusals that tripped it.
  • int $minutes The window, in minutes.

agentwarden_anomaly_counted_reasons#

Filter · src/Safety/AnomalyMonitor.php

Filters the refusal reasons that count toward anomaly auto-pause, besides hard blocks.

  • string[] $reasons Reason codes.

agentwarden_approval_decided#

Action · src/Approvals/ApprovalService.php

Fires once when an approval is decided, before an approved action runs.

Email links and other one-shot decision paths listen here to void themselves.

  • int $approval_id Approval.
  • string $status approved or denied.
  • int $reviewer_id User who decided.

agentwarden_approval_notifications_enabled#

Filter · src/Licensing/Features.php

Filters whether approval notification channels are available on this site.

  • bool $enabled Default: true on paid plans.

agentwarden_approval_requested#

Action · src/Approvals/ApprovalQueue.php

Fires once when a held action creates a new approval (not when a pending one is reused).

  • int $approval_id Approval.

agentwarden_before_execute#

Action · src/Gateway/AbilityGuard.php

Fires just before an allowed ability runs for an agent.

  • string $name Ability name.
  • mixed $input Input.
  • RequestContext $context Agent context.

agentwarden_client_ip#

Filter · src/Auth/ClientIp.php

Filters the client IP Agent Warden uses for token allowlists, rate limits, and logs.

Return a different IP only when REMOTE_ADDR is a proxy you trust. Invalid return values are ignored.

  • string $remote REMOTE_ADDR, validated.

agentwarden_compliance_report_enabled#

Filter · src/Licensing/Features.php

Filters whether this site can generate signed compliance reports.

  • bool $enabled Default: true on Enterprise.

agentwarden_custom_retention_enabled#

Filter · src/Licensing/Features.php

Filters whether this site may set a custom retention period and place a legal hold.

  • bool $enabled Default: true on Enterprise.

agentwarden_dry_run_enabled#

Filter · src/Licensing/Features.php

Filters whether dry-run mode and the Approvals "Preview effect" are available on this site.

  • bool $enabled Default: true on paid plans.

agentwarden_dry_run_transaction_mode#

Filter · src/DryRun/DryRunSandbox.php

Filters how dry runs isolate their writes: a transaction, or a savepoint inside an outer transaction that the caller owns (the test suite).

  • string $mode 'transaction' (default) or 'savepoint'.

agentwarden_emergency_pause#

Action · src/Safety/EmergencyPause.php

Fires after an emergency pause link paused every agent.

  • int $user_id The administrator whose link was used.

agentwarden_execute_result#

Filter · src/Gateway/AbilityGuard.php

Filters what an agent receives from an allowed ability, after the run was logged and journaled.

The resource scope post-check replaces the result with an error when it reverted the run (ADR-0023 §4).

  • mixed $result Result or WP_Error.
  • string $name Ability name.
  • mixed $input Input.
  • RequestContext $context Agent context.

agentwarden_exports_enabled#

Filter · src/Licensing/Features.php

Filters whether activity log exports are available on this site.

  • bool $enabled Default: true on paid plans.

agentwarden_hub_trusted_keys#

Filter · src/Hub/HubEndpoint.php

Filters the hub signing keys this site trusts.

  • string[] $keys Base64 raw Ed25519 public keys. Default: the official hub keys and AGENTWARDEN_HUB_TRUSTED_KEYS.

agentwarden_hub_url#

Filter · src/Hub/HubEndpoint.php

Filters the hub address this site connects to.

  • string $url Hub address. Default: the official hub, or AGENTWARDEN_HUB_URL.

agentwarden_journal_row_restored#

Action · src/Journal/Undo/Restorer.php

Fires after undo restored one journaled row and core's caches for it were cleaned.

  • string $table Logical table.
  • string $pk Key value.
  • mixed $before Image restored (null when the row was deleted).
  • mixed $after Image replaced.

agentwarden_journal_row_restoring#

Action · src/Journal/Undo/Restorer.php

Fires just before undo writes a row back, inside the undo transaction, while the row still holds the state being replaced. Integrations whose own clean-up needs the row (for example to delete derived data for a post undo is about to remove) run it here.

  • string $table Logical table.
  • string $pk Key value.
  • mixed $before Image about to be restored; null when undo removes the row.

agentwarden_journal_skip_option#

Filter · src/Journal/Capture.php

Filters whether an option is left out of the journal.

Transients and the cron schedule are skipped by default: they regenerate, and undoing the schedule would break it. Skipped options cannot be undone.

  • bool $skip Whether to skip.
  • string $option Option name.

agentwarden_journal_tables#

Filter · src/Journal/RowReader.php

Filters the tables the journal can record, so integrations can journal their own tables.

Add entries as logical name => array( 'table' => physical name, 'key' => column, 'set' => bool ). Core tables cannot be replaced.

  • array<string, array{table: string, key: string, set: bool}> $tables Journaled tables.

agentwarden_journal_warning_bytes#

Filter · src/Journal/Retention/StorageEstimator.php

Filters the journal size above which Settings warns about storage.

  • int $bytes Default 1 GB.

agentwarden_license_source#

Filter · src/Licensing/LicenseState.php

Filters where this site's own license comes from. The Pro edition returns its license key once one is entered (ADR-0044).

  • LicenseSource|null $source License source, or null for none.

agentwarden_lockdown_enabled#

Filter · src/Licensing/Features.php

Filters whether this site applies its saved lockdowns.

  • bool $enabled Default: true on Enterprise.

agentwarden_max_agents#

Filter · src/Licensing/Features.php

Filters the maximum number of agents that are not revoked. Return null for unlimited.

  • int|null $max Default: 2 on Free, unlimited on paid plans.

agentwarden_notifications_mock#

Filter · src/Notifications/MockOutbox.php

Filters whether notification channels record to the mock outbox instead of sending.

  • bool $mock Default: the AGENTWARDEN_NOTIFICATIONS_MOCK constant or environment variable.

agentwarden_pending_payload#

Filter · src/Gateway/AbilityGuard.php

Filters the result an agent receives when its action is held for approval.

The approval queue sets approval_id here. status and poll_ability are part of the agent contract and are restored if a filter changes them.

  • array<string, mixed> $payload Pending result.
  • string $name Ability name.
  • mixed $input Input.
  • Decision $decision Hold decision.
  • RequestContext $context Agent context.

agentwarden_policy_evaluate#

Filter · src/Policy/Evaluator.php

Filters an evaluated policy decision.

Return a stricter Decision to add your own rules (allow to hold or deny, hold to deny). Looser decisions and non-Decision values are ignored, so this hook can never grant access that the policy refused.

  • Decision $decision Evaluated decision.
  • string $ability Ability name.
  • mixed $input Ability input.
  • RequestContext $context Agent context.

agentwarden_policy_packs#

Filter · src/Policy/Packs/PackRegistry.php

Filters the policy packs on this site.

Add an instance of AgentWarden\Policy\Packs\Pack to describe your plugin's abilities: their reversibility, hard blocks, capabilities, scope targets, log summaries, and tables.

  • Pack[] $packs Packs registered so far.

agentwarden_policy_packs_enabled#

Filter · src/Licensing/Features.php

Filters whether policy packs contribute scope targets, summaries, capability maps, and template rules on this site.

  • bool $enabled Default: true on paid plans.

agentwarden_policy_saved#

Action · src/Policy/PolicyRepository.php

No description yet.

agentwarden_pro_license_status#

Filter · src/Admin/RestControllers/LicenseController.php

Filters the license key state shown under Settings → Plan. The Pro edition returns its key's status; the Free edition has no key to enter, so it stays null (ADR-0044).

  • array<string, mixed>|null $status Key status, or null when this edition takes no key.

agentwarden_prune_batch_size#

Filter · src/Journal/Retention/Pruner.php

Filters how many rows one prune round selects.

  • int $size Default 500.

agentwarden_prune_max_rounds#

Filter · src/Journal/Retention/Pruner.php

Filters how many rounds one prune run makes per kind of record.

  • int $rounds Default 20.

agentwarden_redact_keys#

Filter · src/Log/LogWriter.php

Filters extra input keys to redact in the action log, in addition to the built-in list.

  • string[] $keys Keys, matched case-insensitively.

agentwarden_register_content_abilities#

Filter · src/Abilities/Content/ContentAbilities.php

Filters whether Agent Warden registers its own post abilities.

Return false when another plugin already provides content abilities for agents.

  • bool $register Whether to register. Default true.

agentwarden_request_decided#

Action · src/Gateway/AbilityGuard.php

Fires once per request for an agent request that did not run: denied, held, or refused by WordPress's own permission check after policy allowed it.

  • string $name Ability name.
  • mixed $input Input.
  • Decision $decision Policy decision.
  • RequestContext $context Agent context.
  • string $result_status permission_denied, or empty for deny and hold.

agentwarden_resource_scopes_enabled#

Filter · src/Licensing/Features.php

Filters whether policies on this site may set resource scopes.

  • bool $enabled Default: true on paid plans.

agentwarden_retention_days#

Filter · src/Licensing/Features.php

Filters how many days agent history is kept before it is pruned.

  • int $days Default: 7 on Free, 365 on paid plans, or the saved Enterprise period. Values below 1 are treated as 1.

agentwarden_scope_targets#

Filter · src/Policy/ScopeTargets.php

Filters the objects an ability call acts on, for the resource scope pre-check.

Return array( 'posts' => int[] ) naming existing posts, or null when the objects are not known until the ability runs. The post-check still enforces scope after every run.

  • array<string, mixed>|null $targets Targets Agent Warden knows as array( 'posts' => int[] ), or null.
  • string $ability Ability name.
  • mixed $input Ability input. Not redacted: never store or print it.

agentwarden_session_entry_limit#

Filter · src/Admin/RestControllers/SessionsController.php

Filters how many journal entries the session detail returns in total.

  • int $limit Default 500.

agentwarden_siem_allow_private_hosts#

Filter · src/Siem/SiemTransport.php

Filters whether SIEM requests may go to private or internal addresses.

  • bool $allow Default false: WordPress refuses internal addresses.
  • string $destination splunk, datadog, or elastic.
  • string $host Destination host.

agentwarden_siem_event#

Filter · src/Siem/SiemPusher.php

Filters one event before it is pushed to a SIEM. Return null to leave it out; its cursor still moves.

  • array<string, mixed> $event Event.
  • string $destination syslog, splunk, datadog, or elastic.

agentwarden_siem_mock#

Filter · src/Siem/SiemMock.php

Filters whether SIEM destinations record to the mock instead of sending.

  • bool $mock Default: the AGENTWARDEN_SIEM_MOCK constant or environment variable.

agentwarden_siem_push_enabled#

Filter · src/Licensing/Features.php

Filters whether this site pushes its action log to SIEM destinations.

  • bool $enabled Default: true on Enterprise.

agentwarden_summary_template#

Filter · src/Log/SummaryRenderer.php

Filters the summary line stored for a logged agent action.

  • string $summary Default summary.
  • string $ability Ability name.
  • mixed $input Ability input (not redacted; do not echo secrets).
  • mixed $result Ability result, or null when it did not run.
  • string $decision allow, deny, or hold.
  • string $result_status success, error, permission_denied, or empty.

agentwarden_tamper_evident_log_enabled#

Filter · src/Licensing/Features.php

Filters whether the action log is hash-chained and checkpointed on this site.

  • bool $enabled Default: true on Enterprise.

agentwarden_undo_all_scopes_enabled#

Filter · src/Licensing/Features.php

Filters whether every undo scope and every journaled table can be undone on this site.

  • bool $enabled Default: true on paid plans (Free: per-action undo of posts).

agentwarden_undo_completed#

Action · src/Journal/Undo/UndoService.php

Fires after an undo run, so integrations can rebuild derived data (ADR-0017 §4).

  • int[] $undone_action_ids Actions fully undone.
  • UndoScope $scope Scope.

agentwarden_undo_transaction_mode#

Filter · src/Journal/Undo/Restorer.php

Filters how undo isolates each action: a transaction, or a savepoint inside an outer transaction that the caller owns (the test suite).

  • string $mode 'transaction' (default) or 'savepoint'.