fix(user-interaction): reject ask_user_question from delegated subagents
This commit is contained in:
Tianyi Cui
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-01-ask-user-delegated-caller-guard.md
|
||||
2026-08-01-ask-user-delegated-caller-guard.md: 17c5e42a1d12c018507c6cf410129bb17099e967
|
||||
2026-08-01-ask-user-delegated-caller-guard.zh.md: 38f059ba87ac5208cca6cb94ba9ee5223a6987b0
|
||||
@@ -0,0 +1,29 @@
|
||||
# Agent Note: Reject ask_user_question from delegated subagents
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-08-01-ask-user-delegated-caller-guard.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
A delegated subagent that calls the `ask_user_question` tool blocks indefinitely. The tool pauses for a human answer, but a child context has no human answerer, so no answer ever arrives and the subagent run hangs until it is cancelled externally.
|
||||
|
||||
## Decision
|
||||
|
||||
`UserInteractionService.ask()` rejects any request whose calling agent is a delegated subagent — `request.agent.session.header.delegationDepth > 0` — with a new `UserInteractionError` code `DELEGATED_CALLER` and the message `ask_user_question is unavailable to delegated subagents; delegate the question to the top-level agent`. The check runs at the top of `ask()`, after the aborted/empty guards and before intent validation, so no provider interaction happens for a rejected child. This mirrors the goal tools' top-level-only authority (`create_goal` rejects non-top-level agents with a direct-human-turn requirement).
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Leave the child blocked until the parent forwards an answer.** Rejected: no answerer exists in the child context and no forwarding seam exists; the observed behavior is a permanent hang.
|
||||
|
||||
**Reject inside the tool (`dsh-tool-ask-user`) instead of the service.** Rejected: that consumer seam is bypassed by direct callers of `ctx.userInteraction.ask()`; the operation boundary that owns the decision is the service itself.
|
||||
|
||||
**Warn children off via the model-facing description.** Rejected: the rejection is already a loud, self-explanatory error, and a description edit would not stop the hang for a model that calls anyway.
|
||||
|
||||
## Consequences
|
||||
|
||||
Delegated subagent calls fail fast with a stable error instead of hanging; a child that needs a decision must delegate the question to the top-level agent. Programmatic askers without an agent and top-level agents (`delegationDepth` absent or 0) are unaffected and still reach the provider. The `DELEGATED_CALLER` code joins the documented `UserInteractionError` taxonomy in the package READMEs, and the model-facing description is unchanged.
|
||||
|
||||
## Testing
|
||||
|
||||
Two new unit tests exercise the guard: `user-interaction.spec.ts` asserts that `ask()` rejects with `DELEGATED_CALLER` and never calls the provider for a session created with `{ meta: { delegationDepth: 1 } }`, plus a positive control at `delegationDepth: 0`; `tool-ask-user.spec.ts` asserts that a tool call from a delegated agent surfaces the structured error and never reaches the provider. Both packages pass, as does the parent `packages/ui` scope, and the two touched `src` files hold 100% per-file coverage.
|
||||
@@ -0,0 +1,29 @@
|
||||
# Agent Note: 拒绝委托子代理调用 ask_user_question
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-08-01-ask-user-delegated-caller-guard.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
委托子代理调用 `ask_user_question` 工具时会无限阻塞。该工具会暂停等待人类回答，但子代理上下文中没有人类应答者，因此永远等不到回答，子代理运行只能被外部取消。
|
||||
|
||||
## 决策
|
||||
|
||||
`UserInteractionService.ask()` 拒绝任何调用方为委托子代理的请求 —— `request.agent.session.header.delegationDepth > 0` —— 抛出新的 `UserInteractionError`，代码为 `DELEGATED_CALLER`，消息为 `ask_user_question is unavailable to delegated subagents; delegate the question to the top-level agent`。该检查位于 `ask()` 开头，在已中止/空问题守卫之后、意图校验之前，因此被拒绝的子代理不会触发任何提供方交互。这与 goal 工具仅限顶层代理的权限保持一致（`create_goal` 以直接人工回合要求拒绝非顶层代理）。
|
||||
|
||||
## 备选方案
|
||||
|
||||
**让子代理一直阻塞，直到父代理转发回答。** 不予采用：子代理上下文中不存在应答者，也没有任何转发 seam；实际观察到的行为就是永久挂起。
|
||||
|
||||
**在工具（`dsh-tool-ask-user`）而非服务中拒绝。** 不予采用：直接调用 `ctx.userInteraction.ask()` 的调用方会绕过该消费方 seam；拥有此决策权的操作边界是服务本身。
|
||||
|
||||
**通过模型侧描述来警告子代理。** 不予采用：拒绝本身已是响亮且自解释的错误，而且修改描述并不能阻止仍然去调用的模型造成挂起。
|
||||
|
||||
## 影响
|
||||
|
||||
委托子代理的调用会以稳定错误快速失败，而不是挂起；需要决策的子代理必须把问题转交给顶层代理。不带 agent 的程序化调用方以及顶层代理（`delegationDepth` 缺省或为 0）不受影响，仍会到达提供方。`DELEGATED_CALLER` 代码已加入包 README 中记载的 `UserInteractionError` 分类，模型侧描述保持不变。
|
||||
|
||||
## Testing
|
||||
|
||||
两个新的单元测试覆盖该守卫：`user-interaction.spec.ts` 断言以 `{ meta: { delegationDepth: 1 } }` 创建的会话调用 `ask()` 会以 `DELEGATED_CALLER` 拒绝且绝不调用提供方，并补充了 `delegationDepth: 0` 的正向对照；`tool-ask-user.spec.ts` 断言委托子代理发出的工具调用会呈现结构化错误且绝不触达提供方。两个包均通过，父级 `packages/ui` 作用域也通过，且两个被改动的 `src` 文件保持 100% 逐文件覆盖率。
|
||||
Reference in New Issue
Block a user