@cr1ms0n/pi-subagent 0.8.7 → 0.8.8

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.8.8 — 2026-09-16
+
+### Remote Context tools are target-model gated
+
+- Restrict `new_context`, `get_context_remaining`, `history`, and `notes` to Pi children whose target model is an exact `compaction.gatewayContextModels` entry of the operator-owned `pi-openai-toolkit` config while `compaction.contextManagement` is `remote`. The previous 0.8.6 behavior appended these tools to every Pi child whenever the parent exposed them, so a non-allowlisted child could receive context tools simply because the parent session had them.
+- Matching is exact and case-sensitive on the full `provider/model` string; prefixes, bare model ids, and native `openai-codex` identity do not match. Explicit requests for a context tool on a non-eligible target are rejected as unavailable, inherited/default lists are filtered, and retry fallback attempts are re-filtered per attempt so a disallowed fallback cannot inherit them. The internally constructed synthesis child uses the same gate.
+- Missing, unreadable, invalid, or non-`remote` toolkit configuration now fails closed to no context tools. Non-Pi backends, read-only/write classification, and model-policy routing are unchanged. The package reads the existing operator-owned allowlist and does not duplicate it in `~/.pi/subagent.json`.
+
 ## 0.8.7 — 2026-09-14
 
 ### Provider-safe tool schemas

package/README.md

@@ -193,17 +193,30 @@ Set a persona's backend in agent frontmatter with `backend: codex`.
 
 | Profile                      | Tools                                                   | Writes                                      |
 | ---------------------------- | ------------------------------------------------------- | ------------------------------------------- |
-| `explore` (parallel default) | read/grep/find/ls + safe extras + Pi context tools      | no project-file writes                      |
+| `explore` (parallel default) | read/grep/find/ls + safe extras + allowlisted 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        |
+| `general`                    | inherited active tools + allowlisted 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.
+allowlists only when all three hold: the toolkit config at
+`$PI_CODING_AGENT_DIR/extensions/pi-openai-toolkit/config.json` (default:
+`~/.pi/agent/extensions/pi-openai-toolkit/config.json`) has
+`compaction.contextManagement: "remote"`, the child's target model exactly
+equals one `compaction.gatewayContextModels` entry, and the parent exposes the
+tool. Eligibility is exact and case-sensitive on the full `provider/model`
+string — prefixes, bare model ids, and native `openai-codex` identity do not
+match. The package reads that operator-owned list and never duplicates it.
+
+Context tools 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. For an eligible target they are appended even when the task supplies a
+narrower tool list; for every other Pi target they are removed from inherited
+tools, never passed to `--tools`, and an explicit request for one is rejected as
+unavailable. Retry fallback attempts are filtered per attempt, so a disallowed
+fallback cannot inherit them. If the toolkit file is missing, unreadable,
+invalid, or not in Remote Context mode, the effective allowlist is empty (fail
+closed). Non-Pi backends are unchanged.
 
 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

@@ -14,7 +14,14 @@
   PID; transcript joins happen only on message boundaries, not per-chunk ticks.
 - Retry with model fallback lives in `orchestrator.ts` (`isTransientFailure`): queue
   timeouts, stalls, spawn errors, and provider errors re-run the same spec on the next
-  fallback model with accumulated usage; task-quality failures never retry.
+  fallback model with accumulated usage; task-quality failures never retry. Each attempt
+  re-derives its Pi context-tool membership from the attempt's target model via
+  `context-policy.ts`, so an ineligible fallback cannot inherit the primary's tools.
+- `context-policy.ts`: sole reader/parser of the operator-owned `pi-openai-toolkit`
+  Remote Context allowlist (`<Pi agent dir>/extensions/pi-openai-toolkit/config.json`).
+  Exposes the exact `gatewayContextModels` match plus the four context-tool names, and
+  fails closed to an empty allowlist on any missing/unreadable/invalid/non-remote
+  configuration. The toolkit's native `openai-codex` rule is intentionally not mirrored.
 - `context: "fork"` spawns the child with `--fork <parent session file>` so it starts
   from a real branched copy of the parent conversation. Fail-fast when the parent
   session is not persisted; single-task only.
@@ -29,7 +36,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. `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.
+- `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 are granted per target model: `context-policy.ts` reads the operator-owned `pi-openai-toolkit` Remote Context allowlist (`compaction.gatewayContextModels` with `contextManagement: "remote"`), `policy.ts` removes the four context names from every non-eligible Pi child, `orchestrator.ts` re-filters them per fallback attempt, and both fail closed to no context tools when the config is missing or invalid.
 - `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,9 +8,17 @@ and can use tools according to their capability profile.
 
 | Profile | Default tools | Writes? |
 |---------|---------------|---------|
-| `explore` | `read`, `grep`, `find`, `ls` (+ safe extras and Pi context tools) | No project-file writes |
+| `explore` | `read`, `grep`, `find`, `ls` (+ safe extras and allowlisted 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 |
+| `general` | inherited active tools (+ allowlisted Pi context tools) | Yes if `bash`/`edit`/`write` are active |
+
+Pi context tools are allowlisted by **target model**, not by parent session: a
+child receives `new_context`, `get_context_remaining`, `history`, or `notes`
+only when the toolkit config has `compaction.contextManagement: "remote"`, the
+child's target model exactly equals a `compaction.gatewayContextModels` entry,
+and the parent exposes the tool. Missing/unreadable/invalid/disabled toolkit
+configuration yields no context tools. Retry fallback attempts are re-filtered
+per attempt, so a disallowed fallback cannot inherit them.
 
 Parallel mode defaults to `explore` to avoid concurrent shared writes.
 
@@ -19,8 +27,9 @@ Parallel mode defaults to `explore` to avoid concurrent shared writes.
 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.
+   exception, but only for the exact target models allowlisted above: they may
+   update continuity notes/window state but cannot access the project write
+   tools, and they are rejected as unavailable for every other target.
 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.7",
+  "version": "0.8.8",
   "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

@@ -59,15 +59,23 @@ const routeModel = "<exact model from current modelPolicy route>";
 
 | Profile   | Tools                                                     | Writes                                      |
 | --------- | --------------------------------------------------------- | ------------------------------------------- |
-| `explore` | read/search/ls (+safe) + Pi context tools                | no project-file 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 + Pi context tools                | yes if tools include bash/edit/write        |
+| `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. 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.
+`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`.

package/src/agents.ts

@@ -64,7 +64,13 @@ export interface AgentDefinition {
 const MAX_AGENT_FILE_BYTES = 64 * 1024;
 const NAME_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
 
-function agentDir(): string {
+/**
+ * Resolve the Pi agent directory: `$PI_CODING_AGENT_DIR` (with `~` expansion)
+ * else `~/.pi/agent`. Exported so other configuration readers (for example the
+ * Remote Context allowlist in `context-policy.ts`) share one path convention
+ * instead of inventing a second one.
+ */
+export function piAgentDir(): string {
   const envDir = process.env.PI_CODING_AGENT_DIR?.trim();
   if (envDir) {
     return envDir.startsWith("~") ? path.join(os.homedir(), envDir.slice(1)) : envDir;
@@ -76,7 +82,7 @@ export function discoveryRoots(cwd: string): Array<{ dir: string; scope: AgentDe
   return [
     { dir: path.join(cwd, ".pi", "agents"), scope: "project" },
     { dir: path.join(cwd, ".agents", "agents"), scope: "shared" },
-    { dir: path.join(agentDir(), "agents"), scope: "global" },
+    { dir: path.join(piAgentDir(), "agents"), scope: "global" },
   ];
 }
 

package/src/context-policy.ts

@@ -0,0 +1,169 @@
+/**
+ * Remote Context eligibility boundary for the four Pi context-management tools.
+ *
+ * `pi-subagent` does not own the Remote Context model list: the operator-owned
+ * `pi-openai-toolkit` configuration owns it. This module reads that file once
+ * per dispatch and fails closed to an empty allowlist whenever the file is
+ * missing, unreadable, malformed, or not in `contextManagement: "remote"` mode.
+ *
+ * Matching is exact and case-sensitive on the complete `provider/model` string:
+ * entries are never trimmed, prefix-matched, or inferred from a bare model id.
+ * The toolkit's separate native `openai-codex` provider rule is intentionally
+ * not mirrored here — only configured `gatewayContextModels` entries are
+ * eligible, because the boundary is "models outside the allowlist receive no
+ * context-manager tools".
+ *
+ * Nothing in this module writes to stdout: that channel is the child RPC
+ * protocol and the parent TUI.
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { piAgentDir } from "./agents.js";
+
+/**
+ * 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: ReadonlySet<string> = new Set([
+  "new_context",
+  "get_context_remaining",
+  "history",
+  "notes",
+]);
+
+/** Canonical enumeration order when appending context tools to a child allowlist. */
+export const CONTEXT_MANAGEMENT_TOOL_NAMES: readonly string[] = Object.freeze([
+  ...CONTEXT_MANAGEMENT_TOOLS,
+]);
+
+/** Toolkit config path relative to the Pi agent directory. */
+export const TOOLKIT_CONFIG_PATH_PARTS: readonly string[] = Object.freeze([
+  "extensions",
+  "pi-openai-toolkit",
+  "config.json",
+]);
+
+/** Immutable per-dispatch snapshot of the operator-owned Remote Context allowlist. */
+export interface ContextManagementPolicy {
+  /** Exact `provider/model` strings eligible for Remote Context. */
+  readonly gatewayModels: readonly string[];
+}
+
+/** Fail-closed policy used for missing/unreadable/invalid/disabled configuration. */
+export const EMPTY_CONTEXT_MANAGEMENT_POLICY: ContextManagementPolicy = Object.freeze({
+  gatewayModels: Object.freeze([]),
+});
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+/**
+ * Pure parser over the toolkit config JSON.
+ *
+ * Returns the exact gateway model set only when `compaction.contextManagement`
+ * is `"remote"` and every `compaction.gatewayContextModels` entry is a non-empty
+ * string. Any other shape — including a partly malformed list — yields the
+ * empty policy so a compromised/edited file cannot widen the boundary.
+ */
+export function parseContextManagementPolicy(raw: unknown): ContextManagementPolicy {
+  const compaction = asRecord(asRecord(raw)?.compaction);
+  if (!compaction || compaction.contextManagement !== "remote") return EMPTY_CONTEXT_MANAGEMENT_POLICY;
+  const listed = compaction.gatewayContextModels;
+  if (!Array.isArray(listed)) return EMPTY_CONTEXT_MANAGEMENT_POLICY;
+  const gatewayModels: string[] = [];
+  for (const entry of listed) {
+    if (typeof entry !== "string" || entry.trim() === "") return EMPTY_CONTEXT_MANAGEMENT_POLICY;
+    if (!gatewayModels.includes(entry)) gatewayModels.push(entry);
+  }
+  return Object.freeze({ gatewayModels: Object.freeze(gatewayModels) });
+}
+
+/** Default toolkit config path, using the shared Pi agent-directory precedence. */
+export function contextManagementConfigPath(agentDir = piAgentDir()): string {
+  return path.join(agentDir, ...TOOLKIT_CONFIG_PATH_PARTS);
+}
+
+/**
+ * Read one Remote Context snapshot. The injectable path keeps checks offline.
+ * Every failure mode (missing, unreadable, invalid JSON, wrong shape) returns
+ * the empty policy, so an ineligible target never inherits context tools.
+ */
+export async function readContextManagementPolicy(
+  file = contextManagementConfigPath(),
+): Promise<ContextManagementPolicy> {
+  try {
+    return parseContextManagementPolicy(JSON.parse(await fs.readFile(file, "utf8")));
+  } catch {
+    return EMPTY_CONTEXT_MANAGEMENT_POLICY; // fail closed; stdout is the RPC channel
+  }
+}
+
+/** True when `model` exactly equals a configured `gatewayContextModels` entry. */
+export function isGatewayContextModel(
+  policy: ContextManagementPolicy | undefined,
+  model: string | undefined,
+): boolean {
+  if (!policy || !model) return false;
+  return policy.gatewayModels.includes(model);
+}
+
+/**
+ * Context-tool names a target model may receive: the parent-exposed subset,
+ * and only for an exact allowlisted model. Empty for every other target.
+ */
+export function contextToolsForModel(
+  policy: ContextManagementPolicy | undefined,
+  model: string | undefined,
+  parentExposed: readonly string[],
+): string[] {
+  if (!isGatewayContextModel(policy, model)) return [];
+  const exposed = new Set(parentExposed);
+  return CONTEXT_MANAGEMENT_TOOL_NAMES.filter((tool) => exposed.has(tool));
+}
+
+/** Tool list for the internally constructed read-only synthesis child. */
+export function synthesisToolsForModel(
+  policy: ContextManagementPolicy | undefined,
+  model: string | undefined,
+  parentExposed: readonly string[],
+): string[] {
+  return ["read", ...contextToolsForModel(policy, model, parentExposed)];
+}
+
+/**
+ * Re-derive a child tool allowlist for one target model (primary request or a
+ * fallback attempt). Non-context names keep their existing order/deduplication;
+ * all four context names are removed first and re-appended only when the
+ * effective backend is Pi and the attempt model is exactly allowlisted.
+ *
+ * Non-Pi backends are returned unchanged. Absent a dispatch policy, a Pi list
+ * loses every context name (fail closed) — low-level `runTasks` callers that
+ * provide a validated `TaskSpec` but no snapshot cannot reintroduce them. A Pi
+ * task with no explicit list becomes `--no-tools` at the backend boundary
+ * rather than silently falling back to Pi's unrestricted default tool set.
+ */
+export function filterContextToolsForModel(
+  tools: readonly string[] | undefined,
+  options: {
+    backend: string;
+    model?: string;
+    policy?: ContextManagementPolicy;
+    parentExposed?: readonly string[];
+  },
+): string[] | undefined {
+  if (tools === undefined) return options.backend === "pi" ? [] : undefined;
+  if (options.backend !== "pi") return [...tools];
+  const kept = tools.filter((tool) => !CONTEXT_MANAGEMENT_TOOLS.has(tool));
+  return [
+    ...new Set([
+      ...kept,
+      ...contextToolsForModel(options.policy, options.model, options.parentExposed ?? []),
+    ]),
+  ];
+}

package/src/extension.ts

@@ -22,9 +22,15 @@ import {
 import { createGetPiCommand, getLaunchResolution } from "./launch.js";
 import { abortAsPromise } from "./maintenance.js";
 import { sweepSessionsLifecycle } from "./distill.js";
-import { runTasks } from "./orchestrator.js";
+import { runTasksWithContextPolicy } from "./orchestrator.js";
 import { OutputManager } from "./output.js";
-import { CONTEXT_MANAGEMENT_TOOLS, parseDepth, parseSpawnPolicy, SPAWNS_ENV_VAR, validateSubagentRequest, type ResolvedTask } from "./policy.js";
+import {
+  CONTEXT_MANAGEMENT_TOOL_NAMES,
+  readContextManagementPolicy,
+  synthesisToolsForModel,
+  type ContextManagementPolicy,
+} from "./context-policy.js";
+import { 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";
@@ -523,7 +529,13 @@ async function runSynthesis(
   runtime: SessionRuntime,
   instruction: string,
   results: TaskResult[],
-  options: { runId: string; modelPolicy: ModelPolicySnapshot; signal: AbortSignal },
+  options: {
+    runId: string;
+    modelPolicy: ModelPolicySnapshot;
+    contextPolicy: ContextManagementPolicy;
+    parentContextTools: readonly string[];
+    signal: AbortSignal;
+  },
 ): Promise<TaskResult | undefined> {
   const sections = results.map((result, index) => {
     // Typed handoff: validated structured results feed the synthesis child
@@ -570,7 +582,9 @@ async function runSynthesis(
         label: "synthesis",
         profile: "review",
         canWrite: false,
-        tools: ["read", ...CONTEXT_MANAGEMENT_TOOLS],
+        // Same exact target-model gate as ordinary children: a disallowed
+        // synthesis model receives no context-manager tools at all.
+        tools: synthesisToolsForModel(options.contextPolicy, approved.route.model, options.parentContextTools),
         model: approved.route.model,
         fallbackModels: [...approved.route.fallbackModels],
         thinking: approved.route.thinking ?? "low",
@@ -976,12 +990,19 @@ export default function registerSubagent(pi: ExtensionAPI): void {
       // restarting the parent session; no provider catalog or credentials are
       // loaded by this path.
       const dispatchConfig = loadConfig(await readConfigFile());
+      // One Remote Context snapshot per dispatch: the same operator-owned
+      // gateway allowlist gates initial validation, every fallback attempt,
+      // and the internally constructed synthesis child. Missing/invalid/off
+      // toolkit configuration fails closed to an empty allowlist.
+      const contextPolicy = await readContextManagementPolicy();
+      const parentToolNames = pi.getAllTools().map((tool) => tool.name);
+      const parentContextTools = CONTEXT_MANAGEMENT_TOOL_NAMES.filter((tool) => parentToolNames.includes(tool));
       const model = ctx.model;
       const validated = validateSubagentRequest(params, {
         cwd: ctx.cwd,
         model: model ? `${model.provider}/${model.id}` : undefined,
         thinking: pi.getThinkingLevel() as TaskSpec["thinking"],
-        availableTools: pi.getAllTools().map((tool) => tool.name),
+        availableTools: parentToolNames,
         activeTools: pi.getActiveTools(),
         depth: parseDepth(),
         sessionFile: ctx.sessionManager.getSessionFile() ?? undefined,
@@ -993,6 +1014,7 @@ export default function registerSubagent(pi: ExtensionAPI): void {
         agents: agentCatalog(runtime),
         modelPolicy: dispatchConfig.modelPolicy,
         modelPolicyError: dispatchConfig.modelPolicyError,
+        contextPolicy,
       });
       if (!validated.ok) fail(validated.error);
 
@@ -1174,6 +1196,7 @@ export default function registerSubagent(pi: ExtensionAPI): void {
       }
 
       const specs: TaskSpec[] = validated.tasks.map((task: ResolvedTask) => ({
+        backend: task.backend,
         task: task.task,
         label: task.label,
         systemPrompt: task.systemPrompt,
@@ -1262,7 +1285,7 @@ export default function registerSubagent(pi: ExtensionAPI): void {
 
       const work = (async () => {
         try {
-          const result = await runTasks(specs, {
+          const result = await runTasksWithContextPolicy(specs, {
             semaphore: runtime.semaphore,
             getPiCommand: runtime.getPiCommand,
             sessionDir: runtime.config.sessionDir,
@@ -1276,6 +1299,8 @@ export default function registerSubagent(pi: ExtensionAPI): void {
             stallAfterMs: runtime.config.stallAfterMs,
             stallKillAfterMs: runtime.config.stallKillAfterMs,
             maxRetries: runtime.config.maxRetries,
+            contextPolicy,
+            parentContextTools,
             onRunnerCreated: (index, runner) => {
               let runners = runtime.liveRunners.get(runId);
               if (!runners) runtime.liveRunners.set(runId, (runners = new Map()));
@@ -1322,6 +1347,8 @@ export default function registerSubagent(pi: ExtensionAPI): void {
             const synthesized = await runSynthesis(runtime, validated.synthesis, result.results, {
               runId,
               modelPolicy: dispatchConfig.modelPolicy!,
+              contextPolicy,
+              parentContextTools,
               signal: controller.signal,
             });
             if (synthesized) result.results = [synthesized, ...result.results];

package/src/orchestrator.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { defaultConfig } from "./config.js";
+import { filterContextToolsForModel, type ContextManagementPolicy } from "./context-policy.js";
 import { createGetPiCommand } from "./launch.js";
 import type { ProcessLockManager } from "./process-lock.js";
 import { ChildRunner, type GetPiCommand } from "./runner.js";
@@ -30,6 +31,40 @@ export interface OrchestratorDeps {
   maxRetries?: number;
 }
 
+/** Internal-only capability snapshot; deliberately absent from the stable SDK type. */
+interface ContextOrchestratorDeps {
+  /** Remote Context allowlist captured once for the parent dispatch. */
+  contextPolicy?: ContextManagementPolicy;
+  /** Parent-exposed context-manager tool names in canonical order. */
+  parentContextTools?: readonly string[];
+}
+
+type RunTasksOptions = OrchestratorDeps & { signal?: AbortSignal };
+type InternalRunTasksOptions = RunTasksOptions & ContextOrchestratorDeps;
+
+/** Internal projection used by the stable public entry and offline checks. */
+export function stripContextOrchestratorOptions(options: RunTasksOptions): InternalRunTasksOptions {
+  return {
+    ...options,
+    contextPolicy: undefined,
+    parentContextTools: undefined,
+  };
+}
+
+/** Resolve the actual tool list that one retry attempt will receive. */
+export function toolsForAttempt(
+  spec: Pick<TaskSpec, "backend" | "tools">,
+  model: string | undefined,
+  options: ContextOrchestratorDeps,
+): string[] | undefined {
+  return filterContextToolsForModel(spec.tools, {
+    backend: spec.backend ?? "pi",
+    model,
+    policy: options.contextPolicy,
+    parentExposed: options.parentContextTools,
+  });
+}
+
 /**
  * Transient failures are infrastructure problems, not task problems: the same
  * spec is safe to retry without duplicating side effects because no meaningful
@@ -88,7 +123,29 @@ async function writeArtifact(spec: TaskSpec, result: TaskResult): Promise<void>
 
 export async function runTasks(
   specs: TaskSpec[],
-  options: OrchestratorDeps & { signal?: AbortSignal } = {},
+  options: RunTasksOptions = {},
+): Promise<OrchestratedRun> {
+  // Deliberately erase any runtime-only fields supplied by JavaScript callers
+  // or `as any` casts. Only the extension-only entry below may carry the
+  // operator-owned context snapshot into the attempt loop.
+  return runTasksInternal(specs, stripContextOrchestratorOptions(options));
+}
+
+/**
+ * Extension-only orchestration entry that carries the trusted, per-dispatch
+ * Remote Context snapshot. It is intentionally not re-exported from src/index.ts;
+ * stable SDK callers cannot forge operator-owned context authorization.
+ */
+export async function runTasksWithContextPolicy(
+  specs: TaskSpec[],
+  options: InternalRunTasksOptions,
+): Promise<OrchestratedRun> {
+  return runTasksInternal(specs, options);
+}
+
+async function runTasksInternal(
+  specs: TaskSpec[],
+  options: InternalRunTasksOptions,
 ): Promise<OrchestratedRun> {
   const semaphore = options.semaphore ?? new Semaphore(defaultConfig.maxActiveProcesses, defaultConfig.maxQueuedTasks);
   const worktrees = options.worktrees ?? new WorktreeManager();
@@ -163,7 +220,15 @@ export async function runTasks(
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
       const model = attempt === 1 ? spec.model : (fallbacks[attempt - 2] ?? spec.model);
       if (model) attemptedModels.push(model);
-      const attemptSpec: TaskSpec = { ...spec, model };
+      const attemptSpec: TaskSpec = {
+        ...spec,
+        model,
+        // Retry safety: a fallback model may differ in Remote Context
+        // eligibility, so context tools are re-derived per attempt from the
+        // original validated list. Without a dispatch snapshot this removes
+        // them entirely (fail closed) instead of leaking the primary's.
+        tools: toolsForAttempt(spec, model, options),
+      };
       const runner = new ChildRunner(
         semaphore,
         options.getPiCommand ?? createGetPiCommand(),

package/src/policy.ts

@@ -9,6 +9,13 @@ import { BACKEND_NAMES, checkCapabilities, type BackendName } from "./backend.js
 import { resolveBackend } from "./backends/index.js";
 import { validateModelRequest, type ModelPolicySnapshot } from "./model-policy.js";
 import { isThinkingLevel } from "./thinking.js";
+import {
+  CONTEXT_MANAGEMENT_TOOLS,
+  EMPTY_CONTEXT_MANAGEMENT_POLICY,
+  contextToolsForModel,
+  isGatewayContextModel,
+  type ContextManagementPolicy,
+} from "./context-policy.js";
 
 export const DEPTH_ENV_VAR = "PI_SUBAGENT_DEPTH";
 export const SPAWNS_ENV_VAR = "PI_SUBAGENT_SPAWNS";
@@ -27,19 +34,8 @@ 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 { 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;
@@ -89,24 +85,43 @@ function resolveTools(
   availableTools: string[],
   activeTools: string[],
   backend: BackendName,
+  contextPolicy: ContextManagementPolicy = EMPTY_CONTEXT_MANAGEMENT_POLICY,
+  targetModel: string | undefined = undefined,
 ): { 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 isPi = backend === "pi";
+  // Remote Context eligibility belongs to the exact target model, never to the
+  // parent session: a parent that exposes context tools is not authorization
+  // for a different child model.
+  const eligible = isPi && isGatewayContextModel(contextPolicy, targetModel);
+  const contextTools = eligible ? contextToolsForModel(contextPolicy, targetModel, availableTools) : [];
+  const nonWritingTools = isPi ? NON_WRITING_TOOLS : READ_ONLY_TOOLS;
+  // A non-eligible Pi target must not see context names at all: not inherited
+  // from the parent's active tools, not in the read-only default set, and not
+  // as a valid explicit request.
+  const availableForTarget = new Set(availableTools);
+  if (isPi && !eligible) {
+    for (const tool of CONTEXT_MANAGEMENT_TOOLS) availableForTarget.delete(tool);
+  }
   const addContextTools = (tools: readonly string[]): string[] =>
     [...new Set([...tools, ...contextTools])];
+  const dropContextTools = (tools: readonly string[]): string[] => {
+    if (!isPi || eligible) return [...tools];
+    return tools.filter((tool) => !CONTEXT_MANAGEMENT_TOOLS.has(tool));
+  };
 
   if (requested) {
-    const unknown = requested.filter((tool) => !available.has(tool));
+    // An explicit context name on a non-eligible target is unavailable, not
+    // silently dropped — the caller gets the existing rejection channel.
+    const unknown = requested.filter((tool) => !availableForTarget.has(tool));
     if (unknown.length) return { error: `Unknown or unavailable tools: ${unknown.join(", ")}` };
   }
 
   if (profile === "explore" || profile === "review") {
-    const source = addContextTools(requested ?? [...nonWritingTools].filter((tool) => available.has(tool)));
+    // Non-writing defaults come from READ_ONLY_TOOLS; context tools are added
+    // back only through the eligibility-gated addContextTools above.
+    const source = addContextTools(
+      requested ?? [...READ_ONLY_TOOLS].filter((tool) => availableForTarget.has(tool)),
+    );
     const unsafe = source.filter((tool) => !nonWritingTools.has(tool));
     if (unsafe.length) {
       return {
@@ -116,8 +131,8 @@ function resolveTools(
     return { tools: source, canWrite: false };
   }
 
-  const source = addContextTools(requested ?? activeTools);
-  const unknown = source.filter((tool) => !available.has(tool));
+  const source = dropContextTools(addContextTools(requested ?? activeTools));
+  const unknown = source.filter((tool) => !availableForTarget.has(tool));
   if (unknown.length) return { error: `Active tools are unavailable: ${unknown.join(", ")}` };
   // General-profile custom tools are conservatively write-capable unless explicitly known non-writing.
   return {
@@ -158,7 +173,7 @@ function normalizeTask(
   index: number,
   parent: ParentContext,
   defaultProfile: TaskProfile,
-  defaults: { timeoutMs?: number; taskDefaults?: TaskDefaultsByProfile; agents?: Map<string, AgentDefinition>; modelPolicy?: ModelPolicySnapshot; modelPolicyError?: string } = {},
+  defaults: { timeoutMs?: number; taskDefaults?: TaskDefaultsByProfile; agents?: Map<string, AgentDefinition>; modelPolicy?: ModelPolicySnapshot; modelPolicyError?: string; contextPolicy?: ContextManagementPolicy } = {},
 ): { task?: ResolvedTask; error?: string } {
   if (!item.task?.trim()) return { error: `Task ${index + 1} must not be blank` };
 
@@ -222,8 +237,20 @@ function normalizeTask(
   }
   const profile = item.profile ?? agent?.profile ?? defaultProfile;
   const requestedTools = item.tools ?? agent?.tools;
-  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 resolved = resolveTools(
+    profile,
+    requestedTools,
+    parent.availableTools,
+    parent.activeTools ?? parent.availableTools,
+    backend,
+    defaults.contextPolicy ?? EMPTY_CONTEXT_MANAGEMENT_POLICY,
+    // The target model is the policy-routed model; the parent's model is not
+    // authorization for a different child.
+    modelRoute.model,
+  );
+  if (resolved.error || !resolved.tools || resolved.canWrite === undefined) {
+    return { error: `Task ${index + 1}: ${resolved.error ?? "Tool resolution failed"}` };
+  }
   const cwd = resolvePath(parent.cwd, item.cwd);
   const output = item.output ? resolvePath(cwd, item.output) : undefined;
   // Non-model fields retain the existing precedence: explicit request > agent
@@ -403,6 +430,8 @@ export function validateSubagentRequest(
     agents?: Map<string, AgentDefinition>;
     modelPolicy?: ModelPolicySnapshot;
     modelPolicyError?: string;
+    /** Remote Context allowlist snapshot; omitted means fail closed (no context tools). */
+    contextPolicy?: ContextManagementPolicy;
   } = {},
 ): ValidationResult {
   const defaults = {
@@ -411,6 +440,7 @@ export function validateSubagentRequest(
     agents: options.agents,
     modelPolicy: options.modelPolicy,
     modelPolicyError: options.modelPolicyError,
+    contextPolicy: options.contextPolicy,
   };
   const depth = parent.depth ?? parseDepth();
   const maxDepth = options.maxDepth ?? defaultConfig.maxDepth;

package/src/schema.ts

@@ -51,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 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." }),
+  tools: Type.Optional(Type.Array(Type.String(), { description: "Optional tool allowlist. explore/review profiles reject project-writing tools. Pi context-management tools are added only when the target model is an exact `compaction.gatewayContextModels` entry of the Remote Context toolkit config and the parent exposes them; requesting one for any other target is rejected as unavailable." })),
+  profile: Type.Optional({ ...Profile, description: "Capability profile: explore/review cannot write project files; Pi context-management tools are retained only for an exact allowlisted Remote Context target and never grant bash/edit/write. 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." })),