feat(provider): add onPermissionRequest callback option

[DaniAkash]

Summary

Upstream: openclaw/acpx#299 — the runtime PR this provider change consumes.

Forwards onPermissionRequest from AcpxProviderSettings into the underlying AcpRuntimeOptions, so hosts can intercept per-call permission requests with their own UI. Returning undefined from the callback (or omitting it entirely) falls through to the existing permissionMode resolver — zero behavior change for existing consumers.

Driven by downstream BrowserOS chat work that wants inline approve/deny CTA cards instead of an up-front mode gate. The mode gate is too coarse for that flow — approve-reads silently denies writes (codex's apply_patch aborts with no signal), approve-all skips approval entirely. A per-call callback is the right primitive.

const provider = createAcpxProvider({
  agent: 'codex',
  cwd: '/path/to/repo',
  permissionMode: 'approve-reads', // fallback for unhandled cases
  onPermissionRequest: async (req, { signal }) => {
    const decision = await myUi.prompt({
      title: req.raw.toolCall.title,
      kind: req.inferredKind,
    })
    return decision // undefined falls through to the mode resolver
  },
})

What changed

File	Change
package.json	Version 0.0.4 → 0.0.5. acpx peer-dep + dev-dep raised to >=0.8.0 (the upstream version that ships onPermissionRequest on AcpRuntimeOptions via openclaw/acpx#299).
src/types.ts	Re-export AcpPermissionRequest + AcpPermissionDecision from acpx/runtime; add onPermissionRequest to AcpxProviderSettings with the documented signature and doc-comment.
src/provider.ts	Thread the option through buildRuntimeOptions() (one line).
src/index.ts	Re-export the two new types.
README.md	Replace the "Permissions are mode-based" limitation bullet with a fall-through explanation; new ## Per-call permissions section with the full callback contract.
test/unit/provider.test.ts	NEW — three tests using bun:test mock.module('acpx/runtime') to intercept createAcpRuntime and assert on the options bag: (1) callback forwards into AcpRuntimeOptions, (2) absent when not configured, (3) pre-built runtime: option skips runtime construction entirely.
test/e2e/permission-callback.test.ts	NEW — opt-in e2e contract test that spawns a real codex-acp process. Asserts the wire-level permission round-trip end-to-end: callback fires with a correctly-shaped AcpPermissionRequest, and the agent honours reject_once, allow_once, and undefined fall-through outcomes. Gated behind SMOKE_AGENTS=codex so it stays out of CI.

Test plan

• bun run lint clean.
• bun run typecheck clean (passes against the now-published acpx@0.8.0).
• bun run fallow clean.
• bun test — 266 pass / 24 skip / 0 fail across the monorepo (290 tests, 30 files; the three new unit tests are part of the 266; the new e2e test is in the 24 skipped because SMOKE_AGENTS is unset).
• SMOKE_AGENTS=codex bun test packages/acpx-ai-provider/test/e2e/permission-callback.test.ts — 3 pass / 0 fail against a real codex 0.130.0 instance, ~42s.
• bun run build clean (ESM + .d.ts).

Coordination

This PR ships alongside two sibling provider features that all target 0.0.5:

• #19 — getModels() helper
• #23 — sessionOptions forwarding

Whichever lands first wins 0.0.5; the other two will need a follow-up bump (0.0.5 → 0.0.6 → 0.0.7) and a one-line package.json rebase to resolve the version conflict. All three are independent on the code side.

[Copilot]

Pull request overview

Adds per-call permission callback support to acpx-ai-provider, forwarding onPermissionRequest into the underlying ACP runtime and documenting/testing the new host-interception flow.

Changes:

• Adds onPermissionRequest to provider settings and exports the related permission request/decision types.
• Threads the callback into runtime construction and documents per-call permissions.
• Bumps acpx dependency requirements and adds unit/e2e coverage for callback forwarding and behavior.

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
packages/acpx-ai-provider/src/types.ts	Adds callback option and permission type exports.
packages/acpx-ai-provider/src/provider.ts	Forwards the callback into AcpRuntimeOptions.
packages/acpx-ai-provider/src/index.ts	Re-exports new permission-related types.
packages/acpx-ai-provider/README.md	Documents per-call permission callback usage and fallback behavior.
packages/acpx-ai-provider/package.json	Bumps package and acpx dependency versions.
bun.lock	Updates locked acpx dependency metadata.
packages/acpx-ai-provider/test/unit/provider.test.ts	Adds unit tests for runtime option forwarding.
packages/acpx-ai-provider/test/e2e/permission-callback.test.ts	Adds opt-in Codex e2e permission callback contract tests.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.