Investigation: CLI compatibility and API breakage check for PR #2133

[enyst]

Context

Review of PR comment #2133 (comment).

Link verification

• OpenHands-CLI PR Refactor: Move state persistence from callback to direct agent.py calls #548 (feat: implement Ctrl+C pause/interrupt flow and update SDK hash OpenHands-CLI#548): open, draft; updates SDK git rev to b9780a1f... and bumps agent-client-protocol to >=0.8.1.
• SDK PR fix(terminal): filter terminal query sequences from captured output #2334 (fix(terminal): filter terminal query sequences from captured output #2334): open; mergeable_state reported as blocked at time of check.

API breakage (Griffe)

• Workflow: .github/workflows/api-breakage.yml (runs SDK programmatic API (Griffe) with SDK_INCLUDE_PATHS=openhands.sdk).
• Check run for PR feat: Add ACPAgent for Agent Client Protocol integration #2133: success. Run: https://github.com/OpenHands/software-agent-sdk/actions/runs/22240640198/job/64343156160.
• Current workflow config limits runs to rel-* release branches, but this PR still had a successful run recorded.
• The methods mentioned in the comment (set_config_option, fork_session, new_session/load_session signature changes, acp.schema renames) are not present in the SDK public API exported via openhands.sdk.__all__. They appear to be CLI- or dependency-specific rather than SDK public surface, so Griffe did not detect a public API break.
• Opinion: Unless we intend third-party SDK users to implement or depend on those CLI-facing hooks, I’d avoid adding them to the SDK public API for now. If we do want them public, we should formalize them on AgentBase and document a deprecation path.

Release PR

• Latest SDK release PR: Release v1.12.0 #2302 – Release v1.12.0 (merged 2026-03-05).

CLI SDK version

• OpenHands-CLI main pins openhands-sdk==1.11.5, openhands-tools==1.11.5, openhands-workspace==1.11.1 in pyproject.toml.

Answer to comment question

• With CLI pinned to 1.11.5, yes: SDK fixes/features on main (post-breaking changes) are effectively blocked for CLI use until CLI is updated.
• If CLI upgrades to SDK 1.12.0 (or merges PR #548), the compatibility note should no longer apply and PRs like fix(terminal): filter terminal query sequences from captured output #2334 should be testable with the CLI.

[enyst]

Here’s what I found about the ACP “CLI‑hooks” surface and where it actually lives today:

What the CLI uses (ACP server side)

The CLI does not use the SDK’s ACPAgent. Instead, it implements the ACP server interface directly via the agent-client-protocol package:

• BaseOpenHandsACPAgent in openhands_cli/acp_impl/agent/base_agent.py subclasses acp.Agent
• It implements protocol methods like initialize, new_session, load_session, set_session_mode, etc.
• These are ACP protocol methods, defined by agent-client-protocol, not by the SDK.

So the “hooks” you’re thinking of are ACP protocol surface, not SDK surface.

What the CLI uses from the SDK

The CLI’s ACP server does use SDK objects, but mostly conversation APIs that are already public:

• BaseConversation, Message, ConversationExecutionStatus
• Methods like send_message, pause, set_confirmation_policy, set_security_analyzer, reject_pending_actions, run, close

All of these live on BaseConversation / Conversation, and those classes are already exported in openhands.sdk.__all__, so they’re already public SDK API.

Why Griffe didn’t flag it

The methods cited in the original comment (set_config_option, fork_session, etc.) are not in the SDK public API. They’re part of ACP protocol changes or CLI‑side abstractions. That’s why Griffe didn’t see a public break.

Should we make ACP “hooks” public in the SDK?

If the goal is to support third‑party ACP server implementations built on the SDK, we could do that — but it would require an explicit API decision:

Possible path if we want this public:

• Add a dedicated openhands.sdk.acp module
• Re-export a stable wrapper around acp.Agent + key schema types
• Document it and treat agent-client-protocol as a first‑class SDK dependency
• Commit to deprecation/back‑compat policy for ACP protocol changes

Trade‑off: we’d be taking ownership of API stability for a protocol that currently lives outside the SDK.

---

Bottom line:
Right now, the ACP “hooks” are protocol-level API, not SDK API. The only SDK surface the CLI depends on is already public (Conversation, BaseConversation, etc.). If we want ACP server integrations to be a supported SDK feature, we should explicitly wrap/export it — otherwise it stays as a CLI + agent-client-protocol concern.

If you want, I can draft a concrete proposal for a openhands.sdk.acp module and what it would expose.