# core/toolintent — AGENTS.md

## Purpose

Plane-2 tool-call intent validation: evaluates proposed tool calls against workspace policy rules before execution, records the assessment as an event, and provides `WorldProbe` for recording environment observations needed by rules.

## Ownership

CORREX kernel team. This module enforces Hard Invariant #9 for the tool-call path.

## Local Contracts

- `ToolCallAssessor` — evaluates a proposed tool call against all active `ToolCallRule`s; returns a `ToolCallAssessmentRecord`.
- `ToolCallRule` — interface for a single validation rule. Built-in rules:
  - `PathContainmentRule` — tool must write within the workspace root.
  - `ReadBeforeWriteRule` — file must be read before being overwritten.
  - `StaleWriteRule` — detects write to a file that has changed on disk since last read.
  - `NetworkHostRule` — egress must be on the allowlist.
  - `ManifestContainmentRule` — write target must appear in the write manifest.
  - `WriteScopeRule` — enforces declared write scope.
  - `ReferenceExistsRule` — referenced entities must exist.
  - `ExecInterpreterRule` — interpreter must be in the allowed list.
  - `CycleExitRule` (in `core:validation`) — imported separately; not defined here.
- `WorkspacePolicy` — aggregates rules and configuration for a workspace.
- `WorldProbe` — performs environment checks (filesystem, network) and records the observations as events immediately (Hard Invariant #9). Never call `WorldProbe` during replay.
- `EgressAllowlist` — current egress allowlist; rebuilt from `EgressAllowlistProjection` (in `core:events`).
- `ParamValueExtractor` — extracts typed parameter values from tool call arguments.
- `RiskMapping` — maps rule violations to risk levels for `core:risk`.
- `SessionContext` — session-scoped context passed to rules during evaluation.

## Work Guidance

- Hard Invariant #9: all `WorldProbe` calls record observations as events. Replay reads those recorded events — it must not call `WorldProbe` again.
- Hard Invariant #5: every tool call must be assessed before execution. Assessment result is recorded as `ToolCallAssessmentEvents` in `core:events`.
- New rules implement `ToolCallRule` and are registered in `WorkspacePolicy`. Do not add rule logic directly to `ToolCallAssessor`.

## Verification

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

## Child DOX Index

No child AGENTS.md (leaf module).