[FEATURE]: Ultra Mode — autonomous full-cycle agent with hardcoded state machine

[GoDiao]

Verification

• I have searched existing issues and confirmed this feature has not been suggested before

Related but distinct issues:

• [FEATURE]: Ephemeral Sub-Agent Teams (parallel multi-agent orchestration) #19999 (Ephemeral Sub-Agent Teams) — focuses on parallel multi-agent orchestration with cleanup
• [FEATURE]: Plugin-based agent orchestration layer — parallel execution without upstream changes #20849 (Plugin-based orchestration) — focuses on plugin-level agent coordination
• [FEATURE]:Implement /loop command for automated iterative task execution #18001 (/loop command) — focuses on iterative task execution loop
• [FEATURE]: Add Agent Teams Equivalent or Better #12661 (Agent Teams) — broader multi-agent coordination discussion

Ultra Mode differs from these by providing a single-agent state machine with hardcoded phase transitions and tool-level enforcement, rather than multi-agent orchestration or plugin systems.

Problem

Currently, going from a requirement to a verified implementation requires manual coordination: switch to plan agent, write a plan, switch to build agent, implement, run tests, fix failures, repeat. This is tedious when you just want to "fire and forget" a well-defined task.

Proposal

Add a new primary agent called ultra that autonomously executes the full plan→build→verify→iterate loop with a hardcoded state machine that enforces correct phase transitions.

State Machine

planning → building → verifying → complete
                         ↓ (test fail, retries < 10)
                     iterating → verifying
                         ↓ (retries ≥ 10)
                     stop, ask user

Each phase restricts which tools are available:

Phase	Allowed	Blocked
planning	read, glob, grep, explore, write(plan file only)	edit, write, bash(modify)
building	all tools	—
verifying	read, glob, grep, ultra_verify	edit, write, bash
iterating	all tools	ultra_verify
complete	read only	edit, write, bash

Three enforcement layers

1. Tool filtering — resolveTools() physically removes blocked tools so the LLM cannot call them
2. Execution guard — ultra_verify rejects calls outside verifying phase; ultra_phase rejects invalid transitions
3. Prompt injection — insertReminders() injects phase-specific constraints every step

New tools

• ultra_verify — auto-detects test command (package.json / Makefile / Cargo.toml / pyproject.toml / go.mod), runs tests, returns structured result. Auto-transitions to complete on pass or iterating on fail.
• ultra_phase — transitions between phases, validates transitions are legal.

Multi-session support

Phase state is stored per sessionID (not per project directory), so multiple ultra sessions can run in parallel without interference.

Usage

@ultra implement user login with JWT auth and tests

Or set as default: { "default_agent": "ultra" }

Implementation

• New files: src/session/ultra-state.ts, src/tool/ultra-verify.ts, src/tool/ultra-phase.ts, src/agent/prompt/ultra.txt
• Modified: src/agent/agent.ts (register agent), src/tool/registry.ts (register tools), src/session/prompt.ts (tool filtering + reminders)
• Tests: 66 passing (22 state machine + 7 agent config + 37 existing agent tests unchanged)

Why a hardcoded state machine?

A prompt-only approach (just telling the LLM what to do) is unreliable — the LLM can skip phases, forget to verify, or claim completion without testing. The state machine makes the workflow deterministic: the LLM physically cannot call edit during planning, cannot skip verification, and must retry up to 10 times before giving up.

Verification

• Built and tested with bun test — 66/66 tests pass
• Manually tested: created a personal website from scratch using ultra mode, full planning→building→verifying→complete cycle completed autonomously

---

Open to feedback on the design. Happy to adjust the approach (e.g., add a feature flag, use InstanceState instead of a plain Map, split into smaller PRs) based on maintainer preferences.

[github-actions]

Thanks for updating the issue! It now meets our contributing guidelines. The [FEATURE]: title prefix and verification checkbox are in place, and the proposal is well-described. Appreciate the effort!