@mlx-node/agent 0.0.12 → 0.0.15

package/src/catalog.ts

@@ -0,0 +1,194 @@
+/**
+ * Curated model catalog for `mlx agent`.
+ *
+ * The first-run download wizard offers `visibleCatalog()` and feeds the chosen
+ * entry's `catalogRepo()` to `mlx download model`. Slugs are verified against the Brooooooklyn
+ * HF account — use them verbatim.
+ */
+
+import { QWEN38_DFLASH2 } from '@mlx-node/lm/draft-companion';
+
+export interface CatalogEntry {
+  /** Wizard display name. */
+  label: string;
+  /** HF slug for `mlx download model` on Apple Silicon — the MXFP4 build. */
+  hfRepo: string;
+  /**
+   * HF slug on Linux + NVIDIA CUDA — the NVFP4 build.
+   *
+   * Absent means the entry has no CUDA-specific build and {@link hfRepo}
+   * serves both. Resolve with {@link catalogRepo}, never by reading the field.
+   */
+  hfRepoCuda?: string;
+  /** Approximate download size in GB, for display. */
+  sizeGb: number;
+  /** Optional companion, downloaded separately and never offered as a chat model. */
+  draft?: { label: string; hfRepo: string; sizeGb: number };
+  /** One line for the wizard. */
+  description: string;
+  /** Exactly one entry carries this. */
+  isDefault?: boolean;
+  /**
+   * The repo is not published yet, so no UI may offer it as a download.
+   *
+   * Two consumers honour this: the agent wizard via {@link visibleCatalog},
+   * and the dashboard Models page, which filters `!item.hidden` before
+   * rendering cards (`packages/dashboard/ui/src/pages/models.tsx`).
+   * `catalogWithState()` deliberately keeps hidden entries so the UI, not the
+   * dashboard core, decides.
+   *
+   * Also honoured by the download allowlist: `DownloadManager.start`
+   * (`packages/dashboard/src/download.ts`) refuses a hidden repo up front
+   * rather than allocating a job that fails mid-download with a 401 from
+   * Hugging Face. No UI reaches that path for a hidden entry, but a direct
+   * API call does.
+   */
+  hidden?: boolean;
+}
+
+export const MODEL_CATALOG: readonly CatalogEntry[] = [
+  {
+    label: 'Qwen3.8-27B',
+    hfRepo: 'Brooooooklyn/Qwen3.8-27B-MXFP4-mlx',
+    hfRepoCuda: 'Brooooooklyn/Qwen3.8-27B-NVFP4-mlx',
+    sizeGb: 23.3,
+    description: 'Best tool use — recommended default',
+    isDefault: true,
+    draft: QWEN38_DFLASH2,
+  },
+  {
+    label: 'Qwen-AgentWorld-35B-A3B',
+    hfRepo: 'Brooooooklyn/Qwen-AgentWorld-35B-A3B-mxfp4-mlx',
+    hfRepoCuda: 'Brooooooklyn/Qwen-AgentWorld-35B-A3B-nvfp4-mlx',
+    sizeGb: 23.3,
+    description: 'Agent-tuned MoE, fast decode',
+  },
+  {
+    label: 'Gemma-4-26B-A4B',
+    hfRepo: 'Brooooooklyn/Gemma-4-26B-A4B-Unsloth-MXFP4-mlx',
+    hfRepoCuda: 'Brooooooklyn/Gemma-4-26B-A4B-Unsloth-NVFP4-mlx',
+    sizeGb: 16.2,
+    description: 'MoE, fast decode',
+  },
+  {
+    // Produced + validated locally as mxfp4 (MLP) + mxfp8 (attention) via
+    // `mlx convert --q-recipe nvidia` on gemma-4-12b-it (coherent + tool
+    // calling through `mlx agent`). Provisional slug — the user finalizes it
+    // on HF upload; entry stays hidden until the repo exists.
+    label: 'Gemma-4-12B',
+    hfRepo: 'Brooooooklyn/Gemma-4-12B-IT-mxfp-mlx',
+    sizeGb: 8.6,
+    description: 'Compact (mxfp4 MLP + mxfp8 attention), fits smaller machines',
+    hidden: true,
+  },
+  {
+    // NOT DOWNLOADABLE. This repo does not exist: the slug below is a
+    // placeholder the user has not uploaded to, and Hugging Face answers 401
+    // for it. Nothing may offer it as an install until the upload happens and
+    // `hidden` is dropped — and do not guess a substitute slug, because a
+    // wrong-but-live repo would install the wrong weights silently.
+    //
+    // The only route to this model today is local conversion from NVIDIA's
+    // modelopt checkpoint:
+    //   mlx convert -m nemotron_h \
+    //     -i <nvidia/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-NVFP4> \
+    //     -o <models>/nemotron-3.5-lightning-30b-a3b-nvfp4-mlx
+    // (NVFP4 preserved byte-for-byte; the FP8 Mamba-2 projections are
+    // re-quantized. See docs/cli.md "modelopt NVFP4 ingest".)
+    //
+    // The entry is kept — rather than deleted — so the wizard, the dashboard
+    // catalog state, and `catalogSlug()` recognize a locally converted
+    // checkpoint sitting at the canonical slug.
+    label: 'Nemotron-3.5-Lightning-30B-A3B',
+    hfRepo: 'Brooooooklyn/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-nvfp4-mlx',
+    sizeGb: 23,
+    description: 'Hybrid Mamba-2 + MoE, native MTP, 1M context',
+    hidden: true,
+  },
+];
+
+/** Visible target repos plus their optional companion downloads. */
+export function catalogDownloadRepos(): string[] {
+  return [
+    ...new Set(
+      MODEL_CATALOG.filter((entry) => !entry.hidden).flatMap((entry) =>
+        entry.draft === undefined ? [catalogRepo(entry)] : [catalogRepo(entry), entry.draft.hfRepo],
+      ),
+    ),
+  ];
+}
+
+/**
+ * The repo THIS platform installs for `entry`. Linux is the CUDA preview
+ * target (README "Platform Support"); everything else is Apple Silicon.
+ *
+ * NOT because Metal cannot run NVFP4 — it can. MLX ships the same 234
+ * quantized Metal kernels for `nvfp4` as for `mxfp4`, NAX variants included,
+ * and only `fp8_e4m3` reconstructs BF16 at load. The MSL 4.1 hardware
+ * block-scale format (`metal_fp8_ue8m0_format`) appears nowhere in MLX's Metal
+ * backend, so it constrains neither format here.
+ *
+ * The split is:
+ * - CUDA takes NVFP4 through `CublasQQMM` (`nvfp4` -> `CUDA_R_4F_E2M1`), a
+ *   native path with no MXFP4 equivalent.
+ * - Metal has no such native-path advantage either way, so prefer the format
+ *   that survives quantization better. NVFP4 stores a block scale as `amax/6`
+ *   in E4M3, and real FFN blocks land in its subnormal band;
+ *   `apply_nvfp4_pow2_lift` repairs that for dense SwiGLU FFNs but SKIPS MoE
+ *   experts by design (`NVFP4_LIFT_MOE_MARKERS`, `crates/mlx-core/src/
+ *   convert.rs`), because the norm there also drives the router and the
+ *   shared-expert gate, neither scale-invariant. Two of the three visible
+ *   entries are MoE. MXFP4's E8M0 block scales have no such failure.
+ *
+ * Unmeasured: whether nvfp4 or mxfp4 decodes faster on Metal. The choice above
+ * is made on quantization quality, not throughput.
+ *
+ * Every consumer that turns a catalog entry into a download, a slug, or an
+ * allowlist check must go through here. Reading `entry.hfRepo` directly
+ * installs the macOS build on a CUDA box.
+ */
+export function catalogRepo(entry: CatalogEntry): string {
+  return catalogRepoFor(entry, process.platform);
+}
+
+/**
+ * {@link catalogRepo} with the platform passed in — the pure half.
+ *
+ * Exists so both branches can be asserted without touching `process.platform`.
+ * Mutating that global leaks across test files sharing a worker: it made
+ * `catalogRepo` disagree with a sibling suite's module-level constant and fail
+ * a download allowlist check that has nothing to do with the catalog.
+ */
+export function catalogRepoFor(entry: CatalogEntry, platform: NodeJS.Platform): string {
+  return platform === 'linux' && entry.hfRepoCuda !== undefined ? entry.hfRepoCuda : entry.hfRepo;
+}
+
+/** Catalog entries the wizard offers (hidden entries filtered out). */
+export function visibleCatalog(): CatalogEntry[] {
+  return MODEL_CATALOG.filter((entry) => !entry.hidden);
+}
+
+/**
+ * Cold-tier facts and family registration data, re-exported through this
+ * subpath.
+ *
+ * `@mlx-node/agent/catalog` is a NATIVE-FREE entry point, alongside the
+ * `delegate` client and `models` discovery subpaths:
+ * the package root re-exports `provider/index.ts`, which value-imports
+ * `@mlx-node/core`. The dashboard is a separate viewer process that must never
+ * link the addon (docs/dashboard.md: "no Metal init, instant start"), and
+ * `mlx agent --help` must print without loading weights — so both reach the
+ * cold-tier allowlist, the cache-root canonicalizer, and the family detection
+ * data through here.
+ *
+ * Every module reachable from here must therefore stay free of runtime addon
+ * imports. `packages/agent/__test__/catalog-native-free.test.ts` gates that in a
+ * real subprocess.
+ */
+export { COLD_TIER_RESTORE_FAMILIES, canonicalCacheRoot, coldTierRestoreFamilyList } from './cold-tier.js';
+export {
+  CHAT_FAMILY_IDS,
+  matchFamily,
+  NON_GENERATIVE_FAMILY_IDS,
+  rawModelTypeToCanonical,
+} from '@mlx-node/lm/family-data';

package/src/cold-tier.ts

@@ -0,0 +1,152 @@
+/**
+ * Cold-tier facts shared by the agent (writer), the CLI (help text) and the
+ * dashboard (reader), kept in a NATIVE-FREE leaf module.
+ *
+ * `provider/model-host.ts` value-imports `@mlx-node/lm`, which loads the native
+ * addon; the dashboard is a separate viewer process that must never link it
+ * ("no Metal init, instant start" — docs/dashboard.md), and `mlx agent --help`
+ * must print without loading weights. This module therefore has NO runtime
+ * imports beyond `node:` builtins, and reaches those consumers through the
+ * existing native-free `@mlx-node/agent/catalog` subpath, which re-exports it.
+ * There is deliberately no `./cold-tier` entry in `package.json`: a second
+ * published subpath would be a second thing to keep native-free, and `catalog`
+ * already carries that guarantee.
+ *
+ * Everything here is a single source of truth. Do not copy the family list or
+ * re-implement the root canonicalization at a call site; import them.
+ */
+
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+
+import type { ModelType } from '@mlx-node/lm';
+
+/**
+ * Model families whose paged prefix blocks can be restored from the SSD cold
+ * tier soundly. The single source of truth on the TypeScript side, mirroring
+ * `COLD_RESTORE_FAMILIES` in `crates/mlx-core/src/cold_tier.rs`; the two gate
+ * the same decision from opposite ends, and
+ * `packages/agent/__test__/cold-tier-families.test.ts` asserts they never
+ * drift.
+ *
+ * A family belongs here only when EVERY piece of per-token state its forward
+ * pass carries between turns is reconstructible from the tier — either because
+ * it all lives inside the paged pool, or because the part that does not is
+ * persisted alongside as a cold-tier sidecar and the restore reconciles down to
+ * a boundary that sidecar actually backs:
+ *
+ *  - `qwen3` (dense) sizes its pool over all layers, so the pool holds the
+ *    complete KV for the prefix and needs no sidecar.
+ *  - `gemma4` owns full and sliding attention in distinct paged groups. The
+ *    full-attention chain is authoritative and one grouped sliding sidecar
+ *    restores every sliding group at the same exact boundary, atomically.
+ *  - `muse_glimmer` uses the same hybrid contract for its 13 full-attention
+ *    and 39 sliding-attention layers.
+ *  - `qwen3_5` (dense) sizes its pool over the full-attention layers only, but
+ *    persists its out-of-pool GDN recurrent state (conv + recurrent) as a
+ *    `ColdGroup::GdnState` sidecar, and its `ColdSidecarPolicy` reconciles the
+ *    native restore down to the deepest block-aligned boundary a validated
+ *    sidecar backs (a recurrent state is valid only at its exact prefix length).
+ *  - `qwen3_5_moe` keeps the SAME GDN recurrent state outside the pool — same
+ *    shapes, same dtype, same layer mapping — so it shares the dense family's
+ *    sidecar codec and `ColdSidecarPolicy` verbatim. Its restart-parity gate has
+ *    since been run on `Qwen3.6-35B-A3B-mxfp4-mlx`: the restore reconciled
+ *    onto ladder rung 304 of `[16, 64, 304, 1248]` with `hits=42` and
+ *    `corruptions=0`, and the text matched a no-persist baseline.
+ *  - `lfm2` / `lfm2_moe` keep ShortConv state outside the full-attention pool.
+ *    A `ColdGroup::ConvState` sidecar persists that state at the same exact
+ *    boundary; missing or malformed state reconciles down or restarts at zero.
+ *
+ * Widening this set is a correctness decision, never a perf one, and it is
+ * authorized by exactly one thing: the family's native restart-parity gate
+ * passing on real weights with `hits > 0` and `corruptions == 0`.
+ *
+ * `mlx agent --no-persist-cache` applies to EVERY family in this set, not to
+ * one of them: it is a SINGLE process-wide boolean handed to every load whose
+ * family is on the allowlist (`MlxModelHost.runWithResident` →
+ * `resolveModelPathFn(entry, { persistPagedCache })`). Families off the
+ * allowlist are handed no policy at all — not because the flag spares them, but
+ * because `cold_tier::resolve_persist_cold` refuses to persist them under ANY
+ * setting. The help text says so in exactly one place, built from
+ * {@link coldTierRestoreFamilyList} in `packages/cli/src/commands/agent/index.ts`
+ * and asserted by `packages/cli/__test__/agent-cmd.test.ts`.
+ */
+export const COLD_TIER_RESTORE_FAMILIES: ReadonlySet<string> = new Set<ModelType>([
+  'qwen3',
+  'qwen3_5',
+  'qwen3_5_moe',
+  'gemma4',
+  'muse_glimmer',
+  'lfm2',
+  'lfm2_moe',
+]);
+
+/** Allowlisted families in a stable, human-facing order (help text, API payload). */
+export function coldTierRestoreFamilyList(): string[] {
+  return [...COLD_TIER_RESTORE_FAMILIES].sort();
+}
+
+/**
+ * Expand a leading `~` / `~/…` against the current home directory. A bare `~`
+ * prefix that is part of a longer name (`~cache`) is left alone — only the
+ * shell's own two spellings are expanded.
+ */
+function expandTilde(path: string): string {
+  if (path === '~') return homedir();
+  if (path.startsWith('~/')) return join(homedir(), path.slice(2));
+  return path;
+}
+
+/**
+ * Canonical identity for a cold-cache root, used as the JOIN KEY between the
+ * agent that wrote a trace and the dashboard that reads it back.
+ *
+ * The two live in DIFFERENT PROCESSES resolving the root from their own
+ * environments: the native tier reports `manager.root().display()` (the path as
+ * constructed, never realpath'd) while the dashboard builds its own from
+ * `MLX_COLD_CACHE_DIR` or the `~/.mlx-node` default. On macOS `/tmp` is a
+ * symlink to `/private/tmp`, so two identical-looking spellings canonicalize
+ * differently — a raw string compare is a silent-zero trap, not a loud failure.
+ * Both sides MUST route through this one function.
+ *
+ * Resolution order: expand `~`, make absolute, then `realpath` the DEEPEST
+ * EXISTING ANCESTOR and re-attach every missing segment lexically. A tier that
+ * has never been opened has no root directory — that is the normal state, not
+ * an edge case — and when `MLX_COLD_CACHE_DIR` itself has never been created
+ * the parent is missing too. Stopping after one level returned a wholly
+ * UNcanonicalized path, so under a symlinked ancestor (`/tmp` → `/private/tmp`
+ * on macOS) the reader's key diverged from the writer's and rows from the SAME
+ * cache were reported as "a different cache directory". Only a path with no
+ * resolvable ancestor at all falls back to the lexical absolute form; this is
+ * an identity key, not a security boundary, so it fails OPEN to a stable string
+ * rather than to `undefined`.
+ *
+ * An empty input stays empty: the native struct reports `root: ''` while the
+ * tier is disabled, and that must never be recorded as a real cache identity.
+ */
+export function canonicalCacheRoot(root: string): string {
+  const expanded = expandTilde(root.trim());
+  if (expanded.length === 0) return '';
+  const absolute = resolve(expanded);
+  const missing: string[] = [];
+  let cursor = absolute;
+  for (;;) {
+    try {
+      // `realpathSync.native` (realpath(3)), not Node's JS walk: on a
+      // case-insensitive volume — APFS's default — `~/CacheDir` and `~/cachedir`
+      // name the SAME directory, but `fs.realpathSync` returns whichever spelling
+      // the caller typed. `.native` folds each existing component to its on-disk
+      // spelling, so both env spellings produce one join key.
+      const resolved = realpathSync.native(cursor);
+      return missing.length === 0 ? resolved : join(resolved, ...missing);
+    } catch {
+      const parent = dirname(cursor);
+      // `dirname` is a fixpoint at the filesystem root, which is the loop's
+      // termination condition: nothing above it is left to canonicalize.
+      if (parent === cursor) return absolute;
+      missing.unshift(basename(cursor));
+      cursor = parent;
+    }
+  }
+}

package/src/delegate.ts

@@ -0,0 +1,136 @@
+/** Addon-free client for the desktop's global instruction installation checks. */
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { expandPiAgentDir } from './paths.js';
+
+export const DELEGATION_PROMPT =
+  'Delegate GitHub investigation to `mlx delegate github --caller-approved --repo OWNER/REPO "TASK"`. Approve the bounded task and its tool execution before invoking. Include the PR, issue, or run number. Wait for the final handoff and read it once; do not poll by dumping worker transcripts. Use its findings and evidence for implementation; address specific gaps with a focused follow-up or relevant evidence excerpt. Add `--allow-write` only for GitHub changes already authorized by the user. If delegation fails or reports incomplete work, continue from its handoff.';
+
+/** Absolute paths avoid dependence on each coding agent's shell startup/PATH. */
+export function delegationCommand(path: string): string {
+  if (/[\0\r\n`]/.test(path)) throw new Error('The delegation command path cannot be represented in instructions.');
+  return `'${path.replaceAll("'", "'\\''")}'`;
+}
+
+export function delegationPrompt(path: string): string {
+  return DELEGATION_PROMPT.replace('`mlx delegate', `\`${delegationCommand(path)} delegate`);
+}
+
+export interface LocalInferenceConnection {
+  url: string;
+  token?: string;
+  model: string;
+}
+
+export interface LocalMessage {
+  role: 'user' | 'assistant';
+  content: string;
+}
+
+/** Shared by setup requests and their verdict cache key. Includes thinking and final output. */
+export const INSTALL_CHECK_GENERATION = Object.freeze({
+  reasoning: Object.freeze({ effort: 'medium' as const }),
+  max_output_tokens: 16384,
+  temperature: 0,
+});
+export const INSTALL_CHECK_TIMEOUT_MS = 600_000;
+
+export function expandHome(path: string, home = homedir()): string {
+  return path === '~' ? home : path.startsWith('~/') ? join(home, path.slice(2)) : path;
+}
+
+/** Match the persisted default used by `mlx agent`; never select a cloud provider. */
+export async function preferredLocalModel(home = homedir(), env = process.env): Promise<string | undefined> {
+  try {
+    const dir = env.PI_CODING_AGENT_DIR
+      ? expandPiAgentDir(env.PI_CODING_AGENT_DIR, home)
+      : join(home, '.mlx-node', 'agent');
+    const value = JSON.parse(await readFile(join(dir, 'settings.json'), 'utf8'));
+    if (value.defaultProvider === 'mlx' && typeof value.defaultModel === 'string') {
+      return value.defaultModel.replace(/^mlx\//, '');
+    }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw new Error('Could not read the default local model. Open mlx agent and select a model again.');
+    }
+  }
+  return undefined;
+}
+
+/** Refuse remote endpoints even if a caller accidentally supplies a cloud API URL. */
+export async function localCompletion(
+  connection: LocalInferenceConnection,
+  system: string,
+  messages: LocalMessage[],
+  signal?: AbortSignal,
+  maxTokens: number = INSTALL_CHECK_GENERATION.max_output_tokens,
+): Promise<string> {
+  const url = new URL(connection.url);
+  if (url.protocol !== 'http:' || !['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname)) {
+    throw new Error('Delegation requires a local inference server.');
+  }
+  const controller = new AbortController();
+  const cancel = (): void => controller.abort(signal?.reason);
+  if (signal?.aborted) cancel();
+  else signal?.addEventListener('abort', cancel, { once: true });
+  const timer = setTimeout(
+    () => controller.abort(new Error('The local model request timed out.')),
+    INSTALL_CHECK_TIMEOUT_MS,
+  );
+  try {
+    const headers = {
+      'content-type': 'application/json',
+      ...(connection.token ? { 'x-api-key': connection.token } : {}),
+    };
+    const catalog = await fetch(new URL('/v1/models', url), { headers, signal: controller.signal, redirect: 'error' });
+    if (!catalog.ok) throw new Error('The local model service is unavailable. Restart it and try again.');
+    const models = (await catalog.json()) as { data?: { id: string }[] };
+    if (!models.data?.some((model) => model.id === connection.model)) {
+      throw new Error(
+        'The default model is not available in the running service. Restart the local model service and try again.',
+      );
+    }
+    const response = await fetch(new URL('/v1/responses', url), {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        model: connection.model,
+        instructions: system,
+        input: messages,
+        ...INSTALL_CHECK_GENERATION,
+        max_output_tokens: maxTokens,
+        store: false,
+        stream: false,
+      }),
+      signal: controller.signal,
+      redirect: 'error',
+    });
+    if (!response.ok) throw new Error(`The local model could not complete the request (HTTP ${response.status}).`);
+    const body = (await response.json()) as {
+      status?: string;
+      output_text?: string;
+      incomplete_details?: { reason?: string } | null;
+    };
+    if (body.incomplete_details?.reason === 'max_output_tokens')
+      throw new Error('The local model ran out of output space. Try checking again.');
+    if (body.status !== 'completed')
+      throw new Error('The local model did not complete its answer. Try checking again.');
+    const text = body.output_text?.trim();
+    if (!text) throw new Error('The local model returned no answer. Try checking again.');
+    return text;
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener('abort', cancel);
+  }
+}
+
+export function parseLocalJson(text: string): unknown {
+  return JSON.parse(
+    text
+      .trim()
+      .replace(/^```(?:json)?\s*\n?/, '')
+      .replace(/\n?```$/, ''),
+  );
+}

package/src/extensions/approval-detail.ts

@@ -0,0 +1,57 @@
+/** Longest detail line (in chars) shown in an approval prompt. */
+const DETAIL_MAX_CHARS = 500;
+/** Most detail lines shown before truncation kicks in. */
+const DETAIL_MAX_LINES = 6;
+const TRUNCATION_MARKER = '… [truncated]';
+
+/**
+ * Every character that must be rendered visibly instead of reaching the
+ * terminal: C0 controls except `\n` and `\t`, DEL, and the C1 range
+ * U+0080–U+009F (which contains the raw CSI/OSC/ST bytes U+009B, U+009D
+ * and U+009C). Matched one character at a time — deliberately NOT as
+ * multi-character escape "sequences": the printable bytes inside those
+ * sequences still belong to the approval detail and must remain visible.
+ */
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHAR_RE = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g;
+
+/** Render one control character as visible `\xNN` text (e.g. ESC → `\x1b`). */
+function encodeControlChar(ch: string): string {
+  return `\\x${ch.charCodeAt(0).toString(16).padStart(2, '0')}`;
+}
+
+/**
+ * Sanitize untrusted text before embedding it in an approval prompt.
+ *
+ * Pi's TUI preserves ANSI, so every terminal control byte is encoded rather
+ * than deleted. Printable text is retained verbatim, and the rendered detail
+ * is capped by line and character count with a visible truncation marker.
+ */
+export function sanitizeApprovalDetail(text: string): string {
+  let out = text.replace(CONTROL_CHAR_RE, encodeControlChar);
+  let truncated = false;
+
+  const lines = out.split('\n');
+  if (lines.length > DETAIL_MAX_LINES) {
+    out = lines.slice(0, DETAIL_MAX_LINES).join('\n');
+    truncated = true;
+  }
+  if (out.length > DETAIL_MAX_CHARS) {
+    out = out.slice(0, DETAIL_MAX_CHARS);
+    // Do not leave a lone high surrogate behind after the hard cut.
+    const last = out.charCodeAt(out.length - 1);
+    if (last >= 0xd800 && last <= 0xdbff) {
+      out = out.slice(0, -1);
+    }
+    truncated = true;
+  }
+  if (truncated) {
+    out += ` ${TRUNCATION_MARKER}`;
+  }
+  if (out.trim().length === 0 && text.length > 0) {
+    // Control characters always encode to visible text, so this only fires
+    // for whitespace-only input.
+    return '(unprintable content)';
+  }
+  return out;
+}

package/src/extensions/delegation.ts

@@ -0,0 +1,109 @@
+import type { ExtensionAPI, ExtensionContext, InlineExtension } from '@earendil-works/pi-coding-agent';
+
+export interface DelegateCallerPermissions {
+  source: 'codex';
+  /** Opaque Codex profile/backend when supplied; otherwise just inherited process permissions. */
+  profile: string;
+  networkDisabled: boolean;
+}
+
+/** Child processes stay inside Codex's actual sandbox; this metadata grants no OS access. */
+export function delegateCallerPermissions(env: NodeJS.ProcessEnv = process.env): DelegateCallerPermissions | undefined {
+  if (!env.CODEX_THREAD_ID?.trim()) return undefined;
+  const profile = env.CODEX_PERMISSION_PROFILE?.trim();
+  // Permission metadata is optional in Codex launches. The thread identifies
+  // the caller; subprocesses inherit its real sandbox regardless of these labels.
+  const sandbox = env.CODEX_SANDBOX;
+  return {
+    source: 'codex',
+    profile: profile || (sandbox === 'seatbelt' || sandbox === 'landlock' ? `sandbox:${sandbox}` : 'inherited'),
+    networkDisabled: env.CODEX_SANDBOX_NETWORK_DISABLED === '1',
+  };
+}
+
+const READ_TOOLS = new Set(['read', 'grep', 'find', 'ls']);
+
+/** Only failed tool executions qualify; quoted CI logs in a successful result do not. */
+export function delegationBlocker(text: string): boolean {
+  return /permission denied|operation not permitted|\bEACCES\b|\bEPERM\b|network access was denied|sandbox.*(?:denied|blocked)|(?:HTTP\s+|status(?: code)?[: ]+)(?:401|403)\b|gh auth login|could not resolve host|could not resolve proxy|failed to connect|error connecting to api\.github\.com/i.test(
+    text,
+  );
+}
+
+export function createDelegationExtension(options: { callerApproved?: boolean } = {}): InlineExtension {
+  // Capture before any model/tool code runs. Never consult model-written settings.
+  const caller = delegateCallerPermissions();
+  const explicitlyApproved = options.callerApproved === true || process.env.MLX_AGENT_AUTO_APPROVE === '1';
+  return {
+    name: 'mlx-delegation',
+    factory: (pi: ExtensionAPI) => {
+      let handoff: string | undefined;
+
+      const stop = (reason: string, ctx: ExtensionContext): string => {
+        if (!handoff) {
+          const sessionFile = ctx.sessionManager.getSessionFile();
+          handoff = `Delegation incomplete: ${reason}\nContinue this task in the calling agent. Do not retry with changed permissions or another agent.${sessionFile ? `\nSaved evidence and tool results: ${sessionFile}` : ''}`;
+          pi.appendEntry('mlx-delegate-handoff', { reason, caller, sessionFile });
+          // Print mode otherwise shows only the final assistant message. A deterministic
+          // diagnostic and failure status let the caller recover without another inference.
+          process.stderr.write(`${handoff}\n`);
+          process.exitCode = 1;
+        }
+        ctx.abort();
+        return handoff;
+      };
+
+      pi.on('before_agent_start', (event, ctx) => {
+        handoff = undefined;
+        // A boundary per invocation keeps ordinary history/resumes out of the
+        // delegate estimate. Custom entries are persisted, never model context.
+        pi.appendEntry('mlx-delegate-session', { version: 1, sessionId: ctx.sessionManager.getSessionId() });
+        const permissions = caller
+          ? `Tool execution inherits the calling Codex process's permissions (${caller.profile}).${caller.networkDisabled ? ' The caller disables network access.' : ''} Additional approval must be handled by the calling agent; this worker cannot request escalation.`
+          : explicitlyApproved
+            ? "The caller explicitly approved tool execution for this bounded task. Child processes inherit its OS sandbox, environment and credentials; this does not copy the calling agent's tool approval rules or grant additional access. Stay within the task authorization."
+            : 'No inherited caller permission context is available. Tools requiring approval will stop this task and return a handoff.';
+        return { systemPrompt: `${event.systemPrompt}\n\n${permissions}` };
+      });
+
+      pi.on('tool_call', (event, ctx) => {
+        if (handoff) return { block: true, terminate: true, reason: handoff };
+        if (event.toolName === 'subagent') {
+          return { block: true, terminate: true, reason: stop('This worker cannot create subagents.', ctx) };
+        }
+        if (READ_TOOLS.has(event.toolName)) return undefined;
+        if (!caller && !explicitlyApproved) {
+          return {
+            block: true,
+            terminate: true,
+            reason: stop(
+              `No caller permission context is available to authorize ${event.toolName}. The calling agent can use --caller-approved after approving this bounded task.`,
+              ctx,
+            ),
+          };
+        }
+        if (event.toolName === 'bash') {
+          const input = event.input as { command?: unknown };
+          if (typeof input.command === 'string') {
+            // Preserve failures through pipelines such as `gh ... | head`, and
+            // stop a multi-command script before later output masks a denial.
+            // This changes shell options only; cwd, environment and sandbox remain inherited.
+            input.command = `set -e -o pipefail\n${input.command}`;
+          }
+        }
+        return undefined;
+      });
+
+      pi.on('tool_result', (event, ctx) => {
+        if (!event.isError) return undefined;
+        const text = event.content
+          .filter((part) => part.type === 'text')
+          .map((part) => part.text)
+          .join('\n');
+        if (!delegationBlocker(text)) return undefined;
+        const reason = stop(`${event.toolName} was blocked. ${text.slice(0, 2000)}`, ctx);
+        return { content: [{ type: 'text', text: reason }], isError: true };
+      });
+    },
+  };
+}