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.

FieldValue
AIP46
TitleSESSION (session/v1): long-running multi-turn agent orchestration
StatusReview
TypeSchema
Domaincli.sh
RequiresAIP-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 withAIP-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:

  1. A guild operator wants claude alive in 4 different folders so it can answer follow-ups without re-pulling each repo's context. The run verb spawns a fresh agent per call — no continuity.
  2. A web UI wants to mirror claude mcp list over HTTP so the user sees what's running on their laptop without ps -aux. There was no enumeration surface.
  3. 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:

  1. 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 is delegates_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 role inverts 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_to declares 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:

  1. 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 → running fires when the agent's protocol arm reports the session ready for the first turn.
  • running → exited is the normal terminal — the underlying child exited with code 0 (or any code; presence of exitCode is what matters, not its value).
  • running → killed fires when a consumer called kill_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 with interrupt: true) stays running — the agent is alive, idle, and holding its context. There is no interrupted status, and consumers MUST NOT infer one from a turn ending early.
  • * → error fires on any unhandled spawn / protocol / IO error; lastOutputAt typically 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:

  1. lookup workspaces[workspaceSlug] → use its ref
  2. fall back to workspaces[active] → use its ref
  3. 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.

StoreNormative force
the sessions registry snapshotMUST be per-bucket
durably-kept transcripts / per-session outputSHOULD be per-bucket
any other store whose records carry a workspace bindingSHOULD 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:

  1. workspaceSlug is non-empty and matches a registered entry in workspaces.json by exact identity → that workspace's bucket.
  2. Otherwise — absent, empty, or unregistered → the default bucket.

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 fieldWhat it supplies to the session
bodythe 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
policyAIP-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

  1. Deny by default. An agent whose resolved delegates_to is absent or empty MUST NOT be permitted to spawn. This mirrors AIP-38's default: deny and makes the safe case the silent one.
  2. Closed allowlist. When delegates_to is non-empty, the host MUST permit a nested spawn only when the requested child's agent-ref resolves to a member of the caller's delegates_to. Membership is by resolved identity, not by the literal string.
  3. 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.
  4. 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:

  1. 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.
  2. MUST store only a one-way hash of the credential.
  3. MUST revoke the credential when the session is retired. A revoked credential MUST NOT authenticate any request.
  4. 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:

ProofThe caller presentsPrincipal
provena 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
claimeda 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 revokednone 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)
noneno credential and no claimanonymous

The rules:

  1. 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.
  2. 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.
  3. 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_unverified a 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 with identity_mismatch a request whose claim names a session other than the one its credential was minted for. A host MUST NOT resolve either request to anonymous or to the operator instead. When the caller presents a session credential, the :id of a route that acts on the caller's own session, at least POST /sessions/:id/checkpoint and the inbox acknowledgement of §Inbox and tools, is a claim under this rule; the operator may name any session there.
  4. An invalid credential is refused. Once it enforces this section, a host MUST refuse with identity_unverified a request presenting a credential that is malformed, unknown or revoked, and MUST NOT resolve that request to anonymous.
  5. The anonymous caller is never a session. A host MUST NOT let an anonymous caller 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 an anonymous caller 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 many anonymous requests 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.
  6. 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. verified is proven, mismatch is proven with a contradicting claim, invalid credential and claim only are claimed, and anonymous is none.
ClassThe request presents
verifieda valid credential, and no claim or a claim naming the credential's session
mismatcha valid credential and a claim naming another session
invalid credentiala credential that is malformed, unknown or revoked
claim onlya claim and no credential
anonymousno credential and no claim
  1. 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 as anonymous in rule 6, and the identifier is not a session:// ref. A host MUST NOT register an external identifier that equals the id of a session it spawned.
  2. 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.
  3. A host may require proof. A host MAY require proven for any action it lists (for example the AIP-39 session:spawn, session:control and auth-profile:use), and then MUST refuse with identity_unverified a claimed caller of a listed action, and a none caller the host does not evaluate as the operator under rule 5, or with identity_mismatch when 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/runtime mints the credential in observe-only mode by default (agentproto/ts#2335): a random apst_ token, stored as a SHA-256 hash in session-credentials.json, sent in the x-agentproto-session-token header 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, while anonymous, verified and the other claim-only classes are never refused. GET /identity reports the five classes as verified, mismatch, invalid_token, claim_only and anonymous, splits claim_only into external, delivered, undelivered and unknown (claimOnlyByClass), and reports which surfaces it enforces; its totals persist in identity-observations.json under the daemon home and add up across restarts, with since the first recorded boot and bootedAt and boots adding the restart history (agentproto/ts#2398).

Informative: where the reference implementation does not conform. It delivers the credential only to unsandboxed claude-code and hermes sessions (rule 2). A restart leaves the previous credential valid until the old row retires (credential rule 4). It evaluates every anonymous local caller as the operator with no switch (rule 5). By default it honours a callerSessionId claim 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 as claim_only in the external class, not as anonymous (rule 7), and one naming an identifier it has not registered as unknown.

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.* in config.json (with peerBinding from agentproto/ts#2326 and agentproto/ts#2330), written through config_set, which refuses a session principal's write to defaults.messaging, defaults.identity and defaults.tasks.operatorDelegates, and their ancestors, with the code operator_only, whatever the sessionTokens mode (agentproto/ts#2371). operator_only is 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).

  1. Form. The value is an AIP-54 ref of kind operator, written in its compact form operator:<slug>. An operator of another workspace carries the cross-workspace suffix of AIP-54's operator-body: operator:<slug>@<workspace>. The ws://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.
  2. Resolved at spawn. A host that accepts operator on a spawn request MUST resolve the ref to an AIP-9 operator before it starts the session, and MUST refuse the spawn with operator_unresolvable when it cannot: a session never records a dangling operator ref. operator does not replace agent: the session's definition is still the agent the request binds, which for an operator is its resolved agent (AIP-9 §Runtime binding).
  3. It binds, it does not authorize. The binding gives the session no spawn authority and no grant: delegation stays the bound agent's delegates_to plus 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 from ground (§Node scope).
  4. 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.
  5. 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.

  1. Only the operator assigns it. Only the operator or system MAY 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_label included).
  2. A spawn records it only for the operator. A host MAY record the label of a spawn request as the operator label of the new session only when the caller is the operator and the new session has no parentSessionId. 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.
  3. 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.
  4. 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:

  1. the request's explicit ground ref, when given
  2. 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:

LimitMeaningOn breach
maxDepthgreatest permitted depthreject, create no session
maxChildrengreatest number of concurrently alive children per sessionreject, 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.

CodeCause
invalid_agentagent ref does not resolve
operator_unresolvableoperator ref does not resolve to an AIP-9 operator (§Operator binding)
delegation_deniedcaller's agent may not spawn the requested child
cwd_outside_parentnested spawn named ground outside its parent's subtree
max_depth_exceededdepth would exceed maxDepth
child_quota_exceededcaller already at maxChildren
identity_unverifiedcaller 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_mismatchcaller'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 governsThe harness's ungoverned twin
the delegation actions on the host's own gatewaya native task / sub-agent facility, spawning off-protocol
host fs / exec tools anchored to the session's groundthe CLI's own built-in shell and file tools
what the host injects into the child's configwhat 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):

MethodPathBodyReturns
GET/sessions—{ sessions: Session[] }
POST/sessions/agentSpawnAgentRequestSession (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.ground of 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:

ToolInputsNotes
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 messagesTyped 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:

  1. 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.
  2. Every other pair needs a grant. A host MUST refuse a send between any other pair unless an AIP-38 grant of session:message allows 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.
  3. 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.
  4. Never to itself. A host MUST refuse a send whose sender is the recipient.
  5. The binding is the host's. A session's workspace binding is the workspace its ground resolves into (§Session data model); a host that does not resolve ground to 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 a workspace: scope MUST derive the binding itself and MUST NOT take it from a slug the session or any caller supplies (the workspaceSlug of a spawn request, a header, a parameter, or a slug recorded on a descriptor from such input). The default bucket of §Bucket resolution is not a registered workspace and MUST NOT satisfy a workspace-scoped grant.
  6. A workspace owner may only narrow. An AIP-34 workspace policy MAY deny session:message for 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

urgencyidle recipientbusy recipient
fyiinbox only, no wakeinbox only
next-turnstart a turnqueue; deliver after the current turn ends naturally
steerstart a turninject into the running turn if the harness supports steering (AIP-44 _session/steering), else as next-turn
interruptstart a turncancel 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:

ToolInputs
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 eventProjected line
text-deltathe 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:

ToolInputsNotes
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" ⇒ amortizedCostUsd absent or 0; costUsd is the actual spend.
  • billingMode: "subscription" ⇒ amortizedCostUsd MUST be present; costUsd is 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 populate billingMode on 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: weekly
  • monthlyUsd is 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

  1. 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", costUsd remains 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).
  2. api session (per-call paid key) — unchanged: costUsd = actual bill, billingMode: "api".
  3. 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 fieldowner
skills, bundles, mcpServers, browserwhat 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 listAIP-38 limits and grants in the spawn policy (spend-usd, model:invoke)
sandbox, cloud, worktreeplacement: 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.

axisclass
modellive 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
effortlive when the harness exposes it as a session option, else restart
posturelive when the harness has a native mode switch (ACP session/set_mode), else restart
contextProfile, route, access, optionsrestart
harnesshandoff

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-resume continuation (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):

toolinputbehaviour
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:

  1. manifest: the harness manifest's defaults (AIP-45 models.default, default mode);
  2. host: host defaults for that harness;
  3. definition: the bound AIP-42 agent's model, then, above it, the bound AIP-9 operator's runtime.config (its mode projected onto posture or contextProfile, then its options, options.model mapping to model). The bound operator is the one Session.operator names (§Operator binding); a session without one has no such layer. Only the portable runtime.config enters here: the preset, the posture and the auth profile are host configuration (AIP-9 §Runtime binding) and arrive at layers 4 and 5;
  4. preset: the session preset whose defaultFor names the harness, then the named preset, after its extends chain is applied;
  5. 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 agent in the request wins over the preset's. A preset's agent is 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, formerly presets, in a harness manifest, which declares a backend endpoint; renamed in agentproto/agentproto#98).

Fallback

When a turn fails with a FailureClass, the host:

  1. retries the same config up to retry.maxRetries times when the class is in retry.on (never after a tool call unless retryAfterToolCalls);
  2. when the requested model was a selector:<id>, moves to the selector's next eligible member, picked by the selector's rotation (AIP-43 §Saved selectors), re-resolved at this step;
  3. walks fallback from the step after fallbackStep: 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-limit and quota-exhausted put (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 a session:fallback event 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:

momentactions evaluated (all must allow)
spawn (after all layers)session:spawn (scope: harness), auth-profile:use (scope: profile), model:invoke (scope: model)
live changesession:configure (scope: axis), plus model:invoke when the model changes
restart or handoff with an overlaythe spawn set, on the new config
every fallback stepthe set of the transition the step performs
a caller other than the owner prompts, or interrupts, kills, restarts or hands offsession: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 childsession: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_ineligible with 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.

  1. 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.

  2. 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.

  3. 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; 0 turns 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 the contextSettings block their keys MUST be prefixed x- (§The SessionConfig carrier), and no conformance check reads them.

  4. The context settings are independent axes. They form a block of their own, contextSettings, outside SessionConfig (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.autoCompactAtTokens leaves a lower layer's contextSettings.hardStopAtPct in force. A host SHOULD offer a way to print the resolved block with the layer of every setting. The legacy name contextContinuity is accepted as an alias of contextSettings for the period AIP-70 §4 allows; its other keys (a mode, the percent bands) are host-defined and no conformance check reads them.

  5. Who may compact. When compactRequiresOperator is true, the action session:compact on 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.

  6. Conformance. A host claims this section when it meets rules 1 and 2 and resolves every setting of contextSettings as its own axis (rule 4). Rule 3 is optional: a host that does not implement it ignores autoCompactAtTokens. A host that does not implement rule 5 MUST refuse a block that sets compactRequiresOperator: 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/runtime writes a checkpoint (checkpointBeforeContextLoss) before every compaction prompt in runAgentTurn, refusing the compaction when it cannot, and before a hard stop. validateAgentTurn holds the floor with no policy (CONTEXT_CONTINUITY_DEFAULTS, 90), skips it when computeContextPct returns null, and starts performContextRescue (compact, continue fresh, then stop); its refusal is a plain error. autoCompactAtTokens defaults 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 only contextContinuity; 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); and assertCompactionAllowed refuses a session's compaction with a plain error, not the AIP-38 denial form. session_checkpoint asks the session for a handoff turn unless askSource is 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 via mcpServerFactory
  • Registry: runtime/src/sessions.ts — in-memory + persisted (debounced) to the per-workspace snapshot ~/.agentproto/workspaces/<slug>/sessions.json of §State partitioning; carries parentSessionId + 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, the default fallback, and the additive split of the legacy global sessions.json
  • Spawn gate: runtime/src/session-spawn.ts — the enforcement point of §Delegation
  • Session credentials: runtime/src/session-credentials.ts, runtime/src/identity-defaults.ts and observeCallerIdentity in runtime/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|use for managing the workspaces config
  • agentproto 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:

  1. The wire surface is untouched. Session.workspaceSlug keeps 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 reads workspaceSlug off a descriptor behaves identically before and after.
  2. 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.
  3. 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, allowPromptFrom is a list kept on the target session that names the callers allowed to prompt or control it, by session id, any, or label: entries. Its label: entries are the session-label:// principal side of a session:prompt or session:control grant, matched against the caller's operatorLabel (§Operator label). defaults.messaging.allowSiblings, allowSameWorkspace and peerGroups are its spelling of session:message grants, and defaults.messaging.peerBinding (slug or verified) 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 with peerBinding: "slug" two sessions that recorded the same slug, a recorded default slug included, are peers. It reports a peerGroups link as the relation granted and the envelope carries from.agentSlug (agentproto/ts#2379); GET /permissions/grants reports the effective grants derived from defaults.messaging.* and each session's allowPromptFrom, 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/runtime keeps SessionDescriptor.operatorLabel (sessions.ts). agent_start (agent-tools.ts) and POST /sessions/agent (http-server.ts) record the request label as the operator label only when the call names no caller session, the new descriptor has no parentSessionId and 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), which session_migrate goes through, copy it; continue-interrupted resumes the same row. A successor declared with agent_start succeeds is a spawn: it receives a label only through the spawn rule above.

Informative: where the reference implementation does not conform. checkSessionOwnerGate (session-owner.ts) matches label: entries through matchesSessionGrant on the callerSessionId claim, not a proven principal, and checks no liveness, so a claimed id of a retired labelled row matches (AIP-23 session-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/:id or 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_start accepts ground from the caller. A ground ref is bounded by the registry — it names a workspace the host already knows, so an unregistered location is unnameable. The deprecated raw-path cwd alias 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_output sees 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. workspaceSlug reaches 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 .gitignore from 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/site artifact's bytes may originate from an agent turn a host does not fully trust; the route MUST send a Content-Security-Policy with no connect-src and no form-action so the rendered page can neither call back into the host's own tool-call surface nor exfiltrate to a third party, and MUST resolve a site version'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 pid field even for protocol-arm (ACP-driven) sessions where the host owns the spawn? Consumers asked for pid for kill -9 debugging; the AIP currently leaves it null for 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 ACP cancel_turn semantics 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 as child.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 computed delegates_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 no delegatesTo.
  • 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 policy deny session:message but 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 workspace policy from 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_prompt across the tree be gated separately from agent_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 →

On this page

AbstractMotivationWhy delegation is in scopeWhy state partitioning is in scope (added 2026-07-17)SpecificationSession data modelStatus transitionsWorkspacesState partitioning (added 2026-07-17)LayoutBucket resolutionPer-bucket boundsMigrationDelegation and the spawn gateThe agent bindingWho may spawn whomThe enforcement pointSession principals (added 2026-10-28)Operator-only configuration (added 2026-10-28)Operator binding (added 2026-10-29)Operator label (added 2026-10-29)A nested spawn inherits its parent's groundLimitsErrorsWhat this gate cannot reach (informative)HTTP surfaceInterrupt (added 2026-07-17)SpawnAgentRequestNode scopeThe agent and the harnessSSE event formatMCP toolsMulti-turn semanticsSession messages (added 2026-09-26)EnvelopeWho may message whom (amended 2026-10-29)RecordingModel-facing formDelivery tiersInbox and toolsOutput projectionSession artifacts (added 2026-09-28)Session outcome (added 2026-09-28)Session cost and billing basis (added 2026-10-18)Descriptor fieldsAccess profile and subscriptionAmortisationQuota statusExamplesCompatibilitySession config, presets and fallback (added 2026-10-23)The SessionConfig carrierApply classesLayers and precedenceSession presetsFallbackPolicy evaluation pointsSession context (added 2026-10-29)RationaleReference ImplementationBackwards CompatibilityThere is no role on this surfaceground replaces workspaceSlug + cwdThe 2026-07-17 state-partitioning amendmentThe 2026-09-26 session-messages amendmentThe 2026-09-28 session-artifacts amendmentThe 2026-10-18 cost-and-billing amendment (draft)The 2026-10-23 session-config amendment (draft)The 2026-10-29 session-message-grants amendment (draft)The 2026-10-28 session-principals amendment (draft)The 2026-10-29 operator-label amendment (draft)The 2026-10-29 session-operator amendment (draft)The 2026-10-29 session-context amendment (draft)The 2026-11-08 harness-rename amendment (draft)Security ConsiderationsOpen Questions