# core/tools — AGENTS.md

## Purpose

Tool contract, registry, executor, and receipt tracking: defines the `Tool` interface, manages tool registration, executes tools within their declared tier, compresses tool output, and projects tool invocation history via the standard event-sourcing stack.

## Ownership

CORREX kernel team.

## Local Contracts

- `Tool` — primary interface all tools implement. Must declare `Tier` (from `core:events`).
- `ToolRegistry` — holds all registered tools for a session; looked up by name.
- `ToolExecutor` — executes a `Tool` given a `ToolRequest`, records `ToolEvents` in `core:events`.
- `ToolResult` — sealed result type: success with output, or failure with error.
- `ToolState` rebuilt from `ToolEvents` via `DefaultToolReducer` + `ToolProjector`.
- `DefaultToolRepository` wraps `EventReplayer<ToolState>`.
- `ToolInvocationRecord` / `ToolInvocationStatus` / `ToolCallAssessmentRecord` — history types.
- `FileMutationRecord` — records file-affecting side effects.
- `FileAffectingTool` — extended `Tool` interface for tools that write files; must declare `affectedPaths`.
- `OutputCompressionSpec` / `ToolOutputCompressor` / `DeclarativeCompressor` — compress large tool outputs to fit token budgets (Hard Invariant #6: compressed output is informational; original events are preserved).
- `ParamRole` — annotates tool parameter semantic roles (input path, output path, etc.).
- `ValidationResult` — result from tool-level parameter validation (pre-execution check).
- Hard Invariant #5: all tool side effects are captured in events. Silent execution is not allowed.

## Work Guidance

- Follow the standard Events→State→Reducer→Projector→Repository pattern (see `core/AGENTS.md`).
- `DefaultToolReducer` only does `state.copy(...)`.
- `ToolExecutor` must record a `ToolExecutedEvent` (or equivalent) before returning, even on failure.
- Output compression must not discard the original event — only produce a derived summary alongside it.
- New tools implement `Tool` (or `FileAffectingTool`) and register in `ToolRegistry`. Do not instantiate tools inside `ToolExecutor`.

## Verification

```bash
./gradlew :core:tools:test --rerun-tasks
```

## Child DOX Index

No child AGENTS.md (leaf module).