adachsoft/agent-rule-tool

SPI tools for exposing and administrating agent rules in the AdachSoft AI tool call ecosystem.

v0.1.0 2026-02-08 08:14 UTC

Requires

• php: ^8.3
• adachsoft/agent-rule-contract: ^0.2
• adachsoft/ai-tool-call: ^2.0.1

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.89
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^12.4
• rector/rector: ^2.3.3

MIT

• Arkadiusz Adach

• tools
• rules
• Agent
• ai
• adachsoft
• ai-tool-call

README

SPI tool agent_rule for adachsoft/ai-tool-call that exposes effective agent rules from RuleRegistryInterface as structured JSON.

Tool definition

• Tool name: agent_rule
• Description: Returns effective agent rules resolved by the injected rule registry.
• Tags: ['agent:rules', 'rules', 'agent:general']

Input parameters (JSON, snake_case)

{
  "project_id": "P1" // optional, string or null; when omitted or null or "" -> global rules
}

Rules:

• project_id may be string, null or absent.
• Any other type for project_id causes InvalidToolCallException.

Mapping to registry:

• missing / null / empty string -> resolveEffectiveRules("")
• non-empty string "P1" -> resolveEffectiveRules("P1")

Output shape (KeyValueMap → JSON)

The tool result is a KeyValueMap that can be serialized to JSON with the following shape:

{
  "project_id": "P1",      // string or null
  "count": 2,               // number of rules
  "rules": [
    {
      "id": "R1",
      "type": "system",
      "scope": "project",
      "target": "agent",
      "content": "...",
      "priority": 100
    }
  ]
}

Notes:

• rules[*].type / scope / target are string values from corresponding enums in adachsoft/agent-rule-contract.
• metadata from RuleDto is intentionally not exposed.
• Sorting is stable by priority descending and preserves original order for ties.

Safety limits (ConfigMap)

Configured via ConfigMap passed to the factory under the tool name agent_rule.

Supported keys (snake_case):

• max_rules (int, default: 100)
• max_rule_content_bytes (int, default: 500)
• max_payload_bytes (int, default: 64000)

Semantics:

• max_rules: maximum number of rules included in the response.
• max_rule_content_bytes: maximum strlen(content) per rule.
• max_payload_bytes: maximum strlen(json_encode(finalResult)) for the whole payload.

Exceptions:

• invalid input types -> InvalidToolCallException
• invalid config (types, <=0) -> ToolConfigurationException
• exceeded limits -> ToolExecutionException
• exceptions from RuleRegistryInterface are propagated as-is.

Quick Start

1. Install dependencies in your project:

composer require adachsoft/ai-tool-call adachsoft/agent-rule-contract adachsoft/agent-rule-tool

1. Implement AdachSoft\\AgentRuleContract\\Contract\\RuleRegistryInterface in your application.

2. Register the tool using AiToolCallFacadeBuilder:

use AdachSoft\\AiToolCall\\Facade\\AiToolCallFacadeBuilder;
use AdachSoft\\AiToolCall\\SPI\\Config\\ConfigMap;
use AdachSoft\\AgentRuleTool\\Tool\\AgentRuleToolFactory;

$builder = new AiToolCallFacadeBuilder();

$builder = $builder
    ->withSpiFactories([
        new AgentRuleToolFactory(static function (): RuleRegistryInterface {
            return $yourRegistry; // your implementation
        }),
    ])
    ->withToolConfigs([
        'agent_rule' => new ConfigMap([
            'max_rules' => 100,
            'max_rule_content_bytes' => 500,
            'max_payload_bytes' => 64000,
        ]),
    ]);

$facade = $builder->build();

1. Call the tool:

$result = $facade->callTool('agent_rule', ['project_id' => 'P1']);
// or
$result = $facade->callTool('agent_rule', []);

The $result is a KeyValueMap that can be converted to an array / JSON according to adachsoft/ai-tool-call documentation.