AIP-46: SESSION (session/v1): long-running multi-turn agent orchestration
A generic session-management protocol for orchestrating long-running, multi-turn harnesses (Hermes, Claude Code, OpenCode, …) on a host. Standardises the lifecycle (spawn → multi-turn → kill), the data model (sessions[] with status / ground / workspace bindings, nested via parentSessionId), the over-the-wire surface (HTTP + SSE + MCP tools), the workspace-resolution pattern that lets a single host serve many bound directories, the per-workspace state partitioning that keeps one workspace's history from evicting another's, and the spawn gate that decides whether a session may delegate to further sessions. Layers over AIP-45 (AGENT-CLI) for the per-harness spawn semantics and AIP-44 (ACP) for the wire format inside one turn; binds AIP-42 (AGENT) as the session's definition, AIP-38 (POLICY) as the delegation authority, and AIP-54 (REF) as the session's ground.
| Field | Value |
|---|---|
| AIP | 46 |
| Title | SESSION (session/v1): long-running multi-turn agent orchestration |
| Status | Review |
| Type | Schema |
| Domain | cli.sh |
| Requires | AIP-17 (RUNNER), AIP-19 (SECRETS), AIP-54 (REF, the session's ground), AIP-36 (SANDBOX), AIP-38 (POLICY, the delegation authority), AIP-23 (IDENTITY-REF, the session:// principal), AIP-42 (AGENT, the session's definition), AIP-44 (ACP), AIP-45 (AGENT-CLI) |
| Composes with | AIP-3 (skills an agent loads), AIP-39 (the actions a policy grants or denies), AIP-47 (ROLE — org context, via AIP-9 OPERATOR; never the spawn authority — see §Delegation) |
| Reference Impl | @agentproto/runtime |
Abstract
agent-session-lifecycle/v1 standardises how a host spawns,
drives, observes, and tears down long-running harness sessions on
a machine. It sits above AIP-45, which defines how
to install and start a single agent binary, by adding the
N-sessions-on-one-daemon plumbing every real orchestration scenario
needs:
- many concurrent agents (claude in
~/code/foo, hermes in~/code/bar, aider in~/blog) - multi-turn continuity per session (don't respawn for every prompt)
- live observation (UI tails output, operator polls for the answer)
- workspace-bound spawns (resolve ground from a stable, named AIP-54 ref instead of hand-typing absolute paths) — and the state each bound workspace accumulates, partitioned per workspace rather than pooled (§State partitioning)
- nested sessions — a session that spawns further sessions, and the gate deciding whether it may (§Delegation)
A daemon implementing this AIP becomes a control plane for local agents. Any host (cloud orchestrator, IDE extension, mobile remote) can drive it through the standard surface — HTTP routes, an SSE stream, and MCP tools — without knowing which harness is wrapped.
A session is the running instance; what it runs is an AIP-42 AGENT. AIP-46 owns the process boundary and the lifecycle; it does not re-declare the agent's prompt, skills, tools, or permissions — those are AGENT fields, and the permission half is AIP-38 POLICY. This split is what keeps the spawn gate honest: the thing being gated is declared somewhere a human can read and sign, not inside the daemon.
AIP-46 is opinionated about the lifecycle and the data shape; it is
not opinionated about the wire format inside a turn (that's
AIP-44/ACP via AIP-45's protocol discriminator). Hosts that already
support AIP-45 harnesses get AIP-46 by adopting the registry +
endpoint table below.
Motivation
Reference implementation history: agentproto shipped AIP-45 with one
canonical entry point (agentproto run <slug> --prompt "…") — a
single, fire-and-forget invocation. This worked for ad-hoc piping but
fell apart for the actual product flows:
- A guild operator wants claude alive in 4 different folders so
it can answer follow-ups without re-pulling each repo's context.
The
runverb spawns a fresh agent per call — no continuity. - A web UI wants to mirror
claude mcp listover HTTP so the user sees what's running on their laptop withoutps -aux. There was no enumeration surface. - A cloud orchestrator wants to dispatch a claude turn into the user's workspace through the same MCP connection it already uses for fs/exec. There was no MCP path; the orchestrator had to shell out.
Three different consumers, three workarounds, one missing primitive: persistent, named, observable agent sessions. AIP-46 fills it.
Why delegation is in scope
The original cut treated a session as a leaf: something a human or a cloud host starts. Real orchestration made sessions spawn other sessions — a supervisor that decomposes work across children — and that turned a lifecycle protocol into an authority question the spec had no vocabulary for:
-
A session spawns further sessions, and nothing says whether it may. Reference implementations grew a private notion — agentproto's
role: executor | supervisor— carrying a prompt fragment, a delegation switch, and a privilege level in one struct. Three problems compound:- It is unspecified. Two hosts implementing AIP-46 have incompatible, undiscoverable delegation semantics. A consumer cannot ask "may this session spawn?" in a portable way.
- It re-invents AIP-42. A prompt fragment is an AGENT body; a
skill list is
skills:; an allowlist of spawnable children isdelegates_to:; a permission is AIP-38 POLICY. The struct is those four primitives fused, minus their schemas. - It collides with AIP-47. "Role" is already
taken: an organizational job template that AIP-47 §Role vs Policy
vs Governance says MUST NOT grant permission. A spawn-time
privilege tier is precisely what AIP-47 calls an access role
and forbids conflating with a role. Naming the delegation switch
roleinverts a security invariant of a neighbouring AIP.
This amendment fills the gap without minting a fifth primitive: the spawn request binds an AIP-42 AGENT, the AGENT's
delegates_todeclares who it may spawn, AIP-38 POLICY decides effect, and AIP-46 specifies only the enforcement point — the one thing that is genuinely session-lifecycle's own.
Why state partitioning is in scope (added 2026-07-17)
This AIP's premise, stated in its own abstract, is "the
workspace-resolution pattern that lets a single host serve many bound
directories". §Workspaces delivered the addressing for that — a slug
resolves to a path — and stopped there. The state those many
directories generate stayed pooled in one store, with workspaceSlug
demoted to a column:
-
The multi-workspace premise had no multi-workspace storage. A slug that only ever appears as a field is a label, not a boundary. Three consequences, in ascending order of how hard they are to see:
- Bounded retention becomes a race. Any host capping how much history it keeps caps it across every workspace at once, so the cap is spent by whoever was busiest. The reference implementation measured this: a 200-descriptor cap against a store holding 201 records from four different slugs, where a workspace contributing 8 of them is one busy afternoon away from losing all 8 — having done nothing to deserve it. The eviction is silent and lands on the quietest workspace.
- Lifecycle has no unit. "Remove this workspace and everything it accumulated" is a filtered rewrite of a shared file rather than the removal of a subtree, which is why no host offers it.
- Scoping has nothing to scope to. A host that wants to hand a consumer a view of one workspace has to filter a global store on every read, and every read that forgets is a leak. A partition lets the host not hold what it should not serve.
This amendment does not mint a new primitive either: it takes the slug §Workspaces already defines and makes it select storage rather than annotate it.
Specification
Session data model
A session is the host's record of one running (or recently exited) harness invocation. Required fields:
interface Session {
/** Stable id for the lifetime of the session. Caller-opaque. */
id: string
/** Harness slug from the AIP-45 manifest the session wraps. */
harness: string
/** Workspace handle (§Workspaces) this session binds to. A host
* evaluating a workspace-scoped grant derives the binding itself and
* does not read it from this field (§Who may message whom rule 5).
* "default" when the host has no workspace registry. */
workspaceSlug: string
/** The session's ground, as the resolved AIP-54 ref. This is the
* value §Delegation's containment check compares against — a
* child's ground MUST resolve inside its parent's. It also gives the
* session its node scope (§Node scope). */
ground: string
/** Absolute path the agent runs in — `ground` resolved against the
* host's filesystem. Reported for observability; it is NOT the
* containment surface (`ground` is). Hosts MUST NOT reconstruct a
* parent's ground by string-matching this. */
cwd: string
/** Lifecycle phase. State machine in §status-transitions. */
status: "starting" | "running" | "exited" | "killed" | "error"
/** ISO-8601. Time the host called the spawn. */
startedAt: string
/** ISO-8601, present when status ∈ {exited, killed, error}. */
endedAt?: string
/** ISO-8601, last stdout/stderr or projected event line. */
lastOutputAt?: string
/** Process exit code when present. -1 / unset for non-process
* sessions or sessions still alive. */
exitCode?: number
/** Free-text label the spawner attaches (conversation id, operator
* name, …) so consumers can group/filter. Display only: a grant
* never matches it. */
label?: string
/** The operator label: a durable name only the operator assigns
* (§Operator label). No session can set, change or clear it. */
operatorLabel?: string
/** The AIP-42 AGENT this session runs, when one was bound at spawn.
* Absent for a bare harness spawn (harness default behaviour).
* Persisted: a consumer MUST be able to ask what a live session is
* running without replaying its prompt. */
agentSlug?: string
/** The AIP-9 operator this session runs for, as an AIP-54 ref
* (§Operator binding). Absent when the session was not started for an
* operator. It binds the session to the operator; it grants nothing.
* Unrelated to `operatorLabel`. */
operator?: string
/** Set when this session was spawned BY another session. Absent ⇒
* a root spawn (a human or an external host started it). This is
* the edge the spawn gate keys off — see §Delegation. */
parentSessionId?: string
/** Depth in the spawn tree: a root spawn is 0; a session spawned by
* a session at depth d is d+1. Present whenever `parentSessionId`
* is. Bounds recursion (§Delegation limits). */
depth?: number
}The host MAY add fields; consumers MUST ignore unknown fields.
parentSessionId + depth make the registry a forest: roots are
sessions with no parent, and a consumer renders the tree by grouping
on parentSessionId. A host that supports delegation MUST populate
both — a nested session that reports no parent is indistinguishable
from a root one, which defeats both the gate and every supervision UI
built on top of it.
Status transitions
starting ──→ running ──→ exited
│ │ ╲──→ killed
│ ╰──────────→ error
╰──→ error (spawn failed)starting → runningfires when the agent's protocol arm reports the session ready for the first turn.running → exitedis the normal terminal — the underlying child exited with code 0 (or any code; presence ofexitCodeis what matters, not its value).running → killedfires when a consumer calledkill_session,DELETE /sessions/:id, or the host shut down with a live agent.- Interrupting a turn is not a transition. A session whose in-flight
turn was cancelled (
POST /sessions/:id/interrupt, or a prompt sent withinterrupt: true) staysrunning— the agent is alive, idle, and holding its context. There is nointerruptedstatus, and consumers MUST NOT infer one from a turn ending early. * → errorfires on any unhandled spawn / protocol / IO error;lastOutputAttypically points at the corresponding line in the ring buffer.
Workspaces
A host implementing AIP-46 SHOULD persist a workspaces config
(reference implementation: ~/.agentproto/workspaces.json) so
spawns can reference a named handle instead of an absolute path:
{
"version": 1,
"active": "agentik-studio",
"workspaces": [
{ "slug": "agentik-studio",
"path": "/Volumes/.../agentik-studio",
"addedAt": "2026-05-10T15:31:56.664Z",
"updatedAt": "2026-05-10T15:32:00.123Z",
"label": "Main monorepo" }
]
}Each entry is addressable as an AIP-54 ref —
ws://workspaces/<id> — and that ref, not the path, is what a spawn
carries as its ground. The path is the host's private resolution
of it. Per AIP-54 §Seams, an AIP-34 workspace id is
@<owner>/<slug>, so a fully-qualified ground ref reads
ws://workspaces/@acme/agentik-studio; a host whose registry predates
AIP-34 ids MAY key by bare slug until it adopts them.
Ground resolution priority for any root spawn that omits an
explicit ground:
- lookup
workspaces[workspaceSlug]→ use its ref - fall back to
workspaces[active]→ use its ref - emit a warning + use the host's
process.cwd()
Steps 2 and 3 are root-only. A nested spawn (one whose caller is a
session) MUST NOT reach them — it inherits its parent's ground
instead. See §Delegation;
the active workspace is ambient host state and resolving a child
through it silently relocates that child outside the subtree its
parent was working in.
Hosts that don't implement workspaces MAY require explicit cwd
on every spawn; consumers MUST then pass it.
State partitioning (added 2026-07-17)
§Workspaces makes workspaceSlug a field on a session. That is
enough to render a filter and not enough to keep two workspaces out of
each other's way: a field distinguishes rows inside one store, and
every row in that store still competes for the same bounded resource.
This section makes the slug a partition of the host's state.
Layout
A host that persists session state and implements a workspace registry MUST partition that state per workspace. The reference layout:
~/.agentproto/
├── workspaces.json # the registry (§Workspaces)
└── workspaces/ # one bucket per workspace
├── agentik-studio/
│ ├── sessions.json # this workspace's registry snapshot
│ └── sessions/ # this workspace's transcripts
│ └── <sessionId>/…
├── choisir-service-public-app/
│ └── …
└── default/ # the fallback bucket — see below
└── …workspaces.json (the registry, a file) and workspaces/ (the state,
a directory) are deliberate siblings: the registry names the
workspaces, the directory holds what each one accumulated.
| Store | Normative force |
|---|---|
| the sessions registry snapshot | MUST be per-bucket |
| durably-kept transcripts / per-session output | SHOULD be per-bucket |
| any other store whose records carry a workspace binding | SHOULD be per-bucket |
| stores with no workspace binding (host config, pairings, harness installs) | MUST stay global — bucketing them would assert a binding that does not exist |
Hosts MAY choose a different root; the partition, not the path, is what this section requires.
Bucket resolution
For any record carrying a workspaceSlug, the host resolves its bucket:
workspaceSlugis non-empty and matches a registered entry inworkspaces.jsonby exact identity → that workspace's bucket.- Otherwise — absent, empty, or unregistered → the
defaultbucket.
A host MUST resolve by exact match against the registry, and MUST
NOT derive a bucket directory from a slug that did not come back from
that lookup. The registry's slugs are host-sanitised (§Workspaces); a
slug on a spawn request is caller input, and a host that paths on it
directly has handed the caller directory traversal under its own state
root. Membership is the validation: an unregistered slug does not get
a bucket of its own, it gets default.
default is a real bucket, not an error state. It receives every
record the registry cannot place — one-off cwd spawns, sessions from
a workspace the user has since removed, and the pre-partition past.
Records in default share a bucket with one another, i.e. they keep
exactly the pooled behaviour this section replaces elsewhere.
Partitioning is therefore not an isolation mechanism for
unregistered work, and hosts MUST NOT present it as one: registering
a workspace is what buys separation.
Per-bucket bounds
A host that bounds how many historical descriptors it retains MUST apply that bound per bucket, never across the union.
This is the concrete fairness property the partition exists to buy. A global bound makes retention a race between workspaces: the busiest workspace's records evict the quietest one's, so a workspace can lose its history by having done nothing at all while a neighbour was busy — the eviction is silent, and the workspace that suffers it is the one with the least evidence that anything happened. A per-bucket bound makes retention local: a workspace's history is bounded by its own volume and nothing else's.
Hosts SHOULD size the bound per bucket rather than dividing a global budget among buckets. The bound exists to keep a single store readable; after partitioning, each bucket is a single store.
Migration
A host that previously pooled this state in one global store MUST treat the move to buckets as additive:
- The host MUST partition the legacy store's records into buckets by the rule above, on first boot after the change.
- The host MUST NOT delete, truncate, or rewrite the legacy artifact. It is the user's data and their only rollback; the partitioned copy is a derivative until they decide otherwise. A host MUST be able to complete the migration with the legacy store held read-only.
- The host SHOULD record a durable marker — what was migrated, when, from where, and how many records landed in each bucket — so the split is auditable, and so a later boot does not re-import records the user has since deleted from a bucket.
- A record whose slug does not resolve MUST land in
default. The migration MUST NOT drop a record it cannot place.
Reclaiming the legacy artifact is a separate, human-gated decision. This AIP specifies no retention or garbage collection for any bucket; see §Open Questions.
Delegation and the spawn gate
A nested spawn is a spawn whose caller is itself a session. The host MUST decide, at spawn time, whether the calling session may create the requested child. That decision is the spawn gate, and this section is the whole of what AIP-46 specifies about it: the enforcement point. What is permitted is declared by AIP-42 and decided by AIP-38 — AIP-46 only guarantees the check happens where it cannot be talked past.
The agent binding
A spawn request MAY carry agent: <agent-ref> — a reference to an
AIP-42 AGENT, resolved by the host through AIP-42's
inline | ref | file pattern. The bound AGENT supplies:
| AGENT field | What it supplies to the session |
|---|---|
| body | the system prompt / disposition given to the child |
skills[] | AIP-3 skills the child loads |
boundaries[] | hard rules surfaced high-priority in the prompt |
delegates_to[] | the closed allowlist of agents this one may spawn |
policy | AIP-38 binding — the access decision |
A host that resolves an AGENT MUST record it as agentSlug on the
session. A host MAY bind a host-configured default AGENT to a spawn
that names none, and MUST then record it as agentSlug; §Who may
spawn whom rule 3 bounds it like any other binding. A session to which
no AGENT is bound, by request or by default, runs the harness's
default behaviour and MUST be treated as declaring no delegates_to,
that is deny (below).
Who may spawn whom
- Deny by default. An agent whose resolved
delegates_tois absent or empty MUST NOT be permitted to spawn. This mirrors AIP-38'sdefault: denyand makes the safe case the silent one. - Closed allowlist. When
delegates_tois non-empty, the host MUST permit a nested spawn only when the requested child's agent-ref resolves to a member of the caller'sdelegates_to. Membership is by resolved identity, not by the literal string. - No self-widening. A child MUST NOT be able to alter its own
delegates_to, its policy, or the toolset the host granted it — not through its prompt, not by requesting a wider binding at spawn, not by re-spawning itself. The caller's grant is a ceiling; a nested grant MUST be bounded by the parent's. - Role is never the authority. A host MUST NOT derive delegation permission from an AIP-47 ROLE, from an operator's seniority, or from any organizational field. AIP-47 is explicit that a role declares intent and MUST NOT grant access; an agent's job title has no bearing on whether it may spawn a process.
The enforcement point
This is the normative core.
- The gate MUST be evaluated host-side, at spawn, before any tool injection or process creation. A rejected spawn MUST create no session.
- The gate MUST bind to the calling session's identity, not to the surface it connects through. The host MUST resolve the caller's grant from the authenticated identity of the calling session and enforce it where the delegating action is invoked. A host MUST NOT derive the grant from anything the caller supplies about itself: a restriction expressed as a URL parameter, a header, a config entry, or any other caller-controlled input is a request, not a gate — the caller omits it and the restriction evaporates.
- Every surface that can reach a delegation action MUST carry session identity. A surface reachable without identity — an unauthenticated loopback endpoint, a permissive local socket — is an ungated surface, and its existence defeats the gate for every session that can reach it, including sessions the host believes it denied. Co-located children can reach loopback by construction; "local" is not an authentication boundary when the thing being authenticated is a process the host itself spawned. §Session principals rule 5 names the one residual a host MAY accept by configuration, an anonymous loopback caller evaluated as the operator. A host that accepts it does not satisfy this bullet for the sessions that can reach loopback, and MUST NOT describe its gate as binding them (the opening paragraph of that section).
- Removing the actions from the surface the host injects is defence in depth, and MUST NOT be the only mechanism. A harness that carries its own configuration for the host's endpoint will connect to the ungated one; a harness with a native delegation facility will not use the host's surface at all. A host that gates only the URL it hands out will report a child as denied while that child delegates freely — the worst available outcome, because it is silent and it reads as enforcement.
- Prompt text is not enforcement. A disposition, a
boundaries[]entry, or any instruction telling a child not to delegate is a hint. A conforming host MUST NOT count it as the gate. Prose that restates the gate is permitted and useful; prose in place of the gate is non-conforming. - The gate MUST be the single decision point shared by enforcement and introspection. A host exposing "what may this session spawn?" MUST answer from the same predicate that rejects the spawn, so the two can never disagree.
Delegation actions. The verbs that spawn or drive another session
— agent_start and agent_prompt in the tool table below — are
AIP-39 actions for policy purposes. A host MUST gate
them as actions, not as tool-name strings, so a renamed or aliased
surface cannot route around the check.
Root spawns. A spawn with no calling session (no
parentSessionId) has no parent to gate against; it is authorised by
the host's own auth boundary (§Security Considerations), not by this
lattice. Hosts MUST NOT treat the absence of a parent as an implicit
grant to the child — a root-spawned session is still subject to its
own agent's delegates_to for anything it spawns in turn.
Session principals (added 2026-10-28)
Draft AIP-46 amendment (2026-10-28). Normative identifiers (principal names, error codes) are English and final.
This section says what proves which session made a call. The session
credential is attribution, not by itself a barrier: a caller that
presents none is anonymous, and where the host evaluates anonymous
as the operator (rule 5) a session that omits its credential gains the
operator's rights. The credential holds a session to its own rights
only where the host leaves it no path to the host without a credential.
The session credential. A host that spawns a session MUST mint a session credential for it: a secret value bound to that one session id, which no other party can derive or guess. The host:
- MUST deliver the credential only to the session it was minted for, on the surfaces the host hands that session, and MUST NOT write it to the session descriptor, a transcript, a log, an error message, any other read surface, or a file under the session's working directory (its ground), which the session's workspace could commit or share.
- MUST store only a one-way hash of the credential.
- MUST revoke the credential when the session is retired. A revoked credential MUST NOT authenticate any request.
- MUST replace the credential when the session restarts, resumes or continues: the host mints a new credential for the new process, and the previous credential MUST NOT authenticate any request once the new one is delivered.
Proof and principals. A host MUST resolve every request on a surface that can reach a delegation action or a session message to one level of proof and at most one principal:
| Proof | The caller presents | Principal |
|---|---|---|
proven | a valid session credential, or the operator credential of the host's own auth boundary (§Security Considerations) | session://<id> (AIP-23), the session the credential was minted for; or the host operator (user://<id> or another host-defined identity-ref; "the operator" throughout this AIP), for the operator credential |
claimed | a session id it names (a URL parameter, a header, a body field) without a valid session credential, or a credential that is malformed, unknown or revoked | none once the host enforces (rules 3 and 4); in observe-only mode (rule 6), the session it claims, as a host did before it minted credentials (anonymous when it names none) |
none | no credential and no claim | anonymous |
The rules:
- The credential decides the session. A host MUST evaluate a request that presents a valid session credential as the session the credential was minted for, and only as that session, narrowed by §Who may spawn whom and the AIP-38 delegation ceiling. A host MUST NOT evaluate such a request as the operator, even when it also presents the operator's credential.
- A host-spawned session presents its credential. A host MUST place a session's credential on every surface it hands that session that can reach a delegation action or a session message, so that a session using the surfaces it was given is evaluated as itself.
- A claim is not an identity. A host MUST NOT evaluate a request
as a session on the strength of a claim. Once it enforces this
section, a host MUST refuse with
identity_unverifieda request that claims the id of a session the host spawned (an external identifier is not a claim, rule 7) and presents no valid credential, and MUST refuse withidentity_mismatcha request whose claim names a session other than the one its credential was minted for. A host MUST NOT resolve either request toanonymousor to the operator instead. When the caller presents a session credential, the:idof a route that acts on the caller's own session, at leastPOST /sessions/:id/checkpointand the inbox acknowledgement of §Inbox and tools, is a claim under this rule; the operator may name any session there. - An invalid credential is refused. Once it enforces this section,
a host MUST refuse with
identity_unverifieda request presenting a credential that is malformed, unknown or revoked, and MUST NOT resolve that request toanonymous. - The anonymous caller is never a session. A host MUST NOT let an
anonymouscaller act as a session: it is never the sender session of a session message nor the calling session of a nested spawn. A host MAY treat ananonymouscaller that reaches it over loopback as the operator's own client, and then evaluates it as the operator. Whether it does MUST be host configuration that only the operator can change (§Operator-only configuration), and a host MUST NOT extend that treatment to a caller reaching it over any other transport. A host that offers that treatment MUST offer the configuration that withdraws it, MUST report how manyanonymousrequests it evaluated as the operator on a surface the operator can read, and MUST NOT describe the credential or that configuration as keeping a session that omits its credential within its own rights. - Observe-only mode. Before it enforces rules 3 and 4, a host MAY
run in an observe-only mode: it classifies every request into one of
the five classes below and records the count per class on a surface the
operator can read, and refuses nothing on that classification. A host in observe-only mode does not
conform to rules 3 and 4 and MUST NOT advertise conformance to
§Delegation.
verifiedisproven,mismatchisprovenwith a contradicting claim,invalid credentialandclaim onlyareclaimed, andanonymousisnone.
| Class | The request presents |
|---|---|
| verified | a valid credential, and no claim or a claim naming the credential's session |
| mismatch | a valid credential and a claim naming another session |
| invalid credential | a credential that is malformed, unknown or revoked |
| claim only | a claim and no credential |
| anonymous | no credential and no claim |
- An external identifier is a label. A caller the host did not
spawn MAY register an identifier of its own for display and
attribution. Such a session holds no credential and is not a
session principal: a request naming it is evaluated as
anonymous, counts asanonymousin rule 6, and the identifier is not asession://ref. A host MUST NOT register an external identifier that equals the id of a session it spawned. - Enforcement never outruns delivery. A host MUST NOT enforce rules 3 and 4 against callers on a surface, or spawned through an harness, to which it does not yet deliver the credential under rule 2. It MAY enforce per surface and per harness and MUST report which it enforces; until it enforces everywhere it delivers everywhere, it does not conform to rules 3 and 4.
- A host may require proof. A host MAY require
provenfor any action it lists (for example the AIP-39session:spawn,session:controlandauth-profile:use), and then MUST refuse withidentity_unverifiedaclaimedcaller of a listed action, and anonecaller the host does not evaluate as the operator under rule 5, or withidentity_mismatchwhen the claim names another session. Where the host evaluates the anonymous loopback caller as the operator (rule 5), a listed action binds a session that omits its credential only once the operator withdraws that treatment. The requirement holds only against a caller that cannot reach the host without a credential, not against a session that can read the operator credential or reach an unenforced surface.
Informative: the reference implementation.
@agentproto/runtimemints the credential in observe-only mode by default (agentproto/ts#2335): a randomapst_token, stored as a SHA-256 hash insession-credentials.json, sent in thex-agentproto-session-tokenheader on the daemon self-mount but not yet in the process environment, so a native hook callback (AIP-71 §8) still authenticates as the operator.defaults.identity.sessionTokens("shadow", the default,"enforce", or"off") selects it (agentproto/ts#2371); under"enforce"it refuses an invalid token, a mismatching claim and a claim without token naming a session it delivered a token to, whileanonymous,verifiedand the other claim-only classes are never refused.GET /identityreports the five classes asverified,mismatch,invalid_token,claim_onlyandanonymous, splitsclaim_onlyintoexternal,delivered,undeliveredandunknown(claimOnlyByClass), and reports which surfaces itenforces; its totals persist inidentity-observations.jsonunder the daemon home and add up across restarts, withsincethe first recorded boot andbootedAtandbootsadding the restart history (agentproto/ts#2398).
Informative: where the reference implementation does not conform. It delivers the credential only to unsandboxed
claude-codeandhermessessions (rule 2). A restart leaves the previous credential valid until the old row retires (credential rule 4). It evaluates everyanonymouslocal caller as the operator with no switch (rule 5). By default it honours acallerSessionIdclaim on loopback without a credential (rule 3); under"enforce"it refuses a claim naming a session it delivered a token to, while a claim naming a session it could not deliver to still resolves to that session (rule 8). It counts a request naming a registered external identifier asclaim_onlyin theexternalclass, not asanonymous(rule 7), and one naming an identifier it has not registered asunknown.
Operator-only configuration (added 2026-10-28)
The host's configuration decides which sessions may message or drive
one another, whether an anonymous loopback caller is the operator and
which actions require proven (§Session principals), and which
AIP-38 policy the host applies. A host MUST refuse a
configuration write made by a session principal when the write would
change any of them. Only the operator MAY change them. The refusal MUST
hold on every surface that carries a configuration write (an MCP tool,
an HTTP route, a command the host runs on the session's behalf). A
session that edits the host's files through its own shell is outside
this rule's reach (§What this gate cannot reach). This is §Who may
spawn whom rule 3 (no self-widening) applied to identity, messaging
and policy.
Informative: the reference implementation. The messaging grants live under
defaults.messaging.*inconfig.json(withpeerBindingfrom agentproto/ts#2326 and agentproto/ts#2330), written throughconfig_set, which refuses a session principal's write todefaults.messaging,defaults.identityanddefaults.tasks.operatorDelegates, and their ancestors, with the codeoperator_only, whatever thesessionTokensmode (agentproto/ts#2371).operator_onlyis the reference implementation's own code, not a normative one, and hosts can add their own, as the error-code paragraph says.
Operator binding (added 2026-10-29)
Session.operator names the AIP-9 operator the session
runs for: the organizational binding of an agent holding a role
(AIP-70 operator). It is what lets a host find every
session of one operator (to refresh them, or to keep one memory across
respawns) and what makes the operator's runtime.config layer 3 of the
session config (§Layers and precedence).
- Form. The value is an AIP-54 ref of kind
operator, written in its compact formoperator:<slug>. An operator of another workspace carries the cross-workspace suffix of AIP-54'soperator-body:operator:<slug>@<workspace>. Thews://operators/<slug>form is also valid, for an operator of the host's own workspace only: it has no suffix, and a host MUST NOT add one while rewriting it to the compact form (AIP-54 §The tenant-scope asymmetry). A bare slug is not a ref. - Resolved at spawn. A host that accepts
operatoron a spawn request MUST resolve the ref to an AIP-9 operator before it starts the session, and MUST refuse the spawn withoperator_unresolvablewhen it cannot: a session never records a dangling operator ref.operatordoes not replaceagent: the session's definition is still the agent the request binds, which for an operator is its resolved agent (AIP-9 §Runtime binding). - It binds, it does not authorize. The binding gives the session no
spawn authority and no grant: delegation stays the bound agent's
delegates_toplus policy (§Delegation), and the policy of the operator and of the session's node chain still applies (AIP-34, AIP-38). It does not choose the session's node scope either, which comes fromground(§Node scope). - Who may name it. The host operator, or
system, MAY name any operator. A session principal MAY name only the operator of its own session, and a nested spawn that names none starts without one: a child never gains an operator its caller does not hold, and never inherits it silently. - It follows the lineage. When a host starts a session as the
continuation of another under a new session id (§Apply classes), it
MUST copy the source's
operator, if any, onto the successor, reading it from its own registry and never from the request.
operator is a plain reference: the host MAY keep other facts about the
operator (a digest of the instructions it resolved) beside it; this AIP
defines none.
Operator label (added 2026-10-29)
The operator label (Session.operatorLabel) is a durable name the
operator gives to a session or to a lineage of sessions. It is the
label the label: scopes of AIP-39 and the
session-label:// principal of AIP-23
match. Session.label is distinct: free text any spawner attaches, for
display only, and a host MUST NOT match a grant against it. Neither is
Session.operator: operatorLabel is the label the host user (the
host operator of AIP-70, a human) gives to a session, and has nothing to
do with the AIP-9 operator that Session.operator names; a host MUST NOT
derive one from the other.
- Only the operator assigns it. Only the operator or
systemMAY assign, change or clear an operator label. A host MUST refuse a request from a session principal that would assign, change or clear any operator label (its own, a child's or another session's), on every surface (a rename, a configuration write, a tool,agent_set_operator_labelincluded). - A spawn records it only for the operator. A host MAY record the
labelof a spawn request as the operator label of the new session only when the caller is the operator and the new session has noparentSessionId. A host MUST NOT record an operator label from a spawn requested by a session principal. A child never inherits its parent's operator label: a session spawned by a session starts without one, and only the operator may give it one later (rule 1). A session started by a spawn request is not a continuation (rule 4), whatever lineage the request declares: it receives an operator label only under this rule. - Not unique. Several live sessions MAY carry the same operator label (a pool, or a lineage while its previous row retires). A consumer MUST NOT read an operator label as naming one session. A host that wants one live session per name refuses or reuses the second spawn; it does not reserve the label.
- It follows the lineage. When a host starts a session as the continuation of another under a new session id (a restart, a resume, a continuation or a handoff, §Apply classes), the host MUST copy the source's operator label, if it has one, onto the successor, reading it from its own registry and never from the request, whoever requested the transition. The session id and the credential are not carried (the Session principals section, credential rule 4): the operator label is the only name that survives. A successor of an unlabelled source has none until the operator assigns one.
A nested spawn inherits its parent's ground
Identity is not the only thing a nested spawn must carry down. A host MUST resolve a nested spawn's ground as:
- the request's explicit ground ref, when given
- otherwise the parent session's ground
A host MUST NOT resolve a nested spawn through §Workspaces' ambient
workspaces[active] fallback. That fallback exists for root spawns,
where the human's active workspace is a sensible default. For a nested
spawn it is actively wrong: active is a property of the human's
session, mutable at any moment by an unrelated workspace use, and
nothing about it is chosen by the spawning agent. A child resolved
that way runs with its parent's credentials in a directory its
parent never named — the parent believed it was delegating inside
its own workspace, and the daemon silently placed the child somewhere
else entirely.
The general rule: a nested spawn's context is derived from its parent, never from ambient host state. Where the host has no parent value to inherit and the request names none, it MUST reject the spawn rather than substitute an ambient default.
Ground narrows, like authority. A nested spawn's ground MUST
resolve inside the parent's own; a host MUST reject one naming ground
outside it (cwd_outside_parent). Inheritance alone is only a
default, and a default is not a boundary — without this rule a parent
hands its child any ground on the machine and the inheritance rule
buys nothing.
This is the same non-escalation principle delegates_to applies to
authority, applied to ground: a child may be given less than its
parent has, never more, on either axis. A subtree is the natural
shape — a parent may legitimately want a child confined to a package
inside its own tree, and never has cause to send one somewhere it
cannot itself reach.
The check is a containment test between two AIP-54
refs, not between two path strings. That is the whole reason ground is
a ref: AIP-54 rejects lexical escapes (.., absolute paths) at
parse time (§Reference syntax, per-kind bodies) — so the escape a naive prefix check would miss
is not expressible in the first place. A host that reduces refs to
strings and prefix-matches those has re-opened what the ref grammar
closed.
Two limits, stated because parse-time validity is not containment:
- Symlinks resolve after parse. A ref that is lexically inside the parent's subtree MAY still land outside it through a symlink. Hosts that treat the subtree as a security boundary MUST verify the resolved real path; hosts that treat it as an orientation default need not. AIP-46 does not decide which it is for you — see the §Delegation boundary note.
- The host's own fs/exec tools MUST anchor to the session's ground by this same rule. A spawn-time boundary that the session's own tools then ignore is not a boundary.
Limits
Independently of the allowlist, a host MUST bound recursion:
| Limit | Meaning | On breach |
|---|---|---|
maxDepth | greatest permitted depth | reject, create no session |
maxChildren | greatest number of concurrently alive children per session | reject, create no session |
An allowlist that names a peer (a delegates to a) is legal and
recursive; maxDepth — not the allowlist — is what terminates it.
Errors
A host MUST reject with a stable, machine-readable code. Codes below are normative; hosts MAY add their own.
| Code | Cause |
|---|---|
invalid_agent | agent ref does not resolve |
operator_unresolvable | operator ref does not resolve to an AIP-9 operator (§Operator binding) |
delegation_denied | caller's agent may not spawn the requested child |
cwd_outside_parent | nested spawn named ground outside its parent's subtree |
max_depth_exceeded | depth would exceed maxDepth |
child_quota_exceeded | caller already at maxChildren |
identity_unverified | caller claims a session id without a valid session credential, or presents a malformed, unknown or revoked credential, or presents none to an action the host requires proven for (§Session principals, rule 9) |
identity_mismatch | caller's claim names a session other than the one its credential was minted for (§Session principals) |
A rejection MUST be distinguishable from a spawn failure: the former means no session was permitted, the latter that one was permitted and failed to start.
What this gate cannot reach (informative)
An honest boundary, because implementations have shipped believing otherwise. Everything in §Delegation governs surfaces the host grants. Every harness also ships its own equivalent of those surfaces, and the host's rules do not reach them:
| The host governs | The harness's ungoverned twin |
|---|---|
| the delegation actions on the host's own gateway | a native task / sub-agent facility, spawning off-protocol |
| host fs / exec tools anchored to the session's ground | the CLI's own built-in shell and file tools |
| what the host injects into the child's config | what the harness already has in its config |
The pattern is one fact wearing three hats: a harness can do natively whatever the host can do for it, and the host's version is the only one with rules on it. A native sub-agent spawn has no session id and no parent edge — there is nothing to gate. A native shell reads any path the process can reach — ground is where it starts, not a fence.
Which decides whether ground is a boundary or a default, the question §A nested spawn inherits its parent's ground defers here. Where the child's only reach is the host's own tools, ground is a boundary: the containment check holds, and verifying resolved real paths against symlinks is worth it. Where the child has a native shell — the common case — ground is an orientation default: it says where work starts, not where it can go, and no amount of symlink-checking at spawn changes that. Hosts SHOULD know which of the two they are running and MUST NOT describe the second as the first. Turning ground into a real boundary for a harness with its own shell is AIP-36's job, not this AIP's.
Consequences a conforming host MUST accept:
- It MUST NOT report as gated anything it did not actually gate. A child spawned off-protocol is invisible, not denied; a path read through the harness's own shell is unbounded, not confined.
- It SHOULD disable the native facility through the harness's AIP-45 options wherever the harness exposes a flag, and SHOULD treat the absence of such a flag as a material property of that harness.
- It SHOULD treat AIP-36 as the only real backstop. A boundary the child's own tooling can step over is a convention. Where a host needs containment rather than convention, the containment is the sandbox — nothing in AIP-46 substitutes for it.
Stated plainly, because it is the rule most likely to be forgotten: AIP-46 bounds what the host hands out. It is not a sandbox, and no amount of naming discipline inside it becomes one.
HTTP surface
The host MUST expose these routes under a fixed prefix (default
/sessions):
| Method | Path | Body | Returns |
|---|---|---|---|
GET | /sessions | — | { sessions: Session[] } |
POST | /sessions/agent | SpawnAgentRequest | Session (201) |
GET | /sessions/:id | — | Session |
POST | /sessions/:id/prompt | { prompt: string } | { ok: true, id } |
POST | /sessions/:id/interrupt | — | { ok: true, id, wasBusy: boolean } |
POST | /sessions/:id/kill | — | { ok: boolean, id } |
DELETE | /sessions/:id | — | { ok: boolean, id } (forget) |
GET | /sessions/:id/stream | — | SSE — see §sse |
Interrupt (added 2026-07-17)
POST /sessions/:id/interrupt cancels the in-flight turn and leaves the
session alive and idle, ready for the next prompt with its context
intact. It is the wire form of the Ctrl-C a human would press at the
agent's own TUI, and hosts SHOULD implement it as exactly that (ACP
session/cancel, or a harness-specific SIGINT for process/PTY-backed
harnesses).
It is deliberately not a status transition: an interrupted session
stays running (see §Status transitions), which is the whole distinction
from kill (running → killed, terminal). Consumers that want "stop what
you're doing" MUST NOT reach for kill to get it — killing a session to
end one turn discards the agent's context and forces a respawn, defeating
the multi-turn continuity this AIP exists to provide.
wasBusy reports whether a turn was actually cancelled. Interrupt is
idempotent: on an idle session or one already in a terminal state it MUST succeed as
a no-op with wasBusy: false rather than erroring — a consumer racing a
turn-end should not have to distinguish "stopped it" from "it had already
finished", and both leave the session in the state the consumer asked
for.
Hosts MUST return 409 when the resolved harness cannot cancel a turn at
all: that is a capability refusal the consumer can act on (fall back to
kill, or surface it), not a server fault.
This route is the ONLY way to end a turn without supplying the next one.
POST /sessions/:id/prompt with interrupt: true (see §Multi-turn
semantics) cancels a turn too, but only as a means of redirecting the
session onto a new prompt — it cannot express "stop, and send nothing".
Hosts predating this route forced consumers to re-send a throwaway prompt
purely to reach the cancel, which pollutes the transcript with a turn the
user never asked for.
SpawnAgentRequest
{
/** AIP-45 harness slug: which harness runs. Required unless `config` or
* `preset` supplies it. */
harness: string
/** AIP-42 AGENT ref — WHAT it runs (prompt, skills, delegates_to,
* policy). Optional; absent ⇒ harness default + no delegation.
* See §Delegation. */
agent?: string
/** The AIP-9 operator the session runs for, an AIP-54 `operator:` ref
* (§Operator binding). Optional; it binds, it does not replace
* `agent` and grants nothing. */
operator?: string
/** WHERE it runs — an AIP-54 ref naming the session's ground.
* `ws://workspaces/@<owner>/<slug>` or its compact form, optionally
* with a subtree body. Root spawns MAY omit it (§Workspaces
* resolves a default); nested spawns inherit the parent's when
* absent and MUST NOT escape it (§Delegation). */
ground?: string
/** DEPRECATED alias for `ground`, accepting a raw absolute path.
* Root spawns only — a nested spawn MUST use `ground`, because a
* raw path cannot express the containment check §Delegation
* requires. Hosts SHOULD reject `cwd` on nested spawns. */
cwd?: string
/** Initial prompt — equivalent to start + prompt back-to-back. */
prompt?: string
/** Free-text label for the descriptor. */
label?: string
/** How the harness runs (2026-10-23, §Session config). `harness` above
* MAY be omitted when `config.harness` or the preset supplies it; when
* both are set they MUST be equal. */
config?: SessionConfig
/** A session preset id (§Session config, Session presets). */
preset?: string
/** An AIP-38 policy composed with the bound agent's; it can only narrow
* (AIP-38 §Delegation ceiling). */
policy?: PolicyRef
}ground replaces the old workspaceSlug + cwd pair. Those were two
fields expressing one axis with a precedence rule between them ("cwd
wins over workspaceSlug"), which is how a nested spawn ended up
resolving through the ambient active workspace: the field that should
have carried the parent's ground was optional, and the fallback behind
it was global. One field, one ref, no precedence rule to get wrong.
A ref also carries what a slug could not — a subtree
(ws://workspaces/@acme/studio/packages/runtime), which is exactly
what a parent needs to hand a child less ground than it holds.
Node scope
The ground also gives the session its node scope, defined by
AIP-34 §Node scope of a session:
the nearest declared node whose folder contains the ground, a subtree
body included (ws://workspaces/@acme/agentik/simone/docs is the
subtree simone/docs, written with slashes as in AIP-54's
local-body). This AIP adds the host's side of that rule:
- The host derives the scope from
Session.groundof the calling session, at spawn for the prompt it composes and on every file, memory, app or tool call that session makes, never from the configuration of the server that executes the call. A call whose caller session it cannot identify is refused, not served unscoped. - The scope belongs to the session, not to the operator named by
Session.operator. A session started through a seat of an AIP-22 office has the seat's node as its ground, not the operator's home node; one operator can run one session per scope. - A nested spawn's ground still narrows (§Delegation), so a child's node scope is its parent's or one nested inside it.
The agent and the harness
harness and agent are orthogonal and both may be present: the
harness is the runtime (which binary), the agent is the definition
(which prompt, skills, and delegation grant). The same
reviewer AGENT MAY be run on any conforming harness; the same
harness MAY run any agent. Hosts MUST NOT infer one from the other.
SSE event format
The /sessions/:id/stream endpoint emits one JSON-encoded event per
SSE message:
event: line
data: { "line": "hello world", "stream": "stdout" }stream is one of "stdout" | "stderr". Hosts MAY emit additional
event types (e.g. status for state transitions); consumers MUST
ignore unknown event types. Hosts SHOULD send a comment-line
keep-alive every 25–30 seconds to defeat proxy idle timeouts.
A host implementing §Session messages
SHOULD surface each message on whatever live event channel it offers —
once when it is accepted and again when it is delivered — as
{ messageId, sessionId, fromSessionId?, relation, kind, urgency, delivered? },
so an observer can react without polling. A host with a dedicated
session-event stream MAY frame it as event: message; one that streams
structured transcript records MAY rely on the session-message record
instead. The reference implementation emits a session:message bus event
and writes the transcript record.
MCP tools
Hosts that already expose an MCP server (the common case for daemons also serving fs/exec tools) MUST register the first five tools of the table below so MCP clients can drive sessions through the same connection:
| Tool | Inputs | Notes |
|---|---|---|
agent_start | {harness, agent?, operator?, ground?, prompt?, label?, config?, preset?, policy?} | Returns the Session JSON. Subject to §Delegation when the caller is a session. |
agent_prompt | {sessionId, prompt} | Fire-and-forget — call agent_output to read the reply. A delegation action (§Delegation). |
agent_sessions_list | {onlyAlive?: boolean} | Returns {sessions: Session[]} |
agent_output | {sessionId, lastN?: number} | Returns the last N ring-buffer lines |
agent_kill | {sessionId} | Returns {ok, sessionId} |
agent_set_operator_label | {sessionId, operatorLabel} | Sets the operator label; an empty string clears it. Returns {ok, sessionId, operatorLabel}. Registered by a host that supports operator labels, in addition to the five tools above. Operator only: a host MUST refuse it from a session principal (§Operator label). |
message_*, inbox_* | see §Session messages | Typed messages between sessions. Not delegation actions. |
The MCP tools and the HTTP routes target the same underlying registry — calling either family results in the same observable state.
agent_start and agent_prompt are the delegation actions of
§Delegation; hosts gate them by action identity, not by tool name.
Multi-turn semantics
A session stays alive after each turn. Subsequent
agent_prompt (or POST /sessions/:id/prompt) calls dispatch
to the same underlying agent process; the agent retains its in-
memory context (previous tool results, file reads, etc.) until the
session is killed.
Agents are single-turn-at-a-time, so a prompt that arrives while a
turn is in flight is never run concurrently with it. The host MUST
either reject it (HTTP 409 / MCP error) or queue it (FIFO) and
dispatch it after the current turn ends. Queueing is the shipped
behaviour of the reference implementation (the queue is inspectable
and reorderable). A queued prompt is dispatched only after a turn that
ended naturally: a turn the host interrupted does not drain the
queue, because "queued" means "after the current turn", not "the
moment anyone cuts it". Consumers can poll agent_output or watch
the SSE stream to know when a turn ended (look for the turn-end
projected line).
Redirecting a busy session (documented 2026-07-17). A prompt MAY
carry interrupt: true, which replaces that 409 with a redirect: the
host cancels the in-flight turn (as §Interrupt describes), waits for it
to settle, and then admits the new prompt on the same session, context
intact. It is a no-op modifier on an idle session — the prompt is
admitted normally, byte-identical to omitting the flag — so a consumer
racing a turn-end never has to choose in advance. This flag has shipped
in the reference implementation since before this AIP was written; the
document simply never described it.
interrupt: true and POST /sessions/:id/interrupt are not
alternatives: the flag cancels a turn in order to start another one
and cannot express "stop, send nothing"; the route ends a turn and stops
there. A consumer wanting the latter MUST use the route.
Session messages (added 2026-09-26)
A host that supports delegation (populates parentSessionId) MUST provide a
typed message channel between sessions in the same tree, distinct from
prompts; §Who may message whom says which other pairs it carries. A
prompt is an instruction from whoever drives the session; a message is
a report between sessions whose sender the host attests.
Envelope
interface SessionMessage {
id: string // host-minted
ts: string
to: string // recipient sessionId
from: {
sessionId?: string // absent only for relation "human" | "system"
label?: string // display only
agentSlug?: string // the sender's AIP-42 agent, when one was bound
relation: "child" | "parent" | "sibling" | "granted" | "human" | "system"
}
kind: "report" | "question" | "blocker" | "done" | "notice"
urgency: "fyi" | "next-turn" | "steer" | "interrupt" // as requested
correlationId?: string // thread id; defaults to the first message's id
replyTo?: string // a SessionMessage.id
text: string
data?: object
delivered?: { via: "wait" | "steer" | "turn" | "interrupt" | "inbox"; at: string }
ackedAt?: string
}from MUST be derived by the host from the principal it resolved for the
request (§Session principals; in
observe-only mode, the session a claimed caller claims), never from the
request body. A send request MUST NOT be able to set any from field;
hosts MUST reject one that tries. relation is computed relative to to
from the session forest. It is parent, child or sibling when that
structural relation holds, and granted when none does and a grant of
session:message allowed the send. label is display-only and MUST NOT
be relied upon for identity.
Who may message whom (amended 2026-10-29)
A send from one session to another is the AIP-39 action
session:message: its principal is the sender, as the Session
principals section defines it, and its target is the recipient. The
operator (the host operator of AIP-70) and the host itself (system)
are principals too, not pairs of sessions, and a host MUST allow a send
from either to any session. Between two sessions:
- A tree edge allows. A host MUST allow a send from a session to its parent and from a parent to its direct child, with no grant.
- Every other pair needs a grant. A host MUST refuse a send between
any other pair unless an AIP-38 grant of
session:messageallows it, evaluated with the AIP-38 composition rules: the union of allow grants, a matching deny wins over any allow, and the default is deny. Two children of one parent are not a tree edge: a grant alone allows them, as it alone allows a cousin or a grandparent. - No precedence. A tree edge and a grant are independent reasons to allow. A host MUST allow a send when either allows it, MUST NOT stop at the first reason it checks, and a deny grant removes only the grant as a reason, never a tree edge.
- Never to itself. A host MUST refuse a send whose sender is the recipient.
- The binding is the host's. A session's workspace binding is the
workspace its
groundresolves into (§Session data model); a host that does not resolvegroundto a workspace derives it as the most specific registered workspace (§Workspaces) whose path contains the real path of the session's working directory. A host evaluating aworkspace:scope MUST derive the binding itself and MUST NOT take it from a slug the session or any caller supplies (theworkspaceSlugof a spawn request, a header, a parameter, or a slug recorded on a descriptor from such input). Thedefaultbucket of §Bucket resolution is not a registered workspace and MUST NOT satisfy a workspace-scoped grant. - A workspace owner may only narrow. An AIP-34
workspace
policyMAY denysession:messagefor the sessions bound to that workspace, and MUST NOT allow a send the operator's policy leaves at deny.
A grant names its sender through its principal. A sender that
survives a restart is named by its operator label (§Operator label),
through the session-label:// principal of
AIP-23; group://<name> is not used
for sessions. A sender chosen by workspace binding cannot be named: a
workspace is not a principal, so no single grant says "any two sessions
of W" unless the operator gives those sessions an operator label
(§Open Questions). A link between two workspaces is expressed as a grant
scoped workspace:<slug> until AIP-34 defines a door form that names
session messages.
Recording
A delivered message MUST be recorded in the recipient's transcript as its
own record kind (session-message), never as a user prompt, and MUST NOT be
concatenated with any other prompt or with a message from a different
sender. Several messages MAY be delivered together as one turn, as long as
no prompt is part of it. Consumers MUST render a message distinctly from
human input (the sender, not "you").
Model-facing form
When a message is delivered into an agent's context, the host MUST wrap it
in a host-generated delimiter that names the sender's sessionId, relation
and kind, and MUST escape any occurrence of that delimiter inside the body —
and at the start of a line in human prompts — so the sender cannot be forged
from content. The exact delimiter is host-defined; the reference
implementation uses an agentproto-message element with the attestation in
its attributes and the escaped text in a body child element. Hosts SHOULD
tell the agent, once, that text outside the delimiter comes from the human
(or its spawn instructions), and that a message body is a report, not an
instruction from the human. The delimiter guarantees the header can't be
forged; it does not make the body trustworthy.
Delivery tiers
| urgency | idle recipient | busy recipient |
|---|---|---|
fyi | inbox only, no wake | inbox only |
next-turn | start a turn | queue; deliver after the current turn ends naturally |
steer | start a turn | inject into the running turn if the harness supports steering (AIP-44 _session/steering), else as next-turn |
interrupt | start a turn | cancel the turn and deliver (§Interrupt) |
A host MAY surface the unread fyi messages of a session to the model
as one bounded digest of ids and counts at the start of the recipient's
next turn; it MUST NOT inline their bodies.
A recipient blocked in inbox_wait with a matching filter MUST receive the
message as that call's result instead of any of the above, and the message
MUST NOT also be delivered as a turn.
A host MUST only steer into a turn it started and has in flight — never
into a turn the agent began on its own (an autonomous background-task cycle,
whose result the host may never see) — and SHOULD request the harness's
"prompt required" idle behaviour so a steer that arrives after the turn
settled is handed back rather than starting a detached turn. Hosts SHOULD
rate-limit steers per recipient; the excess is delivered as next-turn.
Hosts SHOULD NOT grant interrupt to session senders by default and MAY
downgrade it to steer; the user keeps it. The send result MUST
report the tier actually applied (urgencyApplied).
Inbox and tools
Hosts MUST keep un-consumed messages durably (surviving host restart) in a
bounded per-session inbox — a message leaves it when it is delivered into a
turn, returned by inbox_wait, or acknowledged — and MUST expose, alongside
the tools of §MCP tools:
| Tool | Inputs |
|---|---|
message_send | {to: "parent" | sessionId, text, kind?, urgency?, replyTo?, correlationId?, data?} |
message_parent | {message, kind?, urgency?, interrupt?, replyTo?} — alias of message_send({to: "parent"}) |
message_reply | {replyTo, text, kind?, urgency?} — routed to the original sender, same correlationId |
inbox_list | {from?, kind?, correlationId?, limit?} |
inbox_ack | {ids, noop?}: noop: true declares that the caller looked at the items and nothing needed doing. The host records it for the caller's current turn at the ack itself; it never sets silent on its own, and the host decides silent at turn end under AIP delivery triage section 8. Hosts that do not support the flag ignore it and ack normally. |
inbox_wait | {from?, kind?, correlationId?, timeoutMs?} — blocks until a match or the timeout; returns {messages, timedOut, pendingChildren} |
inbox_wait is how a supervisor collects its children's reports without
ending its turn: an idle session has nothing to wake it, so a supervisor
that ends its turn to wait depends on some unrelated prompt arriving. Hosts
SHOULD keep timeoutMs under the MCP request timeout and return
pendingChildren (children still working) so the caller's loop knows when
to stop.
message_* and inbox_* are not delegation actions
(§Delegation): they reach only the
pairs §Who may message whom allows and grant no control over the
recipient.
HTTP hosts SHOULD mirror them as POST /sessions/:id/messages (the
recipient is :id; the sender is the authenticated caller),
GET /sessions/:id/inbox, and POST /sessions/:id/inbox/ack.
The four urgency tiers are the only delivery targets of the triage stage in AIP delivery triage: triage can lower or keep the urgency of an item before it enters the inbox, never raise it.
Output projection
When the underlying harness speaks AIP-44/ACP (the common case), the host SHOULD project structured events into the ring buffer with human-readable prefixes:
| ACP event | Projected line |
|---|---|
text-delta | the delta text, joined on \n boundaries |
thought | [thought] {text} (dim) |
tool-call | [tool] {toolName} (cyan) |
tool-result (error) | [tool-error] (red) |
agent-prompt | [awaiting input] (yellow) |
turn-end | ── turn-end ({reason}) ── (dim) |
error | [error] {message} + child stderr tail (red) |
The exact wire format is non-normative; the goal is that a CLI
observer (agentproto sessions --attach <id>) sees a coherent
transcript without parsing per-event JSON.
Session artifacts (added 2026-09-28)
A session MAY hold a durable artifact store, separate from and
outliving the ring buffer / transcript: a document, image, pdf, html
page, presentation, or site (a directory with an index.html,
served read-only) a session produces or is handed, kept across
restarts and browsable independently of any one chat turn. This is
deliberately a different thing from the plain chat attachment a
composer sends inline with a prompt (materialized read-only,
transcript-scoped) — an artifact is promoted, versioned, labelled, and
pinnable.
An artifact record reuses AIP-58 §1's ArtifactEntry
shape (key, path, sha256, size, contentType) field-for-field
— path here is relative to the SESSION's own directory the same way
ArtifactEntry.path is relative to a run's workspace — plus the
session-artifact envelope AIP-58 has no notion of: kind (image |
document | pdf | html | presentation | site | file),
label, pinned, createdBy (agent | user), and sourceRef
(free-form provenance — e.g. a promoted attachment, an
AIP-58 run artifact, a canvakit export). Re-adding the
same key with different content accrues a new version under it;
re-adding identical bytes is a no-op. No new AIP was warranted: the
concept is session-scoped state, exactly this AIP's domain, over a
shape AIP-58 already fixed.
A conforming host that implements this section MUST expose:
| Tool | Inputs | Notes |
|---|---|---|
session_artifact_add | {sessionId, key?, kind?, label?, createdBy, sourceRef?, bytes? | sourcePath?, name?, mimeType?} | bytes (base64) or sourcePath (an existing file, or a directory for kind: "site"), mutually exclusive. Returns the record. |
session_artifact_list | {sessionId} | Every key's current label/kind/pin plus its full version history. |
session_artifact_get | {sessionId, key, version?, maxBytes?} | Metadata plus bounded content (single-file kinds); a site version returns metadata only. |
session_artifact_pin | {sessionId, key, pinned} | Toggles the pin surfaced in §Session outcome below. |
HTTP hosts SHOULD mirror them as POST/GET /sessions/:id/artifacts,
GET /sessions/:id/artifacts/:key, POST /sessions/:id/artifacts/:key/pin,
and a read-only raw-serve route (GET /sessions/:id/artifacts/:key/raw[/...],
the /... browsing a site version's directory, defaulting to
index.html) that a viewer embeds directly — an html/site artifact
renders sandboxed behind a strict Content-Security-Policy (no
connect-src, no form-action) so the rendered page can reach neither
the host's own tool-call surface nor any other origin, the same
no-bridge posture AIP-53's app-UI iframe takes.
A host SHOULD fire a session:artifact-added / session:artifact- pinned-changed lifecycle event (this AIP's own namespaced vocabulary,
per AIP-37 rule 4) on each mutation, so a live UI
updates without polling.
Session outcome (added 2026-09-28)
A session's derived outcome (a host-computed "what did this session
produce", out of this AIP's scope to fully specify but referenced here
because artifacts feed it) MAY carry type: "file" refs alongside any
pr/commit/url ones it already supports — one per pinned
session artifact, ref set to the artifact's key. An unpinned
artifact still lists via session_artifact_list; pinning is what
promotes it into the terse "ended" summary a supervisor or UI reads
without a separate call.
Session cost and billing basis (added 2026-10-18)
Draft — AIP-46 amendment (2026-10-18). Normative identifiers (field names, literals, tool names) are English and final.
Problem. A conforming daemon today records a costUsd field of
"API equivalent" (or 0) on sessions launched under a flat-rate
subscription (Claude Code ~$200/month, Codex, …). A session that looks
"free" actually consumes an amortised subscription — and a daemon may
spawn dozens of sessions within the same 5-hour window. No
quality-per-USD decision can rest on that number.
The Session interface currently declares no cost fields; every host
added one of its own (tolerated by the "MUST ignore unknown fields"
rule, but with no shared semantics). This amendment fixes the
semantics in this AIP: cost is per-session state, exactly the domain
of the descriptors.
Descriptor fields
The interface Session (§Session data model)
gains three optional fields, filled in by the host at the end of each
turn and aggregated over the session's lifetime:
/** Marginal cost of the session, in USD (float): what the session
* would have cost at the public API price. In "api" mode this is
* the actual bill; in "subscription" mode it is the informative
* API-equivalent price (may be 0 if the harness does not report
* it); in "free" mode, 0.
* MUST NOT be the basis of a quality-per-USD decision when
* billingMode ≠ "api". */
costUsd?: number
/** Share of the plan's cost attributed to this session: the access
* profile's `monthlyUsd` fee apportioned proportionally to usage
* (see Amortisation). 0 when billingMode ≠ "subscription". This is
* THE number to compare in quality-per-USD. */
amortizedCostUsd?: number
/** How the session is billed. */
billingMode?: "api" | "subscription" | "free"Invariants:
billingMode: "api"⇒amortizedCostUsdabsent or 0;costUsdis the actual spend.billingMode: "subscription"⇒amortizedCostUsdMUST be present;costUsdis the API-equivalent price.billingMode: "free"(free models subject to rate limits) ⇒ both costs are 0; the token counter is still reported.- A host declaring a
subscription(§Access profile) MUST populatebillingModeon each of its sessions; without a subscription profile, the three fields stay absent (current behaviour unchanged).
Access profile and subscription
A host declares its accounts as AIP-69 auth profiles
(2026-10-23: AIP-69 owns the document; the first draft of this section
named the billing party provider, which AIP-69 calls endpoint, and its
auth ref resolves to AIP-69's credentialRef or source). This section
keeps only what amortisation needs, the optional and declarative
subscription block:
authProfiles:
- id: claude-sub
endpoint: anthropic
method: oauth-bearer
source: claude-code-oauth # or credentialRef: <AIP-19 secret slug>
subscription:
monthlyUsd: 200 # plan actually paid
windows: # amortisation windows (see Amortisation)
- kind: 5h
- kind: weeklymonthlyUsdis in major units (float): it is declared by the operator, not a transaction — transactional amounts remain in minor units (AIP-55 §Minor units).windows[].limit(optional): a token ceiling, when known/reported; otherwise the host infers it by observation.kind: "5h"— a rolling 5-hour window (Claude Code, Codex);kind: "weekly"— a weekly cap.
Amortisation
planWeeklyCost = monthlyUsd / 4.348 (52 weeks / 12 months)
amortizedCostUsd(session) =
planWeeklyCost × (sessionTokens / profileTokensOnTheWindow)where profileTokensOnTheWindow is the total usage (all sessions
combined) of this profile over the encompassing weekly window. If no
usage has occurred yet, the apportionment is proportional to the
elapsed time of the window: the subscription is being paid regardless.
The 5h window is not used for amortisation (too short, too noisy);
its quota semantics are specified in AIP-67.
Quota status
Quota status (remaining headroom, resetsAt, the quota_status tool
and its HTTP mirror) is not part of this amendment. It is specified in
AIP-67 (agentproto/agentproto#80). This amendment
defines only the per-session cost fields above and the declarative
subscription block that feeds amortisation; the windows declared
there are inputs to the amortisation formula, not a quota read surface.
Examples
- Claude Code on a subscription — the case that motivates the
amendment. Today:
costUsd: 0, same as a free session; the quality-per-USD table distorts every decision. After:billingMode: "subscription",costUsdremains the API equivalent (may stay 0),amortizedCostUsd≈ $0.86 for a session of 1.2M tokens on a weekly profile totalling 80M tokens with a $200/month plan, i.e. 200 × (1.2M / 84.6M monthly-token equivalents). apisession (per-call paid key) — unchanged:costUsd= actual bill,billingMode: "api".- Free model (per-minute rate limit) —
billingMode: "free", tokens visible, costs at 0.
Compatibility
The project has no external users: no migration, direct replacement
(workspace/v2 posture). The "costUsd alone" reading disappears
from quality-per-USD displays in favour of amortizedCostUsd — that
is the intended correction. Third-party consumers that read raw
costUsd continue to receive it, with a clarified meaning: marginal
cost.
Session config, presets and fallback (added 2026-10-23)
Draft AIP-46 amendment (2026-10-23). Normative identifiers (field names, literals, tool names) are English and final.
Problem. SpawnAgentRequest names three axes: which harness
(harness), what it runs (agent), where (ground). Every host also has
to choose how the harness runs: which model, which account pays, which
permission posture, which reasoning effort, which gateway route. Those
choices are scattered: AIP-42 carries an authoring-time
model, AIP-9 carries runtime.config in harness-native
ids (mode, options), AIP-45 carries manifest defaults,
and the reference implementation grew one flat field per choice on
agent_start, two kinds of saved configurations and a retry rotation list.
Nothing says which source wins, which choice can change on a live session,
or what to do when the chosen model or account fails.
This amendment adds one normalized carrier, SessionConfig, with:
- the runtime axes and, for each, its apply class (how a change reaches a live session);
- the layers that produce it and their precedence;
- session presets: named, saved configs;
- fallback: an ordered list of config overlays walked on a classified failure, each step applied with the least disruptive transition that is valid;
- the points where AIP-38 policy is evaluated.
Configuration says what a session wants. Permission stays in AIP-38: a
spawn MAY carry a policy that narrows the bound agent's policy (it can
never widen it, AIP-38 §Delegation ceiling), and that is where model
allow and block rules and spend ceilings live, not in the config.
The SessionConfig carrier
interface SessionConfig {
/** AIP-45 harness slug. Same value as SpawnAgentRequest.harness. */
harness?: string
/** A model id (possibly an AIP-57 virtual key), or `selector:<id>`: an
* ordered, saved selector over the AIP-43 model registry. */
model?: string
/** Reasoning effort, one of the levels the harness declares for the
* model. */
effort?: string
/** What the agent may do without asking. Canonical values, or a raw
* harness mode id when no canonical value fits. */
posture?: "default" | "plan" | "accept-edits" | "bypass" | "read-only"
| { harnessModeId: string }
/** What enters context: an AIP-45 mode of `kind: "context"`. */
contextProfile?: string
/** Gateway or billing route. Normally derived from `model` through the
* catalog; set only to override. `baseUrl` only for a custom gateway the
* catalog cannot resolve. */
route?: { gateway: string; baseUrl?: string }
/** The account: an AIP-69 auth profile. */
access?: { profileRef: string }
/** Harness-native AIP-45 options not covered by an axis above. Validated
* exactly like AIP-9 `runtime.config.options`. */
options?: Record<string, unknown>
/** Same-config retries before any fallback step. */
retry?: {
on: FailureClass[]
maxRetries?: number
/** Retry a turn that already ran a tool call. Default false: a turn
* with side effects is not replayed. */
retryAfterToolCalls?: boolean
}
/** Ordered overlays tried on a classified failure (below). */
fallback?: ConfigOverlay[]
}
/** A patch over the base config. Axes it omits keep the base value. */
type ConfigOverlay = Omit<SessionConfig, "retry" | "fallback">
type FailureClass =
| "rate-limit" | "quota-exhausted" | "upstream-5xx" | "model-unavailable"
| "auth-failed" | "no-output-stall" | "harness-crashed"The JSON Schema is
resources/aip-46/draft/SessionConfig.schema.json.
A host-specific key outside the axes above MUST be prefixed x-, so a
conformance check can tell a host extension from an unspecified field.
The harness axis was named adapter in earlier drafts, and Session and
SpawnAgentRequest carried adapterSlug and adapter. Those names are
removed: they are not fields of this AIP, and a conforming host does not treat
them as synonyms of harness. A host that still accepts one during a
transition does so as a deprecation announced under
AIP-70 §4, not as part of this AIP.
SpawnAgentRequest gains config?, preset? and policy? (see the
updated interface in §SpawnAgentRequest). The Session record gains
config (the resolved config as applied, fallback included; when the
request named model: "selector:<id>", config.model is the concrete
member chosen and configSources.model names the selector),
configSources (for each axis, the layer that produced it:
"manifest" | "host" | "definition" | "preset" | "request" | "fallback")
and fallbackStep (the index of the overlay in effect, absent on the base
config).
What is not in the config. SessionConfig covers how the harness
runs. Other spawn inputs keep their own owners:
| reference implementation field | owner |
|---|---|
skills, bundles, mcpServers, browser | what the agent can use: the AIP-42 agent (tools, skills) or the spawn request; changing them is a restart |
contextSettings (legacy contextContinuity) | §Session context: a block of its own, layered setting by setting |
costBudget, maxCostUsd, a model allow or block list | AIP-38 limits and grants in the spawn policy (spend-usd, model:invoke) |
sandbox, cloud, worktree | placement: AIP-36, AIP-66 and §Workspaces; not changed by fallback |
placement (an ordered ladder of sandboxes) | placement: AIP-36 v1.4 §1; walked before the agent starts, never by fallback |
turnRetry.action: "migrate" (move to another sandbox box) | placement; out of scope of fallback |
Placement and fallback split on whether the agent has started. The AIP-36
v1.4 placement ladder chooses a sandbox (and optionally a model, access
and turnRetry per rung) before the agent starts; fallback changes the
config of a session that is already running. A ladder rung's turnRetry is
the policy of the session placed on that rung: it replaces the spawn's
top-level turnRetry for that session, and its fallback entries are
overlays in the sense of this section, walked by §Fallback on that session
only (AIP-36 v1.4 §4; agentproto/ts
packages/runtime/src/placement-ladder.ts:122-155). A fallback step never
re-walks the ladder. A metered model reached either way, as a rung model
or as a fallback overlay, MUST be admitted only through an owner-controlled
allowlist (AIP-36 v1.4 §5).
Apply classes
Every axis has an apply class: the least disruptive way a change to it reaches a running session.
| axis | class |
|---|---|
model | live when the harness can switch models in session (an ACP session config option or an equivalent its manifest declares) AND the new model resolves to the same route, endpoint and auth profile; otherwise restart |
effort | live when the harness exposes it as a session option, else restart |
posture | live when the harness has a native mode switch (ACP session/set_mode), else restart |
contextProfile, route, access, options | restart |
harness | handoff |
A model change that moves to another route or endpoint is a restart
because the route is part of the process environment: applying it live
would keep the old credential and base URL, billing the wrong account.
The class of a change is the highest class among the axes it modifies
(live < restart < handoff). The three transitions:
- live: the host applies the change to the running process; the conversation is untouched.
- restart: the host stops the process and starts it again on the same
session id with the new config, resuming the conversation through the
harness's
native-resumecontinuation (AIP-45 §Continuation). When the harness cannot resume, a restart is not possible and the change is a handoff. - handoff: the host starts a new session with the new config on the
same
ground, seeded with a bounded summary of the old one, declares it the successor of the old session (live children are re-parented), and ends the old one.
Surface (MCP, with HTTP mirrors):
| tool | input | behaviour |
|---|---|---|
agent_set_model, agent_set_effort, agent_set_posture | {sessionId, value} | live change of one axis. When the change is not live on this session, MUST NOT apply and MUST return {applied: false, requires: "restart" | "handoff", suggestedOverride: ConfigOverlay}. Never throws on a refusal. |
session_restart | {sessionId, config?: ConfigOverlay} | restart transition. When the overlay changes harness, MUST refuse with requires: "handoff". |
session_continue_fresh | {sessionId, config?: ConfigOverlay} | handoff transition. Returns the new session. |
Layers and precedence
The resolved config is built axis by axis (each axis replaced whole by the highest layer that sets it), lowest precedence first:
manifest: the harness manifest's defaults (AIP-45models.default, default mode);host: host defaults for that harness;definition: the bound AIP-42 agent'smodel, then, above it, the bound AIP-9 operator'sruntime.config(itsmodeprojected ontopostureorcontextProfile, then itsoptions,options.modelmapping tomodel). The bound operator is the oneSession.operatornames (§Operator binding); a session without one has no such layer. Only the portableruntime.configenters here: the preset, the posture and the auth profile are host configuration (AIP-9 §Runtime binding) and arrive at layers 4 and 5;preset: the session preset whosedefaultFornames the harness, then the named preset, after itsextendschain is applied;request: explicit fields of the spawn request.
AIP-38 policy is evaluated on the result. It never fills or changes an axis: it allows or refuses. A host SHOULD offer a way to print the resolved config with the layer of every axis.
Session presets
interface SessionPreset {
id: string
label?: string
tags?: string[]
/** Other session presets applied first, left to right. A missing target
* or a cycle is an error at save time. */
extends?: string[]
/** Applied (layer 4) to every spawn on this harness that names no other
* preset. At most one preset per harness. */
defaultFor?: string
/** AIP-42 agent bound when the request names none. */
agent?: string
/** AIP-38 policy composed with the request's (both apply). */
policy?: PolicyRef
config: SessionConfig
}Merging a preset over another (an extends chain, or a preset over the
lower layers): each axis of config is replaced whole, except options,
merged key by key; fallback and retry are replaced whole; tags are a
union; agent is replaced; policy entries accumulate (AIP-38
composition).
- An explicit
agentin the request wins over the preset's. A preset'sagentis a requested agent like any other: when the caller is a session, it MUST pass §Delegation's spawn gate. - A session preset is host configuration owned by the user. It is a
different thing from an AIP-45 gateway (
gateways, formerlypresets, in a harness manifest, which declares a backend endpoint; renamed in agentproto/agentproto#98).
Fallback
When a turn fails with a FailureClass, the host:
- retries the same config up to
retry.maxRetriestimes when the class is inretry.on(never after a tool call unlessretryAfterToolCalls); - when the requested
modelwas aselector:<id>, moves to the selector's next eligible member, picked by the selector'srotation(AIP-43 §Saved selectors), re-resolved at this step; - walks
fallbackfrom the step afterfallbackStep: for each overlay, merges it over the base config (the spawn's resolved config, not the previous step), skips it when the result is not eligible, and applies the first eligible one.
A merged config is eligible when its harness is installed, its auth
profile is eligible for (harness, route, model) (AIP-69
§Eligibility), its (model, profileRef) pair is not in a cooldown, and
policy allows it (next section).
The transition of a step is the highest of the class its changed axes
require and the class its failure requires: harness-crashed requires at
least restart (there is no live process), and a no-output-stall is
interrupted before the step is applied.
- A failure that is not a
FailureClass(a tool error, a user interrupt, a policy refusal) MUST NOT trigger a step. rate-limitandquota-exhaustedput(model, profileRef)in a host-wide cooldown; eligibility reads it, so concurrent sessions do not all hit the same limit.- Steps only move forward. A successful step is sticky: later turns stay on it, and a later failure continues from the next overlay. The session never returns to an earlier step on its own.
- Each step MUST be recorded on the session (
fallbackStep) and emitted as asession:fallbackevent carrying{from, to, transition, failure}(configs without credential material). - An exhausted chain leaves the session idle with the last failure. It MUST NOT loop over the chain again.
Resolving a selector. A selector is resolved when a model is bound
(spawn, restart, handoff, fallback step), never in the middle of a session:
editing it does not move a running session. Each candidate member is
checked as a concrete model id (eligibility, then model:invoke with the
member as scope); the first that passes is used and recorded. A selector
that does not resolve refuses the spawn (selector_unresolvable) and makes
a fallback step ineligible.
Selectors are not AIP-57 chains. An AIP-57 chain
spreads conversations across candidates by a sticky hash, per request, with
no credentials. A selector:<id> here is an ordered candidate list for one
session: the first eligible member is used, the next ones are failover.
When model names an AIP-57 virtual key, AIP-57 selects within it as
usual, and this section only sees the failure.
The reference implementation's turnRetry.rotate list is the special case
of a fallback whose overlays only change model.
Policy evaluation points
Using the AIP-39 standard runtime actions:
| moment | actions evaluated (all must allow) |
|---|---|
| spawn (after all layers) | session:spawn (scope: harness), auth-profile:use (scope: profile), model:invoke (scope: model) |
| live change | session:configure (scope: axis), plus model:invoke when the model changes |
| restart or handoff with an overlay | the spawn set, on the new config |
| every fallback step | the set of the transition the step performs |
| a caller other than the owner prompts, or interrupts, kills, restarts or hands off | session:prompt or session:control (scope: session id or label), in addition to any row above |
| a session messages a session that is not its parent or direct child | session:message (scope: session id, label or workspace), as §Who may message whom defines |
Two refusal vocabularies, kept apart:
- an AIP-69 eligibility failure (disabled profile, wrong endpoint, method
the harness cannot present) is
auth_profile_ineligiblewith the failed rule; - an AIP-38 denial is
{applied: false, reason: "policy:<code>: <detail>"}with the AIP-38 decision record.
On spawn both are client errors (HTTP 400), never server errors.
Session context (added 2026-10-29)
Draft AIP-46 amendment (2026-10-29). Normative identifiers (field names, literals, action names) are English and final.
Problem. A compaction, a fresh continuation and a handoff each discard context the session built. When the host decides one on its own, nobody asked for that loss; when nothing decides, a session that fills its window is truncated or refused by the provider. This section says what a host owes a session before it discards its context, the floor that holds with no setting at all, and how the context settings layer.
A checkpoint is the record that POST /sessions/:id/checkpoint and
the MCP tool session_checkpoint persist: a bounded record of the
session's state (its goal, decisions, changed files and next step),
saved next to its transcript, which it never replaces. A session's
fill is its used context tokens over its context window, as its
harness reports them.
-
A checkpoint precedes any host-decided context loss. Before a host compacts a session, continues it fresh or hands it off on its own decision (a token threshold, a quota, the floor of rule 2), it MUST write a checkpoint built from the transcript and the host's own state, with no model call. A host that cannot write it MUST NOT discard the context. A compaction the user or the operator requests explicitly is not host-decided; a host SHOULD checkpoint it too.
-
The floor holds without a setting. A host MUST refuse a prompt to a session whose fill is at or above the floor (
hardStopAtPct, default 90 percent), whether or not any context setting was ever given for that session, and when it refuses MUST start recovering the session: the checkpoint of rule 1, then a compaction, then a fresh continuation when the compaction left the fill at or above the floor. A compaction prompt is the way out and is not refused by this rule. A host that cannot read the fill (the harness reports no usage or no window) MUST NOT refuse on a guess. -
An absolute token threshold. A host MAY compact an idle session when its used context tokens reach
autoCompactAtTokens, an absolute count, independent of the window size;0turns it off. Such a compaction is host-decided (rule 1) and MUST NOT start mid-turn. The percent bands that warn, compact or continue fresh at a share of the window are not part of this AIP. A host MAY keep them as host extensions: in thecontextSettingsblock their keys MUST be prefixedx-(§TheSessionConfigcarrier), and no conformance check reads them. -
The context settings are independent axes. They form a block of their own,
contextSettings, outsideSessionConfig(the table under "What is not in the config"):interface ContextSettings { autoCompactAtTokens?: number // rule 3; 0 = off hardStopAtPct?: number // the floor of rule 2; default 90 compactRequiresOperator?: boolean // rule 5; default false }The block is resolved over the layers of §Layers and precedence, and each of its settings is its own axis there: replaced whole by the highest layer that sets it. A request that sets only
contextSettings.autoCompactAtTokensleaves a lower layer'scontextSettings.hardStopAtPctin force. A host SHOULD offer a way to print the resolved block with the layer of every setting. The legacy namecontextContinuityis accepted as an alias ofcontextSettingsfor the period AIP-70 §4 allows; its other keys (amode, the percent bands) are host-defined and no conformance check reads them. -
Who may compact. When
compactRequiresOperatoris true, the actionsession:compacton that session is reserved to the operator. A host MUST refuse a compaction of the session requested by a session principal (§Session principals), the session itself included, on every surface that carries one (a compaction command in a prompt, a compaction tool), as an AIP-38 denial in the form of §Policy evaluation points:{applied: false, reason: "policy:explicit-deny: <detail>"}. A host-decided compaction (rules 1 to 3) is not requested by a session principal and is not refused by this rule. -
Conformance. A host claims this section when it meets rules 1 and 2 and resolves every setting of
contextSettingsas its own axis (rule 4). Rule 3 is optional: a host that does not implement it ignoresautoCompactAtTokens. A host that does not implement rule 5 MUST refuse a block that setscompactRequiresOperator: true: a reservation dropped in silence leaves the session compactable by any caller.
Informative: why each setting is its own axis. A host that took the whole block from the highest layer that set any of its keys, and filled the rest from built-in defaults, gave a session the threshold its request set and the built-in floor and bands, not those the operator had configured for the host.
Informative: the reference implementation.
@agentproto/runtimewrites a checkpoint (checkpointBeforeContextLoss) before every compaction prompt inrunAgentTurn, refusing the compaction when it cannot, and before a hard stop.validateAgentTurnholds the floor with no policy (CONTEXT_CONTINUITY_DEFAULTS, 90), skips it whencomputeContextPctreturns null, and startsperformContextRescue(compact, continue fresh, then stop); its refusal is a plain error.autoCompactAtTokensdefaults to 150000 and a non-zero value is clamped into [1000, 600000] (AUTO_COMPACT_DEFAULT_TOKENS,clampAutoCompactTokens): the reference's values, not this AIP's. It does not conform yet: it reads onlycontextContinuity; it keeps the percent bands unprefixed (warnAtPct,compactAtPct,continueFreshAtPct); it takes the whole block from the first layer that sets one (spawn-defaults.ts) and merges it only over its built-in defaults (resolveContextContinuityPolicy); andassertCompactionAllowedrefuses a session's compaction with a plain error, not the AIP-38 denial form.session_checkpointasks the session for a handoff turn unlessaskSourceis false.
Rationale
Why buckets under the host's state root, and not inside the workspace
itself. The obvious alternative to ~/.agentproto/workspaces/<slug>/
is the git-style one: put each workspace's state in the workspace —
<repo>/.agentproto/ — where the partition is free, needs no registry
lookup, no default fallback, and no migration, because the directory
is the identity. It was rejected, and the reason is worth stating
because the ergonomics genuinely are better.
Transcripts are not metadata. They contain the full text of agent
conversations: every prompt a user typed, every file the agent read
back, and every secret that passed through a turn — §Security
Considerations already warns that the ring buffer captures whatever the
agent printed. Co-location writes that stream into a directory whose
defining property is that it is tracked, committed, and pushed. The
failure is not hypothetical or gradual: it is one forgotten
.gitignore between a private transcript and a public remote, on a
path the user did not choose and has no habit of auditing. A host that
partitions this way has fixed a fairness bug by manufacturing a
disclosure bug, and the disclosure bug ships to everyone who clones the
repo.
The registry lookup, the default bucket, and the migration are the
price of keeping the state in a directory that exists to hold state.
That is the trade this section makes deliberately.
Why membership in the registry is the validation. A slug arrives
from a caller; a bucket is a directory name. Every other approach to
that gap is a sanitiser, and a sanitiser is a thing you can get subtly
wrong forever. Requiring the slug to come back from the registry
lookup collapses validation into a step the host already performs: the
only strings that ever become directory names are ones the host itself
minted and sanitised on the way in. An attacker-supplied slug is not
rejected, escaped, or normalised — it simply fails to match, and lands
in default like any other unregistered work.
Why default is a bucket and not an error. Refusing to persist a
session whose workspace is unregistered would make the partition a
breaking change for every one-off cwd spawn, and hosts would respond
by auto-registering, which turns a registry of the user's intent into a
registry of everything that ever ran. Accepting them into a named,
shared bucket keeps the migration additive and keeps the registry
meaningful — at the cost, stated plainly above, that default gives
its occupants no separation from each other.
Why partitioning is specified without a scoping rule. A reader could reasonably expect this section to also say "and a consumer scoped to workspace X MUST NOT see workspace Y's sessions". It deliberately does not. Partitioning is a storage property; confidentiality is an access-control property, and the two are independent — a host can partition perfectly and still serve every bucket to every caller, which is exactly what a host does the day it lands this section. Specifying the storage boundary first is what makes the access rule expressible later; conflating them would let an implementer read this section, ship the layout, and believe they had shipped isolation. §Security Considerations says so in the negative, and §Open Questions carries the scoping rule as the follow-on work it is.
Reference Implementation
The @agentproto/runtime package implements AIP-46 alongside AIP-45.
Daemons started via agentproto serve (or built directly through
createGateway()) expose:
- HTTP routes:
runtime/src/http-server.ts— handler under/sessions/* - MCP tools:
runtime/src/session-tools.ts— registered per-request viamcpServerFactory - Registry:
runtime/src/sessions.ts— in-memory + persisted (debounced) to the per-workspace snapshot~/.agentproto/workspaces/<slug>/sessions.jsonof §State partitioning; carriesparentSessionId+depth - Workspaces config:
runtime/src/workspaces-config.ts— read+write helpers for~/.agentproto/workspaces.json - Bucket resolution + migration:
runtime/src/workspace-buckets.ts— the slug→bucket rule, thedefaultfallback, and the additive split of the legacy globalsessions.json - Spawn gate:
runtime/src/session-spawn.ts— the enforcement point of §Delegation - Session credentials:
runtime/src/session-credentials.ts,runtime/src/identity-defaults.tsandobserveCallerIdentityinruntime/src/http-server.ts, the credentials of §Session principals
§Delegation now has a partial
reference implementation in @agentproto/runtime: agent_start accepts
an agent ref, every session records meta.agentSlug, the built-in
executor and supervisor agents declare delegatesTo, and a
delegation gate evaluates the calling session's bound agent, in
observe mode by default (counting, refusing nothing) with enforce
available. It does not conform by default. Divergences are tracked in
that repository's issues rather
than here: a spec carrying an implementation's bug list goes stale the
moment the bugs close, which is how this document's tool names drifted
in the first place.
That gap generalises into a rule worth stating plainly, because the failure is silent and the consequence is credentialed processes: a consumer MUST NOT assume a host enforces the spawn gate merely because the host implements AIP-46. Delegation is the one part of this AIP whose absence is invisible from the outside — a host that never gates looks identical to one that does until something spawns that should not have. Hosts SHOULD advertise conformance to §Delegation explicitly; consumers that rely on the gate SHOULD verify it rather than infer it.
The CLI shell @agentproto/cli adds:
agentproto workspace add|list|remove|usefor managing the workspaces configagentproto sessions [--watch] [--attach <id>] [--json]for browsing + tailing the registry
Backwards Compatibility
This AIP is Draft and pre-adoption: the reference implementation is its only consumer. Breaking changes are therefore cheap, and this document prefers being right over being compatible with its own earlier drafts. Where the spec and the implementation disagree, the implementation moves. Once a second consumer exists this section gets stricter; until then, treat every rule here as settled by argument rather than by precedent.
The session lifecycle itself is additive over AIP-45: hosts adopt it by
registering the registry + routes, and existing agentproto run
invocations continue to work unchanged (they bypass the registry, which
is fine for one-shot scripting).
Hosts MAY refuse to register the routes when no AIP-45 harness is
installed; they then SHOULD return HTTP 501 from
POST /sessions/agent with a clear message pointing at the install
command.
There is no role on this surface
Some hosts grew a private role: executor | supervisor field carrying
delegation authority. It is not part of this AIP and a host MUST NOT
introduce it: a spawn names an agent, and authority comes from that
agent's delegates_to plus policy. A host carrying the field today
MUST replace it: the delegating tier becomes an AGENT declaring
delegates_to, the leaf tier an AGENT declaring none, each shipped by
the host as a built-in AGENT a spawn request may name. A host MAY keep
the field, for a period it states, as a deprecated alias of agent
that behaves exactly like it (AIP-70 §4): role: <name>
binds the built-in AGENT <name>, is bounded by the caller's
delegates_to like any other binding, MUST NOT accept a name that is
not a built-in AGENT, and MUST NOT grow a new value (a new tier is a
new AGENT). A privilege level or a lattice between tiers is not a
delegation authority (§Open Questions): the only authority is the
caller's delegates_to, which the host evaluates for every nested
spawn on every surface, not only on a scoped gateway. Organizational
role belongs on the AIP-9 OPERATOR that owns the
agent, never on the spawn; AIP-47 forbids a role
granting access at all.
ground replaces workspaceSlug + cwd
The spawn surface previously carried two fields for one axis —
workspaceSlug (a handle) and cwd (a raw path that "wins over" it).
That precedence rule is how a nested spawn came to resolve through the
ambient active workspace: the field that should have carried the
parent's ground was optional, and the fallback behind it was global.
ground is one AIP-54 ref and replaces both.
workspaceSlug remains on the Session descriptor as a reported
binding, but is no longer a spawn input. cwd survives on the spawn
request as a deprecated root-only alias accepting a raw path,
because a human naming a directory on their own machine is a real
case and a ref buys nothing there. On a nested spawn it MUST NOT be
honoured: a raw path cannot express the containment check §Delegation
requires, and accepting one re-opens exactly the hole the ref closes.
New implementations SHOULD NOT offer cwd at all.
The 2026-07-17 state-partitioning amendment
§State partitioning changes where a conforming host keeps state, not what it serves. Compatibility weight sits in three places:
- The wire surface is untouched.
Session.workspaceSlugkeeps its meaning and its field; the HTTP routes, the MCP tools, and the SSE stream are unchanged. A consumer cannot observe the partition, which is the point — this is a host-storage requirement, and a consumer that readsworkspaceSlugoff a descriptor behaves identically before and after. - Migration is additive by mandate. The legacy global store is read, split, and left intact (§Migration). A host that rolls the change back finds its original artifact where it left it; a host that rolls forward twice is protected by the marker. Nothing about this amendment authorises deleting a user's history — retention is explicitly not specified.
- Per-bucket bounds change what survives, in the user's favour. A host moving a global cap to a per-bucket cap retains strictly more history than before (each bucket now gets the whole bound rather than a contested share). Hosts that sized a global cap against a render budget SHOULD re-check it per §Per-bucket bounds rather than dividing it, but a host that keeps its existing number is conforming and simply retains more.
Hosts with no workspace registry are unaffected: §State partitioning binds only hosts that implement §Workspaces, and a host without one has a single implicit workspace, which is already a partition of one.
The 2026-09-26 session-messages amendment
§Session messages is additive. Hosts predating it delivered a child's
report as an ordinary user prompt — at worst string-prepended onto the
parent's next prompt — so a consumer reading an older transcript sees
those reports as user-prompt records; nothing is rewritten. A consumer
that does not know the new session-message record kind MUST treat it as
skippable, which is what the existing "ignore unknown kinds" rule already
requires; it loses the report's text, never the rest of the transcript.
The §Multi-turn change from "MUST reject overlapping prompts" to "reject
or queue" describes what the reference implementation already shipped; a
host that still rejects remains conforming.
The 2026-09-28 session-artifacts amendment
§Session artifacts is additive: a host predating it simply has no
artifact store, session_artifact_* calls are absent, and nothing
about an existing session's ring buffer, transcript, or outcome
changes shape — the new type: "file" outcome-artifact variant is an
addition to a union a consumer already treats as open (the same
posture the 2026-09-26 amendment above takes for an unknown record
kind). A host implementing it reuses AIP-58's
ArtifactEntry shape rather than inventing a parallel one, so a future
consumer that already speaks AIP-58 artifacts needs no new parsing
code, only the extra envelope fields this section adds.
The 2026-10-18 cost-and-billing amendment (draft)
§Session cost and billing basis is additive in the strictest sense of
shapes: the three costUsd / amortizedCostUsd / billingMode
fields are optional on Session, and a host with no subscription
profile emits exactly the same payloads it did before the amendment.
The only break is semantic and targeted: a costUsd field a host
already populated (the current daemon implementation, "API equivalent"
or 0 under a subscription) now receives a normative meaning — marginal
cost, never the basis of a quality-per-USD decision in subscription
mode. There are no external users: the corrected reading replaces the
old one with no deprecation window.
The 2026-10-23 session-config amendment (draft)
§Session config, presets and fallback is additive: config, preset,
policy, Session.config, Session.configSources and
Session.fallbackStep are optional, and a spawn that sets none of them
resolves exactly as before (manifest and host defaults). The reference
implementation's flat agent_start fields (model, access, posture,
effort, contextProfile, route, turnRetry, presetId) are the
flattened form of config; hosts MAY keep accepting them and MUST treat a
flat field and the same axis in config as one layer (the flat field wins
when both are present). User presets and harness presets map to session
presets (a harness preset is a session preset with defaultFor).
turnRetry.rotate maps to fallback overlays on model;
turnRetry.action: "migrate" has no mapping (placement is out of scope;
the before-start placement ladder is AIP-36 v1.4 §1).
modelPolicy and costBudget map to the spawn policy (AIP-38 grants on
model:invoke, spend-usd limits); a costBudget that today trips a
completion check at turn end becomes a limit that refuses the next
model:invoke, a deliberate behaviour change.
The 2026-10-29 session-message-grants amendment (draft)
§Who may message whom keeps the tree edges and replaces every other
pair rule with grants of session:message. Deny by default stays the
normative default for every pair that is not a tree edge. A host whose
pair rule was configured through its own switches (siblings allowed,
same workspace allowed, a group of linked workspaces) MAY keep them as
a way to derive those grants, and MUST report the effective grants it
derives on a surface the operator can read. A host whose same-workspace
allowance was on before this amendment MAY keep it on during migration
if it reports the effective grant and the operator can set it to deny.
A host that binds by recorded slug rather than by working directory
MAY keep allowing a pair whose two sessions recorded the same slug only
while it records each such pair at least once on a surface the operator
can read.
Informative: the reference implementation. In
@agentproto/runtime,allowPromptFromis a list kept on the target session that names the callers allowed to prompt or control it, by session id,any, orlabel:entries. Itslabel:entries are thesession-label://principal side of asession:promptorsession:controlgrant, matched against the caller'soperatorLabel(§Operator label).defaults.messaging.allowSiblings,allowSameWorkspaceandpeerGroupsare its spelling ofsession:messagegrants, anddefaults.messaging.peerBinding(slugorverified) is the migration switch for the working-directory binding (agentproto/ts#2326, agentproto/ts#2330, agentproto/ts#2165). It does not conform yet: the same-workspace allowance is on by default (allowSameWorkspace: true); it checks the tree edge first, so a denied sibling pair gains nothing from the same-workspace allowance, while this text has no precedence; and withpeerBinding: "slug"two sessions that recorded the same slug, a recordeddefaultslug included, are peers. It reports apeerGroupslink as the relationgrantedand the envelope carriesfrom.agentSlug(agentproto/ts#2379);GET /permissions/grantsreports the effective grants derived fromdefaults.messaging.*and each session'sallowPromptFrom, plus the configured entries no grant expresses (agentproto/ts#2393).
The 2026-10-28 session-principals amendment (draft)
§Session principals and §Operator-only configuration change who a
caller is; on the wire they add only the error codes
identity_unverified and identity_mismatch. Deliberately, a session
that names itself by a claim alone is refused once the host enforces,
and observe-only mode lets the operator count those callers first.
The 2026-10-29 operator-label amendment (draft)
§Operator label defines the label AIP-38 §Scope matching already called
operator-assigned, and AIP-23 gains session-label://. On the wire it
adds Session.operatorLabel and agent_set_operator_label. A host that
lets a session set a label that a grant matches, or that matches a grant
against the free-text Session.label, MUST stop: that is the hole this
amendment closes. A host that copies the label through its own restart
and continuation paths conforms to §Operator label rule 4; a host whose
restart, resume or continuation path mints a new session id without
copying it MUST add the copy. A successor declared by a spawn request
(succeeds) is a spawn, not such a path (§Operator label rule 2).
Informative: the reference implementation.
@agentproto/runtimekeepsSessionDescriptor.operatorLabel(sessions.ts).agent_start(agent-tools.ts) andPOST /sessions/agent(http-server.ts) record the requestlabelas the operator label only when the call names no caller session, the new descriptor has noparentSessionIdand the spawn was not deduplicated.agent_set_operator_label(agent-tools.ts) refuses a call naming a caller session. The new-id restarts (session-restart-core.ts, two sites) and continue-fresh (session-continue-fresh.ts), whichsession_migrategoes through, copy it; continue-interrupted resumes the same row. A successor declared withagent_startsucceedsis a spawn: it receives a label only through the spawn rule above.
Informative: where the reference implementation does not conform.
checkSessionOwnerGate(session-owner.ts) matcheslabel:entries throughmatchesSessionGranton thecallerSessionIdclaim, not aprovenprincipal, and checks no liveness, so a claimed id of a retired labelled row matches (AIP-23session-label://rules 2 and 3). A caller that names no session is the operator there, so it may record or set a label (§Operator label rule 1; the Session principals section, rule 5).
The 2026-10-29 session-operator amendment (draft)
§Operator binding adds the optional Session.operator, the optional
operator field of the spawn request and of agent_start, and the
error code operator_unresolvable. It is additive: a host that never
receives operator records none, and the session config resolves as
before, with no operator layer. §Layers and precedence now says which
operator layer 3 means, and states that only its portable
runtime.config enters it. §Node scope adds no wire change: it
cross-references the AIP-34 rule that already derives a session's node
from its ground.
The 2026-10-29 session-context amendment (draft)
§Session context replaces the context-continuity amendment this AIP
used to name. A host that reads contextContinuity and runs the percent
bands keeps working: contextContinuity is an alias of contextSettings, and
the bands leave the normative surface without being forbidden, as host
extensions. An existing host gains no new MUST beyond rules 1 and 2 of
§Session context, the checkpoint before a host-decided context loss and
the floor that holds without a setting; the other rules bind a host
that claims the section (rule 6).
The 2026-11-08 harness-rename amendment (draft)
Session.adapterSlug is now Session.harness, SpawnAgentRequest.adapter
is now SpawnAgentRequest.harness, and the agent_start input follows. The
adapter alias of SessionConfig.harness is removed too. This is a wire
break for a third-party host or client: the old names have no alias in
this AIP, and the replacement is a straight rename of the key with the same
value. The reference implementation keeps accepting the old names, with a
deprecation warning, until its next breaking release (AIP-70 §4). A client
that must talk to both generations reads harness and falls back to
adapterSlug, and sends harness.
Security Considerations
- All sessions execute as the daemon's UID. Hosts SHOULD gate the routes behind their existing auth (bearer / loopback / mTLS), which is the same mechanism protecting the AIP-45 spawn surface.
- The ring buffer captures stdout/stderr verbatim — secrets the
agent printed are visible to anyone with
GET /sessions/:idor the SSE stream. Hosts MAY redact known secret patterns, but the AIP does not require it; consumers MUST treat the buffer as potentially sensitive. agent_startaccepts ground from the caller. Agroundref is bounded by the registry — it names a workspace the host already knows, so an unregistered location is unnameable. The deprecated raw-pathcwdalias has no such property: hosts that still accept it SHOULD reject paths outside their allowed surface (e.g. require the path to be a registered workspace, or under the workspaces' parent directory) when the auth principal is not the local UID. That asymmetry is the argument for retiring the alias.- The spawn gate is an authority boundary, not a guardrail. A session that can spawn can spend money, write files, and reach the network as the daemon's UID — recursively. Hosts MUST evaluate the gate before process creation (§Delegation) and MUST NOT rely on the child's cooperation. The failure mode is not a confused agent; it is an unbounded fan-out of credentialed processes.
- Root authority is the host's auth, and it is total. Because a root spawn has no parent to gate against, whatever authenticates to the spawn surface can request any agent. Hosts MUST NOT expose that surface more broadly than they would a shell. Any surface reachable by a child (a proxied gateway, a forwarded port, a tunnel) that reaches the spawn routes without a parent edge is a privilege escalation: it converts a gated nested spawn into an ungated root one. Hosts MUST ensure a session's onward calls carry their parent edge.
- Loopback is not an authentication boundary here. The usual reasoning — "only local processes can reach it, and local processes are already trusted" — inverts for this AIP: the local processes are precisely the untrusted party, because they are the agents being gated, and the host spawned them there itself. A host that exempts loopback from auth on any surface exposing the delegation actions has published an ungated gateway to every child it runs. Hosts MUST authenticate the delegation surface per-session even on loopback. The one exception, §Session principals rule 5, lets a child that omits its credential reach the surface with the operator's rights: a residual the operator accepts by configuration, not an authentication.
- The realistic defeat of this gate is not an attacker. It is an harness shipping its own config entry for the host's own endpoint, or a well-meaning caller handing a child a broader MCP server. Both are ordinary configuration, neither looks like an attack, and both produce a child the host reports as denied while it delegates. This is why §Delegation binds the gate to session identity rather than to surface composition: surface-based reasoning fails against config, and config is the common case.
- Ring-buffer disclosure crosses the tree. A parent reading a
child's output through
agent_outputsees whatever the child printed, including secrets it was given. Delegation therefore widens the blast radius of §the ring-buffer caveat above by one hop per level. - Partitioning is not isolation. §State partitioning bounds what a workspace's state costs other workspaces; it does not bound who may read it. A host that has partitioned its state and changed nothing else still serves every bucket to every authorised caller — the files moved, the access did not. Hosts MUST NOT describe partitioning as an isolation or privacy control, and consumers MUST NOT infer from a partitioned layout that a scoped credential sees only its own workspace. The rule that would make it one does not exist yet (§Open Questions).
- A bucket name is caller input until the registry says otherwise.
workspaceSlugreaches the host on a spawn request and a bucket is a directory under the host's state root. A host that joins the two without the exact-match lookup of §Bucket resolution has given the caller a path-traversal write primitive —../../in a slug escapes the state root entirely, as the daemon's UID. The lookup is what makes this safe, which is why it is specified as membership rather than as sanitisation: a host cannot forget to validate a value it never chose. - Transcripts are the payload, so where they live is a security
decision. They hold prompts, file contents, and any secret that
crossed a turn. §Rationale records why they are not co-located inside
the user's workspace directory: a state store that lives in a git
repository is one missed
.gitignorefrom a public remote. Hosts adding their own stores under a bucket SHOULD apply the same test — the directory must exist to hold state, not to be published. - The artifact raw-serve route renders untrusted content, not just
transfers it. An
html/siteartifact's bytes may originate from an agent turn a host does not fully trust; the route MUST send aContent-Security-Policywith noconnect-srcand noform-actionso the rendered page can neither call back into the host's own tool-call surface nor exfiltrate to a third party, and MUST resolve asiteversion's sub-path containment-checked against that version's own directory — the same escape risk AIP-53 names for its app-UI data plane, reapplied here because both serve a directory of files a session (not the host) populated.
Open Questions
- Should sessions expose a
pidfield even for protocol-arm (ACP-driven) sessions where the host owns the spawn? Consumers asked forpidforkill -9debugging; the AIP currently leaves itnullfor agent sessions to discourage host-side process tree manipulation. - Cancellation mid-turn — the protocol arms support
session.cancel(), but the AIP doesn't expose it as an HTTP/MCP verb yet. Should be added once we have a real consumer demand (the ACPcancel_turnsemantics differ across harnesses). - Resume across daemon restarts — the per-workspace snapshot
(§State partitioning) persists descriptors but not the live agent
process. A future v2 could specify rehydration (re-spawn + replay
context) for harnesses whose AIP-45 manifest declares
session.mode = "resumable". - Workspace-scoped reads. §State partitioning gives a host the boundary but no rule for honouring it: nothing here says a consumer presenting a workspace-scoped credential MUST be served only that workspace's bucket. The credential it keys off is no longer open: it is the session credential (§Session principals), and a workspace is not a principal. The read-scoping rule itself is still unwritten, so the partition stays a precondition rather than a control (§Security Considerations).
- Retention and reclamation. Buckets grow without bound; this AIP specifies no GC. The obvious question — when may a host delete a transcript, and who decides — is deliberately unanswered, because the failure mode of guessing is deleting a user's only copy of work they care about. A retention rule needs an explicit human policy input, and probably belongs alongside the legacy-artifact reclamation §Migration also leaves open.
- Should the bound be descriptors, or bytes? §Per-bucket bounds caps record count, inherited from the reference implementation. Count is a poor proxy for the thing that actually hurts (a bucket's transcripts are orders of magnitude larger than its descriptors), so a host can be well under the cap and still unreadable on disk. Revisit if a host reports the count bound as the wrong axis.
- Privilege levels vs. explicit allowlists. This amendment
specifies
delegates_to(a closed allowlist) as the only delegation mechanism, and deliberately does not standardise the numeric privilege lattice the reference implementation grew (level, with non-escalation aschild.level <= parent.level). The lattice is terser for large casts — N agents need no N² of allowlist entries — but it is implicit: it grants by arithmetic rather than by name, so nobody can read an agent and know what it may spawn. The allowlist is auditable and matches AIP-42's existing field. If a real cast outgrows enumeration, the lattice should return as an AIP-42 concern (a computeddelegates_to), not as a second authority in AIP-46. Revisit when a host reports the allowlist as the binding constraint. The reference implementation keeps the lattice for agents that declare nodelegatesTo. - Sibling messaging default. §Who may message whom allows two
siblings only through a grant of
session:message. Peer coordination (two workers negotiating a shared interface) is a real use, but it bypasses the supervisor that owns the plan. Revisit if hosts report siblings routing everything through the parent as the binding friction. - A sender chosen by workspace binding.
session-label://names the senders the operator labelled, but a workspace is not a principal, so "any session bound to W may message sessions of X" still needs the operator to label the sessions of W, or a*principal that also admits senders bound elsewhere. Whether a principal form derived from the host's workspace binding is worth its cost is open. The evidence that closes it is the report of effective grants (§Backwards Compatibility) of a host after its same-workspace allowance is set to deny: a pair that still needs the allowance and whose sender was spawned by a session, so could carry no operator label at spawn, decides for the form; none decides against it. - A workspace owner enabling messages. §Who may message whom rule 6
lets an AIP-34 workspace
policydenysession:messagebut not allow it. Whether a workspace owner may allow sends among its own sessions without the operator is open. The evidence that closes it is a host that reads the workspacepolicyfrom a source the workspace's own sessions cannot write, and an operator opt-in naming that workspace, as AIP-38 §Security considerations requires before a child policy relaxes a parent. - A portable steering capability. Steering is advertised today
through an AIP-44 extension (
_meta.steering), and harnesses disagree on idle semantics — one honours "prompt required", another starts a detached turn. A first-class AIP-44 capability with a mandated idle behaviour would let hosts drop the defensive host-turn gate. - Should
agent_promptacross the tree be gated separately fromagent_start? Both are delegation actions today, so an agent that may spawn may also drive. A supervisor that should observe children without steering them has no way to say so. Possibly two actions with separate grants; unclear whether the distinction earns its keep. - Idle compaction and a cold wake. §Session context does not say what a host does for a session that idles past its prompt cache, nor for a prompt that wakes it after the cache lapsed. The evidence that decides is the extra input cost of a cold wake against a warm one, measured over a week of real transcripts from their cache-creation versus cache-read tokens. Until then a host SHOULD NOT invent a wire format for it.
Resources
Supporting artifacts for AIP-46. Links open the file on GitHub — markdown and JSON render natively in GitHub's viewer. Browse the full resource tree →
AIP-45: HARNESS (harness/v1): interactive harness manifest
A markdown + frontmatter format for declaring an interactive harness — a long-running, bidirectional, agent-as-process binary like Hermes Agent, Claude Code, OpenCode, Goose, or Gemini CLI — and how to install, spawn, and converse with it. Layers over AIP-29 (CLI.md) for install/version/auth blocks and AIP-44 (ACP.md) for the session/wire model when protocol=acp; falls back to MCP or proprietary protocols via a discriminator.
AIP-47: ROLE (role/v1): organizational role manifest
A single-doc markdown + frontmatter format for portable organizational roles — mission, responsibilities, capabilities, tools, KPIs, seniority, reporting line, lifecycle hooks. Sibling to AIP-25 PERSONA (face) and AIP-23 IDENTITY (substance); referenced by AIP-9 OPERATOR (its `role` binding) and located in an AIP-6 COMPANY package by the conventional path `roles/<slug>/ROLE.md`. Roles describe what a job is — independent of who holds it (persona/identity) and which instance is hired (operator).