@tekmidian/pai 0.37.0 → 0.39.0

package/docs/commands/worker.md

@@ -24,6 +24,10 @@ pai worker <subcommand> [options]
 | [`pai worker pane [id]`](#pai-worker-pane-id) | Open the follow pane for a worker (or one shared pane for this session) |
 | [`pai worker log [what]`](#pai-worker-log-what) | all = ledger, tail = last ledger lines, <id> = raw event stream, none = list |
 | [`pai worker say <id> <text>`](#pai-worker-say-id-text) | Send one message to a running worker (forwarded to its open stdin) |
+| [`pai worker handoff <json>`](#pai-worker-handoff-json) | From inside a worker: append a handoff to the parent's inbox and (when it runs) say it to the parent. |
+| [`pai worker merge <id>`](#pai-worker-merge-id) | Merge a worker's worktree branch (worker/<id>) into the original checkout, then remove the worktree |
+| [`pai worker discard <id>`](#pai-worker-discard-id) | Drop a worker's worktree and branch, keeping nothing |
+| [`pai worker controls <id> <who>`](#pai-worker-controls-id-who) | Hand the desktop controls (clickr) to a worker or take them back. |
 | [`pai worker resume <id> <text>`](#pai-worker-resume-id-text) | Continue a finished worker on the same provider: claude --resume <session> |
 | [`pai worker proxy [stop]`](#pai-worker-proxy-stop) | The local Anthropic↔OpenAI proxy (loopback only); started on demand by `run`, |
 | [`pai worker mcp [list]`](#pai-worker-mcp-list) | MCP servers workers may load via --mcp / roles, and the configured sets |
@@ -32,7 +36,7 @@ pai worker <subcommand> [options]
 | [`pai worker off`](#pai-worker-off) | Stop routing: Agent tool runs on Anthropic again |
 | [`pai worker install`](#pai-worker-install) | Migrate: Agent hook in settings.json, ~/.local/bin glm* shims, old script cleanup |
 | [`pai worker providers`](#pai-worker-providers) | Providers: list (default), add, remove, use, enable, disable, test |
-| [`pai worker roles`](#pai-worker-roles) | Roles: which provider serves implement / research / spotcheck |
+| [`pai worker classes`](#pai-worker-classes) | Classes: which provider serves draft / implement / review / … |
 
 ### pai worker run [args...]
 
@@ -40,6 +44,8 @@ Run one claude-code worker through the configured provider.
 
 Unknown options are passed to claude verbatim (e.g. -p, --allowedTools);
 --output-format/--verbose are handled here.
+--chain draft,implement[,review] runs a spec-first pipeline;
+--agent <name> runs an agent definition from ~/.claude/agents.
 
 **Arguments**
 
@@ -52,11 +58,16 @@ Unknown options are passed to claude verbatim (e.g. -p, --allowedTools);
 | Option | Description | Default |
 |--------|-------------|---------|
 | `--provider <name>` | Provider to run on (default: active, else routing order) |  |
-| `--role <role>` | Use the provider of this role (implement, research, spotcheck, …) |  |
+| `--class <name>` | Use the provider of this class (draft, implement, review, research, spotcheck, simple, complex, image) |  |
+| `--role <name>` | Alias of --class (roles were renamed to classes) |  |
+| `--chain <stages>` | Comma-separated stage classes, e.g. draft,implement or draft,implement,review |  |
+| `--agent <name>` | Run the agent definition ~/.claude/agents/<name>.md on a worker |  |
 | `--model <model>` | Override the provider's model for this run |  |
 | `--label <text>` | Short task label shown in ps / follow / status line |  |
 | `--mcp <names>` | MCP servers/sets this worker may use (comma-separated; see `pai worker mcp`) |  |
 | `--no-pane` | Do not open a follow pane for this worker |  |
+| `--worktree` | Run in a git worktree on branch worker/<id> (default for implement/complex/plan in a git repo) |  |
+| `--no-worktree` | Run in place, no worktree |  |
 
 
 ### pai worker ps
@@ -124,7 +135,7 @@ Open the follow pane for a worker (or one shared pane for this session)
 
 | Option | Description | Default |
 |--------|-------------|---------|
-| `--check` | Only report whether the pane is open, plus the profile file's path and font |  |
+| `--check` | Only report whether the pane is open, plus the profile file's path, font, and the hosting window's bounds |  |
 
 
 ### pai worker log [what]
@@ -150,6 +161,56 @@ Send one message to a running worker (forwarded to its open stdin)
 | `<text>` | required |
 
 
+### pai worker handoff <json>
+
+From inside a worker: append a handoff to the parent's inbox and (when it runs) say it to the parent.
+
+Payload: {"kind":"proposal|question|blocker","text":"…","data":{…}} — from/to come from the environment.
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<json>` | required |
+
+
+### pai worker merge <id>
+
+Merge a worker's worktree branch (worker/<id>) into the original checkout, then remove the worktree
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<id>` | required |
+
+
+### pai worker discard <id>
+
+Drop a worker's worktree and branch, keeping nothing
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<id>` | required |
+
+
+### pai worker controls <id> <who>
+
+Hand the desktop controls (clickr) to a worker or take them back.
+
+<who> is `you` (the worker may actuate) or `me` (the operator keeps them);
+inside a worker's pane, typing "your controls" does the same.
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<id>` | required |
+| `<who>` | required |
+
+
 ### pai worker resume <id> <text>
 
 Continue a finished worker on the same provider: claude --resume <session>
@@ -235,7 +296,7 @@ Providers: list (default), add, remove, use, enable, disable, test
 
 ### pai worker providers add <name>
 
-Add a provider; the first one also turns workers on and seeds roles.
+Add a provider; the first one also turns workers on and seeds classes.
 
 Example: pai worker providers add glm --base-url https://…/anthropic \
            --key-file ~/.config/zai/api_key --model glm-5.3 --fast-model glm-5.3-flash
@@ -263,11 +324,31 @@ Codex (ChatGPT plan): --engine codex — runs through the Codex CLI.
 | `--engine <engine>` | claude (default) or codex — codex runs `codex exec --json` |  |
 | `--context-window <tokens>` | Context window for the meter (default 200000; init event overrides) |  |
 | `--quota-probe <url>` | URL whose JSON first number is the quota percent (0-100) |  |
+| `--cost-tier <1-5>` | Cost tier 1 (cheapest) … 5 (most expensive; default 3) |  |
+| `--tags <tags>` | Capability tags, comma-separated (from: code, vision, image-gen, long-context, fast, reasoning) | `` |
+
+
+### pai worker providers update <name>
+
+Change cost tier and tags of a provider (routing constraints use these)
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<name>` | required |
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--cost-tier <1-5>` | Cost tier 1 (cheapest) … 5 (most expensive) |  |
+| `--tags <tags>` | Capability tags, comma-separated (from: code, vision, image-gen, long-context, fast, reasoning); --tags '' clears | `` |
 
 
 ### pai worker providers remove <name>
 
-Remove a provider and any roles pointing at it
+Remove a provider and any classes pointing at it
 
 **Arguments**
 
@@ -278,7 +359,7 @@ Remove a provider and any roles pointing at it
 
 ### pai worker providers use <name>
 
-Make this provider the active one for runs without --provider/--role
+Make this provider the active one for runs without --provider/--class
 
 **Arguments**
 
@@ -320,37 +401,49 @@ One-word pong probe through a provider (default: the active one)
 | `[name]` | optional |
 
 
-### pai worker roles
+### pai worker classes
+
+Classes: which provider serves draft / implement / review / …
 
-Roles: which provider serves implement / research / spotcheck
 
+### pai worker classes list
 
-### pai worker roles list
+List classes and their targets (default action)
 
-List roles and their providers (default action)
 
+### pai worker classes set <class> [target]
 
-### pai worker roles set <role> <provider[/alias]>
+Point a class at a provider (or provider/fast), or give only constraints:
 
-Point a role at a provider, optionally its fast model (e.g. glm/fast)
+classes set research --max-cost-tier 2 --require-tags long-context,reasoning
 
 **Arguments**
 
 | Argument | Kind |
 |----------|------|
-| `<role>` | required |
-| `<provider[/alias]>` | required |
+| `<class>` | required |
+| `[target]` | optional |
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--provider <name>` | Pin the class to this provider (object form) |  |
+| `--mcp <names>` | MCP servers/sets for runs of this class (comma-separated) |  |
+| `--max-cost-tier <1-5>` | Auto-routing considers only providers up to this cost tier |  |
+| `--require-tags <tags>` | Auto-routing needs these tags (comma-separated) |  |
+| `--order <providers>` | Per-class routing order overriding workers.routing.order (comma-separated) |  |
 
 
-### pai worker roles unset <role>
+### pai worker classes unset <class>
 
-Remove a role (runs then use the active provider)
+Remove a class (runs then use the active provider)
 
 **Arguments**
 
 | Argument | Kind |
 |----------|------|
-| `<role>` | required |
+| `<class>` | required |
 
 
 ## See also

package/docs/worker.md

@@ -32,22 +32,26 @@ main session (Anthropic)          workers (configured provider)
         "keyFile": "~/.config/zai/api_key",
         "models": { "default": "glm-5.3", "fast": "glm-5.3-flash" },
         "env": { "API_TIMEOUT_MS": "3000000" },
-        "contextWindow": 200000
+        "contextWindow": 200000,
+        "costTier": 2,
+        "tags": ["code", "long-context"]
       },
       "oai": {
         "protocol": "openai",
         "upstreamUrl": "https://api.openai.com/v1",
         "keyFile": "~/.config/pai/keys/oai",
-        "models": { "default": "gpt-5.2", "fast": "gpt-5.2-mini" }
+        "models": { "default": "gpt-5.2", "fast": "gpt-5.2-mini" },
+        "costTier": 4,
+        "tags": ["reasoning", "vision"]
       },
       "codexprov": {
         "engine": "codex",
         "models": { "default": "gpt-5.2-codex" }
       }
     },
-    "roles": {
+    "classes": {
       "implement": "glm",
-      "research": "glm",
+      "research": { "maxCostTier": 2, "requireTags": ["long-context"] },
       "spotcheck": "glm/fast",
       "docs": { "provider": "glm", "mcp": ["office"] }
     },
@@ -70,8 +74,12 @@ main session (Anthropic)          workers (configured provider)
   Code (see below).
 - `contextWindow` overrides the context-meter window when the endpoint's
   init event does not announce one (default 200 000).
-- A role target is `"provider[/model]"` or an object with `provider` and a
-  `mcp` allowlist applied on top of `--mcp`.
+- `costTier` (1 cheapest … 5 most expensive, default 3) and `tags` (from:
+  `code`, `vision`, `image-gen`, `long-context`, `fast`, `reasoning`) describe
+  a provider; classes use them to constrain routing (next section).
+- A class target is `"provider[/model]"` or an object with `provider` and a
+  `mcp` allowlist applied on top of `--mcp`, or an object with only routing
+  constraints (`maxCostTier`, `requireTags`, `order`).
 
 Or add one from the CLI:
 
@@ -80,19 +88,64 @@ pai worker providers add glm \
   --base-url https://api.z.ai/api/anthropic \
   --key-file ~/.config/zai/api_key \
   --model glm-5.3 --fast-model glm-5.3-flash \
-  --env API_TIMEOUT_MS=3000000
+  --env API_TIMEOUT_MS=3000000 \
+  --cost-tier 2 --tags code,long-context
 pai worker providers add oai \
   --upstream-url https://api.openai.com/v1 \
   --key-file ~/.config/pai/keys/oai --model gpt-5.2
+pai worker providers update glm --cost-tier 1   # tiers/tags change later
 ```
 
 The first provider also sets `enabled: true`, makes itself active and seeds
-the three roles. Then:
+the nine classes. Then:
 
 ```
 pai worker install     # Agent hook in settings.json + glm* shims + cleanup
 ```
 
+## Task classes
+
+Roles were renamed to **classes** — task classes pick the provider for a kind
+of work. The nine standard classes: `draft`, `plan`, `implement`, `review`,
+`research`, `spotcheck`, `simple`, `complex`, `image` (any other name can be
+defined too). Configs with the old `roles` key keep parsing; the key migrates
+to `classes` on the first write.
+
+```
+pai worker classes                          # list
+pai worker classes set implement glm        # pin a provider
+pai worker classes set spotcheck glm/fast   # …its fast model
+pai worker classes set research --max-cost-tier 2 --require-tags long-context
+pai worker classes unset research
+```
+
+Every provider carries a **cost tier** (1 cheapest … 5 most expensive,
+default 3) and **tags** (`code`, `vision`, `image-gen`, `long-context`,
+`fast`, `reasoning`). A class resolves its provider as:
+
+1. `--provider` (explicit flag) wins;
+2. else the class mapping when it pins a provider;
+3. else auto-routing (see below) restricted to providers within the class's
+   `maxCostTier` and carrying all its `requireTags`;
+4. nothing qualifies → the run fails with a message listing why every
+   provider was excluded.
+
+`classes.<name>.order` overrides `routing.order` for that class. Cooldown and
+quota logic is unchanged.
+
+### Preferences from chat
+
+The Worker skill maps phrases onto the MCP tools — the answer is one or two
+lines, and the user is never told to edit a file:
+
+- "use X for image generation" / "route research to kimi" →
+  `worker_classes set <class>=<provider>`
+- "prefer the flash model for simple tasks" / "cheap only for drafts" →
+  `worker_classes set simple|draft=<provider>/fast` (or `max_cost_tier`)
+- "reviews should use a reasoning model" → `worker_classes set review` with
+  `require_tags: ["reasoning"]`
+- "what handles reviews" / "show the routing table" → `worker_classes list`
+
 ## The proxy (OpenAI-protocol providers)
 
 A provider with `protocol: "openai"` cannot be talked to by Claude Code
@@ -135,6 +188,8 @@ so it is unavailable for codex workers (their thread id is kept, but
 pai worker run --label "fix black buttons" -p '<task spec>' \
   --allowedTools 'Read,Edit,Write,Bash,Grep,Glob' --output-format json \
   --mcp office
+pai worker run --chain draft,implement -p '<brief>'   # spec-first (below)
+pai worker run --agent engineer -p '<task>'           # agent library (below)
 pai worker ps                    # this session's workers
 pai worker follow [id]           # live transcript (type to talk to it)
 pai worker replay <id>           # transcript of one worker
@@ -145,10 +200,46 @@ pai worker proxy [--port N|stop] # the translating proxy, by hand
 pai worker log [all|tail|<id>]   # raw streams + routing ledger
 ```
 
-Roles pick the provider for a task class: `--role implement|research|spotcheck`.
-`--no-pane` suppresses the iTerm follow pane; `--provider <name>` bypasses
-roles entirely. If you bring your own `--append-system-prompt`, the worker
-contract below is added alongside it, not instead.
+Classes pick the provider for a task class: `--class implement|research|spotcheck|…`
+(`--role` still works as its alias). `--no-pane` suppresses the iTerm follow
+pane; `--provider <name>` bypasses classes entirely. If you bring your own
+`--append-system-prompt`, the worker contract below is added alongside it, not
+instead.
+
+## Chains (draft → implement → review)
+
+```
+pai worker run --chain draft,implement -p '<brief>'
+pai worker run --chain draft,implement,review -p '<brief>'   # + review pass
+```
+
+- The **draft** class turns the brief into a full spec file under
+  `<logDir>/specs/<chain id>.md` — goal, constraints, files likely touched,
+  acceptance checks, verification commands. It reads the repository first and
+  implements nothing.
+- **implement** (or any other stage class) runs with that spec as its prompt
+  and the original brief attached.
+- **review** reads the spec and the working-tree diff and produces the
+  structured report.
+- Each stage is its own worker: own id, own pane, `parent` set to the chain
+  id — `ps` shows the chain as a tree.
+- A stage that fails stops the chain (the exit code is the first failing
+  stage's); a draft that produces no spec stops it with a message telling the
+  caller to write the spec and re-run without the draft stage.
+- `--class` alongside `--chain` overrides the class of every stage; `--label`
+  names the chain (stages render as `<label> · <stage>`).
+
+## Agent definitions as workers
+
+`pai worker run --agent <name>` loads `~/.claude/agents/<name>.md` and runs it
+on a worker: the front matter's `model` maps to a class (haiku→simple,
+sonnet→implement, opus→complex — `--class` overrides), `tools` becomes
+`--allowedTools`, and the body is passed via `--append-system-prompt` (your
+own flags on the command line still win). The label defaults to
+`<agent>: <first 50 chars of prompt>`.
+
+The agent library therefore runs on workers, not on the orchestrator's
+Anthropic account — same hooks, same classes, same `ps`/`follow`/`replay`.
 
 The old habits keep working: `glm`, `glm-run`, `glm-ps`, `glm-log` are shims
 to the pai commands (`pai worker install` moves any previous versions to
@@ -156,13 +247,19 @@ to the pai commands (`pai worker install` moves any previous versions to
 
 ## Routing
 
-A run resolves its provider as: `--provider` > `--role` > `active`.
+A run resolves its provider as: `--provider` > `--class` > `active`.
 
-With `active: "auto"`, providers are tried in `routing.order`, skipping:
+With `active: "auto"`, providers are tried in `routing.order` (or the class's
+own `order`), skipping:
 
 - disabled providers,
 - providers in a cooldown (set for `cooldownMinutes` after a quota failure),
-- providers whose `quotaProbe` URL reports ≥ `quotaSkipAt` (default 95).
+- providers whose `quotaProbe` URL reports ≥ `quotaSkipAt` (default 95),
+- providers above the class's `maxCostTier` or missing one of its
+  `requireTags`.
+
+Nothing qualifying fails the run with the exclusion reason of every provider
+in the order.
 
 A quota failure before the first tool call is re-run on the next provider and
 logged as `WORKER-REROUTE`. `pai worker providers enable <name>` clears a
@@ -213,9 +310,116 @@ stdin closes two seconds later unless another message arrives — after that
 
 `pai worker resume <id> "<text>"` continues the same Claude session (the id
 recorded from the init event) on the same provider, labelled `↩ <original>`,
-and prints a fresh worker id with `--print-id`. A pane running `follow` reads
-its own stdin the same way: type to say while it runs, or to resume after it
-finished.
+and prints a fresh worker id with `--print-id`.
+
+A `follow <id>` pane on a TTY is a chat, not a tail: the transcript lives in
+a scroll region that ends two rows above the pane's bottom, the last two rows
+are fixed — the prompt row (`› `, full readline editing: arrows, backspace,
+Ctrl-A/E, Ctrl-U) and the ticker row — and every transcript line is inserted
+above them with a save-cursor / restore-cursor write, so the cursor never
+leaves the prompt. Enter sends the line: said to the worker while it runs,
+`resume`d into the same session once it has finished (the pane follows the
+fresh run id and keeps the chat). The sent line is echoed into the transcript
+as a `»` row with its time gutter, exactly once — the mirrored `operator`
+event is swallowed. `/help` lists the commands:
+
+| key | action |
+| --- | --- |
+| `/quit` | close the pane |
+| `/resume <text>` | resume the finished worker with `<text>` |
+| `/status` | one-line worker status |
+| anything else | a message — said, or resumed |
+
+Ctrl-C on an empty prompt leaves the pane, on a draft it clears the prompt;
+Ctrl-D leaves. The auto-exit countdown never fires while the prompt holds
+unsent text. Without a TTY (piped output) the pane keeps the plain scrolling
+behaviour — no prompt row, no ticker, stdin still the operator channel.
+
+### Sub-workers and handoffs
+
+Any worker may start its own workers: the runner exports `PAI_WORKER_ID` in
+every worker's environment, and a `pai worker run` launched from inside one
+records `parent` in its status — so the forest is visible in `ps` (children
+indented under their parent, `├`/`└` connectors), the status line (`↳` under
+the parent) and each child gets its own follow pane. Handoffs travel **up
+only**, from a child to its parent:
+
+```
+pai worker handoff '{"kind":"proposal","text":"run this on a cheap provider","data":{…}}'
+```
+
+(or the MCP tool `worker_handoff`; kinds `proposal`, `question`, `blocker` —
+`result` is sent automatically when a child finishes). The handoff is appended
+to `<logDir>/<parent>.inbox.jsonl` (durable, ordered) and, when the parent is
+running, also delivered as an operator message `[handoff from <child id>]`. The
+parent sees it in its pane (`◆ from <id> · kind: text`, magenta), `ps` and the
+status line show `◆N` for an inbox with N handoffs, and `replay`/`follow`
+merge them into the transcript by timestamp. There is no sideways channel:
+siblings never see each other, everything goes up.
+
+Two caps keep the tree bounded (`workers.tree`):
+
+- `maxDepth` (default 2) — how deep sub-workers may nest; a launch one level
+  past the cap fails with a message that suggests a handoff instead,
+- `maxChildren` (default 4) — how many children of one parent may run at the
+  same time (finished children do not count).
+
+Chain stages and planner sub-tasks carry a parent too, but a parent without a
+status file (a chain id) is not a worker and is never capped by depth.
+
+### Worktrees and merge
+
+A run whose class writes files (`implement`, `complex`, `plan`) in a git repo,
+with a prompt that is not read-only, gets **its own git worktree** by default:
+`<logDir>/worktrees/<id>` on branch `worker/<id>` from the current HEAD. The
+worker commits its work on that branch (the no-commit rule applies to the main
+branch only — the appended system prompt says so); when git refuses (no
+commits yet, detached setup) the run degrades to in place with a note on
+stderr and in the ledger.
+
+```
+pai worker merge <id>     # git merge --no-ff worker/<id> + remove the worktree
+pai worker discard <id>   # remove worktree and branch, keep nothing
+```
+
+`ps` marks a worker with an unmerged branch `⎇<commits>` (yellow); the status
+file records `branch`, `commits` and `worktreeDir`. Chains give a worktree to
+the implement stage only; `--worktree` forces one on, `--no-worktree` opts
+out.
+
+### The planner class
+
+`--class plan` runs a small orchestration, not one worker:
+
+1. a planner worker reads the repository and writes
+   `<logDir>/plans/<planner id>.json` — sub-tasks (`title`, `brief`, `class`,
+   `files`, `acceptance`), 5–50 of them, fewer only when the goal names a
+   smaller count;
+2. the runner validates the plan and spawns the sub-tasks as children of the
+   planner, at most `workers.tree.maxChildren` at a time;
+3. each child's structured report arrives in the planner's inbox as a
+   `kind: "result"` handoff;
+4. the run finishes with a summary report (`n/m sub-tasks ok`) and the
+   `pai worker merge` lines for any unmerged branches.
+
+The planner's prompt carries the prompt rules that make plans executable:
+domain-specific instructions only (real files, real commands), constraints
+over step lists, explicit quantity ranges, no checkbox style.
+
+### Clickr controls (desktop set)
+
+The default `mcpSets` ship one set: `desktop = ["clickr"]`. A worker launched
+`--mcp desktop` receives the clickr MCP server — screen control for GUI work
+— and follows the same control handover as a session:
+
+```
+pai worker controls <id> you    # hand control of the desktop to the worker
+pai worker controls <id> me     # take it back
+```
+
+`controls` runs the `clickr controls you|me` CLI and the worker's screenshot
+and input tools honour it. Control starts with the operator: a worker cannot
+drive the desktop until it is handed over.
 
 ### Context meter
 
@@ -239,7 +443,7 @@ pai worker run --mcp office …      # a set, or names: --mcp memory,github
 `--mcp` takes server names and/or `mcpSets` names (comma-separated,
 repeatable); the filtered config is written from `~/.claude.json`'s
 `mcpServers` to `<logDir>/<id>.mcp.json` and passed with
-`--strict-mcp-config --mcp-config`. Role targets may add `"mcp": ["office"]`
+`--strict-mcp-config --mcp-config`. Class targets may add `"mcp": ["office"]`
 on top. An unknown name fails fast, listing what exists;
 `pai worker mcp list` shows servers and sets. A caller-provided
 `--mcp-config` always wins; MCP is chosen at launch, not mid-run.
@@ -263,6 +467,17 @@ separator when the day changes) and, on a TTY, a liveness line
 erased before the next event. `replay` shows a finished transcript with the
 same gutter.
 
+The pane wraps rows itself at the terminal width (re-read on resize, so a
+narrower pane re-wraps what arrives after the resize): breaks on whitespace
+where it can, hard-wraps a long token otherwise, never splits an ANSI escape
+(it measures printable columns, not string length), and carries diff colours
+onto every continuation row. Each continuation row carries a blank-time
+gutter with the `│` bar kept — the bar runs unbroken down the pane and no
+content ever lands left of it. In the chat layout the transcript scrolls
+inside an ANSI scroll region (`ESC[1;rows-2r`, reset on exit and re-set on
+resize) so the prompt and ticker rows stay fixed; piped output keeps the
+terminal's own wrapping instead.
+
 The pane command is `exec pai worker follow …` so the pane holds exactly one
 process — signals reach the follow directly, and when the worker finishes
 the pane counts down its `auto-exit` (default 60 s, `pane.autoExitSecs`).
@@ -288,12 +503,16 @@ background instead. Decisions are ledgered (`DENIED-ANTHROPIC-AGENT`,
 
 ## MCP tools
 
-`worker_status`, `worker_providers` (list/add/remove/use/enable/disable/test),
-`worker_roles`, `worker_toggle`, `worker_ps`, `worker_replay`,
-`worker_say` (message a running worker), `worker_resume` (continue a
-finished one) — the same library the CLI calls. `worker_providers add`
-accepts a raw `key`, parks it in `~/.config/pai/keys/<name>` (mode 0600) and
-stores only the path.
+`worker_status`, `worker_providers`
+(list/add/update/remove/use/enable/disable/test — `update` changes
+`cost_tier`/`tags`), `worker_classes` (list/set/unset), `worker_run` (start a
+worker or chain from chat, returns the id immediately), `worker_toggle`,
+`worker_ps`, `worker_replay`, `worker_say` (message a running worker),
+`worker_resume` (continue a finished one), `worker_handoff` (from inside a
+worker: send a proposal/question/blocker up to its parent) — the same library
+the CLI calls.
+`worker_providers add` accepts a raw `key`, parks it in
+`~/.config/pai/keys/<name>` (mode 0600) and stores only the path.
 
 ## Status line
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekmidian/pai",
-  "version": "0.37.0",
+  "version": "0.39.0",
   "description": "PAI Knowledge OS — Personal AI Infrastructure with federated memory and project management",
   "type": "module",
   "main": "dist/index.mjs",

package/src/hooks/ts/pre-tool-use/route-agents-to-worker.ts

@@ -112,10 +112,10 @@ async function main(): Promise<void> {
     deny(
       "Agent tool is disabled: subagents run on the configured worker provider, not Anthropic. " +
         "Delegate with Bash instead, in the background:\n\n" +
-        `pai worker run --label "${label || "task"}" --role research -p '<full, self-contained task spec>' ` +
+        `pai worker run --label "${label || "task"}" --class research -p '<full, self-contained task spec>' ` +
         "--allowedTools 'Read,Edit,Write,Bash,Grep,Glob' --output-format json\n\n" +
         "- Run it with run_in_background: true and always with a timeout.\n" +
-        "- Use --role spotcheck (or implement) as the task demands.\n" +
+        "- Use --class spotcheck (or implement) as the task demands.\n" +
         "- Web research: add WebSearch,WebFetch to --allowedTools.\n" +
         "- The answer is in the `result` field of the JSON it prints. Review the diff yourself.\n" +
         "- pai worker ps lists running workers; pai worker follow <id> shows one live.\n" +

package/dist/detector-DtLExmHN.mjs

@@ -1,5 +0,0 @@
-import "./embeddings-DOLZnT1X.mjs";
-import "./search-Rpk1cSBC.mjs";
-import { t as detectTopicShift } from "./detector-CMap-9vw.mjs";
-
-export { detectTopicShift };

package/dist/factory-BXzqRYVZ.mjs

@@ -1,3 +0,0 @@
-import { t as createStorageBackend } from "./factory-DD2T33C9.mjs";
-
-export { createStorageBackend };