@wular/coder 0.1.19 → 0.1.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wular/coder",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "Delegating coding-agent runtime",
   "type": "module",
   "bin": {

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "coder",
-  "version": "0.1.19",
-  "description": "Delegate coding tasks to a Coder subagent. Codex first, Claude fallback; your main context stays clean.",
+  "version": "0.1.20",
+  "description": "Delegate coding tasks to a Coder subagent. Your main context stays clean.",
   "author": {
     "name": "muzam1l"
   }

package/plugins/claude/skills/handle/SKILL.md

@@ -16,7 +16,7 @@ If `coder` is not on PATH, install it yourself without asking (`npm install -g @
 - Compose one self-contained task text (goal, relevant paths, constraints) and dispatch it. It backgrounds by default: the runtime does a startup check and prints a task id (or errors / hands off, see exit codes):
 
   ```bash
-  coder task run "<task text>"
+  coder task run --host claude "<task text>"
   ```
 
   Fetch the answer with `coder task result <task-id> --wait` - it blocks until the task finishes, then prints only the final answer (keeps your context clean). Run it as a **background Bash call** so it does not block you and you are re-invoked on completion:
@@ -26,8 +26,10 @@ If `coder` is not on PATH, install it yourself without asking (`npm install -g @
   ```
 
   Only use `--wait` when you can run it in a background shell like that; without one, poll `coder task result <task-id>` (no `--wait`) until it is done. Or skip the two steps and block on the run itself with `--wait` on `coder task run`.
+
 - A `--wait` (on `run` or `result`) exits **4** when the task is waiting on a permission approval: relay the approval to the user, apply their decision with `coder approve <task-id> <approval-id> [--deny]`, then re-fetch with `coder task result <task-id> --wait`. (Unanswered approvals auto-deny after 120s and the task moves on.)
 
+- Always pass `--host claude` to identify yourself.
 - `coder task run` exits after its startup check. Exit 0: the task started - relay the task id and fetch its result (above), BUT if stdout is a `spawn-claude-subagent` payload (Claude is the configured engine), this is a clean delegation - spawn the subagent as below, do not treat it as a result. Exit 1: it failed to start - report it, do not retry or fall back yourself. Exit 3: Codex failed to start and handed off to Claude (see below).
 - Engine, model, and effort come from config; add `--agent` / `--model` / `--effort` when the user asks or it is unambiguous from context (agents: `codex`, `claude`; codex models: `spark`, `luna`, `terra`, `sol`; claude models: `opus`, `sonnet`, `fable`; efforts: `low|medium|high`).
   - `spark` is only for the very lightest tasks (formatting, renames, quick lookups) - very fast and very cheap. It runs on a separate quota, so reach for it when the others hit a usage limit; it may still run once they are exhausted.
@@ -55,5 +57,5 @@ Relay its output when it completes.
 ## Hard rules
 
 - Forward task text verbatim in `steer` and fallback prompts - never rewrite or summarize what the user asked for.
-- NEVER run git write operations yourself (commit, checkout, stash, reset, rebase, merge, push, etc.); the runtime's approval policy enforces this for Codex.
-- Honor any constraints in the user's request (read-only, scoped paths) over your own preferences.
+- Tell every coder to never run git write operations (commit, checkout, stash, reset, rebase, merge, push, etc.) and to leave changes uncommitted - the Claude subagent prompt already prefixes this, and the runtime's approval policy enforces it for Codex.
+- Pass the user's constraints (read-only, scoped paths) into each coder's task text, and honor them over your own preferences.

package/plugins/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "coder",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "interface": {
     "displayName": "Coder (plugin)"
   },

package/plugins/codex/skills/handle/SKILL.md

@@ -7,7 +7,7 @@ description: Use Coder for any coding, implementation, or investigation task - f
 
 You dispatch coding tasks through the `coder` runtime instead of implementing them yourself. By default the runtime picks the engine from its configured chain; `--agent`/`--model`/`--effort` override it. You never spawn agents yourself in this host.
 
-If `coder` is not on PATH, install it yourself without asking: `npm install -g @wular/coder`, then `coder host-setup --codex`. Only if that fails, show the user the error and those two commands. On first setup, mention the chain is Codex-first with Claude on fallback. The Claude fallback engine needs the claude CLI; if it is not installed, ask the user before installing it (on yes: `npm install -g @anthropic-ai/claude-code`, then have them run `claude` once to log in). If the user prefers Claude engines first, run `coder config set chain claude,codex`.
+If `coder` is not on PATH, install it yourself without asking: `npm install -g @wular/coder`, then `coder host-setup --codex`. Only if that fails, show the user the error and those two commands. The configured chain (`coder config`) decides which engine runs first and which is the fallback; set it with `coder config set chain <first>,<second>`. Each engine needs its own CLI; the claude engine needs the claude CLI installed - if it is not, ask the user before installing it (on yes: `npm install -g @anthropic-ai/claude-code`, then have them run `claude` once to log in).
 
 When you run setup, also check codex is new enough for the default GPT-5.6 model, which needs codex `>= 0.144` (`codex --version`). If it is older, update it automatically without asking with `codex update` (codex's own updater; fall back to `npm install -g @openai/codex@latest` if it fails), then tell the user to restart their codex session so the update takes effect.
 
@@ -26,11 +26,7 @@ When you run setup, also check codex is new enough for the default GPT-5.6 model
 
 - Always pass `--host codex` to identify yourself.
 - `coder task run` exits after its startup check. Exit 0: the task started - fetch its result (above). Exit 1: it failed to start / the turn failed - report it, do not retry.
-- Exit 3: Codex could not start (auth, quota, rate limit - mention this to the user, including any limit-reset time). Rerun once with the Claude engine and fetch its result:
-
-  ```bash
-  coder task run --host codex --agent claude "<same task text, verbatim>"
-  ```
+- When the first engine can't start (auth, quota, rate limit), the runtime automatically falls back to the next engine in the chain, runs the same task on it via CLI, and still exits 0 - so just fetch the result. If the failure mentions a usage-limit reset time, relay that to the user.
 
 - Engine, model, and effort come from config; add `--agent` / `--model` / `--effort` when the user asks or it is unambiguous from context (agents: `codex`, `claude`; codex models: `spark`, `luna`, `terra`, `sol`; claude models: `opus`, `sonnet`, `fable`; efforts: `low|medium|high`).
   - `spark` is only for the very lightest tasks (formatting, renames, quick lookups) - very fast and very cheap. It runs on a separate quota, so reach for it when the others hit a usage limit; it may still run once they are exhausted.
@@ -47,5 +43,5 @@ When you run setup, also check codex is new enough for the default GPT-5.6 model
 ## Hard rules
 
 - Forward task text verbatim in `steer` and retries - never rewrite or summarize what the user asked for.
-- NEVER run git write operations yourself (commit, checkout, stash, reset, rebase, merge, push, etc.); the runtime's permission model constrains the engines.
-- Honor any constraints in the user's request (read-only, scoped paths) over your own preferences.
+- Tell every coder, in its task text, to never run git write operations (commit, checkout, stash, reset, rebase, merge, push, etc.) and to leave changes uncommitted. The runtime's permission model also enforces this on the engines.
+- Pass the user's constraints (read-only, scoped paths) into each coder's task text, and honor them over your own preferences.

package/plugins/cursor/.cursor-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "coder",
+  "version": "0.1.19",
+  "description": "Delegate coding tasks to a Coder subagent. Your main context stays clean.",
+  "author": {
+    "name": "muzam1l"
+  }
+}

package/plugins/cursor/skills/handle/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: handle
+description: Use Coder for any coding, implementation, or investigation task - features, fixes, refactors, debugging, tests, code questions. You orchestrate, never implement yourself; dispatch through the `coder` CLI, one coder per focused goal, fanning out many coders in parallel as the work needs.
+---
+
+# Coder dispatch (Cursor host)
+
+You dispatch coding tasks through the `coder` runtime instead of implementing them yourself. By default the runtime picks the engine from its configured chain; `--agent`/`--model`/`--effort` override it. You never spawn agents yourself; the runtime spawns and supervises them.
+
+If `coder` is not on PATH, install it yourself without asking: `npm install -g @wular/coder`, then `coder host-setup --cursor`. Only if that fails, show the user the error and those two commands. The engines need their own CLIs: codex (`npm install -g @openai/codex`, then `codex login`) and claude (`npm install -g @anthropic-ai/claude-code`, then run `claude` once to log in) - ask the user before installing an engine CLI. The configured chain (`coder config`) decides which engine runs first and which is the fallback; set it with `coder config set chain <first>,<second>`.
+
+When you run setup, also check codex is new enough for the default GPT-5.6 model, which needs codex `>= 0.144` (`codex --version`). If it is older, update it automatically without asking with `codex update` (codex's own updater; fall back to `npm install -g @openai/codex@latest` if it fails), then tell the user to restart their codex session so the update takes effect.
+
+## Dispatching a task
+
+- `coder` commands are safe to run in the terminal - the runtime is a supervisor: it spawns engines, keeps state in `~/.coder`, and enforces its own OS sandbox and approval policy on the task. If Cursor asks before running terminal commands, approve the `coder` calls (or allowlist the `coder` command).
+- One coder per focused goal. When the work splits into independent parts, decompose it and dispatch each part as its own `coder task run` call - fan out a wide web of coders, not one giant dispatch. Give each coder a self-contained goal with all context - overview, file paths, constraints (read-only, git rules); use `steer` to continue a single coder's thread.
+- Delegation is a hard gate for anything the engine can do itself: do not read source files, investigate, or write code first - no matter how simple the task. Fold into the task text whatever only you have - conversation context, results from tools the engine lacks. The coder worker runs with plugins disabled (no rules, skills, MCP, or connectors), so include any context only a rule or MCP tool of yours produced.
+- Compose one self-contained task text (goal, relevant paths, constraints) and dispatch it. It backgrounds by default: the runtime does a startup check and prints a task id (or errors, see exit codes):
+
+  ```bash
+  coder task run --host cursor "<task text>"
+  ```
+
+  Fetch the answer with `coder task result <task-id> --wait` - it blocks until the task finishes, then prints only the final result (keeps your context clean). Run it in a **background terminal** so it does not block you; if you can't, poll `coder task result <task-id>` (no `--wait`) until it is done. Or skip the two steps and block on the run itself with `--wait` on `coder task run`. A `--wait` exits **4** when the task is waiting on a permission approval: relay it to the user, apply their decision with `coder task approve <task-id> <approval-id> [--deny]`, then re-fetch with `coder task result <task-id> --wait` (unanswered approvals auto-deny after 120s and the task moves on).
+
+- Always pass `--host cursor` to identify yourself.
+- `coder task run` exits after its startup check. Exit 0: the task started - fetch its result (above). Exit 1: it failed to start / the turn failed - report it, do not retry.
+- Codex startup failures (auth, quota, rate limit) fall back to the next engine in the chain automatically - the runtime reruns the same task on the claude engine via its CLI and still exits 0, so just fetch the result. If it mentions a usage-limit reset time, relay that to the user.
+- Engine, model, and effort come from config; add `--agent` / `--model` / `--effort` when the user asks or it is unambiguous from context (agents: `codex`, `claude`; codex models: `spark`, `luna`, `terra`, `sol`; claude models: `opus`, `sonnet`, `fable`; efforts: `low|medium|high`).
+  - `spark` is only for the very lightest tasks (formatting, renames, quick lookups) - very fast and very cheap. It runs on a separate quota, so reach for it when the others hit a usage limit; it may still run once they are exhausted.
+- Permissions default to auto mode. Pass `--permissions read-only` when the task is read-only; `--permissions workspace-write` to forbid any escalation beyond the project.
+- A background dispatch prints a task id plus its result/steer/stop commands. Relay them and fetch the result (above) rather than polling.
+
+## Controlling tasks
+
+- Continue prior work ("keep going", "apply the top fix"): `coder task steer <task-id> "<follow-up>"`.
+- Inspect: `coder task result <task-id>` (status + answer; add `--wait` to block until done) and `coder task list`. (`coder task stream <task-id>` streams the live progress log - to watch/debug in special cases, generally not for you to consume.)
+- Interrupt: `coder task stop <task-id>`.
+- If status shows `pendingApprovals`, surface them to the user; apply their decision with `coder task approve <task-id> <approval-id> [--deny]`.
+
+## Hard rules
+
+- Forward task text verbatim in `steer` and retries - never rewrite or summarize what the user asked for.
+- Tell every coder, in its task text, to never run git write operations (commit, checkout, stash, reset, rebase, merge, push, etc.) and to leave changes uncommitted. The runtime's permission model also enforces this on the engines.
+- Pass the user's constraints (read-only, scoped paths) into each coder's task text, and honor them over your own preferences.