agent

Files (17)

• LIMITATIONS.md
• SKILL.md
• fno-agents-subcommands.md · references/
• launch-agy.md · references/
• launch-claude.md · references/
• launch-codex.md · references/
• launch-opencode.md · references/
• launch-pi.md · references/
• workflow-routes.md · references/
• confirm-decision.sh · scripts/
• with-timeout.sh · scripts/lib/
• normalize.sh · scripts/
• spawn.sh · scripts/
• test_auto_worktree.sh · tests/
• test_confirm.sh · tests/
• test_normalize.sh · tests/
• test_spawn_guard.sh · tests/

SKILL.md (first lines)

<!-- style-exception: mechanical command rename preserves pre-existing prose -->
# Agents

**Describe the agent outcome you want; this skill remembers the command.**

`/fno:agent` is the natural-language front door over the shipped `fno agents`
mesh. The CLI is intentionally precise, but its provider, substrate, lifecycle,
and receipt shapes are too much syntax to keep in working memory. State the
intent in ordinary language; the skill selects the real command and arguments.

**You (the agent) are the runner.** Read the user's desired outcome, route it to
the right command, normalize it, confirm only costed or destructive operations, run
the **genuine** `fno agents` command, and report the **real** captured receipt -
never a fabricated one.

This skill REUSES the shipped `fno agents` primitives. It does not reimplement
spawn, the addressed bus, or session observation. Its value is command routing +
input normalization + confirmation policy + honest reporting. Smart-quote and
dashless parsing also keep it reliable from remote or runner-less controls.

`SKILL_DIR` below is `skills/agent` inside this plugin.

## Command router

The first whitespace token of the argument is the **command**. An unrecognized
leading token means the whole argument is a `spawn` payload (this preserves the
bare `/agents <task>` ergonomics the former dispatch front door had). `spawn`
means start a session with what you pass, nothing more : an explicit
`/skill` command is dispatched per harness, a resolved backlog node id builds
via `/target`, and any other free text is sent **verbatim as the session seed** -
no `/target` wrap, no build inference. The focused core:

> **Retired commands :** `bare` and `discuss` are gone. A conversational
> session is just `spawn "<seed>"` (the default); a one-shot Q&A to a NEW
> worker is `spawn "<question>" headless`. (The `--ask`/`--discuss` normalize
> flags remain hard errors.)
>
> **`ask` is back with different semantics.** The OLD ask (one-shot Q&A via a
> throwaway worker) stays retired. Today's `ask <name> "<question>"` is the
> synchronous request-reply lane to an EXISTING worker: it runs `fno agents
> ask`, which delivers into the live session, waits for the reply (default
> 600s), and prints it on stdout. Async fire-and-receipt stays on `send`
> (`fno agents mail send`). See the `ask` section for the boundary.

| Command | Envelope | Routes to | Cost |
|------|----------|-----------|------|
| `spawn` (default) | normalize + honest-receipt (no confirm: free lane) | `fno agents spawn` - substrate axis : default `thread` where the harness seats one (persistent, portal view; `pane` placement flags or a `--` fence imply pane); `substrate pane` -> owned-PTY drivable; `substrate headless` -> one-shot (`claude -p` / `codex --exec` / `agy -p`) | free (claude subscription) |
| `handoff <doc>` | normalize `--handoff` + honest-receipt (free lane) | `fno agents spawn` (Claude/Codex/Gemini continuation seed, NO `/target`; default `thread`) | free (provider subscription) |
| `send <name> "..."` | normalize recipient + addressed write | `fno agents mail send` (the addressed jsonl bus, sender-excluded) | free |
| `ask <name> "..."` | parse + refuse-empty + honest reply relay | `fno agents mail ask` - sync deliver into a live worker + reply-wait poll; reply on stdout | free |
| `watch <name>` | thin pass-through | `fno agents session watch` | free |
| `list` | thin pass-through | `fno agents session list` | free |
| `whoami` | thin pass-through (read-only) | `fno agents registry whoami` | free |
| `logs <name>` | thin pass-through | `fno agents session logs` | free |
| `stop <name>` | confirm (destructive) + pass-through | `fno agents session stop` | free |

Advanced lifecycle intents (`drive`/`grid`/`attach`/`resume`/`reconcile`/`rm`/
`ack`/`promote`) map to their corresponding raw `fno agents` commands; the skill
resolves their arguments and runs them rather than reimplementing them. The
capability matrix at `docs/harness-command-matrix.md` remains the per-provider
truth. For the full subcommand map - which are human-facing vs
machine-internal vs exploratory channel infra - see
[references/fno-agents-subcommands.md](references/fno-agents-subcommands.md).

Machine and targeted loop halts use existing `fno agents audit incident stop|clear` commands. Matching sessions refuse watchdog resumes and PR nudges until clear or expiry.

Route on the command, then run the matching section below.

## Launch a worker

Read this table before you seat a worker on a node. Use the harness's own line where it runs without a pane. Use `fno agents spawn` where it does not. If you need a spawn-only flag (`--promote`, `--hand-off`, or pane placement), use spawn too.

| Harness | Unattended teammate | Watched in a pane | Page |
|---|---|---|---|
| claude | `claude --bg --name <name> --model <m> '/fno:target <node>'` | `claude attach <id>` on the same session | [launch-claude.md](references/launch-claude.md) |
| codex | `fno agents spawn -H codex --name <name> --node <node> '$fno:target <node>'` | `fno mux pane run --cwd <repo-root> -- codex ... '$fno:target <node>'` | [launch-codex.md](references/launch-codex.md) |
| opencode | `fno agents spawn -H opencode --name <name> --node <node> '/fno:target <node>'` | not measured on v2 | [launch-opencode.md](references/launch-opencode.md) |
| pi | `fno agents spawn -H pi --name <name> --node <node> '/fno:target <node>'` | `fno mux pane run --cwd <repo-root> -- pi ... '/skill:target <node>'` | [launch-pi.md](references/launch-pi.md) |
| agy | `fno agents spawn -H agy --name <name> --node <node> '/fno:target <node>'` | `fno mux pane run --cwd <repo-root> -- agy ... -i '/target <node>'` | [launch-agy.md](references/launch-agy.md) |
| muse | `fno agents spawn -H muse --as thread --name <name> --node <node> '<task>' -- --yolo` | no pane lane | [launch-muse.md](references/launch-muse.md) |

The implementation lane is claude on glm through zai. A claude route rides a `--settings` file, so ask spawn for the exact line and run what it prints: `fno agents spawn --name <name> '/fno:target <node>' --route 'zai,glm-5.3-flash[1m]' --effort xhigh --permission-mode bypassPermissions --print`.

Spawn owns its own flags (`--name`, `--harness`, `--as`, `--cwd`, `--node`, `--route`) and forwards every other flag to the harness unchanged. `--model`/`-m`, `--effort`, `--permission-mode`, `--add-dir`, `--agent` and `--tools` typed before the `--` fence are shorthand for the same flag behind it. `fno agents spawn --name w -H claude --model sonnet --permission-mode bypassPermissions 'go'` launches claude with both. The receipt names the model and its basis: `model_basis` reads `requested` (you typed it), `route` (a `--route` set it), or `lane-default` (nothing named it). A lane that cannot carry a flag refuses and names it. The opencode thread lane carries only `--model`. The codex thread lane takes `--model`, `--effort`, `--add-dir` and `--permission-mode` (a `sandbox:approval` pair such as `workspace-write:never`).

fno gates, records and adopts every native line. The PreToolUse Bash hook asks the spawn gate and denies a refused launch. The harness's SessionStart hook then gives the session a registry row with your session as its parent. Each page holds the full flag table, read from the harness's own `--help`.

---

## `spawn` (default command) - launch a worker or seed a session

Start a session with what you pass : a `/skill` passthrough, a node-id
build, or a verbatim free-text seed. Strip a leading `spawn` command if present;
otherwise the whole argument is the spawn payload.

A harness-native launch is first-class. [Launch a worker](#launch-a-worker) picks the form per harness.

### Providers (all three are first-class)

Default is claude on the `thread` substrate. When the user names a non-default provider, a `thread`/`headless` substrate, or a one-shot Q&A, load [references/workflow-routes.md](references/workflow-routes.md) for the provider/substrate matrix and per-provider receipt shapes; the default-path invariants hold everywhere: every spawn captures the worker's full resume UUID (best-effort) into the registry, and a codex/agy exec worker is a single autonomous pass, never loop-grade.

### Inputs (dashless grammar - phone-first)

The documented grammar carries **zero dash tokens** so a phone keyboard's smart
punctuation (which rewrites `--` into a long dash and mangles a lone `-`) can
never corrupt it. The user types barewords or natural language; you map them to
the structured fields. The canonical form:

```
<payload> [provider] [drive] [as <name>] [merge]
```

The angle brackets are placeholder notation, not literal syntax. Infer the
fields from the user's unquoted text (a free-form phrasing maps the same way -
see below):

- **payload** (required): a backlog node id (`ab-XXXXXXXX`, builds via `/target`), an explicit slash command (`/target ...`, `/fno:ship pr check 42`, dispatched per harness), or any other free text - sent **verbatim as the session seed** (a live pane), no `/target` wrap. (: `spawn "fix the login bug"` seeds a session; it does NOT build. To build free text, write `spawn /target <text>` or pass a node id.)
- **one-shot Q&A**: append the `headless` substrate (: it replaced the
  old one-shot ask and `bare`) - `spawn "<question>" headless` returns a

From bllshttng/fno, Apache-2.0.

More from bllshttng/fno