@nanmicoder/dsh-agent-teams 0.1.18 → 0.1.20

package/README.md

@@ -22,7 +22,7 @@
 
 `dsh-agent-teams` turns the current DeepSeek Harness session into a captain that can assemble durable sub-agents, split a goal into dependency-aware tasks, and coordinate work through direct messages.
 
-Ask in natural language. The plugin provides the team protocol, 13 coordination tools, persistent state, an automatic shared-task scheduler, and a live Web UI—without requiring a separate workflow engine.
+Ask in natural language. The plugin provides the team protocol, 14 coordination tools, persistent state, an automatic shared-task scheduler, and a live Web UI—without requiring a separate workflow engine.
 
 <p align="center">
   <img src="./assets/ui.png" width="100%" alt="DeepSeek Harness conversation with the AgentTeams live activity panel, members, tasks, dependencies, and reports">
@@ -30,7 +30,7 @@ Ask in natural language. The plugin provides the team protocol, 13 coordination
 
 ## Releases
 
-[v0.1.17](./release-notes/v0.1.17.md) adds automatic light, dark, and system theme support on the npm `latest` channel. Activity panels, conversation cards, and dialog controls follow Harness semantic colors. Recommended host: DeepSeek Harness `0.1.5-rc.1`; the three older supported host targets are retained.
+[v0.1.20](./release-notes/v0.1.20.md) syncs the version references in this document with the npm `latest` channel. It changes no code and no behavior; the packaged artifact is identical to `0.1.19`. The substantive changes since the last documented release are in [v0.1.19](./release-notes/v0.1.19.md): member startup survives a host that disables or renames its delegation tools, automatic repair scope is derived from `requiredFix`, and captains gain `agent_teams_amend_task`. Recommended host: DeepSeek Harness `0.1.5-rc.1`; the three older supported host targets are retained.
 
 ## Why AgentTeams?
 
@@ -49,14 +49,14 @@ The conversation card and activity panel use Harness's official locale service.
 
 ## Install and choose versions
 
-**Recommended pair: DeepSeek Harness `0.1.5-rc.1` + AgentTeams `0.1.17`. Harness remains a prerelease.**
+**Recommended pair: DeepSeek Harness `0.1.5-rc.1` + AgentTeams `0.1.20`. Harness remains a prerelease.**
 
 | Use case | DeepSeek Harness | AgentTeams plugin |
 | --- | --- | --- |
-| **Recommended installation** | **`0.1.5-rc.1`** | **`0.1.17`** |
-| Retaining an older RC | `0.1.2-rc.1` | `0.1.17` |
-| Developer Alpha testing | `0.1.2-alpha.5` | `0.1.17` |
-| Retaining an older Alpha | `0.1.2-alpha.2` | `0.1.17` |
+| **Recommended installation** | **`0.1.5-rc.1`** | **`0.1.20`** |
+| Retaining an older RC | `0.1.2-rc.1` | `0.1.20` |
+| Developer Alpha testing | `0.1.2-alpha.5` | `0.1.20` |
+| Retaining an older Alpha | `0.1.2-alpha.2` | `0.1.20` |
 
 ### 1. Install DeepSeek Harness
 
@@ -72,12 +72,12 @@ Skip this if you already run this version. Alpha is opt-in: select an exact Alph
 Install into the `web` profile. Replace the profile name if needed:
 
 ```sh
-dsh plugin --profile web add --save-exact @nanmicoder/dsh-agent-teams@0.1.17
+dsh plugin --profile web add --save-exact @nanmicoder/dsh-agent-teams@0.1.20
 ```
 
 **After installation, stop and restart Harness for that profile, then refresh the browser.**
 
-The default npm `latest` tag points to `0.1.17`, so `dsh plugin --profile web add @nanmicoder/dsh-agent-teams` installs this version on a fresh profile. Use the exact-version command above to pin it. The recommended Harness version is `0.1.5-rc.1`; installing the plugin does not upgrade the host. See the [source installation guide](./docs/maintenance-workflow.md) and [release verification](./docs/releases/v0.1.17/README.md).
+The default npm `latest` tag points to `0.1.20`, so `dsh plugin --profile web add @nanmicoder/dsh-agent-teams` installs this version on a fresh profile. Use the exact-version command above to pin it. The recommended Harness version is `0.1.5-rc.1`; installing the plugin does not upgrade the host. See the [source installation guide](./docs/maintenance-workflow.md) and [release verification](./docs/releases/v0.1.19/README.md).
 
 > Desktop users must check the app's embedded Harness core; upgrading the global CLI does not upgrade it. For older `0.1.0-*` / `0.1.1-*` or unlisted hosts, keep a working pair and follow the [older-version and diagnostic guide](./docs/maintenance-workflow.md).
 
@@ -100,7 +100,7 @@ Team state is stored under `<workspace>/.agent-teams/`; the Web panel reads that
 
 Member creation is zero-interaction by default: a member on the captain's current LLM route snapshots that provider, model, and reasoning effort, while a member on a requested alternative route snapshots the target model's default effort; later continuations restore the resolved snapshot. Only an explicit heterogeneous-team request (for example, “backend on provider A/model X, frontend on provider B/model Y”) supplies a member-specific `provider` + `model`; there is no per-member model or reasoning prompt.
 
-Captain sessions keep the concise core protocol and the original 13 native team tools from their first request. All business tools are directly available; no loading tool or extra activation call is needed. Configured profiles retain their bounded directory in the fixed system prompt. Creating, approving, continuing or ending a team does not rewrite the system prompt or tool schemas. Core rules remain available after history compaction or discarded code-mode tool results. Members receive four team tools, fixed member instructions, and their ordinary coding/research tools. Web approval wakes the captain with a control message; later member reports wake it again. See the [fixed protocol and benchmark contract](./docs/progressive-loading.md).
+Captain sessions keep the concise core protocol and the original 14 native team tools from their first request. All business tools are directly available; no loading tool or extra activation call is needed. Configured profiles retain their bounded directory in the fixed system prompt. Creating, approving, continuing or ending a team does not rewrite the system prompt or tool schemas. Core rules remain available after history compaction or discarded code-mode tool results. Members receive four team tools, fixed member instructions, and their ordinary coding/research tools. Web approval wakes the captain with a control message; later member reports wake it again. See the [fixed protocol and benchmark contract](./docs/progressive-loading.md).
 
 ## Slash command
 

package/README_ZH.md

@@ -22,7 +22,7 @@
 
 `dsh-agent-teams` 让当前 DeepSeek Harness 会话成为队长：创建可续聊的子 Agent、把目标拆成有依赖的任务，并通过直达消息协调成员工作。
 
-你只需用自然语言提出目标。插件会提供精简的固定团队协议、13 个业务工具、持久化状态、自动共享任务调度和实时 Web UI，不需要额外的 Workflow 引擎。
+你只需用自然语言提出目标。插件会提供精简的固定团队协议、14 个业务工具、持久化状态、自动共享任务调度和实时 Web UI，不需要额外的 Workflow 引擎。
 
 <p align="center">
   <img src="./assets/ui.png" width="100%" alt="DeepSeek Harness 对话与 AgentTeams 实时活动面板，展示成员、任务依赖和回报">
@@ -30,7 +30,7 @@
 
 ## 版本更新
 
-[v0.1.17](./release-notes/v0.1.17.md) 新增浅色、深色和跟随系统的主题适配，作为 npm `latest` 默认安装版本。活动面板、对话卡片与弹窗控件自动继承宿主颜色。推荐 DeepSeek Harness `0.1.5-rc.1`，保留三个旧宿主目标。
+[v0.1.20](./release-notes/v0.1.20.md) 仅把本文档中的版本引用同步到 npm `latest`，不含任何代码或行为变更，打包产物与 `0.1.19` 完全一致。上一份有实质变更的版本是 [v0.1.19](./release-notes/v0.1.19.md)：宿主禁用或改名委派工具时成员仍能正常启动；自动修复范围改为从 `requiredFix` 推导；新增队长专用的 `agent_teams_amend_task`。推荐 DeepSeek Harness `0.1.5-rc.1`，保留三个旧宿主目标。
 
 ## 为什么需要 AgentTeams？
 
@@ -48,14 +48,14 @@
 
 ## 安装与版本选择
 
-**推荐组合：DeepSeek Harness `0.1.5-rc.1` + AgentTeams `0.1.17`。Harness 仍为预发布版本。**
+**推荐组合：DeepSeek Harness `0.1.5-rc.1` + AgentTeams `0.1.20`。Harness 仍为预发布版本。**
 
 | 使用场景 | DeepSeek Harness | AgentTeams 插件 |
 | --- | --- | --- |
-| **推荐安装** | **`0.1.5-rc.1`** | **`0.1.17`** |
-| 保留旧 RC | `0.1.2-rc.1` | `0.1.17` |
-| 开发者测试 Alpha | `0.1.2-alpha.5` | `0.1.17` |
-| 保留旧 Alpha | `0.1.2-alpha.2` | `0.1.17` |
+| **推荐安装** | **`0.1.5-rc.1`** | **`0.1.20`** |
+| 保留旧 RC | `0.1.2-rc.1` | `0.1.20` |
+| 开发者测试 Alpha | `0.1.2-alpha.5` | `0.1.20` |
+| 保留旧 Alpha | `0.1.2-alpha.2` | `0.1.20` |
 
 ### 1. 安装 DeepSeek Harness
 
@@ -71,12 +71,12 @@ dsh --version
 安装到 `web` profile；使用其他 profile 时替换名称：
 
 ```sh
-dsh plugin --profile web add --save-exact @nanmicoder/dsh-agent-teams@0.1.17
+dsh plugin --profile web add --save-exact @nanmicoder/dsh-agent-teams@0.1.20
 ```
 
 **安装后，停止并重新启动该 profile 的 Harness 进程，再刷新浏览器。**
 
-npm 默认标签 `latest` 现指向 `0.1.17`，因此新 profile 使用 `dsh plugin --profile web add @nanmicoder/dsh-agent-teams` 即可安装本版；需要锁定版本时使用上面的精确版本命令。推荐宿主为 Harness `0.1.5-rc.1`，安装插件不会自动升级宿主。源码安装见[维护指南](./docs/maintenance-workflow.md)，验证范围见[本版验收记录](./docs/releases/v0.1.17/README.md)。
+npm 默认标签 `latest` 现指向 `0.1.20`，因此新 profile 使用 `dsh plugin --profile web add @nanmicoder/dsh-agent-teams` 即可安装本版；需要锁定版本时使用上面的精确版本命令。推荐宿主为 Harness `0.1.5-rc.1`，安装插件不会自动升级宿主。源码安装见[维护指南](./docs/maintenance-workflow.md)，验证范围见[本版验收记录](./docs/releases/v0.1.19/README.md)。
 
 > Desktop 用户需核对应用内置的 Harness 核心；全局 CLI 升级不会升级桌面内核。旧 `0.1.0-*` / `0.1.1-*` 或其他未列出的宿主，请先保留已工作的组合，参考[旧版本与诊断指引](./docs/maintenance-workflow.md)。
 
@@ -86,7 +86,7 @@ npm 默认标签 `latest` 现指向 `0.1.17`，因此新 profile 使用 `dsh plu
 
 > 使用 AgentTeams 审查 v0.5.3 之后的提交，分别从性能、安全和产品角度分工，最后输出一份汇总报告。
 
-队长会话从第一轮起保留精简的固定核心协议和原有 13 个业务工具，直接调用，无需额外的加载工具或激活调用。已配置模板的精简目录固定保留。创建、批准、继续或结束团队都不会改写系统提示词和工具 schema，会话压缩或代码模式丢弃工具结果也不会丢失核心规则。成员保留四个团队工具、固定成员说明及普通编程/研究工具。Web 批准后会通知并唤醒队长，后续成员报告会再次唤醒它，无需忙轮询。详见[固定协议与 benchmark 标准](./docs/progressive-loading.md)。
+队长会话从第一轮起保留精简的固定核心协议和原有 14 个业务工具，直接调用，无需额外的加载工具或激活调用。已配置模板的精简目录固定保留。创建、批准、继续或结束团队都不会改写系统提示词和工具 schema，会话压缩或代码模式丢弃工具结果也不会丢失核心规则。成员保留四个团队工具、固定成员说明及普通编程/研究工具。Web 批准后会通知并唤醒队长，后续成员报告会再次唤醒它，无需忙轮询。详见[固定协议与 benchmark 标准](./docs/progressive-loading.md)。
 
 ## 工作方式
 

package/lib/harness-compat.js

@@ -1,5 +1,6 @@
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { SubagentError } from '@deepseek-ai/dsh-subagent';
+import { CAPTAIN_TOOL_NAMES } from "./tool-names.js";
 /**
  * Exact protocol exported by dsh-subagent/internal in Alpha.5 and rc.1.
  * That subpath does not exist in Alpha.2, so importing it statically prevents
@@ -199,3 +200,86 @@ export function guardSubagentDelivery(ctx, isRetired) {
         };
     }, 'agent-teams: retired member guard');
 }
+/**
+ * Names the host's `tools.restrict()` would admit for this agent's layer
+ * chain, or undefined when the host does not expose its registry view.
+ * restrict() rejects unknown names with a hard error, so the spawn path must
+ * check entries against this view before forwarding them. Source:
+ * dsh-tools view()/restrict() in 0.1.5-rc.1; older Harness generations lack
+ * the surface and keep the verbatim list.
+ */
+export function restrictableToolNames(agent) {
+    const tools = agent?.ctx?.tools;
+    if (typeof tools?.view !== 'function')
+        return undefined;
+    try {
+        const names = tools.view.call(tools, agent.ctx)?.restrictableNames;
+        return names instanceof Set ? names : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Member `toolFilter` for one spawn. Captain-only names are registered by
+ * this plugin itself and always resolvable; the depth-related entries name
+ * HOST tools and are only known under some compositions, so they must be
+ * resolved against the running host's registry: the delegation tool name is
+ * host configuration (dsh-tool-subagent `toolName`, default `subagent`,
+ * renamed per composition, e.g. `subagent_fork` in web-style profiles), and
+ * forwarding a name the host dropped aborts every member spawn (#163, #164).
+ * Depth enforcement itself does not depend on these names —
+ * installMemberDelegationGuard bounds descendant creation by parent chain.
+ */
+export function memberToolFilter(maxDepth, knownTools) {
+    const depthDeny = maxDepth === 0 ? ['subagent', 'send_message'] : [];
+    return {
+        deny: [
+            ...CAPTAIN_TOOL_NAMES,
+            ...(knownTools === undefined ? depthDeny : depthDeny.filter(name => knownTools.has(name))),
+        ],
+    };
+}
+/**
+ * Names a `tools.restrict()` rejection reported as unknown, or an empty list
+ * for every other failure. The host names the offenders verbatim
+ * (`tools.restrict() names unknown global tool "x"; known global tools: …`);
+ * only that report may relax a filter (#164, #166).
+ */
+function unknownToolNames(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!message.includes('unknown global tool'))
+        return [];
+    return [...message.matchAll(/"([^"]+)"/g)].map(match => match[1]);
+}
+/**
+ * Start one member, dropping any filter name the host reports as unknown and
+ * retrying.
+ *
+ * Resolving the filter against the registry view ({@link memberToolFilter})
+ * only covers hosts that expose one. A rejected filter still leaves the member
+ * without a session for the lifetime of the team, so the start must survive the
+ * cases that resolution cannot see — no registry view, a name that is known but
+ * not restrictable, a composition that mounted differently than expected. The
+ * host names the offenders in its rejection, so they are removed and the start
+ * retried; the retry only runs while the deny list strictly shrinks, and any
+ * failure that is not an unknown-name report propagates untouched.
+ * @param start - performs one start attempt for the given `toolFilter`.
+ * @param filter - the filter to attempt first.
+ * @returns the started member.
+ */
+export async function startMemberWithLenientFilter(start, filter) {
+    let deny = [...filter.deny];
+    for (;;) {
+        try {
+            return await start({ deny });
+        }
+        catch (error) {
+            const unknown = unknownToolNames(error);
+            const remaining = deny.filter(name => !unknown.includes(name));
+            if (unknown.length === 0 || remaining.length === deny.length)
+                throw error;
+            deny = remaining;
+        }
+    }
+}

package/lib/index.js

@@ -94,7 +94,7 @@ export function usageSectionText(toolNames, profilesText = '') {
 4. Respect Web approve/return/discard control messages. On return, ask what to change before editing; after the answer, use one atomic agent_teams_edit_plan batch (edit downstream references before removals), summarize and await review again. Never inspect or edit .agent-teams state files or plugin source code to revise plans. Discard does not authorize a replacement.
 5. The scheduler dispatches ready tasks after approval. Delegate; do not duplicate slow work or send messages merely to start a stage. Handle reports/user work, then yield when waiting is all that remains: reports wake you automatically. Use status after a delivery or user request, never busy-poll or wait for unassigned members.
 6. Tasks carry attempt_id capabilities. Use the current attempt_id; stale means ownership changed. Pause members only on explicit request; later guidance via send_message continues that same attempt. Retry, transfer or take over through reassign_task first; it revokes the old attempt and waits for quiescence. Prefer a member. Captain implementation/review takeover requires a user request. Every takeover is one ready task at a time, finished in this turn; never yield with captain-owned work open.
-7. In a running team, correct never-started pending tasks with edit_plan update_task; preserve dependency and ownership contracts instead of cancelling and recreating the graph. A captain can cancel a never-started pending task directly. Active attempts still require reassign_task. Quality kinds (requirements, implementation, verification, review, repair, integration) require objective + acceptance; implementation/repair also require inScope + verify. Derive paths/commands from the workspace/profile, never assume src/ or pnpm test. Review/requirements complete only with verdict=pass; needs_revision/reject fail with findings. Never approve your own implementation or ask for a deliberate failure.
+7. In a running team, correct never-started pending tasks with edit_plan update_task; preserve dependency and ownership contracts instead of cancelling and recreating the graph. A captain can cancel a never-started pending task directly. Active attempts still require reassign_task. Quality kinds (requirements, implementation, verification, review, repair, integration) require objective + acceptance; implementation/repair also require inScope + verify. Derive paths/commands from the workspace/profile, never assume src/ or pnpm test. Review/requirements complete only with verdict=pass; needs_revision/reject fail with findings. Never approve your own implementation or ask for a deliberate failure. When a quality contract itself is wrong (a verify command that cannot pass, an inScope that forbids the file the objective requires), fix it with agent_teams_amend_task — captain-only, non-terminal tasks only, frozen after a passing review, and every amendment is recorded in the task's revisions ledger — instead of letting the worker dead-lock or game the gate.
 8. When full quality mode is requested: requirements → implementation → verification → review → integration. Plan the entire DAG while staged, including implementation before requirements finishes and integration depending on review round 1. Failed review automatically adds repair + next review and rewires pending downstream gates. Do not recreate this loop, omit integration or depend on a failed task. Review acceptance judges the latest implementation. Do not put smoke-test scripts into task instructions.
 9. Halted means the user stopped work (including the captain turn). Resume only on a later explicit user request with a reason, via agent_teams_resume or create_task({resume:true,resumeReason}); creating tasks alone never resumes. Escalated means the review loop hit its limit, not a halt. Deployment requires explicit user confirmation.
 10. Wait for all required tasks to be terminal and members idle/ready, present results, then delete/archive unless the user wants to continue. Never discard unfinished work without authorization.

package/lib/members.js

@@ -16,16 +16,13 @@ import { installModelSelection } from '@deepseek-ai/dsh-agent';
 import { foldSubagentDescriptor } from '@deepseek-ai/dsh-subagent';
 import { createUserMessage, LlmError, ReasoningEffortId } from '@deepseek-ai/dsh-llm';
 import { join } from 'node:path';
-import { guardSubagentDelivery, installContinuableMemberSetup, queueMemberPrompt, steerMemberPrompt, sessionOwnEvents } from "./harness-compat.js";
+import { guardSubagentDelivery, installContinuableMemberSetup, memberToolFilter, queueMemberPrompt, restrictableToolNames, startMemberWithLenientFilter, steerMemberPrompt, sessionOwnEvents } from "./harness-compat.js";
 import { markMailboxDelivered, appendMailbox, CAPTAIN_KEY, createMessage, readRetiredMemberIds, readTeamSync, readTeam, releaseMailboxDelivery, withTeamLock, writeTeam } from "./state.js";
 import { mailboxPrompt } from "./mailbox.js";
 import { appendTeamEvent, captainSessionOf } from "./events.js";
 import { TERMINAL_TASK_STATUSES } from "./types.js";
-import { CAPTAIN_TOOL_NAMES } from "./tool-names.js";
 /** Persona snapshot of a profile protocol; the full text lives on team.json. */
 export const PERSONA_PROTOCOL_MAX_CHARS = 400;
-/** Captain-only AgentTeams tools hidden from newly spawned members. */
-const MEMBER_DENIED_TOOLS = CAPTAIN_TOOL_NAMES;
 /**
  * Restore the SessionId brand on a value that round-tripped through the
  * durable team file. The brand is erased by JSON serialization; the value
@@ -514,14 +511,19 @@ export async function spawnMember(ctx, config, selections, llmSelection, captain
         throw new Error(`agent-teams: provider "${config.provider}" cannot restrict captain-only tools for members`);
     }
     const label = `${MEMBER_LABEL_PREFIX}${team.id}:${member.name}`;
-    const start = await selections.withPending(captain.id, label, llmSelection, () => (ctx.subagents.startContinuable({
+    const start = await selections.withPending(captain.id, label, llmSelection, () => (startMemberWithLenientFilter(toolFilter => ctx.subagents.startContinuable({
         provider: config.provider,
         label,
         request: {
             prompt: [{ type: 'text', text: initialPrompt ?? memberWelcome(team, member.name) }],
             parent: captain,
             persona: memberPersona(team, member, stateDir, config.executionPrompt),
-            toolFilter: { deny: [...MEMBER_DENIED_TOOLS, ...(config.maxDepth === 0 ? ['subagent', 'send_message'] : [])] },
+            // Depth deny entries name host tools; resolve them against the
+            // running host's registry so a renamed delegation tool cannot abort
+            // the spawn (see memberToolFilter). Depth is still enforced by the
+            // parent-chain guard installed at plugin mount. A filter the host
+            // still rejects is retried without the names it reported.
+            toolFilter,
             agentOptions: {
                 provider: llmSelection.provider,
                 model: llmSelection.model,
@@ -534,7 +536,7 @@ export async function spawnMember(ctx, config, selections, llmSelection, captain
             // the configured member-relative descendant budget instead.
         },
         signal,
-    })));
+    }), memberToolFilter(config.maxDepth, restrictableToolNames(captain)))));
     member.id = start.childId;
 }
 /**

package/lib/quality-gates.js

@@ -3,7 +3,7 @@
  * coverage, and resume. Tools and persistence call these; they do not I/O.
  * @module dsh-agent-teams/quality-gates
  */
-import { FINDING_SEVERITIES, REVIEW_VERDICTS, TASK_KINDS, } from "./types.js";
+import { FINDING_SEVERITIES, REVIEW_VERDICTS, TASK_KINDS, TERMINAL_TASK_STATUSES, } from "./types.js";
 const QUALITY_KINDS = [
     'requirements',
     'implementation',
@@ -405,6 +405,140 @@ function unresolvedFindings(task) {
 function findingKey(ids) {
     return [...ids].sort().join(',');
 }
+/**
+ * Path-like tokens worth considering as repair-scope candidates. Two shapes:
+ * slash paths (`src/parser.ts`, `docs/guide.md`) and bare filenames with a
+ * known code/doc extension (`README.md`, `wc.js`). An optional `:line`
+ * suffix is tolerated and stripped. The extension allowlist keeps version
+ * tokens (`v0.1.17`), hex hashes, and prose out of the derived scope.
+ */
+const REPAIR_SCOPE_PATH_PATTERN = /(?:[A-Za-z0-9_.\-]+(?:\/[A-Za-z0-9_.\-]+)+|[\w.\-]+\.(?:tsx?|jsx?|mjs|cjs|json|md|txt|ya?ml|py|rs|go|java|html?|css|scss|sh|ps1|toml|xml|sql))(?::\d+)?/gu;
+const REPAIR_SCOPE_LINE_SUFFIX = /:\d+$/;
+/**
+ * Derive the repair round's inScope from the findings that caused it.
+ *
+ * `finding.file` records where the problem was OBSERVED, but the fix often
+ * targets a different file named in `requiredFix` (docs vs sample data,
+ * config vs code). Deriving the scope from both keeps the auto-generated
+ * repair contract satisfiable; deriving from `file` alone can produce a
+ * contract where the acceptance ("edit README.md") names a path the scope
+ * forbids, so no honest completion exists and the repair dead-locks.
+ *
+ * Absolute and otherwise illegal paths are dropped (they can never match
+ * workspace-relative scope patterns anyway); when nothing legal remains,
+ * the source task's own inScope is kept as the fallback. Over-inclusion is
+ * accepted: inScope is an audit upper bound, and the requiredFix text still
+ * tells the implementer what to touch.
+ *
+ * Keep all derived paths until the generator resolves inherited exclusions;
+ * filtering first would silently discard a required fix target.
+ */
+export function repairScopeFromFindings(findings, fallback) {
+    const derived = [];
+    const push = (raw) => {
+        const normalized = normalizeWorkspacePath(raw.replace(REPAIR_SCOPE_LINE_SUFFIX, ''));
+        if (normalized === undefined || derived.includes(normalized))
+            return;
+        derived.push(normalized);
+    };
+    for (const finding of findings) {
+        if (nonemptyString(finding.file))
+            push(finding.file);
+        for (const match of finding.requiredFix.matchAll(REPAIR_SCOPE_PATH_PATTERN))
+            push(match[0]);
+    }
+    return derived.length > 0 ? derived : fallback === undefined ? undefined : [...new Set(fallback)];
+}
+const AMENDABLE_CONTRACT_FIELDS = ['objective', 'acceptance', 'verify', 'inScope', 'outOfScope'];
+/**
+ * Controlled contract amendment (the pure rule; tooling keeps it
+ * captain-only). When a quality contract is wrong — a verify command that
+ * cannot pass, an inScope that forbids the file the objective names — the
+ * worker has no honest completion and either dead-locks or games the gate.
+ * Instead the captain may fix the contract mid-flight: every amendment is
+ * recorded on the task as a {@link TaskRevision} (previous values + reason),
+ * and once a review/requirements task has passed judgment on this task the
+ * contract is frozen. Amendments replace whole fields (lists are full
+ * replacements, not deltas); the implementer re-reads the amended contract
+ * before its next quality gate. Completion gates need no special casing:
+ * they read the task's current fields, so they naturally evaluate the
+ * amended contract.
+ */
+export function amendTaskContract(team, task, input, by, reason) {
+    if (!nonemptyString(by))
+        return { ok: false, error: 'contract amendment requires a non-empty author identity' };
+    if (!nonemptyString(reason))
+        return { ok: false, error: 'contract amendment requires a non-empty reason' };
+    if (TERMINAL_TASK_STATUSES.includes(task.status)) {
+        return { ok: false, error: `task ${task.id} is ${task.status}; terminal contracts are immutable` };
+    }
+    if (taskKindOf(task) === 'work') {
+        return { ok: false, error: `task ${task.id} has kind=work and no contract to amend` };
+    }
+    if (!AMENDABLE_CONTRACT_FIELDS.some((field) => input[field] !== undefined)) {
+        return { ok: false, error: `amendment requires at least one of: ${AMENDABLE_CONTRACT_FIELDS.join(', ')}` };
+    }
+    const next = {};
+    const previous = {};
+    if (input.objective !== undefined) {
+        if (!nonemptyString(input.objective)) {
+            return { ok: false, error: 'amended objective must be a non-empty string' };
+        }
+        next['objective'] = input.objective;
+        previous['objective'] = task.objective;
+    }
+    for (const field of ['acceptance', 'verify']) {
+        const value = input[field];
+        if (value === undefined)
+            continue;
+        if (!nonemptyStringList(value)) {
+            return { ok: false, error: `amended ${field} must be a non-empty list of non-empty strings` };
+        }
+        next[field] = value;
+        previous[field] = task[field];
+    }
+    for (const field of ['inScope', 'outOfScope']) {
+        const value = input[field];
+        if (value === undefined)
+            continue;
+        if (!nonemptyStringList(value)) {
+            return { ok: false, error: `amended ${field} must be a non-empty list of non-empty strings` };
+        }
+        for (const entry of value) {
+            if (normalizeWorkspacePath(entry) === undefined) {
+                return {
+                    ok: false,
+                    error: `amended ${field} entry "${entry}" is not a workspace-relative path (absolute paths and ".." can never match scope patterns)`,
+                };
+            }
+        }
+        next[field] = value;
+        previous[field] = task[field];
+    }
+    const reviewPassed = team.tasks.some((item) => ((taskKindOf(item) === 'review' || taskKindOf(item) === 'requirements')
+        && item.reviewedTaskId === task.id
+        && item.verdict === 'pass'));
+    if (reviewPassed) {
+        return { ok: false, error: `task ${task.id} already passed review; its contract is frozen` };
+    }
+    const revision = {
+        at: Date.now(),
+        by,
+        reason,
+        fields: Object.keys(next),
+        previous,
+    };
+    return {
+        ok: true,
+        revision,
+        task: {
+            ...task,
+            ...next,
+            revisions: [...(task.revisions ?? []), revision],
+            updatedAt: Date.now(),
+        },
+    };
+}
 const CAPTAIN_ASSIGNEE = 'captain';
 const OPEN_FOLLOW_UP_STATUSES = ['pending', 'claimed', 'in_progress'];
 function schedulableAssignee(preferred, team, forbidden) {
@@ -430,6 +564,13 @@ function hasOpenFollowUp(team, sourceTaskId, findingIds) {
         && findingKey(item.sourceFindingIds ?? []) === key
         && OPEN_FOLLOW_UP_STATUSES.includes(item.status)));
 }
+/** Drop previous-round exclusions that intersect this generated repair's scope. */
+function withoutScopeConflicts(outOfScope, inScope) {
+    if (outOfScope === undefined)
+        return undefined;
+    const conflicting = new Set(inScopeOverlap(outOfScope, inScope ?? []));
+    return outOfScope.filter((pattern) => !conflicting.has(pattern));
+}
 export function planQualityFollowUp(team, closed) {
     const empty = { created: [], tasks: [] };
     const kind = taskKindOf(closed);
@@ -468,7 +609,9 @@ export function planQualityFollowUp(team, closed) {
     if (countRepairAttempts(team, sourceId, findingIds) >= policy.maxRepairAttempts) {
         return { ...empty, escalated: true, status: 'escalated' };
     }
-    const files = findings.map((finding) => finding.file).filter((file) => nonemptyString(file));
+    // inScope is derived from the findings below: the observed file plus any
+    // workspace-relative paths referenced by the requiredFix instructions.
+    const repairScope = repairScopeFromFindings(findings, source?.inScope);
     const implementer = schedulableAssignee(source?.assignee, team);
     const repair = {
         id: `repair-round-${nextRound}`,
@@ -478,8 +621,8 @@ export function planQualityFollowUp(team, closed) {
         dependencies: [sourceId],
         round: nextRound,
         objective: source?.objective ?? closed.objective ?? `Fix findings from ${sourceId}`,
-        inScope: files.length > 0 ? files : source?.inScope,
-        outOfScope: source?.outOfScope,
+        inScope: repairScope,
+        outOfScope: withoutScopeConflicts(source?.outOfScope, repairScope),
         verify: source?.verify,
         acceptance: findings.map((finding) => finding.requiredFix),
         sourceTaskId: sourceId,
@@ -615,6 +758,15 @@ export function isCommandResult(value) {
         && (value['exitCode'] === undefined || (Number.isSafeInteger(value['exitCode'])))
         && (value['evidence'] === undefined || typeof value['evidence'] === 'string');
 }
+export function isTaskRevision(value) {
+    if (!isRecord(value))
+        return false;
+    return Number.isSafeInteger(value['at'])
+        && nonemptyString(value['by'])
+        && nonemptyString(value['reason'])
+        && nonemptyStringList(value['fields'])
+        && isRecord(value['previous']);
+}
 // Optional fields whose persisted values must be non-empty when present
 // (mirrors the checks in hasValidQualityTaskFields). Some models materialize
 // optional tool parameters as "" instead of omitting them (e.g. GPT-5.6
@@ -698,6 +850,10 @@ export function hasValidQualityTaskFields(value) {
         if (!Array.isArray(value['commandsRun']) || !value['commandsRun'].every(isCommandResult))
             return false;
     }
+    if (value['revisions'] !== undefined) {
+        if (!Array.isArray(value['revisions']) || !value['revisions'].every(isTaskRevision))
+            return false;
+    }
     return true;
 }
 function isRecord(value) {

package/lib/state.js

@@ -18,7 +18,7 @@ import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promise
 import { join } from 'node:path';
 import { TERMINAL_TASK_STATUSES } from "./types.js";
 import { hasValidQualityTaskFields, isReviewPolicy, normalizeBlankOptionalTaskFields } from "./quality-gates.js";
-export { buildCoverageMatrix, canDeclareDelivery, classifyChangedPath, collectChangedPaths, defaultQualityDeliveryGraph, describeQualityLoop, evaluateQualityCompletion, hasValidQualityTaskFields, isQualityKind, normalizeBlankOptionalTaskFields, pathMatchesScope, planQualityFollowUp, qualityPlanningPrompt, resumeTeamState, sanitizeReviewAcceptance, sanitizeReviewObjective, taskKindOf, validateCreateTask, } from "./quality-gates.js";
+export { amendTaskContract, buildCoverageMatrix, canDeclareDelivery, classifyChangedPath, collectChangedPaths, defaultQualityDeliveryGraph, describeQualityLoop, evaluateQualityCompletion, hasValidQualityTaskFields, isQualityKind, isTaskRevision, normalizeBlankOptionalTaskFields, pathMatchesScope, planQualityFollowUp, qualityPlanningPrompt, resumeTeamState, sanitizeReviewAcceptance, sanitizeReviewObjective, taskKindOf, validateCreateTask, } from "./quality-gates.js";
 /** Mailbox key of the captain. */
 export const CAPTAIN_KEY = 'captain';
 /** A crashed live-delivery attempt becomes retryable after this interval. */
@@ -612,6 +612,7 @@ function isTeamMember(value) {
         && isOptionalString(value['reasoningEffort'])
         && isOptionalString(value['activeProvider'])
         && isOptionalString(value['activeModel'])
+        && isOptionalString(value['spawnError'])
         && (value['executionPrompt'] === undefined || typeof value['executionPrompt'] === 'string')
         && (value['fallback'] === undefined || (isRecord(value['fallback']) && typeof value['fallback']['provider'] === 'string' && typeof value['fallback']['model'] === 'string'))
         && (value['fallbackActive'] === undefined || typeof value['fallbackActive'] === 'boolean')

package/lib/tool-names.js

@@ -3,6 +3,7 @@ export const TEAM_TOOL_NAMES = [
     'agent_teams_create', 'agent_teams_approve', 'agent_teams_edit_plan',
     'agent_teams_add_member', 'agent_teams_remove_member', 'agent_teams_create_task',
     'agent_teams_reassign_task', 'agent_teams_claim_task', 'agent_teams_update_task',
+    'agent_teams_amend_task',
     'agent_teams_send_message', 'agent_teams_status', 'agent_teams_resume', 'agent_teams_delete',
 ];
 export const MEMBER_TOOL_NAMES = [

package/lib/tools.js

@@ -12,7 +12,7 @@ import { createUserMessage } from '@deepseek-ai/dsh-llm';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { join } from 'node:path';
 import { appendTeamEvent, captainSessionOf } from "./events.js";
-import { acknowledgeMailbox, markMailboxDelivered, discardMailboxMessages, appendMailbox, archiveTeamDir, beginTaskAttempt, CAPTAIN_KEY, createMessage, createTeamDir, findTeamByCaptain, findTeamByParticipant, cancelUnfinishedTask, invalidateTaskAttempt, readUnreadMailbox, recordRetiredMemberIds, releaseMailboxDelivery, readTeam, sanitizeKey, transitionError, unsatisfiedDependencies, withTeamLock, writeTeam, validateCreateTask, evaluateQualityCompletion, planQualityFollowUp, resumeTeamState, buildCoverageMatrix, canDeclareDelivery, describeQualityLoop, sanitizeReviewAcceptance, sanitizeReviewObjective, normalizeBlankOptionalTaskFields, taskKindOf, } from "./state.js";
+import { amendTaskContract, acknowledgeMailbox, markMailboxDelivered, discardMailboxMessages, appendMailbox, archiveTeamDir, beginTaskAttempt, CAPTAIN_KEY, createMessage, createTeamDir, findTeamByCaptain, findTeamByParticipant, cancelUnfinishedTask, invalidateTaskAttempt, readUnreadMailbox, recordRetiredMemberIds, releaseMailboxDelivery, readTeam, sanitizeKey, transitionError, unsatisfiedDependencies, withTeamLock, writeTeam, validateCreateTask, evaluateQualityCompletion, planQualityFollowUp, resumeTeamState, buildCoverageMatrix, canDeclareDelivery, describeQualityLoop, sanitizeReviewAcceptance, sanitizeReviewObjective, normalizeBlankOptionalTaskFields, taskKindOf, } from "./state.js";
 import { deliverToMember, installRetiredMemberGuard, installMemberSelectionRuntime, installMemberDelegationGuard, memberActivity, resolveMemberLlmSelection, spawnMember, steerCaptainReport, validateMemberLlmSelections, } from "./members.js";
 import { TERMINAL_TASK_STATUSES } from "./types.js";
 import { collectCompletedDependencyOutputs, formatDependencyOutputs, installTeamScheduler } from "./scheduler.js";
@@ -286,6 +286,24 @@ export function registerAgentTeamsTools(ctx, config) {
     const memberSelections = installMemberSelectionRuntime(ctx, config.stateDir, (workspace, teamId, memberName) => (scheduler.kickMember(workspace, teamId, memberName)));
     async function dispatchMember(captain, teamId, memberName, text, signal, mode, attemptId) {
         const root = stateRootOf(workspaceOf(captain), config);
+        // Record why a member never started. The scheduler treats a failed dispatch as
+        // "not now" and retries, so without this the captain only ever sees an
+        // unexplained `unspawned` member and no diagnostic reaches any surface.
+        const recordSpawnError = async (reason) => {
+            try {
+                await withTeamLock(teamLockKey(root, teamId), async () => {
+                    const fresh = await requireFreshCaptainTeam(root, teamId, captain.id);
+                    const failed = fresh.members.find(item => item.name === memberName && item.status !== 'removed');
+                    if (failed === undefined || failed.id !== '')
+                        return;
+                    failed.spawnError = reason;
+                    await writeTeam(root, fresh);
+                });
+            }
+            catch (error) {
+                ctx.logger.warn(`agent-teams: could not record the member start failure for ${memberName}: ${String(error)}`);
+            }
+        };
         let orphan;
         try {
             return await withTeamLock(teamLockKey(root, teamId), async () => {
@@ -304,6 +322,7 @@ export function registerAgentTeamsTools(ctx, config) {
                 }, signal);
                 await spawnMember(ctx, memberRuntime(config), memberSelections, selection, captain, team, member, config.stateDir, signal, text);
                 orphan = { ...member };
+                delete member.spawnError;
                 await writeTeam(root, team);
                 orphan = undefined;
                 return true;
@@ -314,7 +333,12 @@ export function registerAgentTeamsTools(ctx, config) {
                 await recordRetiredMemberIds(root, [orphan.id]);
                 await stopTeamMemberActivations(ctx, captain, [orphan]);
             }
+            // The stack carries the failing frame; the message alone rarely does.
+            let reason = String(error);
+            if (error instanceof Error && typeof error.stack === 'string' && error.stack !== '')
+                reason = error.stack;
             ctx.logger.warn(`agent-teams: member dispatch failed for ${memberName}: ${String(error)}`);
+            await recordSpawnError(reason);
             return false;
         }
     }
@@ -1641,6 +1665,86 @@ export function registerAgentTeamsTools(ctx, config) {
             return updated;
         },
     }));
+    ctx.tools.register(defineTool({
+        name: 'agent_teams_amend_task',
+        description: 'Captain-only controlled contract amendment for one non-terminal quality task: replace a wrong objective/acceptance/verify/inScope/outOfScope when the original contract makes honest completion impossible (for example a verify command that cannot pass, or an inScope that forbids the file the objective names). The amendment is appended to the task\'s revisions ledger with previous values and the reason, and is rejected once a review/requirements task has passed judgment on this task. Members cannot amend contracts; the implementer re-reads the amended contract before its next quality gate. Lists are full replacements, not deltas.',
+        parameters: {
+            task_id: { type: 'string', required: true, description: 'Task whose contract is being amended.' },
+            reason: { type: 'string', required: true, description: 'Why the current contract is wrong; recorded in the revisions ledger.' },
+            objective: { type: 'string', description: 'Replacement objective.' },
+            acceptance: { type: 'array', items: { type: 'string' }, description: 'Replacement acceptance criteria (full list, not a delta).' },
+            verify: { type: 'array', items: { type: 'string' }, description: 'Replacement verification commands (full list, not a delta).' },
+            inScope: { type: 'array', items: { type: 'string' }, description: 'Replacement workspace-relative inScope paths (full list).' },
+            outOfScope: { type: 'array', items: { type: 'string' }, description: 'Replacement workspace-relative outOfScope paths (full list).' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    task_id: { type: 'string', required: true },
+                    status: { type: 'string', required: true },
+                    revised_fields: { type: 'string', required: true },
+                    revision_count: { type: 'number', required: true },
+                    contract: { type: 'string', required: true },
+                },
+            },
+            render: (_args, value) => [{
+                    type: 'text',
+                    text: `Task ${value.task_id} contract amended (${value.revised_fields}); ${value.revision_count} revision(s) on record, status ${value.status}. New contract: ${value.contract}`,
+                }],
+        },
+        async execute(args, exec) {
+            const captain = requireCaptain(exec);
+            const workspace = workspaceOf(captain);
+            const stateRoot = stateRootOf(workspace, config);
+            const team = await requireCaptainTeam(workspace, config, captain);
+            const amended = await withTeamLock(teamLockKey(stateRoot, team.id), async () => {
+                const fresh = await requireFreshCaptainTeam(stateRoot, team.id, captain.id);
+                const task = requireTask(fresh, args.task_id);
+                const input = {
+                    ...args.objective === undefined ? {} : { objective: args.objective },
+                    ...args.acceptance === undefined ? {} : { acceptance: args.acceptance },
+                    ...args.verify === undefined ? {} : { verify: args.verify },
+                    ...args.inScope === undefined ? {} : { inScope: args.inScope },
+                    ...args.outOfScope === undefined ? {} : { outOfScope: args.outOfScope },
+                };
+                const result = amendTaskContract(fresh, task, normalizeBlankOptionalTaskFields(input), CAPTAIN_KEY, args.reason);
+                if (!result.ok || result.task === undefined) {
+                    throw new Error(result.error ?? 'amend_task rejected by quality gates');
+                }
+                Object.assign(task, result.task);
+                task.updatedAt = Date.now();
+                await writeTeam(stateRoot, fresh);
+                return {
+                    taskId: task.id,
+                    status: task.status,
+                    fields: result.revision?.fields ?? [],
+                    revisionCount: task.revisions?.length ?? 0,
+                    contract: {
+                        ...task.objective === undefined ? {} : { objective: task.objective },
+                        ...task.acceptance === undefined ? {} : { acceptance: task.acceptance },
+                        ...task.verify === undefined ? {} : { verify: task.verify },
+                        ...task.inScope === undefined ? {} : { inScope: task.inScope },
+                        ...task.outOfScope === undefined ? {} : { outOfScope: task.outOfScope },
+                    },
+                };
+            });
+            appendTeamEvent(ctx, captainSessionOf(ctx, team.captainSessionId, captain.session), 'agent-teams/task-amended', {
+                teamId: team.id,
+                taskId: amended.taskId,
+                fields: amended.fields,
+                reason: args.reason,
+            });
+            return {
+                task_id: amended.taskId,
+                status: amended.status,
+                revised_fields: amended.fields.join(', '),
+                revision_count: amended.revisionCount,
+                contract: JSON.stringify(amended.contract),
+            };
+        },
+    }));
     ctx.tools.register(defineTool({
         name: 'agent_teams_send_message',
         description: 'Send coordination or current-task guidance directly to the captain or a teammate. A running recipient receives it at the next model step; an idle recipient wakes. Messages are durably retained until read. Use task creation/reassignment for a new unit of work, not repeated status nudges.',
@@ -1775,6 +1879,7 @@ export function registerAgentTeamsTools(ctx, config) {
                 reasoning_effort: member.reasoningEffort ?? '',
                 status: member.status,
                 activity: member.id !== '' ? (activity.get(member.id) ?? 'unknown') : 'unspawned',
+                ...member.spawnError === undefined ? {} : { spawn_error: member.spawnError },
             }));
             const tasks = team.tasks.map((task) => ({
                 id: task.id,
@@ -2214,7 +2319,8 @@ function renderStatus(value) {
         ...team.members.map((member) => {
             const route = member.provider && member.model ? ` · ${member.provider}/${member.model}` : '';
             const effort = member.reasoning_effort ? ` · reasoning ${member.reasoning_effort}` : '';
-            return `  - ${member.name} [${member.role}] ${member.status}/${member.activity}${route}${effort}`;
+            const failure = member.spawn_error === undefined ? '' : `\n      start failed: ${member.spawn_error.slice(0, 400)}`;
+            return `  - ${member.name} [${member.role}] ${member.status}/${member.activity}${route}${effort}${failure}`;
         }),
         `Tasks (${team.tasks.length}):`,
         ...team.tasks.map((task) => {

package/lib/types/event-types.d.ts

@@ -52,6 +52,15 @@ export interface AgentTeamsTaskUpdatedData {
     readonly verdict?: string;
     readonly round?: number;
 }
+/** Records one captain-only contract amendment on a task. */
+export interface AgentTeamsTaskAmendedData {
+    readonly teamId: string;
+    readonly taskId: string;
+    /** Amended contract field names (`objective`, `inScope`, …). */
+    readonly fields: readonly string[];
+    /** Why the previous contract was wrong. */
+    readonly reason: string;
+}
 /** Records a human halt from the captain chat. */
 export interface AgentTeamsTeamHaltedData {
     readonly teamId: string;
@@ -108,6 +117,11 @@ declare module '@deepseek-ai/dsh-session/types' {
          * @param data - team identity, task id, and the new status/assignee/output.
          */
         'agent-teams/task-updated': AgentTeamsTaskUpdatedData;
+        /**
+         * Records one captain-only contract amendment.
+         * @param data - team identity, task id, amended field names, and reason.
+         */
+        'agent-teams/task-amended': AgentTeamsTaskAmendedData;
         /**
          * Records one mailbox message.
          * @param data - team identity, sender, recipient, and content.
@@ -136,4 +150,4 @@ declare module '@deepseek-ai/dsh-session/types' {
     }
 }
 /** The full set of `agent-teams/*` event names. */
-export type AgentTeamsEventType = 'agent-teams/team-created' | 'agent-teams/member-added' | 'agent-teams/member-removed' | 'agent-teams/task-created' | 'agent-teams/task-updated' | 'agent-teams/message-sent' | 'agent-teams/team-halted' | 'agent-teams/team-resumed' | 'agent-teams/team-deleted' | 'agent-teams/plan-discarded';
+export type AgentTeamsEventType = 'agent-teams/team-created' | 'agent-teams/member-added' | 'agent-teams/member-removed' | 'agent-teams/task-created' | 'agent-teams/task-updated' | 'agent-teams/task-amended' | 'agent-teams/message-sent' | 'agent-teams/team-halted' | 'agent-teams/team-resumed' | 'agent-teams/team-deleted' | 'agent-teams/plan-discarded';

package/lib/types/harness-compat.d.ts

@@ -22,4 +22,48 @@ export declare function queueMemberPrompt(runtime: Context['subagents'], parent:
 export declare function steerMemberPrompt(runtime: Context['subagents'], parent: Agent, childId: SessionId, content: ContentBlock[], signal: AbortSignal, live?: Agent): Promise<MessageId>;
 /** Guard all resumable delivery paths, preserving the native service receiver. */
 export declare function guardSubagentDelivery(ctx: Context, isRetired: (sender: Agent, targetId: SessionId) => Promise<boolean>): void;
+/**
+ * Names the host's `tools.restrict()` would admit for this agent's layer
+ * chain, or undefined when the host does not expose its registry view.
+ * restrict() rejects unknown names with a hard error, so the spawn path must
+ * check entries against this view before forwarding them. Source:
+ * dsh-tools view()/restrict() in 0.1.5-rc.1; older Harness generations lack
+ * the surface and keep the verbatim list.
+ */
+export declare function restrictableToolNames(agent: Agent): ReadonlySet<string> | undefined;
+/**
+ * Member `toolFilter` for one spawn. Captain-only names are registered by
+ * this plugin itself and always resolvable; the depth-related entries name
+ * HOST tools and are only known under some compositions, so they must be
+ * resolved against the running host's registry: the delegation tool name is
+ * host configuration (dsh-tool-subagent `toolName`, default `subagent`,
+ * renamed per composition, e.g. `subagent_fork` in web-style profiles), and
+ * forwarding a name the host dropped aborts every member spawn (#163, #164).
+ * Depth enforcement itself does not depend on these names —
+ * installMemberDelegationGuard bounds descendant creation by parent chain.
+ */
+export declare function memberToolFilter(maxDepth: number | undefined, knownTools: ReadonlySet<string> | undefined): {
+    deny: string[];
+};
+/**
+ * Start one member, dropping any filter name the host reports as unknown and
+ * retrying.
+ *
+ * Resolving the filter against the registry view ({@link memberToolFilter})
+ * only covers hosts that expose one. A rejected filter still leaves the member
+ * without a session for the lifetime of the team, so the start must survive the
+ * cases that resolution cannot see — no registry view, a name that is known but
+ * not restrictable, a composition that mounted differently than expected. The
+ * host names the offenders in its rejection, so they are removed and the start
+ * retried; the retry only runs while the deny list strictly shrinks, and any
+ * failure that is not an unknown-name report propagates untouched.
+ * @param start - performs one start attempt for the given `toolFilter`.
+ * @param filter - the filter to attempt first.
+ * @returns the started member.
+ */
+export declare function startMemberWithLenientFilter<T>(start: (filter: {
+    deny: string[];
+}) => Promise<T>, filter: {
+    deny: string[];
+}): Promise<T>;
 export {};

package/lib/types/quality-gates.d.ts

@@ -3,7 +3,7 @@
  * coverage, and resume. Tools and persistence call these; they do not I/O.
  * @module dsh-agent-teams/quality-gates
  */
-import { type AcceptanceResult, type CommandResult, type FindingSeverity, type ReviewFinding, type ReviewPolicy, type ReviewVerdict, type TaskKind, type TaskStatus, type TeamState, type TeamTask } from './types.ts';
+import { type AcceptanceResult, type CommandResult, type FindingSeverity, type ReviewFinding, type ReviewPolicy, type ReviewVerdict, type TaskKind, type TaskRevision, type TaskStatus, type TeamState, type TeamTask } from './types.ts';
 declare const QUALITY_KINDS: readonly TaskKind[];
 declare const WRITE_KINDS: readonly TaskKind[];
 declare const DEFAULT_REVIEW_POLICY: Required<Pick<ReviewPolicy, 'requirementsMinRounds' | 'requirementsMaxRounds' | 'codeMaxRounds' | 'maxRepairAttempts'>>;
@@ -121,6 +121,55 @@ export declare function collectChangedPaths(gitStatusText: string): string[];
 export declare function inScopeOverlap(left: readonly string[] | undefined, right: readonly string[] | undefined): string[];
 export declare function validateCreateTask(team: TeamState, input: CreateTaskInput): ValidateCreateTaskResult;
 export declare function evaluateQualityCompletion(task: TeamTask, update: QualityCompletionUpdate): QualityCompletionResult;
+/**
+ * Derive the repair round's inScope from the findings that caused it.
+ *
+ * `finding.file` records where the problem was OBSERVED, but the fix often
+ * targets a different file named in `requiredFix` (docs vs sample data,
+ * config vs code). Deriving the scope from both keeps the auto-generated
+ * repair contract satisfiable; deriving from `file` alone can produce a
+ * contract where the acceptance ("edit README.md") names a path the scope
+ * forbids, so no honest completion exists and the repair dead-locks.
+ *
+ * Absolute and otherwise illegal paths are dropped (they can never match
+ * workspace-relative scope patterns anyway); when nothing legal remains,
+ * the source task's own inScope is kept as the fallback. Over-inclusion is
+ * accepted: inScope is an audit upper bound, and the requiredFix text still
+ * tells the implementer what to touch.
+ *
+ * Keep all derived paths until the generator resolves inherited exclusions;
+ * filtering first would silently discard a required fix target.
+ */
+export declare function repairScopeFromFindings(findings: readonly ReviewFinding[], fallback: string[] | undefined): string[] | undefined;
+/** Captain-only amendment payload: replacement values for contract fields. */
+export interface ContractAmendmentInput {
+    objective?: string;
+    acceptance?: string[];
+    verify?: string[];
+    inScope?: string[];
+    outOfScope?: string[];
+}
+export interface AmendTaskContractResult {
+    ok: boolean;
+    error?: string;
+    task?: TeamTask;
+    revision?: TaskRevision;
+}
+/**
+ * Controlled contract amendment (the pure rule; tooling keeps it
+ * captain-only). When a quality contract is wrong — a verify command that
+ * cannot pass, an inScope that forbids the file the objective names — the
+ * worker has no honest completion and either dead-locks or games the gate.
+ * Instead the captain may fix the contract mid-flight: every amendment is
+ * recorded on the task as a {@link TaskRevision} (previous values + reason),
+ * and once a review/requirements task has passed judgment on this task the
+ * contract is frozen. Amendments replace whole fields (lists are full
+ * replacements, not deltas); the implementer re-reads the amended contract
+ * before its next quality gate. Completion gates need no special casing:
+ * they read the task's current fields, so they naturally evaluate the
+ * amended contract.
+ */
+export declare function amendTaskContract(team: TeamState, task: TeamTask, input: ContractAmendmentInput, by: string, reason: string): AmendTaskContractResult;
 export declare function planQualityFollowUp(team: TeamState, closed: TeamTask): PlanQualityFollowUpResult;
 export declare function buildCoverageMatrix(goalItems: readonly string[], tasks: readonly TeamTask[]): CoverageRow[];
 export declare function canDeclareDelivery(team: TeamState): DeliveryResult;
@@ -128,6 +177,7 @@ export declare function resumeTeamState(team: TeamState, reason: string): Resume
 export declare function isReviewFinding(value: unknown): value is ReviewFinding;
 export declare function isAcceptanceResult(value: unknown): value is AcceptanceResult;
 export declare function isCommandResult(value: unknown): value is CommandResult;
+export declare function isTaskRevision(value: unknown): value is TaskRevision;
 /**
  * Normalize blank optional task fields to omitted ("blank means absent").
  * Blank string scalars are deleted; string lists have blank entries filtered

package/lib/types/state.d.ts

@@ -13,7 +13,8 @@
  * @module dsh-agent-teams/state
  */
 import { type TaskStatus, type TeamMessage, type TeamState, type TeamTask } from './types.ts';
-export { buildCoverageMatrix, canDeclareDelivery, classifyChangedPath, collectChangedPaths, defaultQualityDeliveryGraph, describeQualityLoop, evaluateQualityCompletion, hasValidQualityTaskFields, isQualityKind, normalizeBlankOptionalTaskFields, pathMatchesScope, planQualityFollowUp, qualityPlanningPrompt, resumeTeamState, sanitizeReviewAcceptance, sanitizeReviewObjective, taskKindOf, validateCreateTask, } from './quality-gates.ts';
+export { amendTaskContract, buildCoverageMatrix, canDeclareDelivery, classifyChangedPath, collectChangedPaths, defaultQualityDeliveryGraph, describeQualityLoop, evaluateQualityCompletion, hasValidQualityTaskFields, isQualityKind, isTaskRevision, normalizeBlankOptionalTaskFields, pathMatchesScope, planQualityFollowUp, qualityPlanningPrompt, resumeTeamState, sanitizeReviewAcceptance, sanitizeReviewObjective, taskKindOf, validateCreateTask, } from './quality-gates.ts';
+export type { ContractAmendmentInput } from './quality-gates.ts';
 /** Mailbox key of the captain. */
 export declare const CAPTAIN_KEY = "captain";
 /**

package/lib/types/tool-names.d.ts

@@ -1,4 +1,4 @@
 /** Stable business API names; exposure changes never rename these operations. */
-export declare const TEAM_TOOL_NAMES: readonly ["agent_teams_create", "agent_teams_approve", "agent_teams_edit_plan", "agent_teams_add_member", "agent_teams_remove_member", "agent_teams_create_task", "agent_teams_reassign_task", "agent_teams_claim_task", "agent_teams_update_task", "agent_teams_send_message", "agent_teams_status", "agent_teams_resume", "agent_teams_delete"];
+export declare const TEAM_TOOL_NAMES: readonly ["agent_teams_create", "agent_teams_approve", "agent_teams_edit_plan", "agent_teams_add_member", "agent_teams_remove_member", "agent_teams_create_task", "agent_teams_reassign_task", "agent_teams_claim_task", "agent_teams_update_task", "agent_teams_amend_task", "agent_teams_send_message", "agent_teams_status", "agent_teams_resume", "agent_teams_delete"];
 export declare const MEMBER_TOOL_NAMES: readonly string[];
-export declare const CAPTAIN_TOOL_NAMES: ("agent_teams_create" | "agent_teams_approve" | "agent_teams_edit_plan" | "agent_teams_add_member" | "agent_teams_remove_member" | "agent_teams_create_task" | "agent_teams_reassign_task" | "agent_teams_claim_task" | "agent_teams_update_task" | "agent_teams_send_message" | "agent_teams_status" | "agent_teams_resume" | "agent_teams_delete")[];
+export declare const CAPTAIN_TOOL_NAMES: ("agent_teams_create" | "agent_teams_approve" | "agent_teams_edit_plan" | "agent_teams_add_member" | "agent_teams_remove_member" | "agent_teams_create_task" | "agent_teams_reassign_task" | "agent_teams_claim_task" | "agent_teams_update_task" | "agent_teams_amend_task" | "agent_teams_send_message" | "agent_teams_status" | "agent_teams_resume" | "agent_teams_delete")[];

package/lib/types/types.d.ts

@@ -52,6 +52,19 @@ export interface ReviewPolicy {
     maxRepairAttempts?: number;
     requiredReviewers?: string[];
 }
+/** One captain-only contract amendment recorded on a quality task. */
+export interface TaskRevision {
+    /** Epoch ms when the amendment was applied. */
+    at: number;
+    /** Identity that applied it (`captain`). */
+    by: string;
+    /** Why the previous contract was wrong; kept for the audit trail. */
+    reason: string;
+    /** Amended contract field names (`objective`, `acceptance`, …). */
+    fields: string[];
+    /** Previous values of the amended fields; fields absent before are omitted. */
+    previous: Record<string, unknown>;
+}
 /** One task of a team's task list. */
 export interface TeamTask {
     /** Stable task id from the profile template; absent for ad-hoc tasks. */
@@ -102,6 +115,8 @@ export interface TeamTask {
     sourceFindingIds?: string[];
     /** User-constraint / goal items this task claims to cover. */
     coverageOf?: string[];
+    /** Captain-only contract amendments, oldest first (see amendTaskContract). */
+    revisions?: TaskRevision[];
     createdAt: number;
     updatedAt: number;
 }
@@ -134,6 +149,12 @@ export interface TeamMember {
     status: MemberStatus;
     /** Execution admission is closed while a failed/pending handoff is drained. */
     stopping?: boolean;
+    /**
+     * Last member-start failure, recorded so the captain can see why a member
+     * never acquired a session instead of observing an unexplained `unspawned`
+     * member. Cleared by the next successful start.
+     */
+    spawnError?: string;
 }
 /** One mailbox message. */
 export interface TeamMessage {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanmicoder/dsh-agent-teams",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "AgentTeams for DeepSeek Harness: multi-agent team collaboration (captain, members, tasks with dependencies, messaging) driven by natural language, with a tree monitor in the web GUI",
   "type": "module",
   "main": "lib/index.js",
@@ -225,13 +225,15 @@
     "update:skills": "node scripts/update-skills.mjs",
     "test:skills-updater": "node --test scripts/update-skills.test.mjs",
     "verify:skill": "node scripts/sync-skill.mjs --check",
-    "verify": "node scripts/verify.mjs && node scripts/fallback-tdd.mjs && node scripts/member-failure-tdd.mjs && node scripts/quality-gates-tdd.mjs && node scripts/lifecycle-verify.mjs && node scripts/stress-verify.mjs && pnpm verify:web-routes && pnpm verify:release && pnpm verify:skill && pnpm verify:harness-contract && pnpm verify:http-body && pnpm verify:compatibility && pnpm verify:capabilities",
+    "verify": "node scripts/verify.mjs && node scripts/fallback-tdd.mjs && node scripts/member-failure-tdd.mjs && pnpm verify:quality-gates && node scripts/lifecycle-verify.mjs && node scripts/stress-verify.mjs && pnpm verify:web-routes && pnpm verify:release && pnpm verify:skill && pnpm verify:harness-contract && pnpm verify:http-body && pnpm verify:compatibility && pnpm verify:capabilities && pnpm verify:member-spawn-recovery",
+    "verify:quality-gates": "node scripts/quality-gates-tdd.mjs && node --test scripts/quality-gates-repair-scope.test.mjs scripts/quality-gates-amend.test.mjs",
     "verify:web-routes": "node scripts/web-routes-verify.mjs",
     "verify:release": "node --test scripts/release-metadata.test.mjs",
     "verify:harness-contract": "node scripts/harness-compat-tdd.mjs && node scripts/stability-tdd.mjs && node scripts/lifecycle-verify.mjs --modern-harness && node scripts/member-failure-tdd.mjs --modern-harness && node scripts/lifecycle-verify.mjs --delivery-harness && node scripts/member-failure-tdd.mjs --delivery-harness",
     "verify:compatibility": "node scripts/compatibility.mjs && node --test scripts/compatibility.test.mjs && node scripts/doctor.mjs",
     "verify:http-body": "node --test scripts/http-body.test.mjs",
     "doctor": "node scripts/doctor.mjs",
-    "verify:capabilities": "node --test scripts/capabilities.test.mjs"
+    "verify:capabilities": "node --test scripts/capabilities.test.mjs",
+    "verify:member-spawn-recovery": "node --test scripts/member-spawn-recovery.test.mjs"
   }
 }

package/release-notes/v0.1.19.md

@@ -0,0 +1,20 @@
+# AgentTeams v0.1.19
+
+- Fix member startup when the host disables or renames its delegation tools. Missing global tool names no longer abort all member starts; unrelated startup failures remain visible in team status. Thanks to PRs #167 and #172.
+- Derive automatic repair scope from both the observed file and paths named in `requiredFix`. Resolve conflicting exclusions inherited from the previous round after deriving that scope, so a repair can truthfully report the files it must change. Integrates PR #155 and the generated-contract portion of PR #177; manually authored exclusions keep their existing precedence.
+- Add captain-only `agent_teams_amend_task` for correcting non-terminal quality contracts, with durable revision history and freeze checks after a passing review. Members cannot call it.
+- Include repair-scope and amendment regressions in the standard release gate; update the captain tool-surface fixture and tolerate the known closed-session teardown race (PR #180).
+
+## Compatibility
+
+The supported Harness matrix is unchanged: recommended `0.1.5-rc.1`, plus `0.1.2-rc.1`, `0.1.2-alpha.5`, and `0.1.2-alpha.2`. This release does not claim support for untested newer Harness versions or every Desktop distribution.
+
+Existing malformed terminal tasks are not rewritten automatically. Broader findings/revision linkage and stale generated acceptance criteria remain separate issues.
+
+Update the plugin in your existing profile, then restart Harness:
+
+```sh
+dsh plugin --profile <your-profile> add --save-exact @nanmicoder/dsh-agent-teams@0.1.19
+```
+
+See [release verification](https://github.com/NanmiCoder/dsh-agent-teams/tree/main/docs/releases/v0.1.19) for real-provider scenarios, evidence boundaries, and publication results.

package/release-notes/v0.1.20.md

@@ -0,0 +1,20 @@
+# AgentTeams v0.1.20
+
+Documentation-only release. No source, behavior, or dependency changes.
+
+- Sync the version references in `README.md` and `README_ZH.md` with the npm `latest` channel. Both still described `0.1.17` as the recommended installation, so readers copying the documented command installed `0.1.17` while `latest` already pointed at `0.1.19`.
+- The packaged artifact is therefore identical to `0.1.19` apart from the two README files. `0.1.20` exists only because npm writes a package's README at publish time and offers no way to update it afterwards.
+
+## Compatibility
+
+The supported Harness matrix is unchanged: recommended `0.1.5-rc.1`, plus `0.1.2-rc.1`, `0.1.2-alpha.5`, and `0.1.2-alpha.2`.
+
+Because this release ships the same code as `0.1.19`, the verification recorded for that version still covers it. See [v0.1.19 release verification](https://github.com/NanmiCoder/dsh-agent-teams/tree/main/docs/releases/v0.1.19) for the real-provider scenarios, evidence boundaries, and publication results.
+
+For the substantive changes since the last documented release, see [v0.1.19](./v0.1.19.md) and [v0.1.18](./v0.1.18.md).
+
+Update the plugin in your existing profile, then restart Harness:
+
+```sh
+dsh plugin --profile <your-profile> add --save-exact @nanmicoder/dsh-agent-teams@0.1.20
+```