From 7a9c2ef4738ce11b8c9bdde4ce65ea14bc022f61 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sun, 19 Jul 2026 14:20:27 +0800
Subject: [PATCH] docs(core): state loop initiator precondition

---
 packages/core/agent-loop/src/loop.ts       | 5 ++++-
 packages/core/agent-loop/src/tool-calls.ts | 4 +++-
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/packages/core/agent-loop/src/loop.ts b/packages/core/agent-loop/src/loop.ts
index 56211fb2e0..4f2f768d89 100644
--- a/packages/core/agent-loop/src/loop.ts
+++ b/packages/core/agent-loop/src/loop.ts
@@ -94,11 +94,14 @@ export interface LoopHandle {
 
 /**
  * Drive queued batches as durable turns until disposal. Plugin failures end the
- * current turn without terminating the driver.
+ * current turn without terminating the driver. The caller establishes the
+ * `ctx.agents.withInitiator()` boundary before entry; package-private helpers
+ * recover that exact Agent from the inherited store.
  * @param ctx - the plugin context the loop reaches its initiating Agent,
  * events (agent/…, session/flush), and services (systemPrompt, llm, tools)
  * through.
  * @param handle - the bridge to the agent's mutable state: status/abort setters plus the disposal and cancel-marker reads.
+ * @throws when no initiating Agent is active.
  */
 export async function runLoop(ctx: Context, handle: LoopHandle): Promise<void> {
   const agent = ctx.agents.requireInitiator()
diff --git a/packages/core/agent-loop/src/tool-calls.ts b/packages/core/agent-loop/src/tool-calls.ts
index 0b9f9ae26b..5bf41c4895 100644
--- a/packages/core/agent-loop/src/tool-calls.ts
+++ b/packages/core/agent-loop/src/tool-calls.ts
@@ -32,8 +32,10 @@ interface Slot {
  * Schedule one assistant step's tool calls by their live concurrency mode.
  * Started calls receive ordered results. Abort drains them and rethrows after
  * accepting their context into the batch FIFO owned by the caller.
+ * The committed step's AgentLoop driver boundary supplies the initiating Agent
+ * that becomes each explicit {@link ToolExecutionInput.agent}.
  *
- * @param ctx - loop context that owns the tool registry.
+ * @param ctx - loop context that owns the tool registry and carries the initiating Agent.
  * @param turn - current turn number.
  * @param step - current step number.
  * @param toolCalls - assistant calls in model order.