---

id: subagents title: A subagent is a context, so it gets an account status: open crates: [didbot-pds, didbot-agentd, didbot-operator] dependsOn: [ownership, node] exitCriterion: > Two subagents of one session write records signed by two different accounts, each account's registration names the account it was created beneath, and a deployment sets in configuration rather than in code whether that is the session or the host, and whether a session's subagents share its account. #

subagents #

One session is one context. A subagent's context is its own and ends with its task, so it is a different entity from its parent and from its siblings, not a role its parent plays. It gets an account.

What an account buys, and what it does not #

• Revocability. A context's binding is dropped in the daemon without ending the session that spawned it.
• Attribution that survives. The writer is the signer, so nothing has to be tagged onto each record and nothing has to be believed. Where the account sits is stated once, at creation, in bot.did.registration's lineage, and the creator's own bot.did.operator record names it back.
• Not narrower authority. An agent's credential is all-or-nothing over its own repository; what a context may write is decided by policy. A subagent account restricts what a subagent is handed, never what it could reach by acting as the session instead.

The last point holds whatever harness is underneath: a subagent runs inside its parent's process and filesystem, so the boundary is reported rather than enforced. A session id is the same kind of claim from the same bookkeeping as a subagent id. What the server checked is the creator's credential and the operator's allowance for it: the host's key, or the session's own token when the session creates. Read a subagent's account as "an account the operator's allowance covers created this", never as "this agent is who it says it is".

One account reused across every subagent of a type would be cheaper and would denote nothing: two invocations share no context, so they are not one entity.

Which account a subagent is created beneath #

The daemon creates every context with the host's key, so a subagent's lineage ends at the host and its session's account says nothing about it. The other tree creates a subagent as its session, beneath the session. Issue #133 asks which, and how a deployment and a harness choose.

The hook tells the daemon which context is acting. didbot-claude sends the harness's agent_id as the report's context, and leaves it out for the main conversation. The daemon keys a context by {session, context} (crates/didbot-agentd/src/context.rs), so a subagent's session is the context with the same session and no context. Below, {S, A} is subagent A of session S, and {S} is the session. The hook names the acting agent and not the one that spawned it, so a subagent started by another subagent has {S} as its parent too.

Options #

1. Do nothing. Every context is created beneath the host, as today.
   • Costs nothing, breaks nothing, stores nothing new.
   • A lock on a session reaches none of its subagents, and its next subagent is still created. crates/didbot-pds/src/estop.rs names the gap: "a halted agent that can still provision takes a fresh account under the same host".
   • Deleting a session leaves its subagents standing, and nothing at the server names the session they came from: an account's name is a digest of both halves of its context.
   • Every context on the machine spends the host's creates_per_hour, 100 by default, so one session's fan-out can leave another session's next context refused CreatesTooFast.
2. A key, host by default. A deployment, or a harness for one context, chooses agent.
   • Costs the daemon change below. Breaks nothing.
   • Stores nothing new: one environment variable and one optional field on the wire.
3. The same key, agent by default.
   • Costs what option 2 costs, and more. A laptop host is admitted with --creates-beneath agent beside --creates agent; the pool in docs/ownership.md already carries it. The scenario suite's Daemon::agent reports a subagent of a fresh session, so its laptop's allowance and its lineage assertions change. didbot operate --check refuses a chain still hosted here after three edges (MAX_EDGES), and a subagent beneath a session beneath a host beneath a pool is such a chain.
   • Breaks every host whose record lacks the descendants allowance: each subagent is refused NotAllowedToCreate until the record changes or the deployment sets host. No command changes a standing account's creates: a second didbot operate for it is refused AccountAlreadyExists, and the record that stood is put back.
   • Stores nothing new.

Recommendation #

Option 3, agent by default.

• The tree records who spawned what. Lineage tracking is in the mandate. Only agent puts the session in a subagent's lineage, and a record naming the subagent in the session's repository.
• The operator's controls reach what a session spawned. A lock on a session hangs on each subagent beneath it and refuses the next one. A delete of the session's subtree takes its subagents. A policy binding that includes the session's descendants covers them.
• A Revoke holds. Its release ends every agent token, so a session from before it gets no new subagents. Under host the host's key gives them fresh accounts.
• A fan-out is charged to its session. The session's own creates_per_hour bounds it, and the host's counts sessions only. The deployment's [capacity] max_accounts counts the same accounts either way.

The case for host:

• It needs nothing from the operator. agent needs a descendants allowance, and that lets every account beneath the host create, each against its own [tree] bounds. A fan-out from one token is then bounded by max_depth and [capacity] max_accounts, not by the host's hourly rate. Under host an agent's token creates nothing.
• A subagent depends on the host's account alone. Under agent it also needs the session's account provisioned, active and unlocked, and a session token that still verifies: a year by default, ended by a Revoke's release, and gone if the daemon loses the session's binding.
• The tree is one edge shallower. didbot operate --check holds at three hosted edges, and a session can deactivate itself or be erased without its subagents going first.

On a laptop the session's token sits in contexts.json beside the host's key, so a process that reads one reads the other. The wider allowance matters for a token that leaves the machine without the key.

What agent does #

For a report from {S, A}, which has no account yet:

1. The daemon takes {S, A}'s turn, as today.
2. If {S} has no account, the daemon creates one first, under {S}'s own turn and with the host's JWT, as a report from {S} would. {S} is told its identity on its own next report.
3. It calls bot.did.createAccount with {name, kind: "agent"}, and {S}'s account token as Authorization: Bearer. The name is built as today, from both halves of {S, A}.
4. The server checks what it checks for every hosted creator (docs/ownership.md):
   • the operator's record for the root above {S} still stands;
   • {S} and every account above it are active and unlocked;
   • the [tree] bounds hold, counted against {S};
   • an allowance covers the chain [session, host, …]: descendants, with no kinds or with agent, on the host's record or one above it.
5. It writes:
   • bot.did.operator/<subagent> into {S}'s repository, as {S}: subject and createdAt, one commit on the firehose;
   • bot.did.registration/self into the subagent's repository: operator the human, lineage [host, session] (or [pool, host, session] beneath a pool), kind agent;
   • what every account gets: app.bsky.actor.profile/self, a DID document naming the human as operator, and a ledger opened by Provisioned, whose parent is {S};
   • nothing into the host's repository.
6. The daemon keeps the DID and the token in {S, A}'s binding, follows its sign-ins and answers with its identity, as today.

The daemon already holds {S}'s token: createAccount answered it once as accountToken, and contexts.json keeps it. tree::proof::prove reads a token this server issued as Proof::Session, and the account it names is the creator (crates/didbot-serve/src/tree/proof.rs). No second sign-in is needed, and none would work. bot.did.createSession takes a key-signed JWT or an ID token, and {S}'s account holds neither. A getServiceAuth JWT is signed with the #atproto key, which prove_by_key does not read. No credential type is added.

The server half is built and tested: a_descendants_allowance_lets_the_children_create_and_not_the_root (crates/didbot-serve/tests/tree.rs) creates an agent beneath an agent and checks its lineage, and a_session_creates_beneath_the_account_it_names (crates/didbot-serve/src/tests/provisioning.rs) creates with a session's token.

The protocol does not decide this. The reference PDS's com.atproto.server.createAccount takes no creator or parent (bluesky-social/atproto at ff99ec0a, vendored in vendor/atproto-lexicons), so the tree is bot.did.*'s own. The spec governs one side effect: a lock that removes reads changes an account's hosting status, and each account the cascade reaches gets its own #account event (account spec, Hosting Status).

When the allowance does not reach descendants #

The refusal is the subagent's trouble, and nothing is created beneath the host instead.

• The server re-reads the operator's records, waiting up to eight seconds (ALLOWANCE_REREAD_WAIT), and answers NotAllowedToCreate naming {S}.
• The daemon answers the report with that name and sentence as trouble, and logs a warning naming both ways out: --creates-beneath agent on the host's record, or DIDBOT_SUBAGENT_OPERATOR=host.
• didbot-claude writes trouble to its hook error log and puts nothing in front of the model. The subagent runs with no account.
• The subagent stays owed a name, and its next call asks again: the retry a host with no allowance gets today.

A fallback on this one refusal would escape no lock and no bound, because the server checks those before the allowance. It is refused anyway:

• where a subagent lands would depend on when the operator's poll last ran, and the key would stop saying where accounts are;
• the same fallback on AccountLocked, CreatorNotActive, AncestorNotStanding, TreeTooDeep, TooManyChildren, CreatesTooFast, InvalidToken or ExpiredToken takes a subagent out from under what refused it, and one match arm would be all that separates the two.

The key #

DIDBOT_SUBAGENT_OPERATOR: the issue's subagent.operator, spelled the way the daemon's settings are, since "the environment is the whole configuration" (crates/didbot-agentd/src/bin/didbot-agentd.rs). It is read once, at start.

• agent, the default: a subagent is created as its session.
• host: a subagent is created with the host's key, beneath the host.
• Anything else refuses the start, naming the key and both values, as DIDBOT_CONTEXT_TTL_DAYS refuses a number outside its range.

It does not touch a session's own account, which the host always creates.

The per-context override #

A report may carry operator, "agent" or "host".

• It is read on the report that creates a subagent's account, and wins over the key.
• It is ignored on a session's report, and on every report once the account exists: an account is never moved.
• Any other value is trouble naming both, and nothing is created.

The wire needs the field and a new version. Report drops fields it does not know, so a version-2 daemon would create beneath the host and say nothing. Version 3 adds operator. A daemon reads a version-2 report as before, so an adapter that never sends the field need not move. One that sends it writes version 3 on that report, and a version-2 daemon refuses it by name (serve::too_new). ask-report-full.json in crates/didbot-agentd/fixtures/protocol/ gains the field.

Both values are honoured, whatever the key says. host on a daemon set to agent takes a subagent out from under its session. That is no wider than the hook already is: it names the session, and a report naming a new session already gets an account beneath the host. node's rule that nothing from a hook may widen anything is why the owner is asked below.

didbot-claude need not send it: nothing in Claude Code's payload changes the answer.

What a session's freeze, lock, deletion or e-stop does to its subagents #

What happens to the session	host	agent
A lock: the operator's (didbot account lock), its own (bot.did.freezeAccount), or a policy's quarantine	Its subagents keep writing, and new ones are created beneath the host.	Each live subagent carries the same lock from parent until the session's comes off (Provisioner::cascade). A new subagent is refused AccountLocked.
It deactivates itself (bot.did.deactivateAccount)	Allowed.	Refused AccountHasLiveChildren while a subagent beneath it is live.
The operator erases it (didbot account erase)	Allowed; its subagents are untouched.	Refused AccountHasLiveChildren while a subagent beneath it is live.
The operator deletes it (didbot account delete)	It goes alone. Its subagents stay beneath the host, and nothing names their session.	Refused LiveChildren without --recursive. With it, each subagent goes first, then the session.
A lock on the host, or the operator's record for the root lapsing	Reaches every account on the host.	The same, through the session.
An e-stop Pause, or a Revoke while it stands	Every create is refused Halted.	The same.
A Revoke released	Every agent token ends. The host's key still creates the session's new subagents.	The session's token has ended, so its new subagents are refused InvalidToken. A session started after the release is unaffected.
Its token expires ([credential] agent_token_ttl_days, a year by default)	Nothing changes for its subagents.	Its new subagents are refused ExpiredToken.
What the ledger says	A subagent's Provisioned.parent is the host.	A subagent's Provisioned.parent is the session, and a cascaded lock is a Locked entry from parent in its ledger.

State #

The recommended option adds no stored fact, field or lifecycle. It changes which account some existing facts name.

Settings, which nothing stores:

Setting	Type	Where
DIDBOT_SUBAGENT_OPERATOR	agent or host; agent when unset	the daemon's environment: ~/.config/didbot/agentd.env under the unit
Report::operator	agent or host, optional	one report, protocol version 3

Stored facts:

Fact	Type	Where it lives	A subagent under agent	Under host
The subagent's binding	session, context, kind, did, token, told, done, last_reported	contexts.json (context::Binding)	as today	as today
The session's token	a secret	the session's binding in contexts.json	presented to create the subagent	not read
parent	DID	the subagent's account row (HostedAccount::parent)	the session	the host
bot.did.operator/<subagent>	subject, createdAt	the parent's repository	the session's	the host's
lineage	DIDs, root first	bot.did.registration/self in the subagent's repository	[host, session]	[host]
Provisioned.parent	DID	the subagent's ledger	the session	the host
Live children; creates in the last hour	counts	derived from the account store; the provisioner's memory	the session's	the host's
The host's creates	allowances	bot.did.operator/<host> in the operator's repository	subject and descendants, each [agent]	subject [agent]

A subagent context in the daemon. The choice is the report's operator when it has one, and the key when it does not.

From	Trigger	When	Then	To
none	any report from {S, A}		a binding with no did	unnamed
unnamed	began or acted	operator is neither value	trouble naming both; no create	unnamed
unnamed	began or acted	the choice is host	createAccount with the host's JWT	named, or unnamed with the refusal
unnamed	began or acted	the choice is agent; {S} is named and holds a token	createAccount with {S}'s token	named beneath {S}, or unnamed with the refusal
unnamed	began or acted	the choice is agent; {S} has no account	{S} is created first under its own turn, with the host's JWT; then the row above	named beneath {S}, or unnamed with the refusal
unnamed	began or acted	the choice is agent; {S} is named and holds no token	trouble naming {S}'s DID; no create	unnamed
named	any report		told once per asker, as today; operator ignored	named
any	ended		as today	done
any	quiet past DIDBOT_CONTEXT_TTL_DAYS		as today	dropped

A session context moves as it does today, and ignores operator. A subagent's account gains no transitions: the table above says what its session's do to it.

Build #

• The key. DIDBOT_SUBAGENT_OPERATOR read and checked at start in crates/didbot-agentd/src/bin/didbot-agentd.rs, and held by Daemon.
• The create. provision_context presents {S}'s token for a subagent under agent, creates {S} first when it has no account, and logs both ways out on NotAllowedToCreate.
• The override. Report::operator and protocol version 3, with the fixtures blessed.
• The walk. MAX_EDGES in crates/didbot-operator/src/operate/walk.rs goes from three to four.
• The words. A host is admitted with --creates agent --creates-beneath agent in docs/agentd.md, the laptop record and scenario table in docs/ownership.md, docs/first-hour.md and docs/cli.md. docs/agentd.md's provisioning paragraph says which credential creates a subagent, and it, docs/cli.md and didbot-agentd --help list DIDBOT_SUBAGENT_OPERATOR. node's exit criterion says a session's account is created beneath the host.
• The scenarios. The laptop in crates/didbot/tests/scenarios/ is admitted with --creates-beneath agent, and each lineage it asserts follows the tree.
• The order. Everything above lands with host as the default. agent becomes the default in its own breaking change, once the owner has said how a standing host gains its descendants allowance.

Tests #

The daemon, against the Counting registrar in crates/didbot-agentd/src/serve.rs, which keeps the credential it was shown:

• a_subagent_is_created_with_its_sessions_token: under agent, the subagent's create presents {S}'s token and {S}'s presents a host JWT.
• a_subagent_before_its_session_creates_the_session_first: one report from {S, A} makes two creates, {S} first. {S}'s next report is told its identity, and both accounts are followed for sign-ins.
• two_subagents_of_a_session_with_no_account_create_it_once: two reports at once make three creates.
• a_refusal_as_the_session_is_the_subagents_trouble: for NotAllowedToCreate and for AccountLocked, one create and no host JWT; the answer carries the server's words; the next report asks again as {S}.
• under_host_a_subagent_is_created_with_the_hosts_key.
• a_report_saying_where_wins_over_the_key: host under agent, and agent under host.
• a_sessions_report_saying_agent_is_created_beneath_the_host.
• a_report_naming_neither_value_is_refused_by_name.

The wire and the binary:

• operator round-trips in a version-3 report, and ask-report-full.json carries it (crates/didbot-agentd/tests/fixtures.rs).
• didbot-agentd refuses to start on DIDBOT_SUBAGENT_OPERATOR=pool, naming the key and both values, and --help lists it (crates/didbot-agentd/tests/cli.rs).

End to end, with the real binaries in crates/didbot/tests/scenarios/:

• a_laptops_subagent_is_created_beneath_its_session: its lineage is [host, session]; the session's repository holds bot.did.operator/<subagent> and the host's does not; didbot operate --check walks subagent, session, host, human.
• a_host_without_descendants_refuses_subagents_by_name: admitted with --creates agent alone, the subagent is refused NotAllowedToCreate, the daemon's log names both ways out, and nothing is created beneath the host.
• locking_a_session_stops_its_subagents: after didbot account lock on the session, its subagent carries Frozen from parent and a new subagent is refused AccountLocked; unlock lifts both.
• deleting_a_session_takes_its_subagents: didbot account delete on the session is refused LiveChildren; with --recursive both go, the subagent first.
• a_released_revoke_ends_what_a_session_spawns: the session's next subagent is refused InvalidToken, and a new session's subagent is created.
• a_pools_subagent_checks_in_four_edges: subagent, session, host, pool, human, which --check refuses as TooDeep until MAX_EDGES is four.
• a_fan_out_is_charged_to_its_session: under creates_per_hour = 2, a session, its two subagents and a second session are all created in one hour, where host refuses the second subagent CreatesTooFast.

Questions for the owner #

• The default. agent, as recommended, or host.
• A standing host's allowance. didbot operate rewrites creates on a record whose account stands; or operators rewrite it by hand, and set host until they do.
• host from a hook when the key says agent. Honour it, as recommended, since a hook already names the session; or refuse it, under node's rule that nothing from a hook widens anything.
• The names. The issue's operator, which is the record's name; or parent, which createAccount's answer, the account row and the ledger use, and which never names the human.
• What bounds a fan-out beneath descendants. [tree] max_depth and [capacity] max_accounts, as today; or a scope that reaches one level, beside subject and descendants, which is a lexicon change.

The identifier is not reliable, and disk is #

The harness's subagent id has been observed arriving wrong: one subagent's consecutive tool calls under two different ids, and a single stray id collecting calls from more than one real subagent. A stray id would create an account for a context that never existed, or sign several agents' work under one name.

• Confirm a context against the harness's own transcript before creating for it. The harness writes each subagent's calls to that subagent's own file, so which agent made a given call is recoverable from disk with certainty, including for two byte-identical concurrent commands. Measured: the hook's id agreed with the transcript on every call observed, and the row landed within a tenth of a second of the hook firing.
• Decide what happens when they disagree. Disk is authoritative, so the write is either attributed to the agent disk names or refused. What it must not be is attributed to the agent the hook named.
• Record disagreements before enforcing on them. The rate is unknown outside a single report, and a first deployment that blocks on it measures nothing.

Granularity #

Subagent use is bursty and concentrated where the work is: two days on one machine were 16 sessions and 167 subagent invocations, 161 of them from one project. A fan-out of parallel subagents is the same burst node's [tree] bounds cap, moved to the busiest moment, and charged to whichever account creates it: the session under agent, the host under host.

• Granularity is configuration, with per-context the default. account-types already has the kind supply defaults and the account carry values, so a deployment that wants one account per session sets it rather than patching this decision out. The instability above is a second reason to want that switch, and a reason its default should be revisited once there are numbers.

Done #

• The decision this epic existed to make. A subagent gets its own DID and its own account. What tipped it was not cost, since a wildcard DNS record removed the per-account DNS write this epic priced, but that the alternative denotes something untrue: a parent's account signing a subagent's work records the wrong author.
• What a subagent account is a credential for. Revocation and attribution, not scope. Narrowing is policy's, at the write.
• Whether a harness lets a subagent's identity be enforced. No harness examined does: a subagent shares its parent's process and filesystem, and what arrives is the harness's report. Recorded here rather than left as a question, because every design above is built on top of it.
• A subagent is created separately. A context is keyed by session and subagent id, and a session and its two subagents get three accounts; node has the tests.