Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Declare readonly (and destructive) annotations on read-only abilities

Open Beginner friendly
  • Is something wrong?
#564 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
75/100
Issue type
Refactor
Clarity
Clearly specified
Activity status
Active
Tech stack
php
Domain
backend-api-design

Research direction

The issue lists specific ability registration files like register-agent-access-abilities.php. Start by locating these files in the agents/ directory. For each ability listed, update its 'annotations' array to include 'readonly', 'destructive', and 'idempotent' as described. After making changes, verify the annotations are correctly set by checking the output of the ability registration. Look for existing tests or CI that might validate ability declarations.

Written by the indexing model from the issue text.

Description

Problem

Most agents/* abilities declare idempotent but not readonly, and the read-only ones usually don't declare destructive either. Undeclared annotations stay null, so MCP clients (via the MCP adapter's readOnlyHint / destructiveHint) and any consumer that filters on meta.annotations can't tell a lookup from a write. In practice that means pure reads such as agents/get-chat-run get treated like writes: confirmation prompts, and exclusion from any "read-only abilities only" policy.

This is still the case on main (4597dd4): for example register-agent-access-abilities.php, register-agents-chat-run-control-abilities.php and register-agents-workflow-abilities.php pass array( 'idempotent' => true ) alone for their read abilities.

Affected abilities (from an audit of registered declarations)

Reads missing readonly: true and destructive: false:
ability-search (destructive only), can-access-agent, describe-workflow, get-chat-run, get-conversation-session, get-runtime-package-run, get-runtime-tool-request, get-task-run, get-workflow-run, list-accessible-agents, list-chat-run-events, list-conversation-sessions, list-execution-targets, list-runtime-package-run-events, list-runtime-tool-requests, list-workflow-run-events, validate-workflow.

Pending-action reads missing readonly: true:
get-pending-action, list-pending-actions, summary-pending-actions (these set destructive from ! idempotent, so they come out as destructive: false but readonly stays undeclared).

Writes missing an explicit readonly: false:
ability-call (also missing destructive), cancel-chat-run, cancel-runtime-package-run, cancel-runtime-tool-request, cancel-task-run, cancel-workflow-run, chat, create-conversation-session, delete-conversation-session, dispatch-message, queue-chat-message, reconcile-workflow-branch, resolve-pending-action, run-runtime-package, run-task, run-workflow, submit-runtime-tool-result, timeout-runtime-tool-request, update-conversation-session-title.

The explicit readonly: false on writes matters less, but declaring all three everywhere avoids consumers having to guess what null means.

Suggested fix

Declare all three annotations on every ability. For the read abilities:

'annotations' => array(
	'readonly'    => true,
	'destructive' => false,
	'idempotent'  => true,
),

A shared helper (or a check in CI that every wp_register_ability() call declares all three) would stop new abilities regressing.

Lower priority, same audit

  • Many input properties have no description (e.g. run_id, session_id, workspace.*, session_owner.*, principal.*, cursor, limit), which leaves models guessing at parameters.
  • Several output arrays have no items schema: run-workflow / reconcile-workflow-branch (steps, evidence_refs, artifacts, logs), *-task-run / run-task (output), *-conversation-session* (session.messages), chat (structured_output), ability-call (result).
  • resolve-pending-action output result has no type.

Happy to send a PR for the annotations if that's welcome.

Dominant language
PHP
Stars
33
Forks
8
Avg merge
1h 28m
Merged PRs (30d)
13

Getting set up

We have not checked this project's setup files yet. Start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Automattic/agents-api

All issues in Automattic/agents-api

Similar issues

More PHP issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.