Life of a Delegation

Explanation. Step by step: what happens between a delegate_task call and a merged change.

1. Call. The planner calls delegate_task(task, repo_path, model, …) with its current folder as repo_path. agentbox checks that the model exists and that the path is an absolute path inside the AGENTBOX_REPOS_ROOT allowlist. The task then waits for a slot on that model's semaphore (max_agents).

2. Backend. agentbox makes sure the model is servable:

   • vLLM models are started by the launcher if needed, which can take minutes the first time;
   • Ollama models are pulled if missing;
   • remote models are checked through llm-bridge.

   If the GPU belongs to the other family and agents are still using it, the call waits. See GPU arbitration. Time spent here is reported as wait_seconds.

3. Prepare.

   • The launcher starts a git helper that mounts only that folder, read-only. The helper finds the repo root (walking up from a subfolder, and handling git worktrees), refuses anything not owned by you, and copies the HEAD commit into a bare shadow git dir.
   • A scratch clone of it becomes the workspace, on a new branch agent/<id>.
   • A per-task gateway starts on sockets/<id>/llm.sock with a one-time token.

   Anything uncommitted in your checkout is not included.

4. Launch. agentbox asks the launcher to run the agent. It sends only the task id, the model, the claude … command, a short env allowlist and an optional venv path.

5. Start. The launcher hands the workspace to uid 64000 with a throwaway chown container, starts the hardened sandbox, and arms a hard deadline.

6. Work. Claude Code runs headless (claude -p <spec> --output-format json). Every model call goes through the socket to the gateway. The gateway checks the token, pins the model, strips server-side tools, meters tokens and enforces the budget. The executor guide (CLAUDE.md) is installed unless disabled.

7. Exit. The agent finishes, or the deadline kills it.

8. Hand back. agentbox removes the container, and the launcher hands the workspace back to your uid.

9. Collect. agentbox commits the workspace's files through the shadow git dir. Then a git helper, which mounts only your repo, fetches branch agent/<id> into it. Nothing in the agent's own .git is executed.

10. Return. The planner gets the branch, status, the agent's report, the diff, token usage and timings, all marked as untrusted data. A record is appended to $AGENTBOX_DATA/logs/delegations.jsonl.

11. Verify. The planner calls run_checks(repo, branch, command).

12. Test. The same kind of sandbox, without any socket, checks out the branch and runs the command.

13. Result. Pass or fail, plus the tail of the output.

14. Decide. The planner merges (git merge --no-ff agent/<id>, then cleanup_delegation) or re-delegates with the failing output pasted into a corrected spec.