A person's own command (shell.run, the TUI's !cmd) runs where the session runs, through the agent's own runner, for the session's owner or an admin holding control; what forbids the agent's shell forbids it; its output starts no turn and is given to the agent before its next model call unless !! kept it out¶
Decision 813 · accepted · 2026-10-08 · issue #486
- Where the session runs, in its workspace. The local daemon's checkout or worktree, or
the pod's working copy for a session on a plane:
!git diffhas to show the diff the agent is working on, not one on the machine the client happens to be. On a pod the method is one of the session's (Troupe.Worker.Auth), routed as every other method a session's token may call; nothing about it is the plane's. - One runner.
Troupe.Tools.Shell.execute/3is what the agent'sshelltool runs with, factored out of it, and what a person's command runs with: the same shell (bash -c; Git bash, thenpwsh, on Windows, Decision 776), the reaper,Sandbox.checkandSandbox.wrapover the mount table, the timeout and the kill, stdin at the null device. Its output is capped as the tool's is, the tail attool_output_limitwith the whole run kept as a blob and theread_outputmarker naming it (Decision 650). No new sandbox rule: whatever confines the agent's shell confines this. - No approval prompt; the authority is the scope, and the owner's. The person typed
it, and asking them whether they meant it is noise. The method takes
control, as input does, and on top of it the session's owner or anadmin(:adminin the connection's scopes: a plane's owner holds it on their session, a collaborator holdscontrol, every local connection to a daemon holds all three). A collaborator is refusedforbiddenwithrequired_scope: "admin"and the sentence "only the session's owner can run commands on it". Chosen over lettingcontrolrun it: a collaborator'scontrolsteers an agent whose shell asks before it runs, and this would run arbitrary commands on the owner's pod or machine at once. - What forbids the agent's shell forbids this (
refusal/2):managed_permission_rules_only, a platform that allows only its own permission rules, and agent definitions none of whose primary profiles may runshell(deny, or not in itstools). Every primary profile is asked rather than the one in use: a person who switched toplan, which reads and never runs, still has a shell of their own, and an organisation that took the shell away took it from every profile its bundle publishes. Each refusal isforbiddenwithsettingand a sentence a client shows as it is. - The output starts no turn; the next model call is given it. A
user_shellthe agent may have is held as a note (note/1): that the person ran it themselves, the command, its capped output, how it ended. Before the root's next model call the notes since the last one become oneuser_inputfromshell: written before the input that starts a turn, so "the tests fail, fix them" after!mix testreads after the run it is about, or after a tool exchange's results when it ended mid-turn, never between a call and its result. A replay folds both events, so a restart gives a note it had not given yet, and only once;Troupe.Log.Foldwitnesses both, a held note present only while one is, so every recorded fixture folds as it did. Clients draw theuser_shelland not the note. !!cmdkeeps it from the agent (agent: false): run, streamed and logged as the person's command, never given to a model call — for output that is noisy or private.
Governs: apps/troupe_core/lib/troupe/session/shell.ex, apps/troupe_core/lib/troupe/tools/shell.ex, apps/troupe_core/lib/troupe/log/fold.ex, apps/troupe_gateway/lib/troupe/gateway/dispatch.ex, apps/troupe_worker/lib/troupe/worker/auth.ex, apps/troupe_protocol/lib/troupe/protocol/schema.ex