From 60418a5779f073bfbfa19191e8ac095afe24edf9 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 30 Jun 2026 20:48:07 +0800
Subject: [PATCH] =?UTF-8?q?docs(events):=20address=20Codex=20round-2=20?=
 =?UTF-8?q?=E2=80=94=20purge=20remaining=20single-waterfall=20references?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Codex's confirmation review confirmed blocker #1 (post-execute mutation) fixed and
the guard real, but found three current-state references the first sweep missed
(they phrase the seam without the literal "tools/execute" string):

- packages/core/tools/src/index.ts: the ToolExecution JSDoc said "flows through the
  execution waterfall" → now names the pre-execute → dispatch → post-execute pipeline.
- packages/core/tools/src/schema.ts: ToolArgsError's JSDoc said "the registry's
  execute waterfall catches it" → "the registry's execution pipeline".
- AGENTS.md repo layout still described tools/ as "tool registry + tools/execute
  waterfall" → "tools/pre-execute/post-execute pipeline".

Doc-comment-only; no behavior change.
---
 AGENTS.md                         | 2 +-
 packages/core/tools/src/index.ts  | 2 +-
 packages/core/tools/src/schema.ts | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index db20d3f7e4..833aeeea45 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -59,7 +59,7 @@ packages/    Harness packages, grouped by role at packages/<group>/<pkg>/.
   core/           product API spine
     session/        event-sourced session log + in-memory store
     system-prompt/  prompt-section + tool-schema assembly registry
-    tools/          tool registry + tools/execute waterfall
+    tools/          tool registry + tools/pre-execute/post-execute pipeline
     agent/          Agent interface, registry, agent/* event vocabulary
     agent-loop/     THE concrete plugin: ReactLoopAgent + the loop driver
     agent-core/     bundle plugin: the providerless/executor-less/UI-less spine
diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts
index a8f881c214..b08403503e 100644
--- a/packages/core/tools/src/index.ts
+++ b/packages/core/tools/src/index.ts
@@ -224,7 +224,7 @@ export interface ToolResult {
   isError: boolean
 }
 
-/** One pending tool call, as it flows through the execution waterfall. */
+/** One pending tool call, as it flows through the execution pipeline (`tools/pre-execute` → dispatch → `tools/post-execute`). */
 export interface ToolExecution {
   callId: CallId
   name: string
diff --git a/packages/core/tools/src/schema.ts b/packages/core/tools/src/schema.ts
index b717eabf9a..05197986bd 100644
--- a/packages/core/tools/src/schema.ts
+++ b/packages/core/tools/src/schema.ts
@@ -182,7 +182,7 @@ export function schemaSpecToJsonSchema(spec: SchemaSpec): JsonSchemaObject {
 /**
  * Thrown by a {@link defineTool} tool when the model-generated arguments don't
  * match the declared {@link SchemaSpec}. Extends {@link HarnessError}
- * (`code: 'INVALID_ARGS'`); the registry's execute waterfall catches it and
+ * (`code: 'INVALID_ARGS'`); the registry's execution pipeline catches it and
  * returns an `isError` ToolExecutionResult carrying the structured error, so
  * the model can self-correct and downstream plugins can route on the code.
  */