@cr1ms0n/pi-subagent 0.8.8 → 0.9.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cr1ms0n/pi-subagent",
-  "version": "0.8.8",
-  "description": "Community fork of Luke Parke's pi-subagent with explicit model policy and model visibility for Pi",
+  "version": "0.9.0",
+  "description": "Community fork of Luke Parke's pi-subagent with Jev model/tool routing and verified Pi child capabilities",
   "type": "module",
   "license": "MIT",
   "author": "Luke Parke",

package/skills/subagent/SKILL.md

@@ -1,121 +1,142 @@
----
-name: subagent
-description: Delegate work to isolated child agents with the subagent tool — model and thinking policy, explore/review/general profiles, parallel fanout with synthesis, worktree isolation and the diff/apply/discard loop, background runs, steering, output_schema, context fork, and backend tradeoffs (pi/codex/claude). Use when delegating exploration or implementation, running tasks in parallel, or when a subagent run needs inspecting, steering, or landing.
----
-
-# Subagent
-
-Delegate research, parallel exploration, and clean-context implementation to child
-agents. Prefer `subagent` over long in-thread digressions when the work benefits
-from isolation, parallelism, or a fresh context.
-
-## When to use
-
-- Map a codebase area without bloating the parent context (`profile: "explore"`).
-- Review a diff read-only (`profile: "review"`).
-- Implement behind a worktree and land via apply (`profile: "general"`, `isolation: "worktree"`).
-- Fan out independent questions, optionally with `synthesis` to fold results.
-- Background long work (`async: true`) and collect later with `wait` / `subagent_wait`.
-
-## Core calls
-
-```ts
-// Examples use placeholders only. Replace these with the exact model selected
-// from the current modelPolicy route; they do not configure a real model.
-const routeModel = "<exact model from current modelPolicy route>";
-
-// Single foreground task (default profile: general)
-{ task: "Find call sites of parseConfig", description: "Map parseConfig", model: routeModel }
-
-// Parallel read-only explorers (default profile for tasks[]: explore)
-{
-  tasks: [
-    { task: "Map auth middleware", description: "Auth flow", model: routeModel },
-    { task: "List env vars in server/", description: "Env inventory", model: routeModel }
-  ],
-  synthesis: "Merge into one prioritized brief"
-}
-
-// Background — notified on completion; wait/status still work
-{ task: "Audit dependency licenses", model: routeModel, async: true }
-{ action: "status", id: "abc123" }
-{ action: "wait", id: "abc123" }           // interruptible; does not cancel
-{ action: "cancel", id: "abc123" }
-// Same wait semantics as a dedicated tool:
-// subagent_wait { id: "abc123", timeout_ms?: number }
-
-// Worktree loop
-{ task: "Implement feature A", model: routeModel, profile: "general", isolation: "worktree" }
-{ action: "diff", id: "abc123", index: 1 }
-{ action: "apply", id: "abc123", index: 1 }
-{ action: "discard", id: "abc123", index: 1 }
-
-// Dry-run validation + resolved plan (no spawn)
-// plan is a dry-run, but every task still needs the policy-routed model.
-{ action: "plan", tasks: [{ task: "…", model: routeModel, isolation: "worktree" }] }
-```
-
-## Profiles
-
-| Profile   | Tools                                                     | Writes                                      |
-| --------- | --------------------------------------------------------- | ------------------------------------------- |
-| `explore` | read/search/ls (+safe) + allowlisted context tools        | no project-file writes                      |
-| `review`  | same as explore                                           | no project-file writes                      |
-| `general` | inherited active tools + allowlisted context tools        | yes if tools include bash/edit/write        |
-
-For Pi children, `new_context`, `get_context_remaining`, `history`, and
-`notes` are control-plane tools. They are kept in the child allowlist only when
-the target model exactly matches a `compaction.gatewayContextModels` entry in
-the Remote Context toolkit config
-(`$PI_CODING_AGENT_DIR/extensions/pi-openai-toolkit/config.json`, default:
-`~/.pi/agent/extensions/pi-openai-toolkit/config.json`, with
-`contextManagement: "remote"`), and only when the parent exposes them. For an
-eligible target they stay even if a narrower tool list was requested; for any
-other Pi target they are dropped from inherited tools, never passed to
-`--tools`, and an explicit request for one is rejected as unavailable. Fallback
-attempts are filtered per attempt. Missing/unreadable/invalid/disabled toolkit
-configuration means no context tools at all. They may update context
-notes/window state, but never grant `bash`, `edit`, or `write` access.
-
-Parallel write-capable tasks sharing one checkout are rejected unless each uses
-`isolation: "worktree"`, a distinct `cwd`, or `allow_shared_writes: true`.
-
-## Backends
-
-`backend: "pi" | "codex" | "claude"` (default `pi`). Unsupported combinations are
-**refused**, not silently degraded:
-
-|                          | pi             | codex                  | claude         |
-| ------------------------ | -------------- | ---------------------- | -------------- |
-| `max_cost`               | yes            | refused (tokens only)  | yes            |
-| read-only profile        | tool allowlist | OS sandbox             | tool allowlist |
-| steering / grace wrap-up | yes            | no                     | no             |
-| `context: "fork"`        | yes            | refused                | yes            |
-| `thinking`               | yes            | no                     | no             |
-| `output_schema`          | yes            | yes                    | yes            |
-
-## Budgets and safety
-
-- Prefer `max_turns`, `max_cost`, and/or `timeout_ms` on long or write-capable runs.
-- `output_schema` asks the child for a fenced `json:result` block (one repair round).
-- `context: "fork"` continues from a fork of the parent session (pi/claude).
-- Do not poll `status` in a tight loop — use `wait` / `subagent_wait`, or let the
-  completion notification arrive for `async: true` runs.
-- Point the user at `/subagents` for the live inspector and `/subagent-cost` for
-  the root / subagent / combined ledger.
-
-## Model policy
-
-Every new task must pass a `model` that exactly matches the current
-`modelPolicy` mapping in `~/.pi/subagent.json`; agent frontmatter,
-`taskDefaults.model`, and parent-session model inheritance are ignored. An
-agent route replaces the default route, and configured fallback order is
-immutable. Omit `fallback_models` to use the route; if supplied, it must match
-exactly. An optional route `thinking` value is an opaque Pi thinking-level
-string; common values include `off`, `minimal`, `low`, `medium`, `high`, `xhigh`,
-and `max`, but model-specific values are passed through unchanged. It is a
-default; explicit task, agent, and profile `taskDefaults.thinking` values
-override it. Management actions do not require model. The extension re-reads
-this policy on each dispatch and injects it into
-the parent prompt. If the policy is missing or invalid, management remains
-available but new spawns and synthesis are rejected.
+---
+name: subagent
+description: Delegate work to isolated child agents with the subagent tool. Jev routes each new dispatch to an execution model and individual tools from the user's configured candidate list; covers explore/review/general profiles, parallel fanout with best-effort synthesis, worktree isolation and the diff/apply/discard loop, background runs, steering, output_schema, context fork, and the Pi-only new-dispatch rule. Use when delegating exploration or implementation, running tasks in parallel, or when a subagent run needs inspecting, steering, or landing.
+---
+
+# Subagent
+
+Delegate research, parallel exploration, and clean-context implementation to child
+agents. Prefer `subagent` over long in-thread digressions when the work benefits
+from isolation, parallelism, or a fresh context.
+
+## When to use
+
+- Map a codebase area without bloating the parent context (`profile: "explore"`).
+- Review a diff read-only (`profile: "review"`).
+- Implement behind a worktree and land via apply (`profile: "general"`, `isolation: "worktree"`).
+- Fan out independent questions, optionally with `synthesis` to fold results.
+- Background long work (`async: true`) and collect later with `wait` / `subagent_wait`.
+
+## Core calls
+
+```ts
+// Omit model and fallback_models. Jev selects the execution model from the
+// user's configured candidate list and the individual tools from the locally
+// permitted catalog. An explicit model/fallback is rejected on new work.
+
+// Single foreground task (default profile: general)
+{ task: "Find call sites of parseConfig", description: "Map parseConfig" }
+
+// Parallel read-only explorers (default profile for tasks[]: explore)
+{
+  tasks: [
+    { task: "Map auth middleware", description: "Auth flow" },
+    { task: "List env vars in server/", description: "Env inventory" }
+  ],
+  synthesis: "Merge into one prioritized brief"
+}
+
+// Background: notified on completion; wait/status still work
+{ task: "Audit dependency licenses", async: true }
+{ action: "status", id: "abc123" }
+{ action: "wait", id: "abc123" }           // interruptible; does not cancel
+{ action: "cancel", id: "abc123" }
+// Same wait semantics as a dedicated tool:
+// subagent_wait { id: "abc123", timeout_ms?: number }
+
+// Worktree loop
+{ task: "Implement feature A", profile: "general", isolation: "worktree" }
+{ action: "diff", id: "abc123", index: 1 }
+{ action: "apply", id: "abc123", index: 1 }
+{ action: "discard", id: "abc123", index: 1 }
+
+// Dry-run validation + resolved plan (no spawn).
+// plan calls Jev and incurs selector fees, then a later dispatch selects again.
+{ action: "plan", tasks: [{ task: "…", isolation: "worktree" }] }
+```
+
+## Profiles
+
+| Profile   | Tools                                                     | Writes                                      |
+| --------- | --------------------------------------------------------- | ------------------------------------------- |
+| `explore` | locally permitted read-only tools + Pi context tools      | no project-file writes                      |
+| `review`  | same as explore                                           | no project-file writes                      |
+| `general` | Jev chooses from the full available locally permitted catalog + Pi context tools | yes if the selected tools include bash/edit/write |
+
+Jev picks individual tool names, not a capability bundle. Candidates come from
+the full available locally permitted catalog, not from agent `tools` defaults and
+not from only the parent's active tools. An explicit `tools` list is a ceiling,
+explore/review stay read-only regardless of the answer, and an empty selection
+never means "all tools".
+
+For Pi children, `new_context`, `get_context_remaining`, `history`, and
+`notes` are added locally when the parent exposes them, so the selector never
+asks about them. They are control-plane tools: they may update context
+notes/window state, but never grant `bash`, `edit`, or `write` access. Route
+metadata reports them as local additions.
+
+The finalized tool subset is passed to the child as Pi's `--tools` allowlist
+(`--no-tools` for a true empty set). Pi 0.86.0 is the verified baseline for
+built-in, extension and late-registered tool enforcement; an unsupported host is
+refused rather than silently weakened.
+
+Parallel write-capable tasks sharing one checkout are rejected unless each uses
+`isolation: "worktree"`, a distinct `cwd`, or `allow_shared_writes: true`.
+
+## Backends
+
+New dispatch is Pi-only. `backend: "codex"` or `backend: "claude"` on new work
+is **refused** before any selector or provider work, including a backend
+inherited from agent frontmatter, and is never silently switched to Pi. Existing
+Codex/Claude runs remain manageable through `status`/`wait`/`cancel`/`steer`/
+`diff`/`apply`/`discard`.
+
+Another provider's execution model is still eligible through Pi when the user
+lists it in their candidate configuration. Unsupported combinations inside the
+Pi path are **refused**, not silently degraded:
+
+|                          | pi             |
+| ------------------------ | -------------- |
+| `max_cost`               | yes (provider-reported execution only; not selector currency) |
+| read-only profile        | tool allowlist |
+| steering / grace wrap-up | yes            |
+| `context: "fork"`        | yes            |
+| `thinking`               | yes            |
+| `output_schema`          | yes            |
+
+## Budgets and safety
+
+- Prefer `max_turns`, `max_cost`, and/or `timeout_ms` on long or write-capable runs.
+  `timeout_ms` is absolute: local preflight, Jev selection, setup, queue and
+  runtime all count against it.
+- `output_schema` asks the child for a fenced `json:result` block (one repair round).
+- `context: "fork"` continues from a fork of the parent session.
+- Do not poll `status` in a tight loop. Use `wait` / `subagent_wait`, or let the
+  completion notification arrive for `async: true` runs.
+- Point the user at `/subagents` for the live inspector and `/subagent-cost` for
+  the root / subagent / routing / combined ledger. Routing cost is reported as
+  unreported (tokens only, no currency).
+
+## Routing
+
+Omit `model` and `fallback_models` on every new call: both are legacy fields,
+and an explicit value is rejected rather than bypassing selection. Jev chooses
+one execution model from the user's dedicated candidate list plus an individual
+include/exclude decision per eligible tool. The local policy then re-validates
+the answer: unknown or unsafe tools cannot launch, explore/review stay read-only,
+and management actions need no routing config or credential.
+
+There are no emergency or fallback models, and low confidence is accepted rather
+than treated as a threshold. A Jev timeout or API failure stops the affected new
+dispatch with an actionable error; existing runs stay queryable and cancellable.
+Transient child failures retry the already selected model and tool set within the
+original deadline, up to `max_retries`; a quality failure never reselects.
+
+An optional candidate `thinking` value is an opaque Pi thinking-level string;
+common values include `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and
+`max`, but model-specific values are passed through unchanged. It is a default:
+explicit task, agent, and profile `taskDefaults.thinking` values override it.
+The extension re-reads `jevRouting` on each dispatch and injects the current
+routing guidance into the parent prompt. If `jevRouting` is missing or invalid,
+or the credential environment variable is unset, management remains available but
+new spawns, `/btw`, plan, resume, fork and synthesis are rejected.