ToolAuditLogger

Audit logger for tool calls. Logs all tool executions for security and debugging. Since tool-runtime 0.5, this also doubles as an event LISTENER: {@see onToolExecuted()} and {@see onToolFailed()} are handlers for the `tool.executed` / `tool.failed` events dispatched by {@see ToolRegistry::call()}, reproducing exactly the audit calls this class used to receive imperatively. {@see ToolRegistry} wires these up automatically — subscribing them to its dispatcher when one is supplied, and invoking them directly (bypassing the dispatcher) when none is — so audit logging happens unconditionally either way; see the "no dispatcher = today's * behavior exactly" note on {@see ToolRegistry::__construct()}. `logValidationFailure()` / `logAuthFailure()` and the rate-limit branch's `log()` call remain imperative call sites in {@see ToolRegistry::call()} — they fire BEFORE `tool.executing` is ever dispatched (validation/authorization/rate-limiting are security gates that must run unconditionally ahead of the interception point; see that method's security anchor), so there is no `tool.*` event yet to hang them on in this package's catalog.

public function __construct(Psr\Log\LoggerInterface $logger):

Parameters

public function onToolExecuted(string $eventName, array $payload): void

Event listener for `tool.executed` (tool-runtime 0.5). Reproduces the audit call {@see ToolRegistry::call()} used to make imperatively on the success path: {@see log()} with the outcome, plus {@see logTimeout()} when the result carries the soft-timeout metadata. Fires identically for a cache short-circuit (`$event->cacheServed === true`) — a cache hit is audited exactly like a normal execution, never silently skipped.

Parameters

public function onToolFailed(string $eventName, array $payload): void

Event listener for `tool.failed` (tool-runtime 0.5). Reproduces the audit call {@see ToolRegistry::call()} used to make imperatively in its exception handler: {@see log()} with `ok: false` and the `'EXCEPTION'` error code.

Parameters

public function log(Milpa\ToolRuntime\Contracts\ToolContext $ctx, string $tool, array $args, bool $ok, ?string $errorCode, int $took_ms, ?int $outputSize = null): void

Log a tool call.

Parameters

public function logAuthFailure(Milpa\ToolRuntime\Contracts\ToolContext $ctx, string $tool, string $reason): void

Log an authorization failure.

Parameters

public function logValidationFailure(Milpa\ToolRuntime\Contracts\ToolContext $ctx, string $tool, array $errors): void

Log a validation failure.

Parameters

public function addSensitiveField(string $field): void

Add a sensitive field to sanitize.

Parameters

public function logTimeout(Milpa\ToolRuntime\Contracts\ToolContext $ctx, string $toolName, float $executionTime, int $timeoutLimit): void

Log a timeout exceeded warning. Called when a tool execution exceeds its configured timeout. This is a "soft" timeout - the result is still returned.

Parameters