GrokBoy is a general-purpose local CLI agent: **observe → decide → act → verify → respond**. The model chooses the next action from the current environment and user objective. Scenario playbooks are optional guidance, never a fixed task router.
The interaction rules below describe legacy single-session mode. Named-agent mode keeps new chat separate from background work and uses task-specific controls.
- For action tasks, a concise opening explains what the agent will do and is followed by actual tool execution.
- Multi-stage work uses a short `update_plan` checklist. Progress updates report findings and next actions. The agent can revise the plan with an explanation; plan approval is not required.
- Plain text ends a turn only when no known plan steps or command remain active. Standalone progress uses `report_progress`, which continues the loop.
- One stdin broker handles idle tasks, live steering, questions, confirmation and handoff. Input received during work is applied at the next safe tool/model boundary; started effects are not rolled back.
-`request_user_input` handles missing information, `request_user_confirm` handles explicit approval, and `browser_handoff` handles auth walls. Questions and terminal tools must be called alone, so their answers/results can inform subsequent actions.
- Ctrl-C or `/stop` cancels a running turn and preserves resumable state. The REPL remains open; a one-shot run exits 130.
Model requests are bounded by `GROKBOY_MAX_ROUNDS_TOTAL`. `GROKBOY_MAX_ROUNDS` only controls local progress frequency. There are no additional model calls to manufacture progress summaries. A 20-second heartbeat identifies the operation actually being awaited.
Three identical action/result rounds stop as blocked. Three rounds consisting only of commentary/plan updates or invalid control calls also stop. Successful controlled waits use their own deadlines and the total request ceiling rather than the identical-output guard.
The core publishes typed events through `Runtime::set_event_handler`; CLI formatting lives in the binary. Tool output, not narrative promises, drives the next request. Process output is streamed to local files and returned incrementally, with one foreground process group per session.
Checkpoint before and after tools, retain plan/pending questions/command metadata/browser URL, and pair every call with a result. On recovery, missing outcomes become explicit unknown results; never replay automatically. Persistent browser profiles include session cookies. Context trimming operates on request copies, preserving stored history, system instructions and user constraints.
Current target: macOS CLI, existing xAI/OpenAI-compatible API, optional Playwright DOM browser. Persistent named agents use a local daemon, private memory and a background task scheduler; see [TEAM](TEAM.md). No separate search key, UI, MCP, PTY, desktop pixel control, cross-machine protocol, or OS sandbox in this version. Browser-only canvas apps and arbitrary natural-language task correctness remain outside what this MVP can guarantee.
Legacy `chat` stays a no-tools streaming chat. `shell` stays available with a 30-second deadline. Synchronous human-wait library helpers are retained for AUTO/offline compatibility; interactive callers must supply the runtime input broker.
