Modernize tool system: replace AgentType with context-based tool registry + per-agent policies

[chubes4]

Vision

Kill AgentType. Kill tool registration silos. One flat registry, contexts as the grouping primitive, per-agent policies.

Every tool registers once with a contexts declaration. Resolution is: registry → context filter → agent policy → step policy → global policy → done.

Today the tool system has three separate registration channels (datamachine_global_tools, datamachine_chat_tools, datamachine_system_tools), a ToolManager that manages global enablement, a ToolPolicyResolver that gathers tools per-surface, and an AgentType class that exists but isn't formally connected to any of it. Tools are categorized at registration time — you register a "chat tool" or a "global tool" and that bakes in where it can appear. Chat tools bypass the enablement system entirely.

After this: one tool registry, contexts as the only grouping primitive, one policy evaluation path, and per-agent tool policies.

---

Implementation Plan

Phase 1: Unified Tool Registry + BaseTool Rewrite

Goal: Single tool registry replacing 3 separate filter channels.

• Rewrite BaseTool.php:

  • Kill registerGlobalTool() and registerChatTool() methods
  • Single registerTool(string $name, array|callable $definition) method
  • Tool definition must include contexts key (array of strings — extensible, any string valid)
  • Single filter: datamachine_tools replaces datamachine_global_tools + datamachine_chat_tools + datamachine_system_tools
  • No backward compat bridge — update all callers directly

• Rewrite ToolServiceProvider.php:

  • All ~46 tools register via single registerTool() with appropriate contexts
  • Current global tools → contexts: ['chat', 'pipeline', 'standalone']
  • Current chat-only tools → contexts: ['chat']
  • No more separate registerGlobalTools() / registerChatTools() methods

• Update ability-registered tools (PostQueryAbilities, GetPostBlocksAbility, EditPostBlocksAbility, ReplacePostBlocksAbility):

  • Migrate from registerChatTool() to registerTool() with contexts: ['chat']

Phase 2: Rewrite ToolPolicyResolver + ToolManager

Goal: Context-based resolution replacing surface-based gathering.

• Rewrite ToolPolicyResolver.php:

  • Replace surface constants (SURFACE_PIPELINE, SURFACE_CHAT, etc.) with context strings
  • New resolve() context keys: context (required), agent_id (optional), step_id (optional), deny, allow_only, plus pipeline-specific keys
  • Resolution order:
    1. Filter registry by context match (tool's contexts array contains the requested context)
    2. Add handler tools if pipeline context (existing chubes_ai_tools mechanism)
    3. Apply agent policy from agent_config (Phase 3)
    4. Apply step-level disabled_tools (existing)
    5. Apply global disabled_tools (existing)
    6. Apply explicit deny/allow_only overrides
    7. Check tool configuration requirements
    8. Fire datamachine_resolved_tools filter

• Update ToolManager.php:

  • get_global_tools() → get_all_tools() — returns everything from single registry
  • is_tool_available() simplifies — context filtering handled by resolver
  • is_globally_enabled() stays (reads from disabled_tools setting)
  • get_step_disabled_tools() stays (reads from pipeline step config)

Phase 3: Per-Agent Tool Policy

Goal: Agent-level tool scoping stored in agent_config.

• Schema in agent_config JSON:

  {
    "tool_policy": {
      "mode": "deny",
      "tools": ["image_generation", "send_ping"]
    }
  }

  • mode: "deny" → agent can use everything EXCEPT listed tools (default if no policy)
  • mode: "allow" → agent can ONLY use listed tools
  • No policy = no restrictions (backward compatible)

• ToolPolicyResolver reads agent policy when agent_id is provided in context

• Add agent policy resolution to the pipeline between context filtering and step/global filtering

Phase 4: Delete AgentType + Update All Callers

Goal: Eliminate AgentType as a concept. Contexts replace it.

• Delete inc/Engine/AI/AgentType.php
• Replace AgentType::CHAT / AgentType::PIPELINE / AgentType::SYSTEM with string literals 'chat' / 'pipeline' / 'system' everywhere:
  • ChatOrchestrator.php (~10 references) — pass context: 'chat' + agent_id to resolver
  • AIStep.php — pass context: 'pipeline' + step_id + agent_id to resolver
  • Chat.php (database) — change $agent_type parameter to $context, default 'chat'
  • Chat.php REST API — update parameter name
  • CreateChatSessionAbility.php — update parameter
  • AIConversationLoop — receives context string instead of AgentType constant
  • PluginSettings::getAgentTypes() — rename to getContextTypes() or keep with updated internals
  • SettingsAbilities.php — update agent_models validation
  • Providers.php API — update response
  • ToolExecutor.php deprecated shim — update to use context key

Phase 5: Cleanup + Tests

• Delete dead datamachine_system_tools filter handling (no production registrations)
• Remove AgentType references from docs/changelog
• Clean up ToolExecutor.getAvailableTools() deprecated shim
• Update tests:
  • ToolPolicyResolverTest — rewrite for context-based API
  • ChatToolsAvailabilityTest, PipelineToolsAvailabilityTest, WorkspaceToolsAvailabilityTest, WorkspaceScopedToolsTest — update for context-based resolution
  • AllAbilitiesRegisteredTest — update ability list if needed
  • New: per-agent tool policy resolution tests
• Run homeboy test data-machine — 0 failures
• PHP syntax check all modified files

---

What Stays Unchanged

• ToolExecutor.executeTool() — execution logic unchanged
• disabled_tools in pipeline step config — same mechanism, same storage
• disabled_tools in global settings — same mechanism
• Handler tools via chubes_ai_tools filter — pipeline-specific, dynamic, keep as-is
• datamachine_resolved_tools filter — final extensibility hook
• Tool definition structure (class, method, description, parameters)
• Chat tool classes stay in inc/Api/Chat/Tools/ — just registration changes
• agent_type column in chat sessions table — values stay the same strings

Related

• Modernize logging: replace AgentType file routing with agent_id database-backed logs #746 — Logging modernization (completed, removed AgentContext — precursor to this)
• Consider agent-level runtime authentication #740 — Agent runtime authentication
• Agent-first architecture: agent_id as primary scoping key for pipelines, flows, jobs #735 — Agent-first scoping

[chubes4]

All 5 phases complete and merged to main:

• Phase 1 — Unified tool registry (PR feat(#741): unify tool registry — single datamachine_tools filter with context arrays #748)
• Phase 2 — Surface → Context rename (PR feat(#741): Context resolver rename + per-agent tool policies (Phases 2-3) #749)
• Phase 3 — Per-agent tool policies (PR feat(#741): Context resolver rename + per-agent tool policies (Phases 2-3) #749)
• Phase 4 — Delete AgentType class (PR feat(#741): Delete AgentType class (Phases 4-5) #750)
• Phase 5 — Cleanup (PR feat(#741): Delete AgentType class (Phases 4-5) #750)

AgentType.php deleted. Single datamachine_tools filter with context arrays. Per-agent tool policies via agent_config.tool_policy. All 785 tests passing.