compat(agent): track built-in Harness Room-approval behavior after #286 #297

Context

#286 is complete and closed. Agent v0.5.24 now has a production-verified generic Room-native ACP approval path using the built-in Claude Harness:

real Claude tool request
→ ACP session/request_permission
→ production Room approval card
→ Human Allow / Deny
→ exact native option returned
→ same Claude turn continues or is denied

This follow-up does not reopen the Room approval architecture. It tracks truthful per-Harness behavior and public documentation after #286.

Current compatibility matrix

Codex upstream references:

• Sandbox and approval policies from config.toml are ignored agentclientprotocol/codex-acp#310
• Read-only mode is no longer available in JetBrains ACP integration agentclientprotocol/codex-acp#450
• Default Agent prompts overwrite configured writable roots and sandbox permissions agentclientprotocol/codex-acp#477
• feat(sandbox): support launch-configured permission profiles agentclientprotocol/codex-acp#357
• feat: expose configured permission profiles as modes agentclientprotocol/codex-acp#395

Immediate documentation follow-up

Update the public Agent permissions and approvals documentation so it states the shipped behavior truthfully:

• Claude is production-verified for Room-native ACP approval;
• other Harnesses may execute under their own native/default policy and therefore never show a Room card;
• absence of a Room approval card is not automatically a Free4Chat failure;
• Codex currently has a known upstream bridge/policy limitation;
• Pi's current no-prompt/high-trust behavior is acceptable and does not need a fake approval layer;
• OpenCode/Hermes remain compatibility evidence, not blockers for the generic feature.

Keep the docs user-oriented. Do not turn the public page into an implementation matrix dump.

Durable permission choices

The Claude production test also exposed an important presentation boundary:

Deny
Allow Once
Always Allow

A durable native option may have Harness-defined lifetime/storage semantics (session, project-local settings, user settings, etc.).

Free4Chat must not infer those semantics from the button label or kind. Public docs should say so explicitly.

The current generic feature remains correct because it forwards the exact native option id unchanged. A future UI improvement may display native scope/effect metadata when the Harness already provides a bounded safe presentation, but this issue does not require inventing a Free4Chat permission taxonomy.

Final probe results

OpenCode

OpenCode 1.18.18 was tested with opencode acp --pure and a disposable per-process OPENCODE_CONFIG_CONTENT policy setting bash, edit, and external_directory to ask.

A harmless command produced a real production Room approval card with the full command and native options Allow once / Always allow / Reject. Ordinary Human chat yes did not approve the pending request. Allow once resumed the same turn and produced the expected marker contents; Reject prevented a second marker from being created; a later ordinary turn succeeded.

Classification: ROOM APPROVAL VERIFIED.

Hermes

Hermes Agent v0.21.0 (2026.8.31) was verified to contain make_approval_callback and make_acp_edit_approval_requester ACP relay code. Under the tested default/native policy, a harmless shell write executed directly, produced the expected marker, and emitted neither a local approval prompt nor ACP session/request_permission.

Classification: NATIVE POLICY / NO ROOM APPROVAL REQUIRED FOR THE TESTED PATH.

Non-goals

• changing ux/security(agent): Room-native ACP approval for resident Harnesses #286 Room approval semantics;
• requiring every built-in Harness to ask before tool execution;
• adding a Free4Chat universal permission DSL;
• adding RBAC/owners/approval routing;
• adding a CLI approval inbox;
• patching/forking Codex ACP merely to force prompts;
• weakening Pi/Hermes/OpenCode native policies to manufacture approval cards.

Acceptance

• public permission docs reflect the production-verified Claude path;
• docs explain that Harnesses may legitimately run under native/default policies without Room approval;
• durable native choices are documented as Harness-defined in scope/effect;
• OpenCode is classified by one narrow real probe;
• Hermes is classified by one narrow real probe;
• Codex remains tracked upstream unless a concrete Free4Chat-specific defect appears;
• Pi remains acceptable under its observed native/default no-prompt behavior;
• no changes are made to the generic Room approval architecture without new evidence.