08-tooling

background agents capabilities and new work

2026-05-31·tooling-reference·status: validated (capabilities grounded against CLI + Claude Code changelog)·by Ray

Background agents — validated capabilities + new work this enables

Companion to the loop-offload migration doc ([[2026-05-31-cron-loops-to-background-agents-architecture]]). This doc validates the founder's understanding of the claude background-agent surface and brainstorms the new work it unlocks (personas like Felix/Fat Cat, critic boards, persistent-goal agents). Everything below is grounded in the live CLI (v2.1.158) + the Claude Code changelog (~/.claude/cache/changelog.md), not memory.

Validated understanding (founder's 5 bullets)

  1. Monitor other background agents — CONFIRMED. claude agents (agent view: grouped by state, peek with Space, attach with Enter, reply to blocked, pin with Ctrl+T, filter, PR chips). claude agents --json for scripting. Supervisor keeps sessions running independently.
  2. "Pass a message to another background agent" — CORRECTED (with a real exception). There is NO first-class way for one standalone background agent to message another. CLI probe found no send/message/tell/dispatch/exec/etc. My own empirical test: claude --bg --name X "m1" then claude --bg --name X "m2" produced TWO separate sessions both named X (the name is a non-unique display label, NOT a routing key) — so re-invoking does NOT message an existing agent. The only way into a running bg agent is claude attach <id> (interactive; Ctrl+Z detaches). Exception: real agent-to-agent messaging EXISTS inside agent teams (experimental, opt-in CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) — teammates share a task list and have a first-class SendMessage tool + idle notifications (changelog-confirmed). We do not run agent teams today. For standalone agents, coordinate via a shared artifact (file / Notion row the other agent polls) + agents --json status + claude logs <id> — never a pipe.
  3. Spin up / stop — CONFIRMED. claude --bg "<prompt>" dispatches; claude stop <id>, claude respawn <id> (process only; transcript persists), claude rm <id>. From inside a session: /bg "<prompt>". claude kill does NOT exist (a docs claim that failed verification).
  4. Name + agent-specification + model + effort + permission-mode + initial prompt — CONFIRMED, and richer. Dispatch flags: --name, --model <haiku|sonnet|opus|id>, --effort <low|medium|high|xhigh|max>, --permission-mode <acceptEdits|auto|bypassPermissions|default|dontAsk|plan>, plus the initial-prompt arg. The agent-specification mechanism is a subagent definition: --agent <name> runs a definition as the session's main thread (its Markdown body REPLACES the default system prompt; it inherits the definition's tools/model/permissions). Definitions live in ~/.claude/agents/<name>.md (or project .claude/agents/) OR inline via --agents '{JSON}'. Per-run --allowedTools/--disallowedTools further tighten the toolset (intersection wins).
  5. Patterns — NUANCED, mostly yes.
    • Loop offload: fully supported (claude --bg "/loop ..." — the loop keeps it alive past the ~1h idle reap). See the companion migration doc.
    • /goal: REAL built-in command (changelog-confirmed): "set a completion condition and Claude keeps working across turns until it's met. Works in interactive, -p, and Remote Control." Outcome-driven, can run for days. This is exactly the founder's "/goal … persist until done."
    • Board of supervisor critic agents: buildable TWO ways — (a) the Workflow tool (proven, non-experimental — it's what produced this very analysis: 3 designs + adversarial verify + synth), or (b) agent teams (experimental, real teammate messaging). Default to Workflow.
    • Named personas (Felix, Fat Cat): just subagent definition files. No persona registry exists yet; ~/.claude/agents/ does not exist on this machine — we create it.

Capability reference (grounded)

Dispatch (one bg agent): claude --bg --name <n> [--agent <def> | --agents '{json}'] [--model m] [--effort e] [--permission-mode mode] [--allowedTools "..."] [--disallowedTools "..."] "<initial prompt>"

Manage / observe: claude agents [--json] [--cwd <p>] · claude attach <id> (interactive) · claude logs <id> (recent output; raw ANSI) · claude stop <id> · claude respawn <id>|--all · claude rm <id> · claude daemon status|logs|stop|uninstall|run.

Subagent definition format (from on-disk plugin examples, e.g. vercel agents):

---
name: felix
description: Use when ... (when-to-delegate + capability summary)
tools: Bash, Read, Edit, Grep, Glob, WebSearch    # optional; omit = inherit all
model: sonnet                                      # optional; omit = inherit
---
You are <persona>. <full system prompt: role, mandate, behavioral rules, output contract>

Shipped examples use only name + description (inherit everything else). tools, model optional.

Constraints (the RDCO operating envelope — NOT in any doc):

Docs-vs-skill recommendation

Reference the docs for the raw CLI surface; write ONE thin RDCO skill + a persona registry for the load-bearing parts. Generic mechanics (flags, agent-view keys, /goal vs /loop) are well-documented and stable — don't re-document them. What's NOT in any doc and bites us every time is the RDCO operating envelope (the 5 constraints above). Recommended:

Brainstorm — top new work (ranked, feasibility-tagged)

  1. Morning-prep canary (ready-now, gates everything) — one temp cron line claude --bg /morning-prep; settles the TCC-iMessage + locked-keychain unknowns; reversible same-day.
  2. Persona registry (ready-now, prerequisite) — ~/.claude/agents/ + felix.md + fat-cat.md + port existing critics. Self-authored, no age-wait.
  3. Notion "Boardroom" shared-artifact bus (ready-now) — the no-A2A coordination keystone; agents write structured verdict rows, consumers poll.
  4. Compile-from-manifest loop offloader (needs real build) — sync-loops.sh compiles scheduled-jobs.txt bg-mode lines into crontab; retires the duplicate-arming bug. Do AFTER canary.
  5. Loop watchdog (needs small build) — cheap haiku cron scans per-run JSON for missing success sentinels / permission-quota strings (exit-0 lies); prevents a repeat of the 2026-05-26 silent outage.
  6. Paper-trade pre-deploy critic board (needs small build) — fat-cat + strategic + zero-context bear + capital-cycle-phase critics converge before a deploy decision page is built (does NOT bypass the deploy-verb gate).
  7. /goal durability harness (needs small build) — persistent-goals.txt + a SessionStart re-arm hook (mirror of emit-cron-rearm.sh) so long-running goals survive the 4am restart.
  8. Investing / vault fan-out swarms (needs small build, cheap) — one haiku bg agent per ticker (cap ~6) or per vault cluster writes a Notion verdict row; a reducer synthesizes.
  9. Sanity Check editorial board (needs small build) — voice / originality / hook / em-dash-tell critics gate each issue before founder review.

Felix + Fat Cat — concrete shape

Both are read/diagnostic-only subagent defs under ~/.claude/agents/, with the channels-agent as relay seat for any iMessage delivery (TCC). Both write DECISION-class output to a Notion Boardroom row.

First experiment (smallest high-signal)

The morning-prep canary. One temporary crontab line firing claude --bg /morning-prep (with CLAUDE_CODE_OAUTH_TOKEN exported from 1Password), keeping the existing in-session arming live in parallel (non-destructive). It exercises BOTH deciding unknowns: (a) can a cron-launched bg agent inherit the macOS TCC grant to SEND iMessage? (b) does the OAuth-token export survive a locked keychain? A local-only loop would give a false green. Snapshot crontab first; land script changes via branch+PR.

Open questions for founder

  1. Canary fork: if cron-lineage CAN send iMessage, push max loops fully-bg, or keep iMessage-coupled jobs on the channels-agent for reliability regardless?
  2. Any PERSISTENT personas now (fat-cat 6h /goal, felix standing watchdog), or both on-demand only? (Persistent opus loops = real ongoing quota; lean: start on-demand, earn persistence.)
  3. Paper-trade critic board: should a FAIL hard-block the deploy (park + require override), or just annotate and leave the deploy-verb gate as the sole stop?
  4. Scope: felix + fat-cat first, or author the full critic registry at once? (Lean: two named + port pipeline-critic, grow on demand.)
  5. Boardroom: new Notion DB or a row-type in the existing task board? (Lean: new DB, only DECISION-class rows relayed to iMessage.)

Cross-refs