docs: fix verified doc-vs-code mismatches (MCP examples, HITL, defaults, tool names) (en+zh)

[chang6666]

Summary

Fixes a batch of verified doc-vs-code mismatches found by cross-checking the v2 guides against the current source. All snippets were validated against real APIs (several were copy-paste-and-fail). En and zh guides are kept in sync; no code changes. Partially addresses #1883 and #1190.

Corrections (each verified with grep against source)

Building blocks

• MCP examples (agent.md + tool.md, en+zh, 8 spots) — McpClientBuilder.stdio().name(...).command(...).build() etc. do not exist. Rewritten to the real API: McpClientBuilder.create("name").stdioTransport(cmd, args...).buildAsync().block() (and sseTransport / streamableHttpTransport), matching McpStdioExample / McpSseExample / McpStreamableHttpExample.
• HITL (agent.md, en+zh) — ToolUseBlock has no getSuggestedRules() (that accessor is on PermissionDecision). Resume snippet now matches PermissionHITLExample: new ConfirmResult(confirmed, toolCall), with a pointer to passing explicit rules.
• permission-system.md (en+zh) — suggested rules are carried on the ASK PermissionDecision, not on ToolUseBlock.
• agent.md (en+zh) — removed references to the removed legacy stream API and to the non-existent modelConfig() / reactConfig() builder methods.
• tool.md (en+zh) — @Tool.concurrencySafe default is true (Tool.java:117), not false; ToolGroup examples now use ToolGroup.builder() — the 4-arg public constructor in the docs does not exist (real one is protected with a different parameter order).
• model.md / agent.md (en+zh) — structured-output metadata key is _structured_output (MessageMetadataKeys.java:120), not structured_output.

Harness

• memory.md (en+zh) — memory-enabled agents register four tools (memory_search, memory_get, memory_save, session_search — HarnessAgent.java:2691-2694), not two; dropped the undocumented "up to 30 hits" cap (MemorySearchTool has none).
• plan-mode.md (en+zh) — whitelist is 9 tools per PlanModeMiddleware.ALWAYS_ALLOWED (adds agent_spawn / agent_send / agent_list / task_output / task_list); removed the stale "subagents do not inherit plan mode" known-gap — inheritance is implemented (AgentSpawnTool.propagatePlanMode) and subagent.md already documented it, so the two guides contradicted each other.
• skill.md / workspace.md (en+zh) — the shell tool is named execute (ShellExecuteTool.NAME), not execute_shell_command.
• filesystem.md (en+zh) — DockerFilesystemSpec.isolationScope defaults to USER (SandboxIsolationKey: null scope treated as USER), not SESSION.
• compaction.md (en+zh) — list_files is not in ToolResultEvictionConfig.DEFAULT_EXCLUDED_TOOLS.

Examples / README

• agentscope-examples/README.md: agentscope-core-java → agentscope-core, cd examples → cd agentscope-examples, exec:java commands gain -pl documentation (all main classes live in that module), dead ../CLAUDE.md link → CONTEXT.md, documentation link now points to java.agentscope.io (was the Python repo), duplicate section numbers fixed.
• README.md / README_zh.md: dependency snippets 2.0.1 → 2.0.3 (latest release).

Notes

• Documentation-only change; no production code touched.
• Kept deliberately out of scope (left for their own follow-ups): release-notes.md entries for 2.0.2/2.0.3, and the memory_search bounding docs line that overlaps with PR fix(harness): bound memory_search results with maxResults and line truncation #3267.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[oss-maintainer]

Summary

Doc-vs-code alignment pass over README/README_zh, the examples README and the v2 en+zh building-block/harness pages. Spot-checked every behavioural claim this PR changes against main@ea78c317: @Tool.concurrencySafe() really defaults to true (Tool.java:117), the structured-output metadata key is _structured_output (MessageMetadataKeys.STRUCTURED_OUTPUT), ConfirmResult does have the 2-arg convenience constructor and getSuggestedRules() lives on PermissionDecision (not ToolUseBlock), McpClientBuilder.create(..).<transport>(..).buildAsync().block() and ToolGroup.builder() match the current APIs, the filesystem isolation default is USER (HarnessAgent build: IsolationScope fsIsolationScope = IsolationScope.USER), execute is the registered shell tool name, the 4 memory tools are memory_search/memory_get/memory_save/session_search, ToolResultEvictionConfig.DEFAULT_EXCLUDED_TOOLS matches the reworded eviction list, maxIters default is 10, CONTEXT.md exists and CLAUDE.md does not, and 2.0.3 is the latest published release. All of it holds — this is a solid, low-risk docs fix and the en/zh pairs stay in sync.

Findings

• [Warning] docs/v2/en/docs/harness/plan-mode.md:73 — the quoted plan-mode denial output still does not match PlanModeMiddleware.DENY_MESSAGE.
• [Info] docs/v2/en/docs/building-blocks/agent.md:353 — deprecated stream(.., RuntimeContext) overloads still exist; the reworded sentence slightly over-states their removal.
• [Info] plan-mode whitelist (9 tools) and the sub-agent inheritance claim verified correct.

Nothing here blocks the change; the Warning is one more instance of the exact drift this PR sets out to remove.

---

Automated review by github-manager-bot

[oss-maintainer]

[Warning] This block is still presented as the literal tool-result the model sees, but it does not match the implementation. PlanModeMiddleware.DENY_MESSAGE is:

Blocked: you are in PLAN mode (read-only). You may investigate and run read-only tools, record your plan with plan_write, and call plan_exit when ready to execute. Do not modify files or run mutating commands until the plan is approved.

So the real message neither carries the [Tool denied — plan mode is active] header nor enumerates the whitelist. Since this PR is specifically about doc-vs-code drift, worth either quoting DENY_MESSAGE verbatim or dropping the fenced block and keeping the prose (the call is rejected with a plan-mode denial note).

[chang6666]

Fixed in 16df4cd — both guides now quote PlanModeMiddleware.DENY_MESSAGE verbatim (the zh page quotes the English literal too, since that is the string the model actually receives), replacing the invented header + whitelist enumeration.

[oss-maintainer]

[Info] The stream overloads still exist — ReActAgent keeps deprecated stream(List<Msg>, StreamOptions, RuntimeContext) (and the schema/structured variants, @Deprecated(since = "2.0.0", forRemoval = true)), and they do accept a RuntimeContext. Dropping the sentence is fine if the intent is to stop advertising deprecated APIs, but "provides RuntimeContext overloads for call and streamEvents" reads as a statement about the current surface, so a short "(plus deprecated stream overloads kept for compatibility)" would be more accurate. Same for the zh mirror.

[chang6666]

Addressed in 16df4cd — both en and zh now read "(plus deprecated stream overloads kept for compatibility)".

[oss-maintainer]

[Info] Verified against PlanModeMiddleware.ALWAYS_ALLOWED: exactly these 9 names (plan_enter, plan_write, plan_exit, todo_write, agent_spawn, agent_send, agent_list, task_output, task_list) — good. The child-inheritance claim also checks out: AgentSpawnTool.propagatePlanMode(...) activates plan mode on the spawned child when the parent state has isPlanActive(), so removing the "known gap" note is correct.