Reviewing and approving changes

Sudo cannot apply anything. He can only ask, and what he asks with is a diff.

The rule

No silent writes

Edits live in the session's own copy of /workspace until commit stages them and stops. Only an administrator's approval applies anything, and what you approve is the diff you were shown.

Three things follow from that, and each is enforced rather than merely intended:

Build before commit. commit parses every changed file back through the workspace's own importer and compiles its body against the scope it will run in. It refuses the whole set if anything fails. --force exists, says so loudly in the output, and still needs your approval.
One way in. An approved commit is an ordinary definitions import of the files that differ, routed by exactly the same code that reads an uploaded definitions bundle. There is no parallel set of per-surface writers that could drift out of step with it.
One tracked change per approval. The import runs inside the workspace's tracked configuration change, so an approved commit is one commit in the configuration git history, attributed to the administrator who approved it, landing in the same history as a change you made by hand.

What you see

When Sudo runs commit, the chat renders that turn as an approval card instead of an ordinary tool chip, and the pending-changes panel in the chat toolbar picks up a badge. Opening it gives you the change in two shapes, both reading the same diff:

File list

A list of the changed files with a side-by-side diff for the one you select. Best for checking one file closely.

Pull request

Every file's diff one after the other, down one page, with a comment box under each. Best for forming an opinion about a change that spans several files.

The diff is read-only on purpose. Editing Sudo's draft in the review screen would put your change somewhere he cannot see it, and the file still sitting in his shell would silently disagree with what was applied. If something is wrong, say so in the chat: he edits the file, builds it, and commits again.

The three buttons


Approve	Applies every file in the commit. The apply streams its progress, so you see each file as it is imported along with any warnings the importer raises, rather than a spinner.
Discard	Throws the commit away and keeps the edits. Sudo still has the files; tell him what to change.
Reset	Throws away every uncommitted edit, putting his shell back to the live configuration.

A card left open while Sudo staged a newer commit refuses to apply: the id you were shown and the id he is holding differ, so approving would apply something nobody read. Ask him to show you the current one.

What approving does

flowchart TD A[You press Approve] --> B[Deletions applied first] B --> C[Each remaining file imported<br/>through the definitions importer] C --> D{Every file applied?} D -->|Yes| E[One tracked git commit,<br/>attributed to you] E --> F[Sudo's session reloads<br/>from the live configuration] D -->|No| G[Errors reported;<br/>the edits stay in his shell]

Deletions go first, so a change set that removes an endpoint and adds one on the same route removes before it adds rather than deleting what it just created. Search-index halves and package declarations are collected and handled together, because a search index is two files that only mean something as a pair.

On success his session is reloaded so his next command reads what was actually applied, which is what you want him looking at from there. On a partial failure the edits are kept and the errors are reported: whatever did not import is still work someone did, and throwing it away is the worst possible answer to "some of this did not apply".

Deleting things

A definitions file can also say something should be removed. Deleting a file from /workspace and committing resolves to the same deletion an imported bundle would express, so there is one meaning rather than two.

Three behaviours are worth knowing:

A built-in is refused for what it is, before the existence check. A workspace that has not seeded a built-in yet does not make deleting it reasonable.
A UID naming the wrong kind of node is left alone, with an error, because acting on it would delete an unrelated part of the workspace.
Naming something that is already absent is a warning, not an error, so the same change is safe to apply twice.

An index, a schema, a package or a configuration document is not one node that can be taken away, and says so rather than appearing to succeed.

The allow-changes toggle

The Allow changes switch in the chat toolbar is per session and can be flipped at any time. With it off, commit and run refuse and everything else works: Sudo reads the whole workspace, drafts in his own copy, and tells you what is ready. Turning the toggle on does not lose the draft; the same commit then works.

Turning the toggle off deliberately does not remove the shell, because removing it would leave him unable to read the workspace either.

Accountability

Every shell call is metered into the workspace's own metrics under an Admin Agent bucket, separately from ordinary chat tools.
Every applied commit is one entry in the configuration history, attributed to the administrator who approved it, visible under Manage / Access / Audit log and readable from the sandbox at /proc/audit.
Every code surface additionally carries its own code history, so an endpoint, AI tool, task, index or entity post-processing script changed through Sudo can be reviewed and rolled back exactly like one changed by hand.