Tool discovery: list-tools / execute-tool meta-tools (closes #37)

[lezama]

Summary

• Adds two meta-abilities — openclawp/list-tools (paginated, category-filterable catalog) and openclawp/execute-tool (dispatcher by slug) — that let an agent discover and invoke tools on demand instead of paying for every input schema in every system prompt.
• Adds a per-agent catalog_mode toggle in default_config. Default off → byte-identical legacy behavior. On → the resolver swaps the full tool-list declarations for the two meta-tools, regardless of how many abilities the agent allow-lists.
• Categories: respects an ability's explicit category, falls back to inferring from the slug namespace (posts/recent → posts).
• New unit-test suite (tests/unit/ToolDiscoveryTest.php, 12 cases) plus integration smoke checks for the abilities registering, the dispatcher round-trip, and the resolver swap with the toggle on/off.

What ships

• includes/class-openclawp-tool-discovery.php — pure helpers (list_tools, execute_tool, meta_tool_resolver_payload).
• includes/class-openclawp-abilities.php — registers openclawp/list-tools + openclawp/execute-tool.
• includes/class-openclawp-tools-resolver.php — honors default_config.catalog_mode.
• docs/tool-discovery.md — opt-in instructions and the round-trip-vs-tokens trade-off.
• tests/bootstrap.php — adds __(), is_wp_error, WP_Error stubs so the unit suite can run without WP.

What's deferred (follow-up issues)

• Per-conversation / per-workspace caching of list-tools output. The resolver re-walks the registry on every call today. Cheap on sites with <100 abilities, worth caching beyond that.
• A wp-admin checkbox in the per-agent settings UI. Today the toggle lives only in PHP (default_config['catalog_mode'] => true). Add the UI in a follow-up so the admin surface stays unblocked for the other in-flight issues.

Test plan

• vendor/bin/phpunit --testsuite unit — 12 new cases pass (44 total, 90 assertions).
• On a site with the abilities registered, wp_get_ability( 'openclawp/list-tools' )->execute( [] ) returns a paginated catalog excluding the meta-tools themselves.
• wp_get_ability( 'openclawp/execute-tool' )->execute( [ 'tool' => 'openclawp/echo', 'args' => [ 'text' => 'hola' ] ] ) returns { tool: 'openclawp/echo', result: { echoed: 'hola' } }.
• Register an agent with default_config => [ 'catalog_mode' => true, 'tools' => [ ...20 slugs ] ] and confirm OpenclaWP_Tools_Resolver::for_agent() returns exactly two declarations.
• Same agent without catalog_mode returns all 20 declarations (regression guard).
• Multi-turn chat: model calls list-tools then execute-tool and the loop completes in one combined turn budget.

Closes #37

Generated with Claude Code