Launch resolution¶
Every agent launch, whether a first spawn or a later resume, reincarnate, clone or morph, is built from the same set of launch fields. This page lists each field, where its value comes from, and what a relaunch does with it.
How a first spawn picks each value (explicit flag, named profile, group default profile, global default profile, harness default) is described in Default resolution. This page covers what happens to those values after the agent exists.
The rules¶
A spawn profile is copied at first spawn. The named profile, the group's default profile and the global default profile each contribute values to the first launch. Those contributions are copied into the agent, and later edits to the profile, or a change of a group's default profile, apply to new spawns only. Running and stopped agents keep their copy.
Saving an edit to a profile in the dashboard says how many running agents keep their copy. The profile editor's Running agents row lists them, with what re-applying the edited profile would change for each:
- a field the edit changes and the agent took from its copy is marked changes;
- harness, model, effort and directory are kept (fixed);
- a value the spawn request set is kept (explicit);
- a field a higher tier sets is kept (set by that profile): a launch takes each field from the highest tier that sets it, so editing the global default changes nothing where the agent's named profile sets the same field;
- spawn-only values, such as the agent name or the initial message, are not reapplied: they were used once, at the first spawn.
- the model proxy is not reapplied yet: a re-apply does not carry it so far, and the agent keeps its copy;
- roles change together: the grants that come with them (below), the role label and the role briefs.
A re-apply also changes the values a first spawn stores outside the launch settings:
- the group context switch and the profile startup context, which the
agent is briefed with again after a compaction or
/clear, or when it is resumed. The profile's text is replaced, and the role briefs after it are rewritten from the roles the profile names now, with their current text; - the role label, the agent's role in its spawn group, unless someone has changed it since the spawn;
- the profile environment: the profile's entries are recomputed, and the entries the spawn set explicitly stay on top of them;
- the usage-profile links: the agent gets the links the profile has now, unless its spawn named its own usage profiles. The links are read when you apply, so applying an unchanged profile picks up a link edit too.
A value the spawn request set explicitly is kept in each case.
A re-apply also re-applies the grants the profile gave at birth: its roles' grants, with the profile's own permission overrides on top. The preview lists each changed grant with what a re-apply does to the agent's row:
- changed or removed: the row is still the one the profile gave at spawn, so it follows the edit;
- added: the profile gives a new slug, in a part of it (its roles, or its overrides) that took effect at the spawn;
- kept: the agent's row is not the profile's, because the spawn request set it or someone has changed it since;
- not added: the agent no longer has the slug (it was revoked), so the re-apply does not give it back;
- not applied (not in effect at spawn): the change is in a part of the profile that did not apply at the spawn, because the spawn request or a higher tier set its own, or it was empty;
- group ownership (
is_owner) is shown only.
An agent applying a re-apply needs the authority to confer what it widens
(permissions.grant plus attenuation, as for a profile edit); narrowing
needs none. The grant changes are written together with the new copy, and each
is recorded in the audit log as permissions.reapply.
tclaude records which spawn profile, and which of its roles, each birth
grant or deny came from, for agents spawned from now on. A grant has no such
record when it came from the spawn request, from a role the request named, an
inline profile, a group template or federation worker defaults, or when anyone
has changed it since: an operator, a permissions command, a policy generator
or a scope edit. A re-apply only changes grants that still carry the
profile's record. Sudo grants are kept apart and are never involved. Agents
spawned before these records existed have none, so a re-apply leaves all of
their grants alone. Group ownership (is_owner) is not recorded this way yet.
Apply to selected re-applies the edited profile to the agents you tick, one at a time, after a confirm that names the count. What happens depends on the agent:
- a stopped agent gets the new copy; it takes effect on its next resume, reincarnation or clone;
- a running, fully idle agent is stopped, given the copy and resumed, as a restart does;
- a busy agent (working, or with background agents, shells or monitors running) is busy, skipped: nothing is stopped or changed. Apply again once it is idle.
Each agent's result shows in a Result column, and Refresh reads the preview again. The values marked kept or not reapplied stay as they were: the agent's copy keeps its old roles, grants and the other not-yet fields, so the preview keeps listing them as differences. A copy whose launch posture (sandbox, approval) the agent's spawner could not give it, or that would add grants the person applying it could not confer, is refused with the reason; a running agent refused that way is resumed with its old settings. When the profile is a group or global default, re-applying it reaches every agent spawned under that default, and the preview says so.
The preview and Apply need profiles.manage. An agent applying it also needs
agent.morph over each agent it re-applies to, cannot use an operator-only
profile, and cannot give an agent a launch posture it could not give a child
it spawned itself. A disabled profile cannot be re-applied. They are also available as
GET /v1/spawn-profiles/{name}/running-agents and
POST /v1/spawn-profiles/{name}/reapply with {"agent_id": "..."}; each apply
is its own audit entry. Retired agents are not listed.
What an agent references is read again. A spawn can name a sandbox profile, and a spawn profile can link usage profiles. Which ones is kept. Their contents are not: an edit to a sandbox profile takes effect on the agent's next relaunch, and usage rules are evaluated live. A role's text is the exception: it is delivered in the opening brief, and re-injection after compaction repeats the text resolved at spawn, so an edited role reaches new spawns only.
Group and workspace settings are kept current. The group's environment
and remote-control policy, and the group or workspace sandbox-profile
assignment, are read again on every relaunch. This holds for agents spawned
before this table existed too. A group remote-control policy that is set
applies on relaunch unless the spawn gave --remote-control explicitly; with
no policy set, the agent keeps its last state, including a toggle made while
it ran. The group's startup context and mission are not a launch input: a
resume keeps the conversation that already holds them, and re-injection after
compaction reads the group's current text.
Explicit values stay explicit. A value given as a flag at spawn wins over every profile and stays the agent's value on every relaunch. A flag given at resume becomes the agent's new explicit value from then on. So does each field a morph changes, across harnesses too: re-applying the agent's spawn profile afterwards keeps the morphed values, and the fields no morph changed follow the profile. A morph back undoes this: it restores only the fields its morph changed, and afterwards the agent's explicit values are what they were before the morph. A field a re-applied profile set in between keeps the profile's value.
Harness, model, effort and directory are fixed. They are chosen at first spawn and only change by an explicit action: a morph, an explicit resume flag, or moving the agent.
A resume always works. If a value that is read again is no longer valid (a profile was deleted, or no longer suits the harness), the relaunch falls back to the value stored at the last launch and says so.
A relaunch says what changed. A resume or reincarnation lists, under "Changed since last launch", what its sandbox differs in from the one stored at the last launch: which sandbox profiles apply and whether one was edited, filesystem rules added or removed, environment and group environment variables added, removed or changed, network access and rules, the filesystem root, the harness-config posture, and whether temporary filesystems, unix sockets, resource limits, pre-launch blocks or the macOS flags changed. It names variables, never their values. Only a relaunch that happened reports it. The dashboard's wake toast shows the list too, in error style only when the relaunch fell back to the stored policy.
Group permissions and owners are not launch inputs. They apply to members at once, without a relaunch.
Relaunch policy¶
The relaunch policy is one global answer per configurable row. Show and change it in the dashboard's Config tab, under Relaunch policy, or with the CLI below.
Three rows can be switched between two modes:
| Row | Re-resolve (the default) | Reuse |
|---|---|---|
| Group environment | The group's current environment applies. | The group environment stored at the agent's last launch applies; later edits to the group's environment do not reach it. |
| Group remote-control policy | A policy the group sets now applies, unless the spawn gave --remote-control explicitly. In the dashboard's spawn dialog, a remote-control checkbox the operator changed counts as explicit; one left as pre-filled does not, unless the daemon would resolve a different value, when the shown value is sent. Agents spawned from the dashboard before this change all count as explicit. |
The agent keeps its remote-control state from its last launch, whatever the group's policy says now. |
| Sandbox profile contents | The current contents of the agent's sandbox profiles apply. | The profile contents stored at the last launch apply, even if a profile was edited or deleted since. Which profiles apply is still read again: when a group or the workspace now assigns a different profile, its current contents apply and the relaunch says so. |
Re-resolve is what a relaunch did before the policy existed, except for
remote control, which used to always keep the agent's last state. An agent
spawned before launch records were kept has no record of an explicit
--remote-control, so a group policy that would change its state is not
applied; its resume says so.
The group environment, sandbox profile contents and remote-control rows act
on resume, reincarnation, and watch mode and conv resume while agentd runs.
All three rows also act on a clone in its source's groups, as on the
source's own resume, and a clone that keeps its source's environment or
sandbox follows the matching row. A clone that joins another group otherwise
takes that group's settings. Like a resume, a clone whose sandbox cannot be
applied one way (re-read or stored contents) launches under the other and
says so; a Codex clone with a generated profile always re-reads and has no
fallback.
The harness-config posture has three settings, because an explicit
--harness-config choice can disagree with the posture the re-read sandbox
profiles give:
- explicit wins (the default) keeps the explicit posture, as every other explicit flag is kept. It is chosen for least surprise, not maximum security.
- tighten-only is the security option. It differs from explicit wins in
exactly one case: an agent spawned with
--harness-config writewhose sandbox profiles keep the read-only floor gets the floor back on its next relaunch. An explicitreadpin is already the strictest posture, so it always stays. - chain wins always takes the profiles' posture, so a
readpin over profiles that allowwriteis lost on the next relaunch.
For an agent with a recorded spawn request, the explicit posture is not forgotten while another setting overrides it: switching back to explicit wins restores it on the agent's next relaunch. A clone carries its source's record. Agents from before launch layers were recorded, and agents created by the pending-spawn sweeper or a group template, have no such record, so a relaunch under chain wins drops their explicit posture for good. The harness-config repair (see Sandboxing) also follows the setting: it does not list an agent whose posture the setting gave up on purpose.
Every other row follows its layer and has no setting; the Config tab shows it read-only with the reason. Show and change the policy with:
tclaude agent relaunch-policy show
tclaude agent relaunch-policy set group_env reuse
tclaude agent relaunch-policy set harness_config tighten-only
show prints each row's mode, its default and why. Reading is open; set,
and editing the table in the Config tab, need relaunch-policy.manage, which
is not granted by default. Without it the Config tab shows the table
read-only. Treat it like sandbox-profiles.manage: one answer can widen what
a relaunch gives every agent. A change takes effect on each agent's next
resume, reincarnation or clone. The API is GET
and PUT /v1/relaunch-policy ({"field", "mode"}; an empty mode resets the
row to its default).
Per-agent overrides¶
A spawn, and a spawn profile, can set configurable rows for the agents they launch. The rows are copied into the agent's launch record at its first spawn and override the global table for that agent's resumes, reincarnations and clones. Per row, highest first:
- the spawn's own row (
--relaunch-policy field=mode); - the first spawn profile that sets the row: the named profile, then the group's default profile, then the global default profile;
- the global table;
- the row's default.
The rows are copied at spawn: a later edit to the profile does not reach
agents already spawned from it, but a later edit to the global table reaches
every row an agent has not overridden. A clone keeps its source's rows, and a
reincarnation keeps the agent's. A resume or reincarnation of an agent with
overridden rows lists them, with where each came from, for example
relaunch policy for this agent: group_env reuse (profile pinned-env); other
rows follow the global table.
tclaude agent spawn --name worker --relaunch-policy group_env=reuse
tclaude agent spawn --name worker --profile pinned-env --relaunch-policy group_env=inherit
tclaude agent spawn --name worker --relaunch-policy-file policy.json
inherit follows the global table for the row even where a spawn profile
sets it. --relaunch-policy-file takes the shape GET /v1/relaunch-policy
lists ({"rows": [{"field": "group_env", "mode": "reuse"}]}, scope optional);
--relaunch-policy rows override the file's. A spawn profile carries its
rows as relaunch_policy ({"group_env": "reuse"}) in its JSON, and
profiles from-agent copies the agent's rows into the new profile.
Who may set a row. A human may set any. An agent may freely set a row that
applies the operator's current settings (re-resolve, tighten-only,
chain-wins, inherit), and any row the agent would get anyway from its
profiles or the global table. A row that keeps old settings (reuse, or
explicit-wins on the harness-config row) where the agent would otherwise get
something else needs relaunch-policy.manage: with it, an operator who later
tightens a group or a sandbox profile would not reach that agent. The same
applies to an agent writing such a row into a spawn profile, so a profile
cannot pass on what the spawn itself could not set; a row the profile already
carried stays free to keep. Making a profile that carries such a row a group's
or the global default profile is gated the same way, since a default reaches
every spawn into the group, automations included.
An agent without relaunch-policy.manage that sets a reuse or
explicit-wins row the agent would inherit anyway does not pin it: the row
stays with its source. A row inherited from the global table is recorded as
inherit, so a later change to the global table still reaches the agent, and
one inherited from a profile is the profile's copy. Trigger, process and
template workers take their profiles' rows the same way as a spawn from the
dialog.
Fields¶
"Spawn flag" says whether a spawn request can set the field explicitly.
Fixed at first spawn¶
| Field | Key | On relaunch | Spawn flag | Why |
|---|---|---|---|---|
| Harness | harness |
kept | yes | The conversation belongs to one harness; switching it is a morph. |
| Model | model |
kept | yes | Kept as launched; a morph or an explicit resume flag changes it. |
| Reasoning effort | effort |
kept | yes | Kept as launched; a morph or an explicit resume flag changes it. |
| Directory and worktree | directory |
kept | yes | The harness keys the conversation to its directory; only an explicit move changes it. |
| Sandbox deny overlay | sandbox_deny_overlay |
kept | yes | Stored with the agent and reapplied at every relaunch over whatever its profiles resolve to; its children inherit it with their own denies added. |
Copied from the spawn profile at first spawn¶
| Field | Key | On relaunch | Spawn flag | Why |
|---|---|---|---|---|
| Spawn profiles used (named, group default, global default) | spawn_profile |
kept (copy) | yes | A spawn profile is copied at spawn; editing it, or changing a group's default, affects new spawns only. |
| Per-agent relaunch policy | relaunch_overrides |
kept (copy) | yes | The configurable rows a spawn or its spawn profile set for this agent are copied at spawn and override the global table for it; a row neither sets follows the global table, edits to it included. |
| Model proxy | model_proxy |
kept (copy) | yes | Part of the spawn profile copy. |
| Sandbox mode | sandbox_mode |
kept (copy) | yes | Part of the spawn profile copy. |
| Sandbox implementation | sandbox_implementation |
kept (copy) | yes | Part of the spawn profile copy; the host must still support it. |
| Approval policy | approval |
kept (copy) | yes | Part of the spawn profile copy. |
| Tool governance | tools |
kept (copy) | yes | Part of the spawn profile copy. |
| Ask-user timeout | ask_timeout |
kept (copy) | yes | Part of the spawn profile copy. |
| Auto-compact window and context window cap | context_window |
kept (copy) | yes | Part of the spawn profile copy. |
| Context features (trims) | context_features |
kept (copy) | yes | Part of the spawn profile copy; features the harness lacks are dropped. |
| Harness drives (Copilot API, Codex app-server, pi drive) | harness_drives |
kept (copy) | yes | Part of the spawn profile copy; only harnesses with that drive accept it. |
| Fast mode | fast_mode |
kept (copy) | yes | Part of the spawn profile copy. |
| Auto-review | auto_review |
kept (copy) | yes | Part of the spawn profile copy. |
| Remote control (profile default) | remote_control |
kept (copy) | yes | Part of the spawn profile copy; the group policy can still force it. |
| Auto memory | auto_memory |
kept (copy) | yes | Part of the spawn profile copy. |
| Peer messaging | peer_messaging |
kept (copy) | yes | Part of the spawn profile copy. |
| Include group startup context | include_group_context |
kept (copy) | yes | Part of the spawn profile copy; the group context itself is a group setting. |
| SSH workaround | ssh_workaround |
kept (copy) | yes | Part of the spawn profile copy. |
| Profile and explicit environment | profile_env |
kept (copy) | yes | Part of the spawn profile copy; explicit entries stay explicit. |
| Profile startup context | profile_startup_context |
kept (copy) | no | Part of the spawn profile copy; re-injection after compaction uses it. |
| Roles | roles |
kept (copy) | yes | Which roles an agent has is part of the copy; their text is a referenced definition. |
| Sandbox profile named at spawn | explicit_sandbox_profile |
kept (copy) | yes | An explicit choice stays; the named profile's contents are re-read. |
| Usage profiles named by the spawn or linked from its spawn profile | usage_profile_links |
kept (copy) | yes | Which profiles is part of the copy; their rules are read live. |
| Role definitions (text) | role_contents |
kept (copy) | no | The role text is delivered in the opening brief, and re-injection after compaction repeats the text resolved at spawn, so an edit to a role reaches new spawns only. |
Used by the first spawn only¶
| Field | Key | On relaunch | Spawn flag | Why |
|---|---|---|---|---|
| Agent name and description | identity |
not reapplied | yes | Set at spawn; a rename acts on the agent itself. |
| Initial message, saved prompts, attachments | initial_brief |
not reapplied | yes | Delivered once, as the opening brief. |
| Task link | task_link |
not reapplied | yes | Set at spawn; later changes act on the agent itself. |
| Directory trust seeding | trust_dir |
not reapplied | yes | Seeded once for the launch directory, which does not move. |
| Worktree sync and fetch | worktree_setup |
not reapplied | no | Prepares the worktree before the first launch. |
| Auto-focus | focus |
not reapplied | yes | Where the new agent is shown when it starts. |
| Group owner and permission overrides | access |
not reapplied | yes | Granted to the agent at spawn; after that they are the agent's own and edited directly. A profile re-apply changes only the grants the profile gave that nobody has changed since; group ownership is not re-applied. |
| One-shot run, timeouts and queueing | run_mode |
not reapplied | yes | Shape of the spawn call itself. |
| Unenforced-sandbox and break-glass acknowledgements | launch_acknowledgements |
not reapplied | yes | A human's consent for one fresh spawn; never replayed. |
Group and workspace settings¶
| Field | Key | On relaunch | Spawn flag | Why |
|---|---|---|---|---|
| Group environment | group_env |
re-resolved, configurable | no | Group settings are kept current, for agents spawned before this table too (operator decision). |
| Group remote-control policy | group_remote_control |
re-resolved, configurable | no | Group settings are kept current: a policy the group sets applies on relaunch, unless the spawn set remote control explicitly (a flag, or a dashboard checkbox the operator changed); with no group policy the agent keeps its last state, live toggles included. Still clamped to what the harness supports. |
| Group and workspace sandbox-profile assignment | group_sandbox_assignment |
re-resolved | no | Which profile a group or the workspace assigns is a setting, kept current. |
Contents of referenced profiles and roles¶
| Field | Key | On relaunch | Spawn flag | Why |
|---|---|---|---|---|
| Sandbox profile contents | sandbox_profile_contents |
re-read, configurable | no | Edits to a sandbox profile take effect on the next relaunch (operator decision). |
| Harness config posture | harness_config |
configurable: explicit-wins (default), tighten-only, chain-wins | yes | Default chosen for least surprise, not maximum security: an explicit posture stays like any explicit flag. Tighten-only, where a narrower sandbox-profile posture always applies, is the security option. |
| Usage profile rules | usage_profile_contents |
re-read | no | Usage rules are evaluated live, every few minutes. |
Live, not a launch input¶
| Field | Key | On relaunch | Spawn flag | Why |
|---|---|---|---|---|
| Group startup context and mission | group_startup_context |
live | no | Delivered in the opening brief; a resume keeps the conversation that holds it, so there is nothing to relaunch. Re-injection after compaction reads the group's current text. |
| Group and workspace usage-profile assignment | usage_assignment |
live | no | Usage rules are evaluated live against the current assignments. |
| Group permissions and owners | group_access |
live | no | Applied to members at once; no relaunch needed. |
| Member cap, notifications, re-injection after compaction | group_runtime |
live | no | Read when used; not part of a launch. |
Where the code still differs¶
The rules above are the specification. These rows do not follow it yet:
- Model (
model): No resume path takes a model flag yet; only a morph changes it. - Reasoning effort (
effort): No resume path takes an effort flag yet; only a morph changes it. - Model proxy (
model_proxy): Reincarnate and clone drop the model proxy. A re-applied spawn copy does not change it yet; the agent keeps the value from its first spawn. - Group environment (
group_env): With agentd down, watch mode and conv resume reuse the stored group environment, and say so. A clone that joins another group takes that group's environment, unless it keeps its source's. - Group remote-control policy (
group_remote_control): Watch mode and conv resume keep the remote-control state stored at the last launch while agentd is not running, and so does a clone that joins another group for its sandbox. - Group and workspace sandbox-profile assignment (
group_sandbox_assignment): With agentd down, watch mode and conv resume reuse the stored sandbox policy, and say so. - Sandbox profile contents (
sandbox_profile_contents): With agentd down, watch mode and conv resume reuse the stored contents, and say so. A Codex clone with a generated profile always re-reads them, and a clone that joins another group for its sandbox takes that group's current profiles. - Harness config posture (
harness_config): With agentd down, watch mode and conv resume keep the stored posture, as does a resume that falls back to the stored policy when the profiles cannot be read at all; the setting applies on the agent's next ordinary resume.