From 8597cc2c58ad56d9e1ab6e49f170db88e926b8bb Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 20 Jun 2026 13:52:02 +0800
Subject: [PATCH] docs(tool-bash): state ownership tests as current fact
 (review)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two ownership tests narrated the change's history — "the old design fenced by
Agent object identity", "closing the old XXX(tool-bash-owner-hmr) gap". Reword
to state the current contract (ownership fences by session.header.id; the token
lives on the executor task, so a tool-bash reload preserves it) without
referencing the prior design. Per the repo doc-current-state convention.
---
 packages/tool-bash/tests/tools.spec.ts | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)

diff --git a/packages/tool-bash/tests/tools.spec.ts b/packages/tool-bash/tests/tools.spec.ts
index e94cf108a9..c49410a9b2 100644
--- a/packages/tool-bash/tests/tools.spec.ts
+++ b/packages/tool-bash/tests/tools.spec.ts
@@ -490,10 +490,10 @@ describe('background task ownership (cross-session isolation)', () => {
     expect(text(killByA)).toBe(`killed background task ${id}`)
   })
 
-  it('a DIFFERENT Agent object with the SAME session token may access the task (identity no longer matters)', async () => {
-    // The old design fenced by Agent object identity; the token design fences by
-    // session.header.id. Two distinct Agent objects sharing one session token
-    // (e.g. an agent re-created on the same session) are now the SAME owner.
+  it('a DIFFERENT Agent object with the SAME session token may access the task (ownership is by token, not object identity)', async () => {
+    // Ownership fences by session.header.id, NOT Agent object identity. Two
+    // distinct Agent objects sharing one session token (e.g. an agent re-created
+    // on the same session) are the SAME owner.
     const ctx = await setup()
     const a1 = fakeAgent('sess-shared')
     const a2 = fakeAgent('sess-shared') // distinct object, same token
@@ -546,10 +546,9 @@ describe('background task ownership (cross-session isolation)', () => {
   it('ownership SURVIVES an independent tool-bash HMR reload (token lives on the executor)', async () => {
     // The owner token lives on the TASK inside the executor (dsh-bash fiber), NOT
     // in a tool-bash plugin-local map. So reloading ONLY tool-bash (executor +
-    // task survive) preserves ownership — closing the old XXX(tool-bash-owner-hmr)
-    // gap where the fresh map orphaned pre-reload tasks. This is the regression
-    // guard: an accidental return to a plugin-local map would make B accessible
-    // after reload, and this test would catch it.
+    // task survive) preserves ownership. This is the regression guard: a
+    // plugin-local map would make B accessible after reload, and this test would
+    // catch it.
     const ctx = new Context()
     await ctx.plugin(SystemPrompt)
     await ctx.plugin(ToolRegistry)