@cr1ms0n/pi-subagent 0.8.5 → 0.8.7

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## Unreleased
+
+## 0.8.7 — 2026-09-14
+
+### Provider-safe tool schemas
+
+- Strip internal TypeBox `~...` metadata from the `subagent` and `subagent_wait` schemas before Pi provider adapters receive them, while retaining the original schemas for local runtime validation.
+
+## 0.8.6 — 2026-09-14
+
+### Pi context management in child profiles
+
+- Keep Pi context-management tools available to child tool allowlists without granting project-file write access, so configured gateway models such as `uwoacrimson/gpt-5.6-luna` and `uwoacrimson/gpt-5.6-sol` can use `contextManagement` from `explore` and `review` profiles.
+
 ## 0.8.5 — 2026-09-10
 
 ### Read-only FFF search tools

package/README.md

@@ -191,11 +191,19 @@ Set a persona's backend in agent frontmatter with `backend: codex`.
 
 ## Profiles
 
-| Profile                      | Tools                           | Writes                               |
-| ---------------------------- | ------------------------------- | ------------------------------------ |
-| `explore` (parallel default) | read/grep/find/ls + safe extras | no                                   |
-| `review`                     | same as explore                 | no                                   |
-| `general`                    | inherited active tools          | yes if tools include bash/edit/write |
+| Profile                      | Tools                                                   | Writes                                      |
+| ---------------------------- | ------------------------------------------------------- | ------------------------------------------- |
+| `explore` (parallel default) | read/grep/find/ls + safe extras + Pi context tools      | no project-file writes                      |
+| `review`                     | same as explore                                         | no project-file writes                      |
+| `general`                    | inherited active tools + Pi context tools               | yes if tools include bash/edit/write        |
+
+For the Pi backend, the context-management tools `new_context`,
+`get_context_remaining`, `history`, and `notes` are retained in child tool
+allowlists when the parent exposes them. They are control-plane tools: they may
+update continuity notes or the remote context window, but cannot modify the
+child checkout or run a shell command. This exception also applies when a task
+supplies a narrower tool list, so Pi's `contextManagement` remains usable for
+configured gateway models.
 
 Parallel write-capable tasks sharing one checkout are rejected unless each uses
 `isolation: "worktree"`, distinct `cwd`, or explicit `allow_shared_writes: true`.

package/docs/ARCHITECTURE.md

@@ -29,7 +29,7 @@
 - `persistence.ts`: versioned active-branch event folding and bounded child transcript metadata.
 - `maintenance.ts`: filesystem GC (session files) and abort-race helpers; kept out of persistence.
 - `usage.ts`: provider-reported root/subagent/combined accounting.
-- `policy.ts` / `schema.ts`: discriminated request validation and safe capability profiles.
+- `policy.ts` / `schema.ts`: discriminated request validation and safe capability profiles. `schema.ts` retains the canonical TypeBox validators and derives provider-safe tool-schema projections; `extension.ts` registers those projections while validating calls with the originals. Pi context-management control-plane tools remain available to child allowlists without granting project-file write access.
 - `config.ts`: defaults ← `~/.pi/subagent.json` ← `PI_SUBAGENT_*` env overrides.
 - `structured.ts`: structured-output contract (dependency-free JSON-Schema subset
   validation, fenced json:result extraction, contract/repair prompts) and

package/docs/SECURITY.md

@@ -8,16 +8,19 @@ and can use tools according to their capability profile.
 
 | Profile | Default tools | Writes? |
 |---------|---------------|---------|
-| `explore` | `read`, `grep`, `find`, `ls` (+ explicit read-only extras) | No |
-| `review` | same as explore | No |
-| `general` | inherited active tools (may include `bash`/`edit`/`write`) | Yes |
+| `explore` | `read`, `grep`, `find`, `ls` (+ safe extras and Pi context tools) | No project-file writes |
+| `review` | same as explore | No project-file writes |
+| `general` | inherited active tools (+ Pi context tools) | Yes if `bash`/`edit`/`write` are active |
 
 Parallel mode defaults to `explore` to avoid concurrent shared writes.
 
 ## Hard rules
 
-1. **Read-only means no `bash`.** `bash` can rewrite the disc and is never part of
-   an explore/review profile.
+1. **Read-only means no project-file mutation.** `bash` can rewrite the disk and is never part of
+   an explore/review profile. Pi context-management tools (`new_context`,
+   `get_context_remaining`, `history`, `notes`) are an explicit control-plane
+   exception: they may update continuity notes/window state but cannot access
+   the project write tools.
 2. **Parallel writers** require `isolation: "worktree"`, distinct `cwd` values,
    or an explicit `allow_shared_writes: true` opt-in.
 3. **Depth is capped** (`maxDepth`, default 2). Nested children at the ceiling do

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cr1ms0n/pi-subagent",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "description": "Community fork of Luke Parke's pi-subagent with explicit model policy and model visibility for Pi",
   "type": "module",
   "license": "MIT",

package/skills/subagent/SKILL.md

@@ -57,11 +57,17 @@ const routeModel = "<exact model from current modelPolicy route>";
 
 ## Profiles
 
-| Profile   | Tools                  | Writes                                      |
-| --------- | ---------------------- | ------------------------------------------- |
-| `explore` | read/search/ls (+safe) | no                                          |
-| `review`  | same as explore        | no                                          |
-| `general` | inherited active tools | yes if tools include bash/edit/write        |
+| Profile   | Tools                                                     | Writes                                      |
+| --------- | --------------------------------------------------------- | ------------------------------------------- |
+| `explore` | read/search/ls (+safe) + Pi context tools                | no project-file writes                      |
+| `review`  | same as explore                                           | no project-file writes                      |
+| `general` | inherited active tools + Pi context tools                | yes if tools include bash/edit/write        |
+
+For Pi children, `new_context`, `get_context_remaining`, `history`, and
+`notes` are control-plane tools. When available in the parent they remain in
+the child allowlist—even if a narrower tool list was requested—so Pi's remote
+`contextManagement` can stay active. 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`.

package/src/extension.ts

@@ -24,11 +24,18 @@ import { abortAsPromise } from "./maintenance.js";
 import { sweepSessionsLifecycle } from "./distill.js";
 import { runTasks } from "./orchestrator.js";
 import { OutputManager } from "./output.js";
-import { parseDepth, parseSpawnPolicy, SPAWNS_ENV_VAR, validateSubagentRequest, type ResolvedTask } from "./policy.js";
+import { CONTEXT_MANAGEMENT_TOOLS, parseDepth, parseSpawnPolicy, SPAWNS_ENV_VAR, validateSubagentRequest, type ResolvedTask } from "./policy.js";
 import type { ChildRunner } from "./runner.js";
 import { ProcessLockManager } from "./process-lock.js";
 import { SessionScopedRunRegistry, snapshotFromLiveRun } from "./registry.js";
-import { SubagentParamsSchema, SubagentWaitParamsSchema, type SubagentParams, type SubagentWaitParams } from "./schema.js";
+import {
+  ProviderSubagentParamsSchema,
+  ProviderSubagentWaitParamsSchema,
+  SubagentParamsSchema,
+  SubagentWaitParamsSchema,
+  type SubagentParams,
+  type SubagentWaitParams,
+} from "./schema.js";
 import { BTW_ENTRY_TYPE, btwLabel, type BtwEntry } from "./btw.js";
 import { Semaphore } from "./semaphore.js";
 import type { RunSnapshot, TaskResult, TaskSpec, UsageStats } from "./types.js";
@@ -563,7 +570,7 @@ async function runSynthesis(
         label: "synthesis",
         profile: "review",
         canWrite: false,
-        tools: ["read"],
+        tools: ["read", ...CONTEXT_MANAGEMENT_TOOLS],
         model: approved.route.model,
         fallbackModels: [...approved.route.fallbackModels],
         thinking: approved.route.thinking ?? "low",
@@ -944,7 +951,7 @@ export default function registerSubagent(pi: ExtensionAPI): void {
     // usable immediately via agent:'name' (execute-time refresh); only the
     // system-prompt advertisement waits for the next session.
     promptGuidelines: guidelines(discoverAgents(process.cwd())),
-    parameters: SubagentParamsSchema,
+    parameters: ProviderSubagentParamsSchema,
     async execute(_id, params: SubagentParams, signal, onUpdate, ctx) {
       // `subagent_wait` delegates here with a synthesized action:"wait" params
       // object, carrying its timeout through this non-schema field so the two
@@ -1507,7 +1514,7 @@ export default function registerSubagent(pi: ExtensionAPI): void {
     label: "Subagent wait",
     description:
       "Block until a background subagent run (async:true) settles, then deliver its output. Equivalent to subagent { action: 'wait', id }. Aborting or timing out leaves the run alive and collectable; use subagent { action: 'cancel' } to stop it.",
-    parameters: SubagentWaitParamsSchema,
+    parameters: ProviderSubagentWaitParamsSchema,
     async execute(id, params: SubagentWaitParams, signal, onUpdate, ctx) {
       return subagentTool.execute(
         id,

package/src/policy.ts

@@ -27,6 +27,19 @@ export const READ_ONLY_TOOLS = new Set([
   "web_search",
   "web_fetch",
 ]);
+/**
+ * Pi context-management tools are control-plane capabilities: they may update
+ * continuity notes or the remote context window, but they cannot modify the
+ * child checkout. Keep them separate from ordinary source-inspection tools so
+ * the read-only profile's exception remains explicit.
+ */
+export const CONTEXT_MANAGEMENT_TOOLS = new Set([
+  "new_context",
+  "get_context_remaining",
+  "history",
+  "notes",
+]);
+const NON_WRITING_TOOLS = new Set([...READ_ONLY_TOOLS, ...CONTEXT_MANAGEMENT_TOOLS]);
 export const KNOWN_WRITE_TOOLS = new Set(["bash", "edit", "write"]);
 /** Backward-compatible export; policy uses fail-closed classification above. */
 export const WRITE_TOOLS = KNOWN_WRITE_TOOLS;
@@ -75,31 +88,41 @@ function resolveTools(
   requested: string[] | undefined,
   availableTools: string[],
   activeTools: string[],
+  backend: BackendName,
 ): { tools?: string[]; canWrite?: boolean; error?: string } {
   const available = new Set(availableTools);
+  const contextTools = backend === "pi"
+    ? [...CONTEXT_MANAGEMENT_TOOLS].filter((tool) => available.has(tool))
+    : [];
+  const nonWritingTools = backend === "pi" ? NON_WRITING_TOOLS : READ_ONLY_TOOLS;
+  // Keep Pi's context-management control plane available to every child when
+  // the parent exposes it, even if the task requested a narrower tool subset.
+  const addContextTools = (tools: readonly string[]): string[] =>
+    [...new Set([...tools, ...contextTools])];
+
   if (requested) {
     const unknown = requested.filter((tool) => !available.has(tool));
     if (unknown.length) return { error: `Unknown or unavailable tools: ${unknown.join(", ")}` };
   }
 
   if (profile === "explore" || profile === "review") {
-    const source = requested ?? [...READ_ONLY_TOOLS].filter((tool) => available.has(tool));
-    const unsafe = source.filter((tool) => !READ_ONLY_TOOLS.has(tool));
+    const source = addContextTools(requested ?? [...nonWritingTools].filter((tool) => available.has(tool)));
+    const unsafe = source.filter((tool) => !nonWritingTools.has(tool));
     if (unsafe.length) {
       return {
         error: `${profile} is strictly read-only. Unclassified or writable tools are not allowed: ${unsafe.join(", ")}`,
       };
     }
-    return { tools: [...new Set(source)], canWrite: false };
+    return { tools: source, canWrite: false };
   }
 
-  const source = requested ?? activeTools;
+  const source = addContextTools(requested ?? activeTools);
   const unknown = source.filter((tool) => !available.has(tool));
   if (unknown.length) return { error: `Active tools are unavailable: ${unknown.join(", ")}` };
-  // General-profile custom tools are conservatively write-capable unless explicitly known read-only.
+  // General-profile custom tools are conservatively write-capable unless explicitly known non-writing.
   return {
-    tools: [...new Set(source)],
-    canWrite: source.some((tool) => KNOWN_WRITE_TOOLS.has(tool) || !READ_ONLY_TOOLS.has(tool)),
+    tools: source,
+    canWrite: source.some((tool) => KNOWN_WRITE_TOOLS.has(tool) || !nonWritingTools.has(tool)),
   };
 }
 
@@ -193,9 +216,13 @@ function normalizeTask(
     }
   }
 
+  const backend: BackendName = item.backend ?? agent?.backend ?? "pi";
+  if (!BACKEND_NAMES.includes(backend)) {
+    return { error: `Task ${index + 1}: unknown backend '${backend}' (expected ${BACKEND_NAMES.join(", ")})` };
+  }
   const profile = item.profile ?? agent?.profile ?? defaultProfile;
   const requestedTools = item.tools ?? agent?.tools;
-  const resolved = resolveTools(profile, requestedTools, parent.availableTools, parent.activeTools ?? parent.availableTools);
+  const resolved = resolveTools(profile, requestedTools, parent.availableTools, parent.activeTools ?? parent.availableTools, backend);
   if (resolved.error || !resolved.tools || resolved.canWrite === undefined) return { error: resolved.error ?? "Tool resolution failed" };
   const cwd = resolvePath(parent.cwd, item.cwd);
   const output = item.output ? resolvePath(cwd, item.output) : undefined;
@@ -216,10 +243,6 @@ function normalizeTask(
 
   // Backend capability gate. Refuse combinations the backend cannot honor
   // rather than silently dropping a budget or a read-only guarantee.
-  const backend: BackendName = item.backend ?? agent?.backend ?? "pi";
-  if (!BACKEND_NAMES.includes(backend)) {
-    return { error: `Task ${index + 1}: unknown backend '${backend}' (expected ${BACKEND_NAMES.join(", ")})` };
-  }
   const capabilities = resolveBackend(backend).capabilities;
   const problems = checkCapabilities(
     {

package/src/schema.ts

@@ -1,5 +1,27 @@
 import { Type, type Static } from "typebox";
 
+/**
+ * Remove TypeBox's internal compositor metadata before a schema crosses into
+ * Pi's provider-facing tool catalog. The original schema is kept intact for
+ * local Value.Check/Value.Errors validation.
+ */
+export function sanitizeProviderSchema<T>(value: T): T {
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeProviderSchema(item)) as T;
+  }
+
+  if (value && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    return Object.fromEntries(
+      Object.entries(record)
+        .filter(([key]) => !key.startsWith("~"))
+        .map(([key, entry]) => [key, sanitizeProviderSchema(entry)] as const),
+    ) as T;
+  }
+
+  return value;
+}
+
 const ThinkingLevel = Type.String({
   minLength: 1,
   maxLength: 64,
@@ -29,8 +51,8 @@ export const TaskFields = {
   system_prompt: Type.Optional(Type.String({ description: "Extra system prompt appended to the child's prompt (does not replace it)." })),
   model: Type.Optional(Type.String({ description: "**REQUIRED for every spawn call (task/tasks).** Exact model id from modelPolicy, in provider/model-id form. Calls without an explicit model are rejected; agent-file model, taskDefaults, and parent-session inheritance are ignored. Management actions (status/wait/cancel/steer/diff/apply/discard) do not need it." })),
   thinking: Type.Optional({ ...ThinkingLevel, description: "Opaque Pi thinking level for the child. Values such as max are passed through unchanged; Pi/model support decides validity. Defaults to agent thinking, profile taskDefaults.thinking, modelPolicy route thinking, then the parent's level." }),
-  tools: Type.Optional(Type.Array(Type.String(), { description: "Optional tool allowlist. explore/review profiles reject write-capable tools." })),
-  profile: Type.Optional({ ...Profile, description: "Capability profile: explore/review are strictly read-only; general inherits the parent's active tools and may write." }),
+  tools: Type.Optional(Type.Array(Type.String(), { description: "Optional tool allowlist. explore/review profiles reject project-writing tools; Pi context-management tools remain available for context continuity." })),
+  profile: Type.Optional({ ...Profile, description: "Capability profile: explore/review cannot write project files but retain Pi context-management tools; general inherits the parent's active tools and may write." }),
   cwd: Type.Optional(Type.String({ description: "Working directory for the child process." })),
   timeout_ms: Type.Optional(Type.Number({ minimum: 1, maximum: 24 * 60 * 60_000, description: "Total budget in milliseconds including queue time. Timed-out runs report which phase timed out." })),
   max_turns: Type.Optional(Type.Number({ minimum: 1, maximum: 500, description: "Budget: at this many turns the child is steered to wrap up and given grace turns for a final answer; ends as 'partial' with output preserved." })),
@@ -152,6 +174,10 @@ export const SubagentWaitParamsSchema = Type.Object(
   },
 );
 
+/** Provider-facing projections without TypeBox's internal `~...` metadata. */
+export const ProviderSubagentParamsSchema = sanitizeProviderSchema(SubagentParamsSchema);
+export const ProviderSubagentWaitParamsSchema = sanitizeProviderSchema(SubagentWaitParamsSchema);
+
 export type SubagentWaitParams = Static<typeof SubagentWaitParamsSchema>;
 
 /** Runtime guard used by tests/docs to assert provider compatibility. */