When Saphan stops work, and why
Every limit an agent works inside, what happens when it reaches one, and what you can do next.
AI agents in Saphan Studio work inside limits that a person signs. When an agent reaches a limit, Saphan does not let the agent decide what to do next: the action is refused, the refusal is recorded with its reason, and the decision comes back to a person.
You sign the limits, not every action
A plan is split into work packages. You read the plan and sign it, and your signature covers the limits of each package:
| Limit | What it means | What enforces it |
|---|---|---|
| Write set | The one repository, branch and workspace the package may change. | The sandbox and the engine refuse a write outside it. |
| Permissions | The commands and actions the agent's role may run. | The role's grant. Anything not granted is refused. |
| Network | The destinations the agent may reach. | Saphan's network control. Everything else is closed. |
| Time | How long one run may take. | The engine ends the run when its time is up. |
Because the limits are fixed when you sign, "the agent needs more" has an exact meaning: it reached one of them.
The stops
A change outside the write set
Example. A package may change the billing service. While fixing a bug, the agent decides the shared logging library needs a change too.
What happens. The write to the logging library is refused before it happens. If the package cannot finish without it, the work comes back to you with the file and the reason. You can sign a wider plan, add a separate package for the library, or say no.
Shared records, such as the project's plans and decisions, are protected the same way: they accept only the paths a signed write set lists.
A command or action the role may not run
Example. An agent working as a developer tries to merge its own branch into the main branch.
What happens. Merging is not in the developer role's permissions, so it is refused and recorded. See roles for what each role may do.
A destination that is not on the network list
Example. To check an idea, the agent tries to download a package from a site that is not on the list.
What happens. The connection is refused and recorded. If the work really needs that site, it comes back to you, and adding the site is your decision. See network control.
Time or spending reached
Example. The agent runs into an unexpected problem and keeps trying.
What happens. When a run reaches its time limit, the engine ends it, and the run reports what it did and where it stopped. Where the agent's own program accepts a spending cap, the run is started with one, and the program stops when the cap is reached. How a run's cost is estimated and capped is in cost management.
No review decision
Example. A package has passed its checks, but nobody has reviewed it yet.
What happens. A change cannot land until a review decision is recorded for it.
No signature
Example. Someone changed one of the packages of a plan you signed.
What happens. Work starts only under a valid signature. A change to a signed plan voids the signature of the work it affects, and that work waits until you sign again — or until you decide not to.
Landing on the main branch
Example. A package has passed its checks and its review.
What happens. It still waits for you. Nothing lands on the main branch without a person's approval. See merging.
What you see when work stops
A refusal is written to the record as data: a class name that says which limit was reached, and a sentence that says why. Troubleshooting lists the classes and what each one asks of you.
Settings
Numbers such as time limits are settings with defaults, not values fixed in code. Your team can
change them with saphan config set; see configuration keys.