[saucam]

What this adds

Session-level controls an unattended worker needs, so a loop can run agents for hours without a person watching (docs/loop-engineering-design.md §6, §8, §12.11). By default every session behaves exactly as before; a controller opts in.

• Usage limits are recognized. When a turn fails because a subscription or API allowance is spent, the session records it as an infrastructure error with its reset time where the backend gives one. A loop can then wait for the reset instead of spending an attempt. The classifier matches the real strings from the Claude Agent SDK and CLI, Codex (including its structured resets_at), gemini-cli and qwen-code. It ignores replies that merely talk about rate limits, and ignores rejected rate-limit events while the account is on overage.
• An attempt can end when its tool budget is spent. With onBudgetExhausted: "end_attempt", the next tool call is denied, the turn ends, and background tasks are stopped. The session ends idle rather than waiting on an approval. A person taking over the session clears the lock by setting a mode or sending a message. Codex's autonomous mode skips approvals, so it reports that it can't enforce the budget, and the controller falls back to wall-time limits.
• Wall-time limits that hold. supervise(session, { wallMs }) interrupts at the deadline and, if the backend doesn't settle, kills it, including tool processes left behind. The process kill matches pid, command line and start time, so a reused pid is never touched. Self-detached commands are outside its reach, as documented.
• Per-session extra environment (daemon-controlled). extraEnv reaches every process-backed backend. Names are validated, and an extensive denylist stops it overriding credentials or injecting code execution (BASH_ENV, GIT_*, RIPGREP_CONFIG_PATH, …).

No loop uses these yet; the controller lands separately.

Review

Two independent correctness and security audit rounds, all findings folded in.

• Round 1 fixed: usage limits misread from overage events and from short assistant replies; stale infra errors; budget denial bypassed by backend-started or joined turns; denylist gaps that allowed code execution; codex budget enforcement; races in interrupt and teardown; processes surviving a backend kill.
• Round 2 fixed: lockout on takeover; children spawned after the kill snapshot; pid identity; exact Claude pid matching; turn-bound interrupts.

Full suite: 3874 pass / 0 fail.

For agents: implementation

• Usage limits:
  • providers/usage-limit.ts: classifyUsageLimit, classifyCliNotice (CLI-shaped prefixes only, last-block aware), and reset parsing (epoch, relative, wall-clock with zone, DST).
  • Session.lastTurnInfraError, cleared at turn start.
  • The Claude rate_limit_event is surfaced as a provider event and is overage-aware. Claude resultText is carried on is_error success turns.
  • codexErrorDetail for structured resets.
• Tool budget:
  • SessionOptions.onBudgetExhausted "park" (default) or "end_attempt".
  • The budgetExhausted lock is cleared by a non-system setMode or prompt.
  • The scheduled interrupt is bound to its turn, with stopBackgroundTasks.
  • SessionProvider.enforcesToolBudget (false on codex) and Session.toolBudgetEnforced.
• Extra env:
  • SessionOptions.extraEnv, names matching ^[A-Z][A-Z0-9_]{0,63}$.
  • Denylist in providers/env.ts; the constructor throws on a refused key, and providers re-filter.
• Wall time:
  • supervisor.ts: supervise().
  • Session.terminateBackend() and the shared #hardStop, with a 10 s teardown bound.
  • process-tree.ts: snapshot before teardown, then killSurvivors over a fresh ps -ww table. It matches pid, args and start time (/proc stat field 22 or lstart) and kills descendants.
  • Claude pid found by exact argv tokens.

🤖 Generated with Claude Code