feat(middlewares): add permission middleware for tool call gating

[shentongmartin]

Summary

Problem	Solution
No built-in way to gate tool execution behind permission checks in the ADK middleware layer	Implement a permission.Middleware that intercepts tool calls with a user-defined BeforeToolCall evaluator, supporting Allow/Deny/Ask decisions with interrupt/resume for interactive approval

Key Insight: Framework Skeleton vs. Strategy Pattern

Inspired by Claude Code's permission system (7 modes, 8 rule layers, 5 parallel racers), but deliberately scoped as a framework skeleton rather than an opinionated strategy engine. The middleware provides the interrupt/resume plumbing; users supply the evaluation logic. This matches Eino's position as a general-purpose framework that must serve diverse product forms.

The critical design choice is the three-outcome model:

• Allow: Execute the tool (optionally with modified input via UpdatedInput)
• Deny: Return a formatted deny message as the tool result—crucially, this does NOT interrupt the agent loop. The LLM sees "Permission denied" and self-adapts, matching CC's battle-tested pattern.
• Ask: Trigger StatefulInterrupt to pause the agent loop, checkpoint state, and await external approval via ResumeWithParams.

Design Decisions

Why fail-closed for unknown decisions?

Unknown Decision values (e.g., a typo like "alow") produce a deny result rather than an error. This prevents fail-open security vulnerabilities—a permission system that accidentally allows unknown states is worse than one that blocks them.

Why error only for infrastructure failures?

BeforeToolCall returning error is reserved for infrastructure failures (rule store unreachable, network timeout). This aborts the agent loop. Permission denials use Decision: Deny instead, which keeps the agent loop running. This separation prevents conflating policy decisions with system failures.

Why re-interrupt on non-target resume?

When the runtime resumes a different tool but this tool was previously interrupted, it must re-interrupt to preserve its pending state. This supports parallel tool call scenarios where only one tool is approved at a time.

What Changed

File	Change
adk/middlewares/permission/permission.go	New package: Middleware struct, permissionGate logic, WrapInvokableToolCall/WrapStreamableToolCall, all supporting types (Decision, ToolCallDecision, AskInfo, AskState, ResumeResponse)
adk/middlewares/permission/permission_test.go	22 unit tests covering Allow/Deny/Ask/Unknown/Nil/Error paths for both invokable and streamable tool calls

How to Verify

go test -race -count=1 ./adk/middlewares/permission/...
golangci-lint run ./adk/middlewares/permission/...

---

摘要

问题	解决方案
ADK 中间件层缺少内置的工具调用权限控制机制	实现 permission.Middleware，通过用户定义的 BeforeToolCall 评估函数拦截工具调用，支持 Allow/Deny/Ask 三种决策，Ask 决策通过中断/恢复机制实现交互式审批

核心洞察：框架骨架 vs. 策略引擎

受 Claude Code 权限系统（7 种模式、8 层规则、5 路并行竞争）启发，但刻意定位为框架骨架而非固化的策略引擎。中间件提供中断/恢复的管道设施，用户自行实现评估逻辑。这符合 Eino 作为通用框架需服务多样产品形态的定位。

三态结果模型的关键设计：

• Allow：执行工具（可选通过 UpdatedInput 修改输入）
• Deny：返回格式化的拒绝消息作为工具结果——不中断 agent 循环。LLM 看到 "Permission denied" 后自行适应，沿用 CC 经过实战验证的模式。
• Ask：触发 StatefulInterrupt 暂停 agent 循环、持久化状态、等待外部通过 ResumeWithParams 回注审批结果。

设计决策

为何对未知决策采用 fail-closed？

未知的 Decision 值产生 deny 结果而非 error，防止 fail-open 安全漏洞。

为何 error 仅用于基础设施故障？

BeforeToolCall 返回 error 仅表示基础设施故障（如规则存储不可达），会中断 agent 循环。权限拒绝使用 Decision: Deny，保持 agent 循环正常运行，避免将策略决策与系统故障混淆。

为何非目标恢复时重新中断？

当运行时恢复其他工具而当前工具之前已中断时，必须重新中断以保留挂起状态，支持并行工具调用场景下的逐个审批。

[codecov]

Codecov Report

❌ Patch coverage is 95.00000% with 5 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (alpha/09@d7161f7). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
adk/middlewares/permission/permission.go	95.00%	4 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##             alpha/09     #966   +/-   ##
===========================================
  Coverage            ?   82.23%           
===========================================
  Files               ?      163           
  Lines               ?    20405           
  Branches            ?        0           
===========================================
  Hits                ?    16781           
  Misses              ?     2447           
  Partials            ?     1177           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.