From Chat to Control Plane: Making Agent Sessions Addressable and Orchestratable

Problem: Sessions Trapped Inside Terminals

Teams routinely run five or more agent sessions against the same repository — one refactoring a core module, another fixing failing tests, a third exploring dependencies, others idle or stalled. The friction comes not from the sessions themselves but from how they are controlled: to intervene in any session you must locate its terminal, step inside, and type in the chat. No external channel can tell a session "stop," "switch directories," or "here is the latest build log." The conversation is the only control path, and it is private to each session.

Solution: A Control Plane for Agent Sessions

Recent tooling breaks this limitation by treating a running session as an addressable, externally writable, orchestratable runtime object. Three capabilities combine to form the control plane:

Addressing : Sessions get stable, human-readable names that persist with metadata (working directory, branch, model). A name like "refactor-core" makes "send a message to that refactoring session" an executable command, not a description.

External writes : A command-line API injects messages into any local or remote session from outside; large payloads (e.g., a full CI build log) are sent via file. The terminal is no longer the sole input gateway.

Lifecycle visibility : An overview command ( codex agents) renders a table of all sessions showing state (waiting for input, working, ready), working directory, and branch. A session stuck on input becomes an observable "need input" state that a scheduler can act on.

Concrete daily operations illustrate the shift:

codex queue --session "refactor-core" --text-file build.log   # deliver a message from outside
codex agents                                                  # tabular view of all sessions
@refactor-core look at this new failure                         # one session references another

Together these turn a session from a terminal-private chat buffer into an identity-bearing, metadata-carrying, externally readable/writable runtime object. The chat loop remains but becomes the data plane.

Control Plane vs. Data Plane

This split mirrors earlier infrastructure evolution. Database admins once "logged in" to operate instances; later connection pooling, backup, and monitoring were extracted into a management plane independent of any single connection. Server ops moved from per-machine SSH to a unified control plane. Agent sessions follow the same path: the model's "read–think–tool–observe" loop is the data plane; where a session runs, whether it should stop, who may write to it, and what state it is in belong to the control plane.

Separating the layers unlocks orchestration. An external orchestrator no longer masquerades as a chat user; it enqueues messages, subscribes to state changes, and throttles low-priority sessions. CI pipelines benefit directly — feeding test results to the session fixing the corresponding bug becomes a natural closed loop. Inter-agent collaboration changes flavor: one task @-references another running session, communicating by address rather than wrapping the peer as a tool call, while each retains its own state, directory, and history. Orchestration shifts from "prompt the model to arrange subtasks" to "schedule a fleet of real running tasks from outside."

Engineering Challenges the Control Plane Must Solve

Session Metadata Must Survive Independently

Managing a session as an object demands reliable metadata: name, working directory, branch, model, reasoning tier. These must be queryable at runtime and restorable after stop. Implementation details reveal the design: model and reasoning-tier fields are nullable — a restored session may have no assigned model until the user specifies one; the metadata schema must tolerate missing fields in a "dormant" state. On recovery, if no directory is given, the saved one is reused; codex exec resumes using the compressed rolling record tied to that directory. In short, "which directory, based on which commit, running on which model" is durable state, not ephemeral process memory. For custom agent platforms, the first step is assigning every session a stable ID and persisting its metadata before building anything else.

Working Directory Is a Capability Boundary, Not Just a Path

Once sessions are externalized, the working directory becomes the boundary of what the model can touch — the sandbox couples to the directory, so changing it changes the accessible file set. Treating mid-session directory changes as a harmless string swap is dangerous. A real fix hardened /cd against sandbox-weakening, proving that directory migration is a security-relevant state transition, not a free action. If your agent has a sandbox, directory changes must pass the same policy checks as tool calls. An external actor directing a session to switch directories is effectively altering its permission scope; that operation must be audited and policy-constrained.

External Writes Are a High-Privilege Instruction Channel

Injecting a message into a session is injecting instructions into the model's context. This expands the prompt-injection surface: previously injection required tricking the chat user or a tool return; now any process with queue-write permission speaks directly to the model. CI logs, another session's output, or external notifications become executable text once inside.

The most common pitfall is feeding untrusted output verbatim. A build log containing third-party error text — or a maliciously planted string — can become an injection vector. External writes must at minimum: (1) authenticate the writer so not every queue-accessible process can message any session; (2) audit-log every write for post-hoc tracing of which external message caused which action; (3) mark or downgrade content so the model and logs can distinguish "human-typed" from "system-injected" data instead of letting them look identical in context. Governing external writes as high-privilege input, not a convenient message pipe, is a prerequisite for safe deployment.

State Must Be Queryable; UI Must Detach from Process

The control plane only works if session state is exposed. "Need input," "working," "ready" must be queryable and subscribable; otherwise orchestration degrades to polling and guesswork. Equally critical is attach/detach semantics: when the front-end disconnects, the session must keep running. Implementations explicitly handle "external app-server disconnects, UI reconnects" — the session continues. Agent processes must be designed for repeated attach/detach cycles, not bound to a single frontend session.

Implementation Checklist

Converge the discussion into verifiable questions for your platform:

Does every session have a stable address usable outside the conversation, not just a UI-visible number?

Can external systems write to a designated session with auditing? Is the channel authenticated, and are writes and content traced?

Are "waiting for input," "working," "completed" queryable and subscribable states, not implicit terminal-hidden states?

Do working directory, branch, model, and other metadata persist with the session, restore on resume, and allow nullable fields in a dormant state?

Does changing the working directory undergo the same policy checks as tool calls, rather than bypassing the sandbox?

Can the UI detach without killing the session, and can the session re-attach later?

For most agents still stuck in "one process, one conversation, all control via chat," implementing the minimal trio — stable session ID, external message injection, queryable state — is enough to graduate from "chat boxes" to "schedulable services." The remaining work is hardening those three: durable metadata, secure governance of external writes, and directory-as-capability-boundary policies. The value of out-of-band orchestration lies not in a few extra commands but in the fact that agents can finally be operated as a fleet of stateful, addressable, externally steerable processes instead of a row of doors you must personally walk through.