feat(middleware): add on_check_permission hook

[Miracle778]

Note

Scope update

This PR originally implemented structured decision-path observability and
separate read-only hooks for permission decisions and confirmations.

Following the maintainer feedback in #2000, the PR has been narrowed to one
standard onion-style on_check_permission hook. The structured evaluation
types and confirmation hook have been removed. Decision-path observability
will be discussed separately.

AgentScope Version

2.0.4.post1

Description

Closes #2000.

Adds a standard onion-style on_check_permission middleware hook around
permission checking.

The hook provides a public extension point for both permission auditing and
application-owned authorization policies, while keeping
PermissionEngine.check_permission as the sole built-in engine interface.

Background

AgentScope performs permission checking after tool resolution and input
validation, but before on_acting.

This means existing middleware cannot observe the permission decision itself:

• ASK and DENY return before on_acting;
• ALLOW reaches on_acting, but only as an already-permitted execution;
• application policies based on user, role, or tenant cannot be composed around
  the built-in permission check through a public middleware interface.

Changes

on_check_permission middleware hook

Adds the following hook to MiddlewareBase:

async def on_check_permission(
    self,
    agent: Agent,
    input_kwargs: dict,
    next_handler: Callable[..., Awaitable[PermissionDecision]],
) -> PermissionDecision:
    ...

The hook runs after tool resolution and input validation, and before Agent
consumes the returned decision.

Its input_kwargs contains:

• tool_call;
• the resolved tool;
• parsed and validated tool_input.

As a standard middleware onion, a middleware may:

• delegate with next_handler(**input_kwargs);
• observe or replace the downstream decision;
• return a decision without delegating, short-circuiting the remaining chain.

The built-in PermissionEngine.check_permission is the innermost handler.
With no permission middleware registered, Agent follows the existing direct
engine path.

Confirmed tool calls

A tool call resumed after user confirmation still traverses
on_check_permission immediately before execution.

The innermost handler returns the already-confirmed ALLOW without re-evaluating
the built-in engine. This keeps application policies and auditing active while
preserving the existing confirmation behavior.

Input isolation

The middleware chain receives copies of tool_call and tool_input.

Middleware may forward modified copies to downstream permission middleware or
the built-in permission check, but those changes do not alter the tool call or
input eventually executed by Agent.

Runnable example

Adds examples/permission_middleware_service/ with:

• PermissionAuditMiddleware, which records the final decision returned by
  the complete permission chain;
• UserToolPolicyMiddleware, which denies PermissionDemoTool for a
  configured application user before invoking the built-in engine;
• a side-effect-free PermissionDemoTool covering ASK, DENY, and ALLOW;
• bilingual README files with setup instructions, security boundaries, and
  screenshots.

The example demonstrates both primary uses of the hook:

1. observing the final permission decision for audit logging;
2. extending authorization with an application-owned per-user tool policy.

Tests

Tests cover:

• the no-middleware compatibility path;
• middleware detection and registration;
• onion execution order;
• observing final ASK, DENY, and ALLOW decisions;
• replacing a downstream decision;
• short-circuiting before the built-in engine;
• forwarding modified permission-check inputs;
• exception propagation;
• consumption of middleware-returned decisions by the tool lifecycle;
• confirmed calls traversing middleware without engine re-evaluation;
• the audit and per-user policy examples.

Backward compatibility

• PermissionEngine.check_permission remains the sole engine interface.
• Existing permission modes, rules, and PermissionDecision semantics are
  unchanged.
• Applications without on_check_permission middleware retain the existing
  execution path.
• No AgentEvent, message, storage, or UI schema is changed.

Security boundary

A middleware that replaces or short-circuits a permission decision becomes part
of the application's trusted authorization boundary.

Returning without calling next_handler intentionally bypasses the built-in
permission engine for that call. This behavior is documented explicitly in the
hook contract.

Out of scope

• Permission-decision transformation tracing.
• A dedicated permission-confirmation hook; confirmation input remains
  observable through on_reply.
• Changes to built-in permission modes or rule evaluation.

How to test

python -m pytest \
  tests/middleware_test.py \
  tests/permission_middleware_example_test.py \
  -q

pre-commit run --files $(git diff --name-only origin/main...HEAD)

Run the example with Redis and an LLM configured:

cd examples/permission_middleware_service
python main.py

Then connect the existing examples/web_ui frontend to
http://localhost:8000.

Checklist

• An issue has been created for this PR
• I have read the CONTRIBUTING.md
• Docstrings use the project style
• Tests cover the middleware contract and runnable example
• The example includes English and Chinese documentation
• Code is ready for review

[Premsenareddy]

I pulled this branch locally and did a quick validation pass for #2000.

Passing:

.venv/bin/python -m pytest -p no:cacheprovider tests/permission_engine_test.py tests/permission_mode_test.py tests/middleware_test.py tests/agent_basic_test.py tests/permission_audit_example_test.py -q
# 152 passed in 1.13s

One thing that looks pending before review/merge: file-scoped repo pre-commit currently fails locally:

.venv/bin/pre-commit run --files src/agentscope/agent/_agent.py src/agentscope/middleware/_base.py src/agentscope/permission/__init__.py src/agentscope/permission/_engine.py src/agentscope/permission/_evaluation.py tests/middleware_test.py tests/permission_audit_example_test.py tests/permission_engine_test.py tests/permission_mode_test.py

Observed failures:

• add-trailing-comma / black rewrites tests/middleware_test.py
• mypy reports missing type annotations in the new middleware/permission tests, plus module_from_spec receiving ModuleSpec | None in tests/permission_audit_example_test.py
• pylint reports missing test docstrings in tests/permission_audit_example_test.py and one unnecessary-dunder-call

The behavior shape looks good from the first pass; this is mostly local gate hygiene since GitHub currently only shows the lightweight notify check on the PR.

[Miracle778]

Thanks @Premsenareddy for the validation pass. The pre-commit issues you flagged are fixed in a6e1db0b:

• add-trailing-comma / black — reformatted tests/middleware_test.py.
• mypy (--disallow-untyped-defs) — added type annotations to the nested middleware test subclasses and the example hook overrides (on_permission_decision / on_acting / on_permission_confirmation); added assert spec is not None before module_from_spec.
• pylint — added Google-style docstrings to the permission_audit_example_test tests; replaced a direct __call__ invocation with a direct call (C2801).

pre-commit run --files <changed> now passes clean; pytest still passes (152 passed). No functional logic changed.

[DavdGao]

@Miracle778 Plz see comments on issue #2000

[DavdGao]

@Miracle778, thanks for the detailed implementation. A few points after reviewing the PR and our discussion in #2000:

1. Hook type: use onion pattern, not read-only notification

Suggest making the hook an onion-pattern hook (with next_handler) consistent with existing hooks like on_acting and on_reasoning, and naming it on_check_permission to match the existing check_permission method. This keeps the middleware system uniform and leaves room for future use cases beyond audit logging.

2. Remove PermissionEvaluation, PermissionResolution, and evaluate_permission

Adding a parallel abstraction layer on top of PermissionDecision is too much API surface for this change. Please remove:

• PermissionEvaluation dataclass
• PermissionResolution enum
• PermissionEngine.evaluate_permission() method

Keep check_permission as the sole engine interface.

3. Decision path observability: defer to a separate PR / issue

I agree that exposing the decision transformation path is valuable for debugging and attribution. However, this should not be part of this PR — let's keep this PR focused on the middleware hook only. Please open a new issue to discuss how to record decision paths (e.g., whether to add fields to PermissionDecision or another approach). We can design that separately.

4. on_permission_confirmation

As discussed, on_reply can already observe raw confirmation events. Let's defer this hook to keep the initial scope focused.

[Miracle778]

Thanks @DavdGao, understood. I’ll revise this PR to:

• replace the read-only notification with an onion-pattern on_check_permission hook;
• keep PermissionEngine.check_permission as the sole engine interface;
• remove PermissionEvaluation, PermissionResolution, and evaluate_permission;
• remove on_permission_confirmation;
• defer decision-path observability to a separate issue/PR.

I’ll update the implementation, tests, example, and PR description accordingly.

[Miracle778]

@DavdGao The requested scope update is now complete.

The current revision:

• adds a standard onion-style on_check_permission hook;
• keeps PermissionEngine.check_permission as the sole engine interface;
• removes PermissionEvaluation, PermissionResolution, and
  evaluate_permission;
• removes the dedicated confirmation hook;
• defers decision-path observability to a separate issue;
• updates the tests and runnable example to demonstrate both audit logging and
  application-owned permission policies.

I have also updated the issue and PR titles and descriptions to match the
revised scope.

The latest example includes a bilingual README and screenshots covering ASK
confirmation, permission audit logging, and per-user tool denial.

Ready for another review when you have time. Thanks!

[DavdGao]

lgtm

[babyblueviper1]

Built and live-verified a small on_check_permission middleware exercising this hook for a use case the mode table doesn't currently cover: DONT_ASK converts every ASK (including bypass-immune safety asks) to DENY with no recourse, and BYPASS skips safety asks entirely — there's no built-in middle path for "unattended run, but a genuinely risky action still gets a real second opinion instead of a blanket deny."

The middleware calls next_handler first; if the resulting decision is ASK, it sends the tool call to a hosted review API (I used my own — api.babyblueviper.com/review, an independent signed-verdict service, but the pattern works with any reviewer) and converts to ALLOW only on a clean, high-confidence verdict (attaching the verdict's audit reference to decision_reason), otherwise falls through to DENY — same fail-closed behavior as DONT_ASK today, just with a real second opinion instead of an automatic denial.

Tested live against both cases from the tool description above (real HTTP calls, not mocked):

BENIGN case      -> PermissionBehavior.ALLOW | Approved by independent review (confidence=0.99).
DESTRUCTIVE case -> PermissionBehavior.DENY  | ... independent review did not clear the bar: verdict=reject confidence=1.0

Code: https://gist.github.com/babyblueviper1/cd6e4666bcf81f3ad139450fba53a0e2 (happy to open a PR against examples/ instead if that's preferred)

Small thing I noticed while building this — the PR description above lists examples/permission_middleware_service/ (PermissionAuditMiddleware, UserToolPolicyMiddleware, bilingual READMEs) as part of this change, but gh api repos/agentscope-ai/agentscope/pulls/2001/files only shows _agent.py, middleware/_base.py, and middleware_test.py in the merged diff — looks like the example got trimmed along with the scope-narrowing mentioned in the note at the top, but the description wasn't updated to match. Did that example land somewhere else, or is it still on the todo list?