Prove successful native Claude Code / Codex host sessions in Workbench #683

Priority and scope

P2 — native acceptance and qualification gap; PTY implementation is delivered. Follow-up to #675 and #600, preserving the install/cleanup fixes in #677/#678.

Audited commit: b435f7b9179271cbff81d3e40d14ee342cbd65dd.

Origin: owner-requested deep-dive, 2026-09-06. Expanded with the complete native acceptance and test-hardening criteria.

Problem

Fake-host tests establish useful PTY/transport/lifecycle behavior, not successful authenticated Claude/Codex model-driven tool-and-hook completion. The prior #675 acceptance run recorded Claude authentication and Codex usage-limit blockers; those are not successful native execution evidence.

The opt-in native-host-sessions.test.ts currently has two weaker conditions:

1. A requested native suite can skip a host when its --version invocation fails. enabled(host) combines the opt-in flag with executable availability and chooses it.skip otherwise.
2. Success requires only a correlated outgoing mcp.request whose summary includes tools/call. It does not require the matching successful response, expected tool value, or corresponding real hook.

A terminal launch, outgoing request, authentication refusal, usage-limit refusal, or all-skipped run must not be reported as completed native acceptance.

Existing implementation to preserve

HostSessionService is mounted by the production Workbench server and uses the PTY adapter and attached development installation. Existing fake-host acceptance remains valuable and should stay separately labelled. This issue does not request a host-session redesign or assert that the implementation is wholly missing.

Acceptance

• Default unauthenticated CI may explicitly skip native acceptance; it must label that outcome clearly.
• When AGENT_BUNDLE_NATIVE_HOST_CONTRACTS=1 requests native qualification, missing executable/authentication/quota prerequisites fail or explicitly block that qualification rather than producing an all-skipped success.
• Use a harmless deterministic plugin operation with a known result; avoid unnecessary dependence on a third-party service merely to prove host integration.
• For both logged-in Claude Code and Codex, attach the plugin through the supported native development-install path and complete a model-driven tool call.
• Match the outgoing tools/call to a successful response and expected value under the intended host/session identity.
• Observe a corresponding intended real hook receipt and correlate it with the session; do not substitute a test-injected receipt.
• Exercise cancellation, resize, restart, and termination; verify cleanup settles and no owned process or stale development registration remains after shutdown.
• Preserve native authentication, trust prompts, and permission behavior. No approval-bypass flags or synthetic success in place of native evidence.
• Record the repository SHA, exact host versions, relevant sanitized environment/prerequisite status, executed/skipped cases, and redacted evidence.
• Keep deterministic fake-host proof, real host installation/adoption proof, and authenticated tool/hook completion proof distinct in tests and documentation.

Test owners

• packages/agent-bundle/tests/native-host-sessions.test.ts
• packages/workbench/tests/sessions.e2e.test.ts
• packages/agent-bundle/tests/support/fake-host-cli/
• existing host-install/cleanup regression suites

Non-goals

No credentials in issues/logs/screenshots/artifacts, no weakening native permissions, no remote PTY service, no new host support, and no requirement to run paid authenticated model calls in every ordinary PR. Record a blocked run honestly rather than redefining acceptance to hide it.