Make human-control handoff explicit in agent skills and DSH tool descriptions #474

Problem

During a browser task, my agent asked me in chat to perform an in-page action without first invoking BrowserSkill’s human-help mechanism. The tab remained under agent control, preventing normal interaction.

The original tool trace is unavailable, so I cannot conclusively attribute this to missing guidance, failure to follow existing guidance, or a runtime issue.

Triage findings

• The main DSH skill links to human-help guidance, but does not explicitly require a handoff before asking the user to interact.
• The help reference specifies bsk_assist(action: "request-help"), but does not explain that a chat request alone leaves browser control unchanged.
• The exposed bsk_assist description describes human assistance, while its internal request-help implementation uses clearer wording: “Pause browser automation.”
• Temporary human assistance and returning a borrowed tab are different operations; making this distinction explicit could prevent incorrect recovery attempts.

Controlled check

Environment: CLI 0.3.3, DSH plugin 0.3.3, DeepSeek subagent (deepseek-v4.1-flash).

1. Opened https://example.com in a fresh Agent Window.
2. Invoked bsk_assist(action: "request-help"), asking the human to click “Learn more.”
3. The human confirmed normal clicking worked.
4. The agent reported completed, observed the destination title “Example Domains,” and stopped its session.
5. Session removal was independently verified.

Limitation: This was a guided retry, not an unbiased reproduction of the original omission. No borrowed-tab scenario was tested. The explicit handoff path worked.

Suggested improvement

Consider adding a short, prominent rule to the main skills and exposed tool descriptions:

When human help is enabled and an in-page human action is needed, invoke request-help rather than relying on a chat message alone. This temporarily enables human interaction; returning a borrowed tab is a separate lifecycle operation. Resume only after an accepted help outcome, then observe again.

Keep existing disabled-help, cancellation, and timeout rules unchanged.

Would maintainers welcome a focused documentation/tool-description PR, accompanied by behavioral evaluation scenarios?

中文说明

代理曾仅在聊天中要求我操作网页，未先调用人工协助机制，页面仍处于代理控制状态。原始工具记录不可用，因此尚不能确认具体原因。

后续使用 CLI／DSH 插件 0.3.3 和 DeepSeek 子代理进行检查：明确调用 request-help 后，我可以正常点击链接；代理随后读取目标页面并结束会话。此次检查经过引导，并未复现最初的遗漏行为，也未测试借用标签页场景。

建议在主技能及对外工具描述中明确：

• 聊天请求本身不会交出网页控制权；需要调用人工协助工具。
• 临时人工协助不等同于归还借用的标签页。
• 人工协助结束后，应重新观察页面，再继续操作。

希望先确认维护者是否接受范围明确的文档、工具描述及行为评估改进，而非将其直接认定为运行时缺陷。