Skip to content

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 write whose sandbox profiles keep the read-only floor gets the floor back on its next relaunch. An explicit read pin is already the strictest posture, so it always stays.
  • chain wins always takes the profiles' posture, so a read pin over profiles that allow write is 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:

  1. the spawn's own row (--relaunch-policy field=mode);
  2. the first spawn profile that sets the row: the named profile, then the group's default profile, then the global default profile;
  3. the global table;
  4. 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.