feat(harness): built-in ask_user tool — model-initiated questions to the user (HITL ask direction)

[Letter2025]

Summary

Adds the HITL "ask" direction to AgentScope: the model can proactively ask the user structured questions during a run, complementing the existing user-confirms-tool flow.

A tool whose checkPermissions() returns PermissionDecision.askUser(...) pauses the run with the new GenerateReason.ASK_USER_ASKING — in every PermissionMode (including BYPASS, since it rides the bypass-immune tool self-check) — and is never executed. Callers render the questions and resume with AskUserResult(s) under Msg.METADATA_ASK_USER_RESULTS; the framework formats the answers into the ask_user tool result so the model reads them on the next reasoning iteration.

The harness ships a built-in ask_user tool (JSON-schema'd questions[]: id/header/question/type single|multiple|free|secret/options/required), enabled via HarnessAgent.Builder.enableAskUser() (opt-in, off by default — no behavior change for existing builders).

Motivation

HITL today only answers "may this tool run?" (PERMISSION_ASKING + RequireUserConfirmEvent). There is no way for the model to request information from the user. This is a standard capability in current coding agents (OpenAI Codex request_user_input, Claude Code / Agent SDK AskUserQuestion, Cline, DeepSeek Harness ask_user_question) and has been requested in:

• [human in loop]how to interrupt the agent flow and give a confirm/new information to the agent to continue the flow when coding by fastapi? agentscope#1120 — "give a confirm/new information to the agent to continue the flow"
• [Feature]: human in loop wanted agentscope#926 — "[Feature]: human in loop wanted"
• Why does DeepSeekFormatter convert system messages to user messages? #2168 — "Fail to continue Human-in-the-Loop"

Core changes (agentscope-core)

Area	Change
PermissionBehavior	new ASK_USER constant (not registerable as a rule; produced only by a tool's checkPermissions())
PermissionDecision	new askUser(String) factory
PermissionEngine	ASK_USER short-circuits immediately in the bypass-immune tool-sef-check phase (not swallowed by rule/BYPASS handling)
ReActAgent	gate routes ASK_USER to a dedicated pending list; actingStream emits RequireUserAskEvent + RequestStopEvent(ASK_USER_ASKING); acting() returns the pausing assistant Msg; resumes with answers via validateAndAcceptAskUserResults which formats them into the tool result without executing it
Events	new RequireUserAskEvent / UserAskResultEvent (replyId-correlated, parallel to the confirm flow; registered in AgentEvent subtypes)
GenerateReason	new ASK_USER_ASKING

Harness changes (agentscope-harness)

• Built-in AskUserTool in io.agentscope.harness.agent.tool (name ask_user, checkPermissions() → askUser(...))
• HarnessAgent.Builder.enableAskUser() (no-arg + boolean overload), registers the tool at build()

Docs & examples

• docs/v1/{en,zh}/docs/task/hitl.md — new "Ask the user for input" section
• docs/v2/{en,zh}/docs/building-blocks/permission-system.md — new "Ask the user (model-initiated questions)" section (incl. DONT_ASK note)
• agentscope-examples/.../hitl/AskUserHITLExample.java — runnable interactive example

Tests

• ReActAgentAskUserTest (core): pause with ASK_USER_ASKING, tool not executed, pause under BYPASS, resume → answers visible in next reasoning, resume-without-answers guidance error, streaming RequireUserAskEvent/UserAskResultEvent correlation, answer formatting (scalar/list/selected+text/skipped)
• HarnessAgentAskUserTest (harness): enableAskUser() registers the tool and pauses; BYPASS still pauses; full resume round-trip (answer reaches the model, ask_user not executed); tool self-description
• Existing HITL/permission suites stay green

Compatibility

Opt-in feature: existing HarnessAgent/ReActAgent builders are unaffected (tool not registered, no new gate entries, GenerateReason gains one value). ASK_USER is not a rule behavior, so no permission-config surface changes.

Closes #2860

[Letter2025]

Non-blocking note on CI: the remaining build failures are a pre-existing harness test flake, not caused by this PR.

The failing jobs report Failed to close extension context / Failed to delete temp directory at JUnit @TempDir teardown time, in a different test class on every run:

• a7250f9 → HarnessAgentSubagentStreamTest + HarnessAgentIntegrationExampleTest
• 64c83f3 → HarnessAgentDynamicHookBuilderTest
• a0d565a → HarnessAgentSubagentStreamTest (again)
• 75c7381 → JsonSessionDefaultLocationTest

The same failure pattern hit main's own CI on an unrelated commit (guava bump, run 32981277153 — HarnessAgentSubagentStreamTest.call_localSubagent_returnsReplyWithoutStreaming -> Failed to close extension context), and all of these classes pass locally (and pass on CI in runs where they are not the flaky one). Root-cause hypothesis: harness default memory flush/maintenance middleware keeps writing workspace files on a background scheduler after the test body completes, racing @TempDir cleanup.

The deterministic failures caused by this PR were fixed and verified:

• added ASK_USER to PermissionBehaviorTest expectations
• added REQUIRE_USER_ASK / USER_ASK_RESULT samples to RemoteEventCodecPassthroughTest
• added @JsonCreator/@JsonProperty to AskUserResult so UserAskResultEvent round-trips through RemoteEventCodec

Happy to rebase/adapt if maintainers prefer a different approach.

[Letter2025]

Hi @mikemikimike @helloworldtang @wzq-xzwj — could someone rerun the failed CI jobs on this PR? The failure is a pre-existing harness @TempDir teardown flake, unrelated to the change itself:

• The only failing test in the last runs is HarnessAgentSubagentStreamTest.call_localSubagent_returnsReplyWithoutStreaming (and in earlier runs HarnessAgentDynamicHookBuilderTest / JsonSessionDefaultLocationTest) — each failing at Failed to close extension context / Failed to delete temp directory during teardown, with the test bodies passing.
• The same failure appeared on main's own CI for the unrelated guava-bump commit (run 32981277153: same test class, same Failed to close extension context), and all these classes pass locally and on CI in runs where they are not the flaky one.
• Suspected root cause: the harness default memory flush/maintenance middleware keeps writing workspace files on a background scheduler after the test body completes, racing @TempDir cleanup. Happy to file/adjust a follow-up if a global fix is preferred.

This branch already verified locally: full core + harness suites pass (only known local-only errors: DangerousPathBypassTest symlink cases on Windows without symlink privileges).

[codecov]

Codecov Report

❌ Patch coverage is 91.41414% with 17 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...e/src/main/java/io/agentscope/core/ReActAgent.java	84.41%	3 Missing and 9 partials ⚠️
...n/java/io/agentscope/core/event/AskUserResult.java	92.10%	0 Missing and 3 partials ⚠️
.../io/agentscope/core/event/RequireUserAskEvent.java	90.90%	0 Missing and 1 partial ⚠️
...a/io/agentscope/core/event/UserAskResultEvent.java	90.90%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[oss-maintainer]

⚠️ Merge conflict detected

This PR has conflicts with the main branch and cannot be merged. Please rebase or merge main into your branch and resolve the conflicts:

git fetch origin
git checkout feat/ask-user-tool
git rebase origin/main
# resolve conflicts, then:
git push --force-with-lease

This is a one-time reminder. Feel free to @mention me for a re-review after conflicts are resolved.

---

Automated notification by github-manager-bot