Experimental agent API: bounded inspection and guarded prompt submission

[aakhter]

Following the design request on PR #694, I propose shipping the three new agent operations as experimental, across both the CLI verbs and HTTP routes. The PR now explicitly documents the stability exception, including the /api/v1 paths and their /api aliases. This avoids committing to their final shape while we gain usage experience.

The use case is an agent coordinating another Codeman session: read a bounded amount of evidence, prepare a prompt without Enter, inspect it, then submit that exact prompt once. Existing send, read, and wait remain useful, but they do not provide a resumable evidence cursor or a server-checked receipt binding preparation to submission.

Proposed contract

Operation	Proposed route	Contract
Inspect	GET /api/v1/sessions/:id/inspect	Bounded UTF-8 evidence, explicit source and identity, activity observations, and an opaque cursor where incremental reading is supported.
Stage	POST /api/v1/sessions/:id/stage	Type a single printable line without Enter into a verified empty local Codex composer; return a short-lived receipt and hash.
Submit	POST /api/v1/sessions/:id/submit	Consume that receipt and conditionally dispatch Enter once after rechecking the exact composer, caller, session, lifecycle, input revision and geometry.

Inspection uses strictly attributed local Codex JSONL where available and an explicitly labeled, nonincremental pane snapshot otherwise. Native attribution proves the evidence file's identity; it does not claim authoritative tracking of an in-CLI thread switch. Cursors expire and can be invalidated by source or lifecycle changes. Resizing alone should not invalidate an inspection cursor.

Stage/submit initially support only a recognizable, unwrapped local Codex composer. They refuse uncertain captures, active work, modal screens, remote/container sessions and unsupported modes. Width is checked before typing. Receipts hold hashes and ephemeral identity, not prompt content. A receipt is consumed on any owned submit attempt, including a refusal or ambiguous failure. Success means Enter was dispatched once; it does not prove that the native CLI accepted or completed the request. There is no automatic submission retry.

Recovery is part of the contract: a stage failure or refused/ambiguous submit may leave an unsent draft. Receipts cannot be reused, and ordinary send appends to and submits existing composer text. Inspection may return JSONL rather than the unsent composer, so recovery requires a fresh terminal capture. Only a definitely unsent, fully visible, input-ready draft with exclusive writer access may be cleared through the existing raw input path without Enter (or manually), followed by verification that the composer is empty and a fresh stage. An accepted, working, modal or uncertain state must be observed rather than replayed. There is currently no guarded cancel operation.

The three operations share existing authentication and ownership checks. The CLI remains an HTTP client; there is no additional transport or direct tmux fallback in the client. Inspection output and pane text remain observations, never authorization.

Proposed experimental scope

The new codeman agent inspect, stage and submit verbs, their flags, the three route paths, payloads and behavior may change or be removed in minor or patch releases. Callers should pin a compatible Codeman version. Existing authentication, ownership and shared response-envelope rules continue to apply; existing agent commands and other API routes keep their current stability guarantees. Promotion to stable requires an explicit documented decision.

I propose retaining the dedicated routes for the experimental phase: bounded evidence and a two-phase receipt lifecycle have different validation and failure semantics from ordinary input. There is no additional feature flag in this proposal; the CLI help, README, API reference, versioning policy and packaged skill all identify the experimental scope.

Does this experimental boundary address the API concern, or would you prefer a different route organization before merge? The PR leaves these paths available for revision rather than treating them as a stable contract.

The implementation and tests are in PR #694. All concrete correctness findings from the review are addressed; the previous full suite passed 12,372 tests with 12 skipped. The latest follow-up only labels and documents the experimental contract and updates CLI help.

[Ark0N]

Thanks @aakhter for taking this to a Discussion, and sorry for the wait.

Short version: yes, an experimental label answers the stability concern, and the three dedicated routes can stay as they are. Before merge, I'd like one change: put them behind an opt-in setting.

The label is already in the policy. docs/versioning-policy.md ("What SemVer does NOT cover", item 3) excludes "anything labeled experimental in the UI or docs". Your new "Experimental agent coordination" subsection is a case of that rule, not a new exception, so please frame it that way. On paths: the rewrite in src/web/server.ts serves every /api/* route as /api/v1/* as well, so no route can stay out of /api/v1. An experimental path segment would make every caller rewrite its URLs when the route is promoted. Keep inspect, stage and submit where they are.

Dedicated routes are the right shape. codeman agent send --no-enter already types without Enter, so typing isn't what's missing. What's missing is the receipt and the recheck right before Enter, and neither fits the clientId/seq contract of POST /api/v1/sessions/:id/input or GET .../terminal.

Opt-in. When Codeman ships an opt-in server surface, it is usually a synced setting, default OFF, whose routes answer 403 FORBIDDEN with a message naming the setting while it is off. The closest examples are cliManagementEnabled (src/web/routes/cli-registry-routes.ts) and mcpSyncEnabled (src/web/routes/mcp-sync-routes.ts). The policy's own examples, Gesture Control and Agent Teams, are opt-in too. Without a gate, "experimental" exists only in docs that someone writing automation may never read. One setting covering all three routes is enough, and the CLI verbs can pass the 403 through verbatim like the other server errors they already show.

What the label covers. It covers the three verbs and their routes. The changes underneath them run for every session, so I'll review those as stable behavior: the input revision tracking in write() and writeViaMux() in src/session.ts, the SubmitVerifier re-press now going through writeViaMux, and the -- operands in src/tmux-manager.ts. Your #677 makes that same -- change and is going into the next release, so please drop it from #694 when you rebase onto master after that.

Before promotion to stable, the guard should stop depending on Codex internals. Today it is gated on capabilities.transcript === 'codex-rollout', and src/agent-staging.ts hardcodes Codex's › and footer, even though Codex's composer glyph is already registry data (capabilities.workDetect.promptGlyph in src/config/cli-registry/stock.ts). Promotion needs a capability of its own, with a second CLI such as claude behind it. That's what will show whether the stage/submit shape holds.

Wiki page. docs/wiki/Driving-Codeman-From-An-Agent.md lists the three verbs without an experimental marker. Its new link ../api-reference.md#bounded-agent-inspection-and-guarded-input is broken in two ways. The wiki sync mirrors only docs/wiki/, so other wiki pages link to docs with full https://github.com/Ark0N/Codeman/blob/master/... URLs. And the heading is "Experimental bounded agent inspection and guarded input", so the anchor doesn't match.

Once the setting is in, together with the five small items from my last review on #694 (the wiki link is one of them), I'll do the next review pass there.