correx/core/toolintent/AGENTS.md

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 ToolCallRules; 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

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

Child DOX Index

No child AGENTS.md (leaf module).