Files

T

claude 6a8a7b31c1 fix(events,tools,toolintent): failure attribution, one path normalization rule, file_copy (#713 )

Three generic harness fixes from the web-ui postmortem dataset. Nothing here keys
on a language, framework, build tool or task type.

1. Failure attribution. WorkflowFailedEvent carries one primary FailureAttribution
   (AGENT | HARNESS | WORKFLOW | ENVIRONMENT | PROVIDER | OPERATOR | UNKNOWN),
   defaulted to UNKNOWN so pre-field events replay unchanged. FailureAttributor is
   the deterministic reason->layer mapping, used both at emission and when
   classifying history, so the baseline and the live metric are one measurement.
   Emission sites set it: failWorkflow derives from the reason unless the caller
   knows the layer, cancellation is OPERATOR, the server catch-all falls back to
   HARNESS, a grounding-rejected plan is AGENT. Multi-cause chains stay on
   FailureTicketOpened — no second causal structure.

   GET /metrics/failure-attribution (FailureAttributionInspectionService, mirroring
   ToolReliabilityInspectionService) reports counts, share, UNKNOWN share, the
   preserved reasons and the ticket categories from the same sessions. Read-only:
   historical events are classified at READ time and reported as `inferred`, never
   written back over an append-only log.

   Baseline over the local log, 122 terminal failures: AGENT 51 (41.8%),
   OPERATOR 28 (23.0%), WORKFLOW 19 (15.6%), PROVIDER 15 (12.3%), HARNESS 6 (4.9%),
   ENVIRONMENT 3 (2.5%), UNKNOWN 0.

2. The `~` guard bug. ToolPath is now the ONE canonical normalization rule
   (expand a leading `~`/`~/`, keep absolutes, anchor relatives on the session
   working dir). Every filesystem tool, all six plane-2 path rules and the approval
   preview resolve through it, so policy and existence checks inspect the path the
   tool will operate on. `~/.gradle/init.d/offline.gradle` used to resolve to
   `<workspace>/~/.gradle/...`: reported non-existent AND in-workspace, so the
   reference gate called a real file a hallucination and the out-of-workspace prompt
   never fired. Containment and external-read approval behaviour are unchanged —
   the expanded path is simply outside the workspace, where it always belonged.

3. file_copy (#713). A first-class tool with the writer's jail, tier, receipt,
   replay and CAS pre/post images; static and binary assets no longer move through
   the model's token stream. Needed one generic split: ParamRole.SOURCE_PATH marks a
   path a call reads FROM, so containment gates judge both params while write-target
   gates (read-before-write, stale-write, write scope, write manifest) judge the
   mutated one. ReadBeforeWriteRule exempts any call declaring a SOURCE_PATH: its
   content comes from disk, not from memory, and requiring a read of a binary is
   unsatisfiable. Existing tools declare no SOURCE_PATH, so their behaviour is
   byte-identical.

Tests: ToolPathTest (9), FailureAttributionTest (10), PathNormalizationRuleTest (6),
FileCopyToolTest (10), plus a home-relative FileReadTool read. ./gradlew check green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-27 11:57:49 +04:00

3.2 KiB

Raw Blame History

infrastructure/tools/

Purpose

Tool implementations and execution infrastructure. Provides DefaultToolRegistry, DispatchingToolExecutor, and SandboxedToolExecutor. Implements concrete tools: shell execution (ShellTool), web search (WebSearchTool, requires SearXNG), web fetch + HTML→Markdown extraction (WebFetchTool, jsoup), task management tools, and filesystem tools (in filesystem/).

Ownership

Adapter for core:tools. Depends on core:tools, core:events, core:approvals, core:sessions, core:tasks, core:artifacts, core:artifacts-store. The filesystem/ submodule is a dependency of this module.

Local Contracts

DefaultToolRegistry implements ToolRegistry from core:tools.
SandboxedToolExecutor wraps DispatchingToolExecutor; it enforces approval gates and records all tool side effects as events before returning (invariant #5).
No tool may execute a side effect without emitting an event — silent execution is not allowed.
Web search and web fetch results are environment observations; they must be recorded as events by callers to preserve replay determinism (invariant #9).
ToolConfig is the only configuration surface; pass via InfrastructureModule.createToolExecutor().
buildTools() extension on ToolConfig assembles the full tool list; add new tools there, not in the registry directly.
file_copy copies one existing file to another path ({source, dest}) so static/binary assets never pass through the model's token stream. Same jail, anchor and fileWrite.enabled toggle as file_write; dest is the mutated target (ParamRole.PATH, the only affected path), source is read-only (ParamRole.SOURCE_PATH) and may sit under an operator-granted out-of-workspace path exactly as a file_read may. One regular file per call: no recursion, no globs.
Every path parameter resolves through ToolPath.resolve (core:tools), which expands a leading ~ and anchors relatives on the bound workspace's working dir. Do not re-implement path resolution in a tool.
Filesystem mutation is split by intent: file_write only writes ({path, content}), file_edit edits, and file_delete only deletes ({path}) — deletion is a separately-named capability so a model can never delete by getting a write-mode parameter wrong. file_delete shares file_write's path jail and fileWrite.enabled toggle and carries ToolCapability.FILE_WRITE.
list_dir is shallow by default, but collapses a non-symlink single-child directory chain (bounded depth) to the first branch point and explains that expansion in its output; recursive listings retain normal tree traversal.

Work Guidance

Standard adapter rules apply (see parent AGENTS.md). Network calls (web tools) use Ktor CIO client with withContext(Dispatchers.IO). Shell tool executes OS processes — never suppress CancellationException in process wait loops.

Verification

./gradlew :infrastructure:tools:test --rerun-tasks
./gradlew :infrastructure:tools:filesystem:test --rerun-tasks

Child DOX Index

filesystem/ — filesystem tools implementing core:tools contracts: FileReadTool, FileWriteTool (write-only), FileDeleteTool, FileEditTool, list; no separate AGENTS.md (sub-leaf, covered by this doc)

3.2 KiB Raw Blame History