SPI tool agent_rule for adachsoft/ai-tool-call that exposes effective agent rules from RuleReaderInterface as structured JSON, and SPI tool agent_rule_admin for creating, updating and deleting rules via RuleWriterInterface.

Tool definitions

`agent_rule`

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

`agent_rule_admin`

Tool name: agent_rule_admin
Responsibility: create, update and delete rules using RuleWriterInterface while enforcing the same content-size limits as the agent_rule tool.

Input parameters for `agent_rule` (JSON, snake_case)

{
  "project_id": 1 // optional, integer or null; when omitted or null -> only global rules; when integer -> global + project rules
}

Rules:

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

Mapping to reader:

missing / null -> getAllByProject(null) (only global rules)
integer 1 -> getAllByProject(1) (global + project rules for project 1)

Output shape for `agent_rule` (KeyValueMap → JSON)

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

{
  "project_id": 1,       // integer or null
  "count": 2,            // number of rules
  "rules": [
    {
      "id": "rule_1",          // RuleId as string
      "type": "REQUIREMENT",   // RuleTypeEnum::name
      "target": "AGENT",       // RuleTargetEnum::name
      "content": "...",        // string
      "priority": 100           // integer
    }
  ]
}

Notes:

rules[*].type / target are string values from corresponding enums in adachsoft/agent-rule-contract (RuleTypeEnum::name, RuleTargetEnum::name).
metadata from Rule is intentionally not exposed.
Sorting is stable by priority descending and preserves original order for ties.

Safety limits (ConfigMap, shared)

Both tools share the same configuration object AgentRuleToolConfig, which is built from a ConfigMap passed to the factories under the tool names agent_rule and agent_rule_admin.

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 agent_rule response.
max_rule_content_bytes: maximum strlen(content) per rule; enforced centrally for both read and write paths:
- agent_rule: refuses to return rules whose content exceeds this limit.
- agent_rule_admin: refuses to create or update a rule whose content exceeds this limit.
max_payload_bytes: maximum strlen(json_encode(finalResult)) for the whole agent_rule payload.

Exceptions:

invalid input types -> InvalidToolCallException
invalid config (types, <=0) -> ToolConfigurationException
exceeded limits (max_rules, max_rule_content_bytes, max_payload_bytes) -> ToolExecutionException
exceptions from RuleReaderInterface / RuleWriterInterface are propagated as-is.

Quick Start (`agent_rule`)

Install dependencies in your project:

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

Implement AdachSoft\\AgentRuleContract\\Contract\\RuleReaderInterface in your application or use adachsoft/agent-rule JSON-based implementation.
Register the tool using AiToolCallFacadeBuilder:

use AdachSoft\\AiToolCall\\PublicApi\\Builder\\AiToolCallFacadeBuilder;
use AdachSoft\\AiToolCall\\PublicApi\\Dto\\ToolCallRequestDto;
use AdachSoft\\AiToolCall\\SPI\\Collection\\ConfigMap;
use AdachSoft\\AgentRuleTool\\Tool\\AgentRuleToolFactory;
use AdachSoft\\AgentRuleContract\\Contract\\RuleReaderInterface;

$reader = /* your RuleReaderInterface implementation */;

$builder = AiToolCallFacadeBuilder::new()
    ->withSpiFactories([
        new AgentRuleToolFactory($reader),
    ])
    ->withToolConfigs([
        'agent_rule' => new ConfigMap([
            'max_rules' => 100,
            'max_rule_content_bytes' => 500,
            'max_payload_bytes' => 64000,
        ]),
    ]);

$facade = $builder->build();

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

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

Quick Start (`agent_rule_admin`)

To use the admin tool, you need an implementation of RuleWriterInterface:

use AdachSoft\\AiToolCall\\PublicApi\\Builder\\AiToolCallFacadeBuilder;
use AdachSoft\\AiToolCall\\PublicApi\\Dto\\ToolCallRequestDto;
use AdachSoft\\AiToolCall\\SPI\\Collection\\ConfigMap;
use AdachSoft\\AgentRuleTool\\Tool\\AgentRuleAdminToolFactory;
use AdachSoft\\AgentRuleContract\\Contract\\RuleWriterInterface;

$writer = /* your RuleWriterInterface implementation */;

$builder = AiToolCallFacadeBuilder::new()
    ->withSpiFactories([
        new AgentRuleAdminToolFactory($writer),
    ])
    ->withToolConfigs([
        'agent_rule_admin' => new ConfigMap([
            'max_rules' => 100,
            'max_rule_content_bytes' => 500, // must match read-side limit to avoid inconsistencies
            'max_payload_bytes' => 64000,
        ]),
    ]);

$facade = $builder->build();

// Example: create a rule within the configured content limit
$result = $facade->callTool(new ToolCallRequestDto('agent_rule_admin', [
    'action' => 'create',
    'rule' => [
        'id' => 'rule_1',
        'type' => 'REQUIREMENT',
        'target' => 'AGENT',
        'content' => 'Short rule content',
        'priority' => 100,
    ],
    'project_id' => null,
]));

If the content value exceeds max_rule_content_bytes, the admin tool will throw a ToolExecutionException with a message indicating that the maximum rule content size has been exceeded, and the rule will not be persisted.