Tool System

Tool System Purpose Every Teddy capability that reads or changes WordPress data must be a tool: a named, typed, capability-gated unit of work. The agent never calls raw WP APIs directly. Lifecycle…

v5 README.md Download markdown Updated July 18, 2026

Tool System#

Purpose#

Every Teddy capability that reads or changes WordPress data must be a tool: a named, typed, capability-gated unit of work. The agent never calls raw WP APIs directly.

Lifecycle (mandatory)#

  1. Resolve tool from ToolRegistryInterface
  2. Check required_capability() via PermissionPolicyInterface
  3. Validate input against JSON Schema (InputValidator)
  4. If is_dangerous() and not approved → return ToolPreview
  5. Write audit log (running)
  6. Execute ToolInterface::execute()
  7. Write audit log (success/error)
  8. Dispatch domain events

Classes#

Layer Path
Contract src/Domain/Tool/ToolInterface.php
Context / result ToolContext, ToolResult, ToolPreview
Registry src/Infrastructure/Tool/InMemoryToolRegistry.php
Executor src/Application/Agent/ToolExecutor.php
Abilities bridge src/Infrastructure/Tool/DomainToolAbilityRegistrar.php
Legacy bridge src/Infrastructure/Tool/LegacyToolsBridge.php

Naming#

  • Domain names: post.create, wc.product.list, system.ping
  • Ability names: teddy/post-create via DomainToolNaming
  • Extension tools must include a vendor prefix: myplugin.appointment.list

Manager tools (v1.4)#

Name Dangerous Notes
site.briefing no Daily digest: stats, comments, backup, updates, Woo, actionable
content.gaps no Missing image/excerpt/short title / stale
content.scheduled no Future posts
comment.list no Inbox by status
comment.set_status yes approve/spam/trash/hold
ops.recent_changes no Audit log recent
ai.usage.summary no Token/cost summary
knowledge.status no RAG readiness

Recent domain tools (Vision gap slice)#

Name Dangerous Notes
post.delete yes Trash by default; force=true permanent
wc.product.find_missing_images no Products without featured image
wc.product.list_expired_promotions no Sale ended, sale price still set
wc.product.clear_expired_sales yes Clears those sale prices
wc.report.revenue no day/week/month/year gross
system.clear_cache no Object cache + expired transients + teddy_clear_cache
system.optimize_db yes OPTIMIZE TABLE (site prefix only)
system.backup.run yes UpdraftPlus / teddy_run_backup
system.send_email yes wp_mail to administrators only
system.wp_cli yes Whitelist: cache flush, plugin list, cron list, transient cleanup
media.generate_image no GD placeholder PNG; optional featured image

Feature flags#

  • use_agent_pipeline — admin Copilot uses domain tools + audit
  • enable_database_access — gates legacy/public read tools
  • enable_extension_sdk — unlocks dev.* code-generation tools

External agents (MCP / OpenClaw)#

Domain tools are also available over MCP via mcp-server/ — see mcp-bridge.

Verification#

composer test:unit
php tests/e2e-agent-pipeline.php   # Laragon PHP 8.2+