feat: add onPermissionRequest callback for host-driven per-call gating

[DaniAkash]

What

Adds an optional onPermissionRequest callback to AcpRuntimeOptions and AcpClientOptions. When set, the host receives every per-call permission request the agent emits and can resolve it with its own UI; when unset (the default), behavior is identical to today's mode-based resolver.

Why

Today's permission surface (permissionMode + nonInteractivePermissions) is the right primitive for CLI use, but it's coarse for UI-driven hosts. A browser extension or IDE integration that wants to render an inline approve/deny card for apply_patch / shell / delete has to either:

• pick approve-all and skip approval entirely (unsafe), or
• pick approve-reads + nonInteractivePermissions: "deny" and watch every write get silently denied with no signal to the user.

A callback hook gives those hosts a clean, opt-in way to gate per-call without changing any defaults. The mode-based resolver remains the fallback — it still runs when the callback returns undefined, throws, or isn't set.

This change is purely additive: zero behavior change for any existing consumer.

Wire shape

The host receives:

type AcpPermissionRequest = {
  sessionId: string;
  raw: RequestPermissionRequest;       // full ACP request, untouched
  inferredKind: ToolKind | undefined;  // best-effort classification
};

…and returns:

type AcpPermissionDecision =
  | { outcome: "allow_once" }
  | { outcome: "allow_always" }
  | { outcome: "reject_once" }
  | { outcome: "reject_always" }
  | { outcome: "cancel" };

…or undefined to fall through. The decision outcomes map 1:1 to the SDK's PermissionOption["kind"] strings, so a new decisionToResponse helper in src/permissions.ts resolves them against whatever options the agent advertised — hosts never see optionId strings. The existing inferToolKind helper is now exported so hosts can render kind-aware UI without re-implementing the keyword classifier.

The gate sits at the top of AcpClient.handlePermissionRequest, before the existing resolvePermissionRequest call. Throws inside the host callback are caught + logged + fall through to the mode-based resolver, so a buggy host UI can't take down an agent turn. A per-session AbortSignal is exposed to the callback and aborts when the session is cancelled or the client is reset.

Tests

• 5 new unit cases in test/permissions.test.ts covering decisionToResponse option mapping (allow_once / allow_always preference order, fallback when one allow kind is absent, reject_once → reject_always fallback, cancel always cancels, missing-option cancel).
• 4 new integration cases in test/client.test.ts covering the gate (decision honored over mode, undefined fallthrough, thrown error fallthrough, abort signal aborts on session cancel).
• pnpm run check (format + typecheck + lint + build + viewer + test:coverage) passes locally — 613 tests, coverage 84.09 / 78.46 / 88.98 (above 83 / 76 / 86 thresholds).

Changelog

Entry added under ## Unreleased → ### Changes per AGENTS.md.

Driving consumer

acpx-ai-provider needs this to allow approve / deny options on the Vercel AI SDK so it can be integrated with UI components built with the Vercel AI SDK. Other tools can leverage it the same way.