AgentScope Java 2.0 Permissions: From ALLOW, ASK, and DENY to Sandbox Isolation

An Agent that can call a shell or write files has two separate security problems. The application must decide whether an operation is allowed, and the runtime must limit the damage if the decision is wrong. AgentScope Java 2.0 addresses the first problem with permission evaluation and the second with tool validation and optional sandbox execution.

This article reads the implementation at commit d60414a6. The running example is a coding Agent that wants to update a deployment file and run a package command. We will trace the call through PermissionEngine, human approval, the tool executor, and the Harness sandbox.

The useful security model has layers:

model tool request
    -> permission decision
    -> optional human approval
    -> schema and tool-specific validation
    -> execution environment
    -> persistent state and audit record

Removing one layer changes the guarantee. A sandbox cannot decide business authorization. An ALLOW rule cannot prevent a container escape or a badly written tool from touching the wrong resource.

First check which permission path is active

ReActAgent.evaluatePermissions() has a compatibility branch that is easy to miss.

When PermissionContextState has DEFAULT mode, no working directories, and no allow, deny, or ask rules, isTrivial() returns true. The Agent uses the lightweight path. A ToolBase can still return ASK or DENY from its own checkPermissions(), but the full rule engine is not used. Legacy tools that do not extend ToolBase pass as approved.

Any configured mode, rule, or working directory makes the context nontrivial and enables the full PermissionEngine pipeline.

This preserves older applications, but it affects security reviews. A builder that merely constructs the default context has not activated the same policy path as an application that explicitly configures permissions. Tests should assert the decision for each sensitive tool instead of assuming that the presence of a permission object means enforcement is complete.

The full decision order

PermissionEngine.checkPermission() evaluates one tool invocation in this order:

1. matching DENY rule
2. matching ASK rule
3. mode handling and tool self-check
4. matching ALLOW rule
5. BYPASS fallback
6. default ASK, or fallback DENY in DONT_ASK mode

The order is part of the policy.

A matching deny rule wins before every later branch. A matching ask rule also stops evaluation before an allow rule. Tool self-checks run before allow rules, so a tool can block an unsafe input even when the caller has a broad allow entry. BYPASS appears near the end rather than at the start.

The mode check has concrete behavior. EXPLORE automatically allows tools marked read-only and denies modification tools. ACCEPT_EDITS automatically allows read-only tools, while other calls continue through the tool check and rule tables. Other modes do not add a decision at this stage.

A tool self-check can return ALLOW, DENY, ASK, or PASSTHROUGH. In this source snapshot, an ASK from the tool ends the full-engine path only when its decisionReason contains safety. Other ASK results continue to later rules and fallback. The lightweight compatibility path treats any tool ASK as a pause. Custom tool authors should test both configurations if they depend on ASK.

A rule is only as precise as the tool matcher

PermissionRule stores a tool name, optional rule content, behavior, and source. Rule tables are keyed by tool name and keep insertion order within that tool.

The engine does not interpret rule content. It calls tool.matchRule(ruleContent, input). The default ToolBase matcher accepts only null, which means a tool-wide rule. A path pattern, command prefix, repository name, or resource ID works only when that tool overrides matchRule() and defines the syntax.

This API allows useful policies:

ALLOW read_file under /workspace/project
ASK write_file under /workspace/project
DENY shell command matching a destructive pattern

Those examples are policy goals, not behavior supplied by a generic string matcher. The owning tool must parse the rule and compare it with normalized input. A security review should read matchRule(), checkPermissions(), and generateSuggestions() for every tool that receives non-null rule content.

Suggested rules need the same care. A human approval screen may offer a broad tool-level rule when the tool does not implement a narrower suggestion. Accepting that suggestion can turn one approved call into approval for every future input to the tool.

Mode names do not replace source-level checks

PermissionMode defines DEFAULT, ACCEPT_EDITS, EXPLORE, BYPASS, and DONT_ASK. The names are useful, but the implementation order decides the result.

At this commit, BYPASS is a fallback after deny rules, ask rules, and tool self-checks. An earlier decision still wins. An application should therefore test the exact tools it intends to bypass instead of reading BYPASS as an unconditional first branch.

DONT_ASK converts the default fallback ASK to DENY when no user is available. A matching explicit ask rule returns earlier, before that fallback conversion. An unattended job should avoid explicit ASK rules unless its outer runtime has a deterministic timeout or converts unresolved confirmation into failure.

setPermissionMode(userId, sessionId, mode) replaces the mode in the session's PermissionContextState, rebuilds the cached engine, and saves the state. The new mode applies to later calls. An in-flight call keeps the engine with which it started.

These details are worth recording in an operational policy. A mode name is too small to describe rule precedence, custom tool checks, and behavior during a rolling deployment.

How ASK enters the ReAct loop

The Agent evaluates tool calls with concatMap, which keeps permission decisions in model order. It divides the result into pending ASK calls and automatically denied IDs.

Denied calls never reach Toolkit.callTools(). The Agent creates ToolResultBlock values with DENIED state so the model can see what happened. Calls that require approval become ToolUseBlock values in ASKING state. The Agent emits RequireUserConfirmEvent and returns with GenerateReason.PERMISSION_ASKING.

The application displays the tool name, input, and any suggested rules. On the next call it sends a ConfirmResult for each pending tool. Confirmation can approve the input, replace it with a reviewed version, or reject it. Approved blocks move to ALLOWED; rejected blocks receive a denied result.

One persistence detail deserves attention. In this source snapshot, accepted suggested rules are added to the current PermissionEngine. applyConfirmResults() does not copy them into PermissionContextState. When a configured state store reloads a session on a later call, the Agent rebuilds the engine from that stored context. An application should not assume that an accepted suggestion is durable across reloads without verifying or persisting the rule itself.

That distinction matters for user interfaces. A checkbox labeled remember this decision should correspond to durable policy storage, not only a mutation of the current JVM cache.

Permission is not input validation

An ALLOW result only answers the policy question. The tool executor still checks whether the tool is active and validates input against its schema. Preset parameters are merged after model input, and preset values win so the model cannot replace framework-controlled fields.

File tools also need path validation at execution time. FileToolUtils.validatePath() resolves relative paths against a base directory, normalizes the result, and rejects paths outside that base. ToolBase.isDangerousPath() can detect configured sensitive filenames and directory segments, including a resolved symlink target.

The dangerous-path helper is protected utility code. The default ToolBase.checkPermissions() returns PASSTHROUGH and does not call it automatically. A custom file tool must use the helper in its own permission check if that behavior is required. Annotation fields that populate dangerous file lists do not remove the need to verify the actual check path.

Shell validation is another boundary. ShellCommandTool uses a platform command validator and optional command allowlist during execution. Permission rules can decide who may request the shell, while command validation decides whether this command shape is accepted. Both checks should produce an audit record with normalized input and the final decision.

Permission is not isolation

Permission logic runs before a tool, but a programming error or incomplete rule may still approve harmful work. Harness sandboxing moves filesystem and command execution into an isolated environment.

IsolationScope controls which calls share a persistent sandbox slot:

| Scope | State sharing | |---|---| | SESSION | One slot per session ID | | USER | One slot per user ID, with session fallback when user ID is absent | | AGENT | One slot for all users of the Agent | | GLOBAL | One slot for the workspace or store instance |

USER is the default. The broader scopes are useful for shared workspaces, but they also increase the number of callers that can affect the same files.

The source describes sandbox sharing as sequential reuse of persisted state, not automatic live-container sharing. Concurrent calls for the same scope may run in separate containers and write back to the same slot. Without a guard, the last persisted snapshot wins.

SandboxExecutionGuard covers the window from acquire through release. Its default is a no-op. Shared scopes in a multi-replica deployment need a real guard, such as a Redis lease or database lock, if concurrent last-write-wins behavior is unacceptable.

Conversation state and workspace state are separate

Agent state persistence does not preserve files inside a stopped container. Sandbox recovery uses a SandboxSnapshotSpec.

The default NoopSnapshotSpec does not persist workspace state between session stops. A new start initializes a fresh workspace from the manifest. Local, object-storage, Redis, or JDBC snapshot implementations can preserve workspace data for later resume.

A distributed deployment therefore has at least three state concerns:

AgentStateStore       -> conversation, permission, tool, and task state
Sandbox snapshot      -> files and environment needed by the next sandbox
Execution guard       -> exclusive access to a shared persistent slot

Configuring one does not imply the other two. A distributed Agent state store cannot restore packages installed inside a vanished container. A remote snapshot cannot stop two replicas from racing on the same user workspace.

A security review based on behavior

A useful review starts with each side-effecting tool and follows the request to the operating system or external service.

1. Confirm whether the full permission engine or lightweight compatibility path is active.
2. Record which deny, ask, and allow rules can match the tool and what ruleContent means.
3. Read the tool's checkPermissions(), matchRule(), and suggested-rule implementation.
4. Verify schema, path, command, and business validation after approval.
5. Run the tool in the narrowest practical sandbox scope.
6. Configure durable snapshots only when workspace recovery is required.
7. Add a real execution guard when several callers share one sandbox slot.
8. Log the normalized input, decision source, human response, tool result, and external operation ID.

Then test bypasses. Use path traversal, symlinks, case changes, command composition, duplicate confirmation, stale rules, missing user identity, concurrent requests, and worker restart. The test should check the actual side effect, not only the permission message.

The final security claim should be narrow and testable. For example: this session may write under one workspace after approval, the command passes an allowlist, execution occurs in a session-scoped container, and duplicate operation IDs are rejected. That statement is much more useful than saying the Agent runs in secure mode.

Source files

• PermissionEngine
• PermissionContextState
• PermissionRule
• ToolBase
• ReActAgent
• IsolationScope
• SandboxIsolationKey
• SandboxExecutionGuard