@cr1ms0n/pi-subagent 0.8.8 → 0.8.9

package/src/schema.ts

@@ -1,189 +1,189 @@
-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,
-  description: "Opaque Pi thinking level passed through unchanged. Pi/model-specific values such as max are allowed; the active Pi process decides support.",
-});
-
-const OutputMode = Type.Union([Type.Literal("inline"), Type.Literal("file-only")]);
-const Profile = Type.Union([Type.Literal("explore"), Type.Literal("review"), Type.Literal("general")]);
-const Isolation = Type.Union([Type.Literal("shared"), Type.Literal("worktree")]);
-const Backend = Type.Union([Type.Literal("pi"), Type.Literal("codex"), Type.Literal("claude")]);
-const Action = Type.Union([
-  Type.Literal("status"),
-  Type.Literal("wait"),
-  Type.Literal("cancel"),
-  Type.Literal("steer"),
-  Type.Literal("diff"),
-  Type.Literal("apply"),
-  Type.Literal("discard"),
-  Type.Literal("plan"),
-]);
-
-/** Shared optional task configuration fields. */
-export const TaskFields = {
-  backend: Type.Optional({ ...Backend, description: "Agent CLI powering the child. pi (default) supports every feature. codex uses codex exec with an OS-level read-only sandbox, but reports no cost (max_cost is refused) and cannot be steered. claude uses the claude CLI, reports cost, and cannot be steered. Unsupported combinations are refused with an explanation rather than silently ignored." }),
-  agent: Type.Optional(Type.String({ minLength: 1, description: "Named agent to use (from .pi/agents/<name>.md). Supplies persona system prompt and defaults; explicit params still override." })),
-  description: Type.Optional(Type.String({ description: "Short human label (3-5 words) shown in UIs and result indexes." })),
-  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 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." })),
-  max_cost: Type.Optional(Type.Number({ minimum: 0, description: "Soft cost ceiling in dollars; checked after each turn, triggers the same wrap-up flow as max_turns." })),
-  grace_turns: Type.Optional(Type.Number({ minimum: 0, maximum: 20, description: "Wrap-up turns allowed after a budget breach before hard stop. 0 = immediate stop. Default from config (2)." })),
-  fallback_models: Type.Optional(Type.Array(Type.String(), { maxItems: 5, description: "Ordered backup models tried automatically on transient failures (provider error, stall, queue timeout)." })),
-  max_retries: Type.Optional(Type.Number({ minimum: 0, maximum: 5, description: "Extra attempts on transient failures. Defaults to config maxRetries (1). Task-quality failures never retry." })),
-  context: Type.Optional(
-    Type.Union([Type.Literal("fresh"), Type.Literal("fork")], {
-      description: "fork starts the child from a branched copy of the parent conversation (needs a persisted parent session); fresh (default) starts clean. Fork is single-task only.",
-    }),
-  ),
-  output: Type.Optional(Type.String({ description: "File path to write final output." })),
-  output_schema: Type.Optional(
-    Type.Unsafe<Record<string, unknown>>(
-      Type.Object({}, {
-        additionalProperties: true,
-        description: "JSON Schema the child's final result must satisfy. The child ends with a fenced json:result block; validation failures get one steer-based repair round, then end 'partial' with the errors reported.",
-      }),
-    ),
-  ),
-  output_mode: Type.Optional({ ...OutputMode, description: "file-only returns a pointer instead of inline text; use for large reports." }),
-  resume: Type.Optional(Type.String({ description: "Child session id to continue." })),
-  fork_resume: Type.Optional(Type.Boolean({ description: "Fork the resumed session instead of direct resume." })),
-  isolation: Type.Optional({ ...Isolation, description: "worktree runs the task in an isolated git worktree; changed work is preserved on a branch." }),
-  include_wip: Type.Optional(
-    Type.Boolean({ description: "Seed a worktree with the parent checkout's uncommitted changes (staged + unstaged + untracked). Only valid with isolation:'worktree'." }),
-  ),
-  allow_shared_writes: Type.Optional(
-    Type.Boolean({ description: "Unsafe opt-in for parallel writers sharing one checkout." }),
-  ),
-  keep_background: Type.Optional(
-    Type.Boolean({ description: "Keep processes the child backgrounded (e.g. dev servers) alive after a clean exit." }),
-  ),
-} as const;
-
-export const ParallelTaskItem = Type.Object(
-  {
-    task: Type.String({ minLength: 1, description: "Task text for one parallel worker." }),
-    ...TaskFields,
-  },
-  { additionalProperties: false },
-);
-
-/**
- * Provider-facing tool parameters.
- *
- * IMPORTANT: LLM tool APIs (OpenAI-compatible / OpenRouter / Anthropic via many
- * providers) require the top-level parameters schema to be JSON Schema
- * `type: "object"`. A Type.Union serializes as `anyOf` without `type: "object"`,
- * which surfaces as:
- *   Invalid schema for function 'subagent': schema must be a JSON Schema of
- *   'type: "object"', got 'type: "None"'.
- *
- * Mode exclusivity (action vs task vs tasks) is enforced in policy validation,
- * not at the JSON Schema layer.
- */
-export const SubagentParamsSchema = Type.Object(
-  {
-    // Management actions
-    action: Type.Optional({ ...Action, description: "Management action on an existing run: status, wait, cancel, steer (inject guidance into a running child), diff/apply/discard (worktree results). action:\"plan\" dry-runs validation + preflight with task/tasks — no spawn." }),
-    id: Type.Optional(Type.String({ minLength: 1, description: "Run id (or unique prefix) for management actions." })),
-    message: Type.Optional(Type.String({ minLength: 1, description: "Steering message injected into the running child (action: steer)." })),
-    index: Type.Optional(Type.Number({ minimum: 0, description: "Task index within a parallel run for steer/diff/apply/discard. Defaults to the only eligible task." })),
-
-    // Single-task mode
-    task: Type.Optional(Type.String({ minLength: 1, description: "Task to delegate (single mode)." })),
-    ...TaskFields,
-    async: Type.Optional(Type.Boolean({ description: "Run in the background and return a handle immediately." })),
-
-    // Parallel mode
-    tasks: Type.Optional(
-      Type.Array(ParallelTaskItem, {
-        minItems: 1,
-        maxItems: 8,
-        description: "Array of independent tasks for parallel mode. Parallel tasks default to the read-only explore profile; parallel writers need isolation:'worktree'.",
-      }),
-    ),
-    synthesis: Type.Optional(
-      Type.String({
-        minLength: 1,
-        description: "Optional synthesis prompt for parallel mode: after all tasks finish, one read-only child folds their outputs using this instruction and its result is delivered first.",
-      }),
-    ),
-  },
-  {
-    additionalProperties: false,
-    description: "Subagent request: single, parallel, status, wait, or cancel.",
-  },
-);
-
-export type SubagentParams = Static<typeof SubagentParamsSchema>;
-export type ParallelTaskInput = Static<typeof ParallelTaskItem>;
-
-/**
- * Dedicated blocking-wait tool.
- *
- * `subagent` already exposes wait via `action: "wait"`, but collecting a
- * background run is the one management step a model reaches for reflexively
- * mid-flow, and burying it behind an action union costs a discovery step.
- * This mirrors the highest-adoption package in the ecosystem (`pi-subagents`
- * ships `subagent` + `subagent_wait` for the same reason). It is a thin
- * front-end over the identical handler — no second delivery path.
- */
-export const SubagentWaitParamsSchema = Type.Object(
-  {
-    id: Type.String({ minLength: 1, description: "Run id (or unique prefix) of the background run to collect." }),
-    timeout_ms: Type.Optional(
-      Type.Number({
-        minimum: 1,
-        maximum: 24 * 60 * 60_000,
-        description: "Give up waiting after this long and return a still-running notice. The run is NOT cancelled; collect it later with subagent_wait or action:'status'. Omit to wait until the run settles.",
-      }),
-    ),
-  },
-  {
-    additionalProperties: false,
-    description: "Block until a background subagent run settles, then deliver its output.",
-  },
-);
-
-/** 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. */
-export function assertObjectToolSchema(schema: unknown): asserts schema is { type: "object" } {
-  if (!schema || typeof schema !== "object" || (schema as { type?: unknown }).type !== "object") {
-    const type = schema && typeof schema === "object" ? (schema as { type?: unknown }).type : typeof schema;
-    throw new Error(`Tool parameters must be JSON Schema type "object", got ${JSON.stringify(type ?? "None")}`);
-  }
-}
+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,
+  description: "Opaque Pi thinking level passed through unchanged. Pi/model-specific values such as max are allowed; the active Pi process decides support.",
+});
+
+const OutputMode = Type.Union([Type.Literal("inline"), Type.Literal("file-only")]);
+const Profile = Type.Union([Type.Literal("explore"), Type.Literal("review"), Type.Literal("general")]);
+const Isolation = Type.Union([Type.Literal("shared"), Type.Literal("worktree")]);
+const Backend = Type.Union([Type.Literal("pi"), Type.Literal("codex"), Type.Literal("claude")]);
+const Action = Type.Union([
+  Type.Literal("status"),
+  Type.Literal("wait"),
+  Type.Literal("cancel"),
+  Type.Literal("steer"),
+  Type.Literal("diff"),
+  Type.Literal("apply"),
+  Type.Literal("discard"),
+  Type.Literal("plan"),
+]);
+
+/** Shared optional task configuration fields. */
+export const TaskFields = {
+  backend: Type.Optional({ ...Backend, description: "Agent CLI powering the child. pi (default) supports every feature. codex uses codex exec with an OS-level read-only sandbox, but reports no cost (max_cost is refused) and cannot be steered. claude uses the claude CLI, reports cost, and cannot be steered. Unsupported combinations are refused with an explanation rather than silently ignored." }),
+  agent: Type.Optional(Type.String({ minLength: 1, description: "Named agent to use (from .pi/agents/<name>.md). Supplies persona system prompt and defaults; explicit params still override." })),
+  description: Type.Optional(Type.String({ description: "Short human label (3-5 words) shown in UIs and result indexes." })),
+  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." }),
+  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." })),
+  max_cost: Type.Optional(Type.Number({ minimum: 0, description: "Soft cost ceiling in dollars; checked after each turn, triggers the same wrap-up flow as max_turns." })),
+  grace_turns: Type.Optional(Type.Number({ minimum: 0, maximum: 20, description: "Wrap-up turns allowed after a budget breach before hard stop. 0 = immediate stop. Default from config (2)." })),
+  fallback_models: Type.Optional(Type.Array(Type.String(), { maxItems: 5, description: "Ordered backup models tried automatically on transient failures (provider error, stall, queue timeout)." })),
+  max_retries: Type.Optional(Type.Number({ minimum: 0, maximum: 5, description: "Extra attempts on transient failures. Defaults to config maxRetries (1). Task-quality failures never retry." })),
+  context: Type.Optional(
+    Type.Union([Type.Literal("fresh"), Type.Literal("fork")], {
+      description: "fork starts the child from a branched copy of the parent conversation (needs a persisted parent session); fresh (default) starts clean. Fork is single-task only.",
+    }),
+  ),
+  output: Type.Optional(Type.String({ description: "File path to write final output." })),
+  output_schema: Type.Optional(
+    Type.Unsafe<Record<string, unknown>>(
+      Type.Object({}, {
+        additionalProperties: true,
+        description: "JSON Schema the child's final result must satisfy. The child ends with a fenced json:result block; validation failures get one steer-based repair round, then end 'partial' with the errors reported.",
+      }),
+    ),
+  ),
+  output_mode: Type.Optional({ ...OutputMode, description: "file-only returns a pointer instead of inline text; use for large reports." }),
+  resume: Type.Optional(Type.String({ description: "Child session id to continue." })),
+  fork_resume: Type.Optional(Type.Boolean({ description: "Fork the resumed session instead of direct resume." })),
+  isolation: Type.Optional({ ...Isolation, description: "worktree runs the task in an isolated git worktree; changed work is preserved on a branch." }),
+  include_wip: Type.Optional(
+    Type.Boolean({ description: "Seed a worktree with the parent checkout's uncommitted changes (staged + unstaged + untracked). Only valid with isolation:'worktree'." }),
+  ),
+  allow_shared_writes: Type.Optional(
+    Type.Boolean({ description: "Unsafe opt-in for parallel writers sharing one checkout." }),
+  ),
+  keep_background: Type.Optional(
+    Type.Boolean({ description: "Keep processes the child backgrounded (e.g. dev servers) alive after a clean exit." }),
+  ),
+} as const;
+
+export const ParallelTaskItem = Type.Object(
+  {
+    task: Type.String({ minLength: 1, description: "Task text for one parallel worker." }),
+    ...TaskFields,
+  },
+  { additionalProperties: false },
+);
+
+/**
+ * Provider-facing tool parameters.
+ *
+ * IMPORTANT: LLM tool APIs (OpenAI-compatible / OpenRouter / Anthropic via many
+ * providers) require the top-level parameters schema to be JSON Schema
+ * `type: "object"`. A Type.Union serializes as `anyOf` without `type: "object"`,
+ * which surfaces as:
+ *   Invalid schema for function 'subagent': schema must be a JSON Schema of
+ *   'type: "object"', got 'type: "None"'.
+ *
+ * Mode exclusivity (action vs task vs tasks) is enforced in policy validation,
+ * not at the JSON Schema layer.
+ */
+export const SubagentParamsSchema = Type.Object(
+  {
+    // Management actions
+    action: Type.Optional({ ...Action, description: "Management action on an existing run: status, wait, cancel, steer (inject guidance into a running child), diff/apply/discard (worktree results). action:\"plan\" dry-runs validation + preflight with task/tasks — no spawn." }),
+    id: Type.Optional(Type.String({ minLength: 1, description: "Run id (or unique prefix) for management actions." })),
+    message: Type.Optional(Type.String({ minLength: 1, description: "Steering message injected into the running child (action: steer)." })),
+    index: Type.Optional(Type.Number({ minimum: 0, description: "Task index within a parallel run for steer/diff/apply/discard. Defaults to the only eligible task." })),
+
+    // Single-task mode
+    task: Type.Optional(Type.String({ minLength: 1, description: "Task to delegate (single mode)." })),
+    ...TaskFields,
+    async: Type.Optional(Type.Boolean({ description: "Run in the background and return a handle immediately." })),
+
+    // Parallel mode
+    tasks: Type.Optional(
+      Type.Array(ParallelTaskItem, {
+        minItems: 1,
+        maxItems: 8,
+        description: "Array of independent tasks for parallel mode. Parallel tasks default to the read-only explore profile; parallel writers need isolation:'worktree'.",
+      }),
+    ),
+    synthesis: Type.Optional(
+      Type.String({
+        minLength: 1,
+        description: "Optional synthesis prompt for parallel mode: after all tasks finish, one read-only child folds their outputs using this instruction and its result is delivered first.",
+      }),
+    ),
+  },
+  {
+    additionalProperties: false,
+    description: "Subagent request: single, parallel, status, wait, or cancel.",
+  },
+);
+
+export type SubagentParams = Static<typeof SubagentParamsSchema>;
+export type ParallelTaskInput = Static<typeof ParallelTaskItem>;
+
+/**
+ * Dedicated blocking-wait tool.
+ *
+ * `subagent` already exposes wait via `action: "wait"`, but collecting a
+ * background run is the one management step a model reaches for reflexively
+ * mid-flow, and burying it behind an action union costs a discovery step.
+ * This mirrors the highest-adoption package in the ecosystem (`pi-subagents`
+ * ships `subagent` + `subagent_wait` for the same reason). It is a thin
+ * front-end over the identical handler — no second delivery path.
+ */
+export const SubagentWaitParamsSchema = Type.Object(
+  {
+    id: Type.String({ minLength: 1, description: "Run id (or unique prefix) of the background run to collect." }),
+    timeout_ms: Type.Optional(
+      Type.Number({
+        minimum: 1,
+        maximum: 24 * 60 * 60_000,
+        description: "Give up waiting after this long and return a still-running notice. The run is NOT cancelled; collect it later with subagent_wait or action:'status'. Omit to wait until the run settles.",
+      }),
+    ),
+  },
+  {
+    additionalProperties: false,
+    description: "Block until a background subagent run settles, then deliver its output.",
+  },
+);
+
+/** 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. */
+export function assertObjectToolSchema(schema: unknown): asserts schema is { type: "object" } {
+  if (!schema || typeof schema !== "object" || (schema as { type?: unknown }).type !== "object") {
+    const type = schema && typeof schema === "object" ? (schema as { type?: unknown }).type : typeof schema;
+    throw new Error(`Tool parameters must be JSON Schema type "object", got ${JSON.stringify(type ?? "None")}`);
+  }
+}

package/src/context-policy.ts

@@ -1,169 +0,0 @@
-/**
- * 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 ?? []),
-    ]),
-  ];
-}