From 000cb1a0dbe46b8e3ee679ce8d23c8b9ebe22076 Mon Sep 17 00:00:00 2001
From: pku-xht <xht@deepseek.com>
Date: Mon, 17 Aug 2026 17:05:18 +0800
Subject: [PATCH] docs(subagent): clarify unattended review contracts

---
 .../acp-agent/tests/fixtures/subagent-result-diagnostic.ts    | 2 +-
 packages/subagent/subagent-claude-code/src/index.ts           | 4 ++--
 .../subagent/subagent-claude-code/tests/messages-fixture.ts   | 2 +-
 packages/subagent/subagent/src/run-settlement.ts              | 2 +-
 4 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/examples/acp-agent/tests/fixtures/subagent-result-diagnostic.ts b/examples/acp-agent/tests/fixtures/subagent-result-diagnostic.ts
index f381bf3a81..3f9f9ebe55 100644
--- a/examples/acp-agent/tests/fixtures/subagent-result-diagnostic.ts
+++ b/examples/acp-agent/tests/fixtures/subagent-result-diagnostic.ts
@@ -44,7 +44,7 @@ class DiagnosticProvider implements SubagentProvider {
   }
 }
 
-/** Register the fixed snapshot provider under the public product provider name. */
+/** Register the fixed provider behind the public Codex-shaped snapshot tool. */
 export function apply(ctx: Context): void {
   ctx.subagents.registerProvider(new DiagnosticProvider())
 }
diff --git a/packages/subagent/subagent-claude-code/src/index.ts b/packages/subagent/subagent-claude-code/src/index.ts
index 4960e54def..4095ca8f8e 100644
--- a/packages/subagent/subagent-claude-code/src/index.ts
+++ b/packages/subagent/subagent-claude-code/src/index.ts
@@ -29,8 +29,8 @@ import {
 export const name = 'subagent-claude-code'
 export const inject = ['subagents', 'subprocess']
 
-/* jscpd:ignore-start -- sibling product providers intentionally expose the
- * same two deployment-owned fields without adding a shared config owner. */
+/* jscpd:ignore-start -- sibling product providers intentionally expose
+ * overlapping deployment-owned fields without adding a shared config owner. */
 /** Deployment-owned permission, environment, and process-release settings. */
 export interface Config {
   /**
diff --git a/packages/subagent/subagent-claude-code/tests/messages-fixture.ts b/packages/subagent/subagent-claude-code/tests/messages-fixture.ts
index accab2951b..78d2f84176 100644
--- a/packages/subagent/subagent-claude-code/tests/messages-fixture.ts
+++ b/packages/subagent/subagent-claude-code/tests/messages-fixture.ts
@@ -193,7 +193,7 @@ export async function startMessagesFixture(
       ) {
         complete(response, body, behavior.finalText)
       }
-      // A hold deliberately leaves the response pending until client abort.
+      // A hold, or a tool-use without final text, waits for client abort.
     })
   })
   await new Promise<void>((resolve, reject) => {
diff --git a/packages/subagent/subagent/src/run-settlement.ts b/packages/subagent/subagent/src/run-settlement.ts
index d23812ca6a..d17fdaad35 100644
--- a/packages/subagent/subagent/src/run-settlement.ts
+++ b/packages/subagent/subagent/src/run-settlement.ts
@@ -42,7 +42,7 @@ function runOutcome(result: SubagentResult): JobOutcome {
     case 'max-tokens':
     case 'refusal':
       return { status: 'failed', detail: failureDetail(result) }
-    // Merge-extensible reasons remain failures with their raw detail.
+    // Merge-extensible reasons remain failures with provider-authored detail.
     default:
       return { status: 'failed', detail: failureDetail(result) }
   }