An agent is read whole, checked as it is saved and written into the user or project scope through the daemon's agents.* methods and onboarding's confined writer, and a session's or branch's agent changes with profile.switch, read from its file at the switch, keeping the conversation¶
Decision 841 · accepted · 2026-10-10 · issue #503
Superseded in part
In part by 852.
- Four methods, daemon-written, like
mcp.*(Decision 700, #60's layer pattern).agents.validateanswers{ok, errors, warnings}and writes nothing.agents.put {name, scope, source}writes<config>/agents/<name>.md(user) or.troupe/agents/<name>.md(project;workspacetaken as the same,mcp.*'s word). Reading and checking answer on a worker too; writing does not: on a pod the agents are the bundle's, and both writes areforbiddenwith a sentence pointing at the console (#56), notmethod_not_found, so a client says why.getandvalidateareobserve;putanddeleteareadmin, asmcp.addis: a definition decides what runs. - One writer, onboarding's.
Troupe.Onboard.put_file/5andremove_file/4are the writer Decision 823 made, opened to a file that came from nobody else's: the same whitelist of paths (agents/<name>.md), the same judgement by real path (a project file under the workspace's real.troupe/, so a.troupe,.troupe/agentsor file that is a link out is refused: Decision 829's edge for the reader, held by the writer), the same temporary file renamed over it in the same VM-wide transaction, and no provenance. Not chosen: a writer of its own in the gateway (a second edge to keep), andwrite_file(a free path). - Checked on save, loudly; loaded leniently. The loader stays lenient, as it must (one
broken file should not stop a session), but a file it cannot read or parse is now in
skippedwith the reason in words (not read: mode must be primary or subagent, not "main"), so it reachesagents.listand the session'sfiles_skipped, which clients already show, as well as the log. - What is not a person's to change here. A built-in is changed by a copy: a
putof its text into either scope, under its name (which then hides it) or another; deleting a built-in is refused, and deleting the copy brings it back (agents.deleteanswers the layer that answers now). A bundle's agent is the profile's (editable_reason: change it in the console). - A branch's agent changes; extended
profile.switch, not a new method. A branch is a session with aparent(Decision 646), so its agent is its root's, and the method that switches a root already names the session: a newagent.switch {session, path, agent}would have been the same thing with a second name, and an agent path below the root is a delegated task, not a window. The rule is the issue's honest one, which the root switch already followed: the conversation stays and the definition applies from the next turn; tools it no longer holds are neither offered nor callable (the gate isTools.authorize/3, which reads the definition at each call), its permissions are the new definition's at each call, and a standingallow_sessionthe person gave stays theirs (adenyin the new definition still refuses first). A workspace'sautostill waits for trust (Decision 825): the switch reads with the trust the session was stamped with.
Governs: apps/troupe_core/lib/troupe/agent/validate.ex, apps/troupe_core/lib/troupe/agent/local.ex, apps/troupe_core/lib/troupe/agent/definitions.ex, apps/troupe_core/lib/troupe/agent/definition.ex, apps/troupe_gateway/lib/troupe/gateway/agents.ex