Practical technical guides / Agent-era architecture

Keep Your Host in Control When Embedding an Agent Runtime

When an agent runtime is embedded in a product, the host owns capacity, capabilities and identity. Turn admission, restricted root-only tools and inherited session ids, with tests.

By Sandeep Belgavi · Published 2026-11-13

The host owns the edges: Admission slots, then Restricted tools, then Inherited session
Original conceptual diagram by Sandeep Belgavi; no measured performance is represented.

When an agent runtime is embedded in a product, the host owns capacity, capabilities and identity. Turn admission, restricted root-only tools and inherited session ids, with tests.

The runtime is no longer the top of the stack

The first generation of agent runtimes assumed they owned the process. They decided when a turn ran, which tools existed and who the session belonged to. That works for a command-line tool on a laptop. It stops working when the runtime is embedded in a product that already has its own scheduler, its own permission model and its own notion of a user session: a help-desk console, a workflow engine, a chat service with thousands of tenants.

Codex CLI rust-v0.168.0, released on 13 November 2026, ships three changes, merged on 2 November, that show this shift clearly. Pull request 58963 adds host-owned turn admission: a host can supply an admission provider so that it acquires execution capacity before the runtime runs any task, root turns included, and the runtime holds the host's execution guard for the lifetime of the task. Pull request 58984 adds a RestrictRootCapabilities marker in thread startup data, so a host can apply the restrictions native subagents already receive, such as no user-input requests and no plugin installs, without changing the thread's session attribution or permission profile; the host must supply the marker again when cold-resuming the thread. Pull request 59000 lets a host give a fresh child thread an inherited root session id, while rejecting it for resumed, forked or native agent threads and when it equals the child's own thread id.

This guide uses those three changes as a map of the boundaries any embedded agent runtime needs. It does not describe Codex internals beyond what the pull request descriptions say. The companion code is an original model of the same three boundaries.

Admission belongs to whoever owns the capacity

Consider the fictional Belgavi's Book Store help-desk console. Staff such as Geetha and Jenya open cases, and the console starts an agent thread for each to draft replies. The console runs on a fixed pool of workers and has a contract with its model provider for a fixed request rate. If each agent thread decides for itself when to start a turn, ten staff clicking at once produce ten turns, and the provider's rate limit sorts it out with errors.

Host-owned admission inverts that. Before the runtime starts a turn, it asks the host for a slot. The host answers with a guard object, or a denial. The runtime keeps the guard until the turn's work is finished, and releases it on every exit path, including errors and cancellation. The host now has a single place to apply fairness between tenants, priority for interactive work over background work, and back-pressure when the provider is slow.

The detail that matters most is what happens to the user's input when admission is denied. The pull request description says the runtime records accepted input before exposing the error and preserves recoverable input during suspension. In the companion model, the console holds its only slot for another thread, Jenya submits "Summarise CASE-6120", admission is denied, and the text stays in the thread's pending input. When the slot frees and she adds "and CASE-6121", both messages run in order in one admitted turn. A runtime that drops input on denial teaches users to retype, and a runtime that silently queues it without saying so teaches them to submit twice.

def submit(thread, host, text):
    thread.pending_input.append(text)      # keep it before asking for capacity
    try:
        guard = host.acquire(thread.thread_id)
    except AdmissionDenied:
        thread.transcript.append(("system", "turn not admitted; input kept"))
        return "denied"
    try:
        run_turn(thread)
        return "ran"
    finally:
        guard.release()                    # every exit path

The other subtlety is hooks. The pull request notes that on interruption the runtime skips prompts that still require a submit hook rather than recording them without inspection. If your host inspects user input before it reaches the model, for policy or redaction, admission must not become a path around that inspection.

Capabilities are a host decision, captured once

Agent runtimes usually distinguish the root agent, which talks to the user, from subagents, which do delegated work. Subagents are typically denied capabilities that only make sense at the root: asking the user a question, installing a plugin, sending the user an asynchronous message, approving a tool on the user's behalf. An embedded runtime needs a way for the host to apply the same restriction to a thread that is, from the runtime's point of view, a root thread, because the host knows that the thread is actually a background worker.

In the example, the console starts a background thread to pre-draft replies for the night queue. Nobody is watching it. It should be able to read cases and draft text, and it should not be able to ask a question that no one will answer or install anything. With the restriction applied, the model's tool list is read_case and draft_reply, and a call to ask_user is refused.

Two design rules follow from the pull request. First, capture the restriction once at startup and treat it as part of the thread's identity, not as a per-turn flag that a later message could change. Second, the runtime does not persist it on the host's behalf: on cold resume the host must supply it again. The companion model shows why that is a sharp edge. Resume the thread without the marker and it regains install_plugin. Make the host's resume path read the restriction from the host's own record of the thread, and add a test that resumes a restricted thread and asserts the root-only tools are absent.

The pull request also excludes inherited user messages from the retained authorization context of restricted threads. The general principle is that a message a person typed into another thread is not authorization for a background thread to act. Approval should be bound to the thread and the request it was given for.

Identity: thread, session and lineage

Hosts track sessions in their own terms. For the console, a session is one staff member's handling of one case, and every model call, log line and cost record should roll up to it. When that session spawns a child thread to do background work, the child needs its own thread id, so its transcript and state are separate, and the parent's session id, so accounting and audit roll up correctly.

The rules in pull request 59000 are worth copying. Only a fresh child may receive an inherited session id; a resumed, forked or native agent thread already has one, and overwriting it would rewrite history. The inherited id must differ from the child's thread id, which catches a whole class of copy errors. And the inherited id is persisted and restored on resume, so a restarted child does not silently become its own session.

What stays deterministic

All three boundaries are plain code that the model never sees: the admission decision, the capability list and the identity rules. The model sees only the tools it has been given, and a refusal message if it tries one it has not. None of these decisions should ever be delegated to a prompt instruction such as "do not ask the user questions"; a restricted capability should be absent from the tool list, so there is nothing to call.

Migration steps for an existing host

  • Inventory what your host already owns: scheduling, rate limits, users, tenants, audit. Each is a boundary the embedded runtime must defer to.
  • Put an admission call in front of every turn, root turns included, and hold its guard in a finally block.
  • Record user input before admission, and make denial visible in the transcript.
  • Start background threads with an explicit capability restriction, persisted in the host's own record, and reapply it on every resume path.
  • Give child threads their own thread id and the parent's session id, and reject inheritance for resumed and forked threads.
  • Route cost and telemetry by session id, not thread id.

Failure modes

  • A slot is leaked when a turn throws before reaching the release, and the pool slowly drains. Test the error path.
  • A restricted thread regains root-only tools on cold resume because the restriction lived in memory.
  • A forked thread inherits a session id and two sessions' costs merge.
  • Admission denial loses input, or a retry after denial submits it twice.
  • A background thread waits forever on a question nobody can see.

When you do not need this

If your agent runs as a single-user tool on one machine, the runtime owning its own scheduling is fine, and adding a host admission layer is ceremony. The boundaries matter as soon as there is more than one user, more than one tenant, or any thread that runs without a person watching.

Verify it

The companion model has six tests: restricted tool lists, denial that keeps input, the guard released on an exception, cold resume with and without the marker, and the inherited session id rules. In your own host, add the same tests against the real runtime with a scripted model, and add a load test that opens more threads than slots and asserts that every input appears exactly once in some admitted turn.

Run the example yourself

A host that owns execution slots, a restriction marker that must be resupplied on cold resume, inherited session id rules and six tests. No Codex code is used and no model is called. Companion code on GitHub; its README lists the prerequisites, exact commands, expected output and limits.

Primary references and authorship

Sources read 2026-11-13. Original explanation and synthetic examples by Sandeep Belgavi. Views are my own and do not represent any employer, past or present.