fix(agent): treat only an omitted case as a directory spawn, and document the directory launch

`codeman agent spawn ""` (for example `spawn "$CASE"` with CASE unset)
used to launch a worker in the caller's cwd. Both case checks now test
`caseName !== undefined`, so an empty name reaches quick-start and is
refused by its schema as before.

Drop the `{ id }` fallback on the create answer: `POST /api/sessions`
answers `{ session: { id } }`, and the test fakes now use that shape.

Tests: an empty case name (unit and through the real argument parser
and HTTP transport), the claude `--ready` order create, /interactive,
wait-output on the created id, and a non-JSON failed start (id alone on
stdout, reason on stderr, exit 1).

Docs: the spawn mapping and directory-launch JSON shape in
docs/api-reference.md, the README and wiki `codeman agent` sections, the
cli-agent @fileoverview and the skill reference tables; reflow the new
SKILL.md paragraph (plugin mirror synced); the changeset notes the
local exit-4 refusal of an unknown mode for named cases.
This commit is contained in:
Aamer Akhter committed 2026-10-24 22:39:16 -04:00
1 parent b2e96ddfaf
commit c5ffea0ed2
12 files changed
+160 -35

No files matched your search

+7 -5
View File
@@ -41,11 +41,13 @@ verbs over the same endpoints, with the guards below (no control bytes, no self-
no guessed URL) enforced in code, and it is also your own way through when this
machine has no `jq` for the preamble below.
For an existing project, use `codeman agent spawn --working-dir /path/to/project --mode codex` (one command). With no case or `--working-dir`, `spawn` uses cwd. Give
editing workers separate worktrees. A positional case keeps quick-start behavior;
it cannot be combined with `--working-dir`. Directory launches keep parent lineage
and never mark the project as agent scratch. If startup fails or is ambiguous, the
CLI reports the exact created ID: inspect it before retrying or cleaning up.
For an existing project, use one command:
`codeman agent spawn --working-dir /path/to/project --mode codex`. With no case and
no `--working-dir`, `spawn` uses cwd. Give editing workers separate worktrees. A
positional case keeps quick-start behavior and cannot be combined with
`--working-dir`. Directory launches keep parent lineage and never mark the project
as agent scratch. If startup fails or is ambiguous, the CLI reports the exact
created ID: inspect it before retrying or cleaning up.
## 0. Guard and bootstrap
@@ -48,7 +48,7 @@ own head: the worker enforcing the cap is the one who has to be told about it.
| Job | Channel |
| --- | --- |
| spawn a worker, create its case | HTTP `quick-start` (the only path) |
| spawn a worker, create its case | HTTP `quick-start` (the only path that creates a case); an existing directory is `POST sessions` + `interactive` (`codeman agent spawn --working-dir`) |
| readiness, incl. the trust dialog | HTTP, Flow 1 (a message cannot answer a dialog) |
| deliver a task to a READY claude worker | **messaging** (preferred) or HTTP input |
| steer a BUSY claude worker mid-turn | **messaging** (read between the worker's tool calls; the HTTP path can only type into the composer, where text waits for the turn to end) |
@@ -31,7 +31,7 @@ wrong directory.** `quick-start` with a new `caseName` does not find your repo:
|-------------------|------|------------------------------|
| a fresh scratch dir (throwaway experiments) | `POST /api/v1/quick-start {"caseName":"scratch-1","mode":"claude"}` with a **new** case name | Codeman creates the directory and **writes hooks**: `stop` and `blocked` fire, send-and-wait is trustworthy |
| a linked case (a real repo in the linked-cases registry) | same call with the linked name | **hooks installed at session create**, so `stop` fires here too. Not guaranteed: the operator can turn it off. Check |
| any other absolute path, e.g. a git worktree you made | `POST /api/v1/sessions {"workingDir":"/abs/path","mode":"claude"}` then `POST /api/v1/sessions/:id/interactive` | same: **hooks installed at session create**, subject to the same setting. Check |
| any other absolute path, e.g. a git worktree you made | `POST /api/v1/sessions {"workingDir":"/abs/path","mode":"claude"}` then `POST /api/v1/sessions/:id/interactive` (what `codeman agent spawn --working-dir /abs/path` sends) | same: **hooks installed at session create**, subject to the same setting. Check |
Read `.data.casePath` back from the `quick-start` response and check it is where you
meant. `caseName` accepts letters, digits, `-` and `_` only, and it resolves through