Approvals and control

An agent asks before it runs anything that needs your permission, and waits for the answer. You decide; the agent never decides for itself, and no command ever decides for you.

Deciding a request

In the app, a waiting request opens as a box above the input with the exact action: y allows it once, n denies it, d shows it in full. /approvals lists every request waiting in the session, and /approval show <request> gives one in full. From a terminal:

ks approval list --session <session>
ks approval show <request> --session <session>
ks agent approve <request> --session <session>
ks agent deny <request> --session <session>

ks approval show gives everything a decision needs: the action as the agent stated it, the instruction it was asked for, what it touches, what deciding costs, and until when it can be decided.

A decision binds to what you were shown

The client records what it put in front of you (a digest of the exact action, not its text) and compares the decision with it. If the agent changed the action after it was shown, nothing is decided: the new action is shown and you are asked again. Reading the request again and deciding whatever it says now would approve an action nobody saw.

• An allow is once: the next request is asked again.
• While the agent waits, a decision must arrive within about 45 seconds. After that the tool is refused and the request is closed; a decision sent later is refused, not applied.
• An agent waiting on a request reads waiting_approval, is marked ⚑ on the app’s home screen, and the other agents’ windows say that one needs you.

One window steers

Several windows can show the same agent, but only one controls it:

• the window that opens an agent first holds its control lease, renews it while it is open, and releases it when you leave;
• any other window watches: it shows everything and sends nothing;
• /take in the app (or ks agent open <name> --take-control) takes control explicitly, and the window that had it is told and drops to watching.

An instruction sent from a window carries its lease, so the service refuses it the moment that window is no longer the controller, instead of letting two windows steer one agent. ks agent tell sends an instruction from outside any window and does not take control from the one that has it.

Stopping and interrupting

Esc interrupts the instruction in flight; /stop --confirm <agent> stops the agent and holds its queue. What each does, and the terminal forms: stop the work in flight.