feat(buzz-agent): gate LLM tool calls on session/request_permission

[wpfleger96]

Summary

buzz-agent now authorizes every LLM-issued MCP tool call through session/request_permission before it executes, instead of running tools unconditionally. The agent always asks; the client applies BUZZ_ACP_PERMISSION_POLICY and answers. buzz-agent never reads the policy — this keeps the policy decision on the client side, matching the layering of the other ACP harnesses, and avoids duplicating policy logic that would drift.

Broker

A crate-local PermissionBroker (crates/buzz-agent/src/permission.rs), owned by App for the connection lifetime, owns the full request-correlation lifecycle:

• Process-wide admission. A global Semaphore (BUZZ_AGENT_MAX_PENDING_PERMISSIONS, default 32, validated >= 1) is acquired before any correlation entry is inserted. This is the security bound: the per-turn tool semaphore is constructed fresh per turn and max_sessions is unbounded by default, so neither bounds simultaneously-outstanding asks process-wide.
• Abort-safe cleanup. A successful admission returns a PendingPermission lease that owns the admission permit and the correlation id. Its Drop synchronously removes the still-pending entry and releases the slot, covering task abort/panic that bypasses the normal run_prompt tail.
• At-most-once resolution. deliver claims (removes) the entry before waking the waiter, so each id resolves once and a later lease Drop is a no-op. Unknown/late ids are logged and dropped; only ids the broker minted (perm-<n>) are recognized.
• Single absolute deadline. Admission, request enqueue, and response wait all share one deadline (BUZZ_AGENT_PERMISSION_TIMEOUT_SECS, default 330s, validated >= 1), so a saturated call cannot outlive one timeout window even when a stalled writer blocks the enqueue. Cancellation races inside every wait — resolution never depends on the outer abort drain. A writer that dies mid-connection (stdout closed, or a blocking write that only surfaces its error at flush) is connection-fatal: it cancels all sessions, which resolves any ask waiting on a reply that can never be written.

Wire

request_permission_params (crates/buzz-agent/src/wire.rs) is version-aware, keyed on the protocol version negotiated at initialize and stored on App for the connection lifetime (never derived from a later mutable session field). v2 nests the tool call under subject: {type: "tool_call", toolCall} with top-level title/options; v1 uses the legacy top-level toolCall. No hybrid shape. Both offered options (allow_once, reject_once) carry optionId == kind, so the client's kind-based selection and this side's optionId-based predicate agree without a lookup table.

Gate

In each spawned tool task (crates/buzz-agent/src/agent.rs) the sequence is: acquire per-turn permit → argument-shape validation → broker admission + request + wait → cancellation recheck → emit_in_progress → mcp.call. Argument-shape validation is hoisted out of mcp.rs::do_call into validate_arg_shape so a malformed non-object argument is rejected locally without prompting for a call that could never execute.

Authorization is fail-closed, stated once in evaluate: execute IFF outcome.outcome == "selected" and the selected optionId equals the offered allow option. Every other shape (reject, cancelled, JSON-RPC error, malformed, unknown outcome, wrong/unknown option, timeout, wire-channel closure) denies with a synthetic tool error, and the turn continues.

Scope

Only LLM-issued MCP calls are gated. The built-in load_skill tool and call_hooks lifecycle calls (_Stop, _PostCompact) are exempt — they are not model-issued. readOnlyHint is never treated as a security boundary.

First cut ships allow_once/reject_once only; session-scoped grants are deliberately out of scope.

Related issue

Part of #4938. This PR and #5106 jointly implement the feature: #5106 is the client-side policy engine and permission cards; this PR is buzz-agent's asking side (session/request_permission). Neither closes #4938 alone.