handoff_agent example: hand it a task and walk away

[yuanhao]

A new example beside coding_agent, focused on one idea: a personal handoff agent. You give it a task and leave; it works, asks you only when it must (without waiting for you), and hands back a report.

cd my-project
path/to/yoagent/scripts/try-handoff.sh --live "move the config to TOML, keep the tests green"
path/to/yoagent/scripts/try-handoff.sh --phone --live "…"   # serve on the LAN, for a phone

What it does

• Plans: with a pi extension used unchanged, @juicesharp/rpiv-todo (207k downloads a month). A new todo-plan UI plugin draws the plan as a checklist in the page.
• Researches and works: DSH's free web search, plus yoagent's file and shell tools in the current directory.
• Asks without waiting (ask_owner):
  • The question goes to every frontend and the tool returns at once, so the agent carries on with independent work.
  • The answer comes back as a steer message: picked up mid-run, or starting a new run if the agent had stopped.
  • A dismissed question comes back as "skipped"; the agent decides itself and says so.
• Guardrails:
  • pi's approval for dangerous commands. Those do wait, and with nobody connected they're refused.
  • require_policy.
  • Turn and minute limits.
  • A dollar Budget when the model is priced (DeepSeek isn't in the bundled table, so it gets turns and minutes only).
• Handoff report:
  • A verifier sends the agent back until the run ends with Done / Waiting on you / Decisions / Next.
  • The host then adds facts the model can't make up: the change since the handoff started (git diff --shortstat against the starting commit, plus the number of commits), tokens, tool calls, time, and open questions.

One library addition: Session::ask_later

• ask gives up at once when no frontend is attached. ask_later keeps the question open until it's answered, and a frontend that connects later gets it in its Hello.
• While doing this I found that an ended session left its open questions pending. It now ends them with their default, and a question asked on an ended session is refused. Two new session tests cover both.

Tried live

DeepSeek, a phone-sized headless Chrome, and a scratch Python project ("move the config from JSON to TOML, keep python3 -m unittest passing"). The agent started before any browser connected.

• Run 1: planned 5 steps, migrated, verified that JSON and TOML hold the same values, and committed. It asked feat: complete multimodal image pipeline for tool results #1 (delete config.json?) and feat: add SubAgentTool for delegating tasks to child agent loops #2 (outside consumers?) without stopping, and reported both open.
• While nobody was connected: rm -rf __pycache__ was refused by the pi approval's safe default, and the agent worked around it.
• The owner answered feat: complete multimodal image pipeline for tool results #1 ("delete"), which started run 2: delete, re-verify, commit separately.
• feat: add SubAgentTool for delegating tasks to child agent loops #2 was dismissed: run 3, where the agent decided itself and wrote down why, then tidied up .gitignore with one approval granted.
• Every run ended with the four-section report. The plan rendered 15 times.

A first-run flaw is fixed in this PR: the facts compared against the current HEAD, which hides the agent's own commits. They now compare against the commit the handoff started from.

Checks

• --demo (scripted: plan, a question, a report; then the answer starts run 2) self-checks and runs in CI (frontend-experimental).
• All 38 frontend tests pass with the runtimes required; clippy, docs and fmt are clean.
• The lockfile only gained entries (rpiv-todo and rpiv-i18n 2.12.0, installed without pi's peers, which the adapter provides).

🤖 Generated with Claude Code

https://claude.ai/code/session_01T7iq5hpndSiHQcnAsywKuG