@ours.network/fleet-claude-code 0.10.0-nightly.4 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/fleet-claude-code",
-  "version": "0.10.0-nightly.4",
+  "version": "0.10.0",
   "description": "Claude Code plugin for ours-fleet — spawn and oversee fleet agents from inside a session. Bundles the spawn-ours-agent and oversee-agents skills; the ours-fleet CLI (@ours.network/fleet) does the actual work.",
   "license": "FSL-1.1-Apache-2.0",
   "author": "Adapt Framework Solutions Ltd",
@@ -10,25 +10,8 @@
     "url": "git+https://github.com/adapt-toolkit/ours-fleet.git",
     "directory": "integrations/claude-code"
   },
-  "keywords": [
-    "claude",
-    "claude-code",
-    "plugin",
-    "fleet",
-    "agents",
-    "tmux",
-    "spawn",
-    "oversight",
-    "ours"
-  ],
-  "files": [
-    ".claude-plugin",
-    "skills"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=20"
-  }
+  "keywords": ["claude", "claude-code", "plugin", "fleet", "agents", "tmux", "spawn", "oversight", "ours"],
+  "files": [".claude-plugin", "skills"],
+  "publishConfig": { "access": "public" },
+  "engines": { "node": ">=20" }
 }

package/skills/oversee-agents/SKILL.md

@@ -32,26 +32,50 @@ Schedule a repeating check every N minutes using your harness's mechanism
 ward once. Keep the loop armed across restarts — re-arm it right after re-binding
 your identity.
 
-## 3. Each tick: peek and judge
+## 3. One console command is not a liveness verdict
 
-Run `ours-fleet peek <Name>` per ward and classify the console:
+This is the mistake that gets busy agents killed. `peek` and `send` tell you what
+happened to YOUR REQUEST. Only one of their outcomes is evidence that the agent
+is gone. Each tick, run BOTH — they answer different questions:
+
+```sh
+ours-fleet status <Name>     # is the role supervised and alive?
+ours-fleet peek <Name>       # what is on its console right now?
+```
+
+Read the result you actually got:
+
+- **queued** — the session accepted the prompt for '<Name>'; a turn already running is not a failure. → Nothing. Do not resend, and do not read the absence of a reply as a stall — check progress with: ours-fleet peek <Name>
+- **timeout** — '<Name>' did not answer in time; a busy agent looks exactly like this. Check: ours-fleet status <Name> → Treat delivery as UNCERTAIN — the request may already have been acted on, so do not resend it blindly.
+- **rejected** — '<Name>' is running and refused the request. → Fix the request, not the agent. A refusal is proof of life.
+- **control-unavailable** — this says nothing about whether '<Name>' is alive — its control plane did not answer; check: ours-fleet status <Name> → Read the role logs as well. The control plane and the agent are separate things, and one being unreachable is not evidence about the other.
+- **backend** — this is a transport failure, not evidence that '<Name>' is gone; check: ours-fleet status <Name> → Investigate the transport, not the agent.
+- **offline** — '<Name>' is confirmed offline. → This is the ONLY result that justifies a restart on its own: ours-fleet restart <Name> for a permanent role. Read the logs first.
+
+Never translate any other result into "dead". `ours-fleet` prints the same
+liveness note the CLI derived the result from, so quote what it said rather than
+paraphrasing it as "not running".
+
+## 4. Judge the console content
+
+Once you know the role is alive, classify what the console actually shows:
 
 | Console shows | Action |
 |---|---|
 | Permission prompt or trust dialog | Answer only within already-authorized scope. Use `send --key` for tmux or the `/permit` control shown by ACP `attach`. |
 | A question the agent asked its (absent) user | Answer with what you know of the mission: `ours-fleet send <Name> "<answer>"`. |
-| Crashed to a shell prompt / error text | Investigate (`ours-fleet logs <Name>`); for permanent roles `ours-fleet restart <Name>`; report to the owner. |
+| Crashed to a shell prompt / error text | Investigate (`ours-fleet logs <Name>`); restart a permanent role only once `status` confirms it is offline. |
 | Idle with work still assigned | Nudge: `ours-fleet send <Name> "Status? Continue with <task> or declare BLOCKED."` |
-| Actively working / healthy | Nothing. Do not interrupt. |
+| Actively working / healthy | Nothing. Do not interrupt, and do not mistake a long turn for a stall. |
 
-## 4. Escalate when unsure
+## 5. Escalate when unsure
 
 If the resolution would make a decision that is not yours (spending, deleting,
 publishing, changing scope), do NOT press through it — message the owner or
 coordinator over ours messaging (`send_message`) with the session snapshot and your
 recommendation.
 
-## 5. Log
+## 6. Log
 
 Append notable interventions (ward, what was stuck, what you did) to your
 WORKLOG so the history survives restarts.

package/skills/spawn-ours-agent/SKILL.md

@@ -8,42 +8,84 @@ description: Spawn and configure an ours-fleet agent from Claude Code, using a p
 Use the `ours-fleet` CLI to create the role. Do not simulate a subagent inside
 the current conversation.
 
-## 1. Read the installed CLI reference
-
-Run:
+## 1. Read the installed CLI reference — this step is not optional
 
 ```sh
 ours-fleet docs
 ours-fleet doctor
 ```
 
-The installed CLI reference is authoritative for supported harnesses, session
-backends, common permissions, and flags. Stop at a failed required doctor check.
-
-## 2. Resolve the role design
-
-Ask the requester (skip only if they already said):
-
-- **Permanent** — written to `~/fleet.d/<Name>.yaml`, supervised (auto-restart,
-  survives reboot). For roles that should stay.
-- **Temporary** — detached supervisor, auto-cleaned when it exits, gone on
-  reboot. For one-off background work.
-- **Session:** `tmux` (detached interactive TUI) or `acp` (structured session
-  with attach/peek/send control). Both lifetimes support both backends.
-- **Harness:** `claude-code` or `codex`.
-- **Permissions:** prefer common `approval`, `filesystem`, and `unattended`
-  intent from `ours-fleet docs`; use harness-native flags only when requested.
-
-Default to `--harness claude-code --session tmux --approval ask --filesystem
-workspace --unattended deny`. Never grant `bypassPermissions`, unrestricted
-filesystem access, or unattended approval without explicit user authorization.
-
-## 3. Pick a name
+`ours-fleet docs` from the INSTALLED CLI is authoritative for supported
+harnesses, session backends, permissions, and flags. This skill ships with a
+plugin and the CLI is upgraded separately, so where the two differ the installed
+reference wins. Stop at a failed required doctor check.
+
+## 2. Understand the two permission traps before you choose anything
+
+Both traps produce the same symptom: an agent that does less than its briefing
+told it to and reports no error, because the refusal happened inside the harness
+with no console attached to see it.
+
+**Trap 1 — a mode that suppresses the prompt without granting the action.**
+Claude's `dontAsk` hides the permission prompt and still refuses the action. It
+reads like a grant and is not one. This is why neutral `--approval allow` maps
+to `bypassPermissions`, which genuinely permits what the role was authorized to
+do. Nothing else is elevated: `ask` stays on Claude's default mode and `deny`
+maps to `plan`.
+
+**Trap 2 — the unattended capability floor.** A role with no console cannot
+answer a permission request, so the request is refused. `ours-fleet` checks each
+role's resolved permissions against a fixed floor before launch:
+
+- `read-state` — read its briefing, ROUTINES.md, and WORKLOG.md
+- `write-state` — append its WORKLOG and its own state files
+- `messaging` — bind its identity, send and receive ours mail
+- `monitor` — arm and observe its mail monitor
+- `workspace-edit` — edit and test files in its working directory
+- `status-commands` — run the inspection commands its briefing prescribes
+
+`ours-fleet config` and `ours-fleet doctor` report this per role as
+`unattended floor: <Name>`. Under `--unattended deny` a shortfall FAILS doctor,
+because those requests will be denied silently. Under `--unattended wait` it
+warns, because a human can still attach and answer.
+
+What this means in practice, on this harness:
+
+| Neutral intent | Native mode | Meets the floor? |
+| --- | --- | --- |
+| `--approval allow --filesystem workspace` | `bypassPermissions` | yes |
+| `--approval allow --filesystem read-only` | `bypassPermissions` | no — no `write-state`, no `workspace-edit` |
+| `--approval ask` | Claude's default | no — `read-state` only |
+| `--approval deny` | `plan` | no — `read-state` only |
+| `harness_options.permission_mode: dontAsk` | `dontAsk` | no — `read-state`, `status-commands` |
+
+## 3. Choose permissions from the job, not from a default
+
+There is no safe blanket default. Ask what the role has to do and whether the
+user authorizes it, then pick:
+
+- **It must work with nobody watching** (the usual reason to spawn a fleet
+  role): it needs `--approval allow --filesystem workspace`. That is a real
+  grant, so get the user's explicit authorization for it, and confine the role
+  with `--isolation-file` rather than by withholding permissions it needs.
+  Use `--unattended deny` so the role never blocks on an unanswerable request.
+- **A human will attach and answer prompts**: `--approval ask --filesystem
+  workspace --unattended wait`. Doctor warns that the floor is unmet — that
+  warning is correct and expected; the role will block until someone answers.
+- **The user will not authorize `allow`, and nobody will attend it**: say so
+  plainly. That role cannot do its job, and doctor will fail it. Reduce the
+  job or get the authorization; do not paper over it with `dontAsk`.
+
+Never choose `--filesystem unrestricted`, `harness_options.permission_mode:
+bypassPermissions` written directly, or `dontAsk` without the user asking for
+it by name and understanding what it grants.
+
+## 4. Pick a name
 
 `<Name>` must match `[A-Za-z0-9_-]+` (it becomes the role/service name). Check it
 is free: `ours-fleet config` must not list it and `ours-fleet ls` must not show it.
 
-## 4. Co-draft bio and persona
+## 5. Co-draft bio and persona
 
 Draft WITH the requester, iterating until they approve:
 
@@ -55,45 +97,83 @@ Draft WITH the requester, iterating until they approve:
 Write approved text to uniquely named files under `/tmp` without interpolating
 untrusted text into shell commands.
 
-## 5. Spawn
+## 6. Confine the role at creation, not later
+
+`--isolation-file <path>` supplies the role's sandbox policy at creation, so the
+FIRST launch is already confined. A role that only gains `isolation:` on a later
+`up` ran unsandboxed until then. The file holds exactly the `isolation:` mapping
+documented in `ours-fleet docs` and nothing else:
+
+```yaml
+network: deny
+fs:
+  read: [/opt/reference]
+resources:
+  mem: 2G
+```
+
+An invalid file is rejected before anything is created — no config, no state
+directory, no identity reservation. This is the right control for a role that
+needs `--approval allow`: isolation is the outer boundary a permission mode
+cannot cross.
+
+## 7. Spawn
 
-Permanent (announce it to yourself if you are its coordinator):
+Permanent, unattended (announce it to yourself if you are its coordinator):
 
 ```sh
 ours-fleet spawn <Name> \
   --harness claude-code --session <tmux|acp> \
   --mission "<one-line mission>" \
   --bio-file /tmp/spawn-bio.md --persona-file /tmp/spawn-persona.md \
-  --approval ask --filesystem workspace --unattended deny \
+  --approval allow --filesystem workspace --unattended deny \
+  --isolation-file /tmp/spawn-isolation.yaml \
   [--cwd <dir>] [--coordinator <YourRoleName>]
 ```
 
-Temporary:
+Permanent, attended — a human will answer its prompts:
+
+```sh
+ours-fleet spawn <Name> \
+  --harness claude-code --session <tmux|acp> \
+  --mission "<one-line mission>" \
+  --bio-file /tmp/spawn-bio.md --persona-file /tmp/spawn-persona.md \
+  --approval ask --filesystem workspace --unattended wait
+```
+
+Temporary — add `--temp`; it supports both session backends:
 
 ```sh
 ours-fleet spawn --temp <Name> \
   --harness claude-code --session <tmux|acp> \
   --mission "<one-line mission>" \
   --bio-file /tmp/spawn-bio.md --persona-file /tmp/spawn-persona.md \
-  --approval ask --filesystem workspace --unattended deny
+  --approval allow --filesystem workspace --unattended deny
 ```
 
 Pass model, permission, session, and coordinator choices exactly as approved.
 Do not persist secrets in fleet YAML.
 
-## 6. Verify
+## 8. Verify
 
 ```sh
+ours-fleet doctor
 ours-fleet peek <Name> 60
 ours-fleet status <Name>
 ```
 
+Read doctor's `permissions: <Name>` and `unattended floor: <Name>` lines for the
+role you just created. `permissions:` shows the neutral intent and the native
+settings it translated to; the floor line lists what the role actually grants,
+or names what is missing. A failure there means the role will silently do less
+than its briefing says — fix the permissions rather than starting it.
+
 For ACP, `status` must report `backend: acp`, `alive: true`, and a running/idle
 readiness. For tmux, the pane is authoritative. Confirm the role loaded its
 briefing and reached identity binding. Never answer a permission prompt beyond
 the scope already approved by the user.
 
-## 7. Arm oversight
+## 9. Arm oversight
 
 The spawner babysits its subagent. Ask the requester for a check interval
 (default **5m**), then follow the **oversee-agents** skill for `<Name>` at that