feat(permission): model-requested escalation with approval-gated widening

[birdie7761]

Fixes #3011

Description

Adds an opt-in mechanism for the model to request a strictly wider permission mode for a single tool call, with the user approving before anything executes — the third path between confirmation fatigue (DEFAULT asks for everything) and dropping the safety story (BYPASS). Design follows the choreography DeepSeek's open-source harness ships in production (deepseek-harness, escalation.ts).

Core pieces:

• PermissionEscalation (one home shared by tool families): the closed target vocabulary read-only / workspace-write / danger-full-access, the strictly-wider ladder, argument-pairing validation (sandbox_permissions requires a non-empty string justification; either alone is a malformed ask; non-string values are rejected rather than coerced; the justification is trimmed and capped at 500 characters with a visible ellipsis), and fail-closed resolution. Validation happens at execution time from the raw tool-call input, never baked into a tool schema — schemas are registry-global while the effective mode is per-call truth. A key explicitly mapped to null carries no escalation intent.
• PermissionEngine: escalation requests resolve after deny rules (a hard integrator ceiling escalation can never override) and before everything else. A valid strictly-wider request becomes ASK carrying the target and justification, riding the existing user-confirmation loop (RequireUserConfirmEvent → confirm → ALLOWED → execute). DONT_ASK denies: no approver, no escalation. The branch evaluates every call that carries the arguments (not just the shell tool — only shell advertises them today; legacy non-ToolBase tools bypass permission evaluation entirely, as before).
• ReActAgent: denial reasons now reach the model — PermissionVerdict carries the decision message and the auto-denied gate is a call-id → message map, so writeAutoDeniedResults / runToolBatch write the engine's (or tool self-check's) own denial text into the DENIED ToolResultBlock and its delta event instead of a generic placeholder. A model facing a malformed escalation ask learns exactly what to fix instead of blindly retrying. Note this also improves plain deny-rule and tool-self-check denials — an intentional, deliberate behavior improvement beyond the escalation scope. Calls carrying escalation arguments engage the engine per call (useEngine || hasEscalationArgs(input)); every other call keeps exactly its previous evaluation path.
• PermissionContextState: new escalationEnabled flag, serialized as escalation_enabled, default false — pre-feature JSON deserializes unchanged. The flag deliberately does NOT affect isTrivial(): enabling escalation must not flip an otherwise default-configured agent from auto-execution to ask-per-call.
• HarnessAgent.Builder.permissionEscalation(boolean) (default false): merges the flag onto the effective permission context (preserving user-supplied modes and rules, call-order independent) and registers EscalatingShellExecuteTool in place of the plain shell tool — same tool name, execution body shared via ShellExecuteTool.executeAndFormat (the working-directory validation is a security check and must not drift between variants), plus the two optional escalation arguments in the schema.

Compatibility: default builds observe no change at all — no schema, state, or evaluation difference; enabling the flag changes only calls that actually carry the escalation arguments.

Test evidence (TDD, compile-level red on main)

• PermissionEscalationTest (14): ladder, pairing, type rejection, capped truncation with marker, null-valued keys, normalization, DONT_ASK, ladder-phrased denials
• PermissionEngineEscalationTest (8): deny-rule supremacy, malformed pairing, disabled agent, no-args-unchanged evaluation, serialization round-trip + legacy JSON, posture-preserving triviality, withMode preservation
• ReActAgentEscalationHitlTest (3, end-to-end on a trivial-context agent): plain call auto-executes after the flag is enabled; escalation call pauses → confirms → executes; hallucinated args on a disabled agent deny closed with the specific reason asserted in the DENIED tool result; a message-less tool self-check DENY still denies (fail-closed regression)
• HarnessAgentPermissionEscalationWiringTest (3): default build unchanged, flag travels onto context + schema, user context preserved on merge

Full core suite 2344/0, full harness suite 926/0.

Checklist

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (builder/class javadocs document the posture-preservation and pairing contracts)
• Code is ready for review

[codecov]

Codecov Report

❌ Patch coverage is 86.17886% 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	71.42%	5 Missing and 3 partials ⚠️
...tscope/core/permission/PermissionContextState.java	77.77%	3 Missing and 1 partial ⚠️
...entscope/core/permission/PermissionEscalation.java	92.15%	1 Missing and 3 partials ⚠️
...harness/agent/tool/EscalatingShellExecuteTool.java	75.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[CryoThrust]

I reviewed the proposal and the opt-in posture-preserving design is a good fit. Two details are worth making explicit before merge:\n\n1. Please add a test for approval-to-execution drift: after an approval is recorded, mutate or replay the same toolCallId with different canonical arguments and assert it cannot reuse the approval. The approval must be bound to the exact call snapshot, not only the id.\n2. Please add a concurrent duplicate-resume test asserting that only one decision wins and the tool executes at most once. This is especially important because the approval path is asynchronous and the same callback can be retried by a transport.\n\nThe current tests cover malformed pairing, disabled escalation, deny precedence and ordinary calls, but these two cases protect the runtime security boundary described in the issue. I will avoid a competing implementation and am happy to review the follow-up.