# 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: `PATH` (the path a call acts on / mutates), `SOURCE_PATH` (a path it only reads from while acting on another target, e.g. `file_copy`), `EXEC_COMMAND`, `NETWORK_TARGET`. Plane-2 gates dispatch on these, never on tool names.
- `ToolPath` — the ONE canonical path normalization rule: expands a leading `~`/`~/` to the user home, keeps absolute paths, anchors relative paths on the session's working dir (never the JVM cwd). Every filesystem tool and every plane-2 path rule must resolve through it so policy checks and execution act on the same path. `~other/…` is deliberately NOT expanded.
- `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).