@mlx-node/agent 0.0.7

package/dist/catalog.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Curated model catalog for `mlx agent`.
+ *
+ * The first-run download wizard (Task 8) offers `visibleCatalog()` and
+ * feeds the chosen `hfRepo` to `mlx download model`. Slugs are settled
+ * with the user and verified against the Brooooooklyn HF account —
+ * use them verbatim.
+ */
+export interface CatalogEntry {
+    /** Wizard display name. */
+    label: string;
+    /** HF slug for `mlx download model`. */
+    hfRepo: string;
+    /** Approximate download size in GB, for display. */
+    sizeGb: number;
+    /** One line for the wizard. */
+    description: string;
+    /** Exactly one entry carries this. */
+    isDefault?: boolean;
+    /** Not offered by the wizard (repo not yet published). */
+    hidden?: boolean;
+}
+export declare const MODEL_CATALOG: readonly CatalogEntry[];
+/** Catalog entries the wizard offers (hidden entries filtered out). */
+export declare function visibleCatalog(): CatalogEntry[];
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,eAAO,MAAM,aAAa,EAAE,SAAS,YAAY,EA+BhD,CAAC;AAEF,uEAAuE;AACvE,wBAAgB,cAAc,IAAI,YAAY,EAAE,CAE/C"}

package/dist/catalog.js

@@ -0,0 +1,44 @@
+/**
+ * Curated model catalog for `mlx agent`.
+ *
+ * The first-run download wizard (Task 8) offers `visibleCatalog()` and
+ * feeds the chosen `hfRepo` to `mlx download model`. Slugs are settled
+ * with the user and verified against the Brooooooklyn HF account —
+ * use them verbatim.
+ */
+export const MODEL_CATALOG = [
+    {
+        label: 'Qwen3.6-27B',
+        hfRepo: 'Brooooooklyn/Qwen3.6-27B-NVFP4-mlx',
+        sizeGb: 22.2,
+        description: 'Best tool use — recommended default',
+        isDefault: true,
+    },
+    {
+        label: 'Qwen-AgentWorld-35B',
+        hfRepo: 'Brooooooklyn/Qwen-AgentWorld-35B-A3B-nvfp4-mlx',
+        sizeGb: 22.7,
+        description: 'Agent-tuned MoE, fast decode',
+    },
+    {
+        label: 'Gemma-4-26B-A4B',
+        hfRepo: 'Brooooooklyn/Gemma-4-26B-A4B-NVFP4-mlx',
+        sizeGb: 18.8,
+        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,
+    },
+];
+/** Catalog entries the wizard offers (hidden entries filtered out). */
+export function visibleCatalog() {
+    return MODEL_CATALOG.filter((entry) => !entry.hidden);
+}

package/dist/extensions/approval-detail.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 declare function sanitizeApprovalDetail(text: string): string;
+//# sourceMappingURL=approval-detail.d.ts.map

package/dist/extensions/approval-detail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-detail.d.ts","sourceRoot":"","sources":["../../src/extensions/approval-detail.ts"],"names":[],"mappings":"AAsBA;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA2B3D"}

package/dist/extensions/approval-detail.js

@@ -0,0 +1,53 @@
+/** 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) {
+    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) {
+    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/dist/extensions/permission-gate.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `createPermissionGateExtension` — pi has no permission system of its
+ * own, so this inline extension is the product's v1 safety layer: every
+ * `bash` / `write` / `edit` / delegated `subagent` tool call must be approved before pi
+ * executes it.
+ *
+ * Behavior (settled design):
+ * - Interactive (`ctx.hasUI`): prompt via `ctx.ui.select` with the
+ *   command (bash), file path (write/edit), or delegated task (subagent) as the detail line, passed
+ *   through `sanitizeApprovalDetail` (control-byte encoding + length cap).
+ *   "Always (this session)" allow-lists the tool name in memory for the
+ *   lifetime of this extension instance.
+ * - Non-interactive: allow only when `MLX_AGENT_AUTO_APPROVE=1`,
+ *   otherwise block with a reason naming the env var. Fail closed.
+ *
+ * Import discipline (load-bearing, same as the provider extension): pi
+ * is import-order sensitive to its config env vars, so this module must
+ * not runtime-import `@earendil-works/pi-coding-agent` at module top
+ * level — type-only imports appear here, and the event input is
+ * narrowed defensively by hand instead of via `isToolCallEventType`.
+ */
+import type { InlineExtension } from '@earendil-works/pi-coding-agent';
+/**
+ * Build the `mlx-permission-gate` inline extension. The per-session allow list
+ * lives in the `factory` closure, so every extension load (session start or
+ * `/reload`) starts with a clean slate. The bash-prefix snapshot, by contrast,
+ * lives in THIS outer closure so it PERSISTS across factory reinvocations.
+ */
+export declare function createPermissionGateExtension(): InlineExtension;
+//# sourceMappingURL=permission-gate.d.ts.map

package/dist/extensions/permission-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-gate.d.ts","sourceRoot":"","sources":["../../src/extensions/permission-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,KAAK,EAAkC,eAAe,EAAiB,MAAM,iCAAiC,CAAC;AA4MtH;;;;;GAKG;AACH,wBAAgB,6BAA6B,IAAI,eAAe,CA+G/D"}

package/dist/extensions/permission-gate.js

@@ -0,0 +1,309 @@
+/**
+ * `createPermissionGateExtension` — pi has no permission system of its
+ * own, so this inline extension is the product's v1 safety layer: every
+ * `bash` / `write` / `edit` / delegated `subagent` tool call must be approved before pi
+ * executes it.
+ *
+ * Behavior (settled design):
+ * - Interactive (`ctx.hasUI`): prompt via `ctx.ui.select` with the
+ *   command (bash), file path (write/edit), or delegated task (subagent) as the detail line, passed
+ *   through `sanitizeApprovalDetail` (control-byte encoding + length cap).
+ *   "Always (this session)" allow-lists the tool name in memory for the
+ *   lifetime of this extension instance.
+ * - Non-interactive: allow only when `MLX_AGENT_AUTO_APPROVE=1`,
+ *   otherwise block with a reason naming the env var. Fail closed.
+ *
+ * Import discipline (load-bearing, same as the provider extension): pi
+ * is import-order sensitive to its config env vars, so this module must
+ * not runtime-import `@earendil-works/pi-coding-agent` at module top
+ * level — type-only imports appear here, and the event input is
+ * narrowed defensively by hand instead of via `isToolCallEventType`.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { sanitizeApprovalDetail } from './approval-detail.js';
+import { normalizeSubagentMode } from './subagent.js';
+const GATED_TOOLS = new Set(['bash', 'write', 'edit', 'subagent']);
+const AUTO_APPROVE_ENV = 'MLX_AGENT_AUTO_APPROVE';
+/**
+ * Recompute ONE settings layer's `shellCommandPrefix` the way pi's
+ * `SettingsManager.reload()` does (`tryLoadFromStorage` → `loadFromStorage` +
+ * `withLock`, `dist/core/settings-manager.js`), given the layer's PRIOR value:
+ * - `!active` (untrusted project) → `undefined` (pi's `loadFromStorage` returns
+ *   `{}` for an untrusted project, no error → the layer is CLEARED).
+ * - file ABSENT → `undefined` (`withLock` yields `current=undefined` → `{}`, no
+ *   error → CLEARED).
+ * - file present + parseable object → its RAW `shellCommandPrefix` value if the
+ *   key is present (ANY JSON type — pi does no validation), else `undefined`
+ *   (REPLACE with the new value). Presence, not string-ness, decides: pi's
+ *   merge keys on key-presence, and pi bakes any truthy value's `String(...)`.
+ * - file present but malformed / unreadable / a non-object (pi's
+ *   `migrateSettings` does `"key" in settings`, which throws for a non-object) →
+ *   `tryLoadFromStorage` returns an error → reload RETAINS the prior value.
+ *
+ * The retention branch is what closes the reload under-disclosure: on a FAILED
+ * reload pi keeps baking the prior prefix into BashTool, so the gate must keep
+ * showing it rather than degrade to empty. Whether `prior` is a real prior
+ * snapshot (reload) or a blank `undefined` baseline (a fresh lifecycle, which
+ * builds a NEW `SettingsManager` with boot semantics — bad file → empty, no
+ * retain) is decided by the CALLER (the `session_start` handler, on `reason`);
+ * this per-layer rule is identical either way.
+ */
+function resolveLayerPrefix(prior, path, active) {
+    if (!active) {
+        return undefined; // untrusted project layer → dropped
+    }
+    if (!existsSync(path)) {
+        return undefined; // absent → pi clears the layer
+    }
+    try {
+        const content = readFileSync(path, 'utf-8');
+        if (!content) {
+            // Zero-byte file → pi's `loadFromStorage` short-circuits (`if (!content)
+            // return {}`, no error) → the layer is CLEARED (not retained). `!content`
+            // matches pi's exact truthiness, so whitespace-only (`" "`) is NOT empty:
+            // it reaches JSON.parse, throws, and falls to the retain branch below —
+            // exactly as pi errors and retains for it.
+            return undefined;
+        }
+        const parsed = JSON.parse(content);
+        if (typeof parsed !== 'object' || parsed === null) {
+            // pi's migrateSettings throws on a non-object → reload retains the prior.
+            return prior;
+        }
+        // Presence, NOT string-ness, decides — pi does no type validation and its
+        // key-presence merge treats a present non-string / falsy value as "set".
+        // Return the RAW value (any JSON type) when the key is present, else
+        // `undefined` so the presence-based merge sees this layer as unset.
+        return 'shellCommandPrefix' in parsed ? parsed['shellCommandPrefix'] : undefined;
+    }
+    catch {
+        // Malformed JSON / unreadable (EACCES) → pi retains the prior layer value.
+        return prior;
+    }
+}
+/**
+ * Recompute both settings layers for one context, applying {@link
+ * resolveLayerPrefix} per layer with a DIRECT, lock-free read — deliberately
+ * NOT via pi's `SettingsManager`, whose load takes a proper-lockfile lock
+ * (creating/removing `<file>.lock`) and, under contention or a non-writable
+ * dir, degrades to `{}`. This reader never takes a lock and MIRRORS pi's reload
+ * retention, so it can never show empty where pi is still baking a non-empty
+ * prefix. `prior` carries the last snapshot so the retain branch is faithful.
+ *
+ * `getAgentDir`/`CONFIG_DIR_NAME` are imported at call time (deferred), so this
+ * module keeps its "no pi runtime import before env seeding" discipline; both
+ * are pure (env read lazily inside `getAgentDir`). NEVER throws: a hostile
+ * `ctx.isProjectTrusted` getter or a failed deferred import retains `prior`.
+ *
+ * ACCEPTED RESIDUAL (do NOT try to fix): pi's LOCKED read also retains on lock
+ * CONTENTION, which this lock-free reader cannot detect. So a `/reload` that
+ * simultaneously (i) contends pi's settings lock and (ii) sees the file
+ * concurrently reduced to empty could make pi retain a non-empty prefix while
+ * this reader observes empty and under-discloses. That needs a concurrent
+ * lock-holder emptying the file at the reload instant — an actor with settings
+ * write access who could instead just inject a (disclosed) prefix directly, so
+ * it grants no escalation. Left as an extreme-adversarial residual.
+ */
+async function resolveShellPrefixLayers(prior, ctx) {
+    try {
+        const { getAgentDir, CONFIG_DIR_NAME } = await import('@earendil-works/pi-coding-agent');
+        const trusted = ctx.isProjectTrusted();
+        return {
+            global: resolveLayerPrefix(prior.global, join(getAgentDir(), 'settings.json'), true),
+            project: resolveLayerPrefix(prior.project, join(ctx.cwd, CONFIG_DIR_NAME, 'settings.json'), trusted),
+        };
+    }
+    catch {
+        return prior;
+    }
+}
+/**
+ * Merge the two layers exactly as pi's `deepMergeSettings(global, project)` +
+ * `getShellCommandPrefix()` do, returning the RAW merged value (any JSON type or
+ * `undefined`). pi's `deepMergeSettings` overrides on KEY-PRESENCE: it iterates
+ * `Object.keys(project)` and, for any `shellCommandPrefix` whose value is not
+ * `undefined`, the project value wins — so a present project `""` / `0` /
+ * `false` / `null` overrides the global one, and only an ABSENT project key
+ * (our `undefined`) falls through to global. A `??` merge would be WRONG here:
+ * it would let a present project `null` / `""` / `0` / `false` fall through to
+ * global, disagreeing with pi. Coercion to a string (and the `''` empty default)
+ * happens once at the call site, mirroring `bash.js:213`.
+ */
+function mergedPrefixRaw(layers) {
+    return layers.project !== undefined ? layers.project : layers.global;
+}
+/**
+ * `session_start` reasons that build a FRESH `SettingsManager` (boot semantics:
+ * a bad/malformed file → empty, NEVER a retain). pi's `SettingsManager.reload()`
+ * — reason `'reload'` — is its ONLY retain-on-error path, so ONLY a reload may
+ * inherit the prior snapshot; these fresh lifecycles must restart from a blank
+ * baseline or the gate would show a prior session's prefix that pi won't
+ * execute (over-disclosure). Any unknown/missing reason falls OUTSIDE this set
+ * and therefore retains — over-disclosing a stale prefix is safe; under-
+ * disclosing an executed one is not. Verified against pi 0.80.6 `SessionStartEvent`.
+ */
+const FRESH_SESSION_REASONS = new Set(['startup', 'new', 'resume', 'fork']);
+/**
+ * Derive the human-readable detail line for the approval prompt.
+ * Defensive on purpose: a malformed or missing `event.input` must never
+ * throw — a handler error would fail closed upstream, but the prompt
+ * should still render and let the user decide.
+ */
+function describeToolCall(toolName, event, defaultCwd) {
+    const rawInput = event.input;
+    const input = typeof rawInput === 'object' && rawInput !== null ? rawInput : {};
+    if (toolName === 'bash') {
+        const command = input['command'];
+        return typeof command === 'string' && command.length > 0 ? command : '(unknown command)';
+    }
+    if (toolName === 'subagent') {
+        const agent = typeof input['agent'] === 'string' ? input['agent'] : undefined;
+        const task = typeof input['task'] === 'string' ? input['task'] : undefined;
+        const scope = typeof input['agentScope'] === 'string' ? input['agentScope'] : 'user';
+        const tasks = Array.isArray(input['tasks']) ? input['tasks'] : [];
+        const chainItems = Array.isArray(input['chain']) ? input['chain'] : [];
+        const { mode } = normalizeSubagentMode({ agent, task, tasks, chain: chainItems });
+        const describeItems = (value) => Array.isArray(value)
+            ? value.map((raw, index) => {
+                const item = typeof raw === 'object' && raw !== null ? raw : {};
+                const itemAgent = typeof item['agent'] === 'string' ? item['agent'] : '(unknown agent)';
+                const itemTask = typeof item['task'] === 'string' ? item['task'] : '(unknown task)';
+                const resolvedCwd = typeof item['cwd'] === 'string' ? item['cwd'] : defaultCwd;
+                const cwd = resolvedCwd ? ` [cwd: ${resolvedCwd}]` : '';
+                return `${index + 1}. ${itemAgent}: ${itemTask}${cwd}`;
+            })
+            : [];
+        const items = describeItems(tasks);
+        const chain = describeItems(chainItems);
+        const singleCwd = typeof input['cwd'] === 'string' ? input['cwd'] : defaultCwd;
+        const single = `${agent ?? '(unknown agent)'}: ${task ?? '(unknown task)'}${singleCwd ? ` [cwd: ${singleCwd}]` : ''}`;
+        const summary = mode === 'chain'
+            ? `Chain: ${chain.join(' | ')}`
+            : mode === 'parallel'
+                ? `Queued tasks: ${items.join(' | ')}`
+                : single;
+        return [
+            'Delegated agent sessions may use bash/write/edit without further prompts.',
+            `Execution mode: ${mode}`,
+            `Agent scope: ${scope}`,
+            summary,
+        ].join('\n');
+    }
+    // write/edit: pi's canonical field is `path`; `file_path` is the
+    // compat alias pi's own renderers also accept.
+    const path = typeof input['path'] === 'string' ? input['path'] : input['file_path'];
+    return typeof path === 'string' && path.length > 0 ? path : '(unknown path)';
+}
+/**
+ * Build the `mlx-permission-gate` inline extension. The per-session allow list
+ * lives in the `factory` closure, so every extension load (session start or
+ * `/reload`) starts with a clean slate. The bash-prefix snapshot, by contrast,
+ * lives in THIS outer closure so it PERSISTS across factory reinvocations.
+ */
+export function createPermissionGateExtension() {
+    // Per-layer snapshot of pi's bash `shellCommandPrefix`, recomputed at each
+    // `session_start` — which fires at boot AFTER pi bakes the prefix into
+    // BashTool and again on `/reload` AFTER the rebuild, i.e. the SAME lifecycle
+    // instant pi bakes it. Kept per-layer (not pre-merged) so each reload applies
+    // pi's exact RETENTION rule: a failed layer reload keeps baking the prior
+    // value, so we keep showing it. `snapshotted` tells a real empty snapshot
+    // apart from "no session_start yet" (which falls back to a one-shot on-demand
+    // read). Snapshot-primary is FAITHFUL: it shows exactly what pi baked, even
+    // after an edit-without-reload where an on-demand re-read would drift.
+    //
+    // MUST live here, not in `factory`: pi re-invokes the inline extension factory
+    // on every `/reload` (resource-loader `loadExtensionFactories`) BEFORE
+    // emitting the reload `session_start`. If this state were reset per factory
+    // run, a failed reload (malformed/unreadable file) would `retain` against a
+    // freshly-reset `undefined` and drop pi's still-baked prefix — the exact
+    // under-disclosure the retain rule exists to prevent.
+    let layers = { global: undefined, project: undefined };
+    let snapshotted = false;
+    return {
+        name: 'mlx-permission-gate',
+        factory: (pi) => {
+            const sessionAllowed = new Set();
+            pi.on('session_start', async (event, ctx) => {
+                // Only a /reload (pi's sole retain-on-error path) may inherit the prior
+                // snapshot. A fresh lifecycle (startup/new/resume/fork) builds a NEW
+                // SettingsManager with boot semantics (bad file → empty), so it must
+                // start from a blank baseline or we'd retain a prefix pi won't execute.
+                // Unknown/missing reason → retain (over-disclose is safe; under-disclose
+                // is not); read defensively since a hostile event need not be well-typed.
+                const reason = event.reason;
+                const fresh = typeof reason === 'string' && FRESH_SESSION_REASONS.has(reason);
+                const prior = fresh ? { global: undefined, project: undefined } : layers;
+                layers = await resolveShellPrefixLayers(prior, ctx);
+                snapshotted = true;
+            });
+            pi.on('tool_call', async (event, ctx) => {
+                const toolName = event.toolName;
+                if (typeof toolName !== 'string' || !GATED_TOOLS.has(toolName)) {
+                    return undefined;
+                }
+                if (sessionAllowed.has(toolName)) {
+                    return undefined;
+                }
+                if (!ctx.hasUI) {
+                    if (process.env[AUTO_APPROVE_ENV] === '1') {
+                        return undefined;
+                    }
+                    return {
+                        block: true,
+                        reason: `Blocked ${toolName}: no interactive UI to approve it (set ${AUTO_APPROVE_ENV}=1 to auto-approve)`,
+                    };
+                }
+                // Defense in depth: the detail is model-controlled text and this
+                // title is rendered by a third-party TUI that passes ANSI through.
+                // For bash, prepend pi's effective `shellCommandPrefix` so the prompt
+                // shows the full program pi will execute, not just the model's arg.
+                const command = describeToolCall(toolName, event, ctx.cwd);
+                let detailSource = command;
+                if (toolName === 'bash') {
+                    // Snapshot is primary (faithful to pi's baked value, incl. reload
+                    // retention). Only if a bash approval somehow precedes the first
+                    // session_start do we fall back to a one-shot on-demand read from a
+                    // clean baseline (lock-free, never throws). A snapshotted empty prefix
+                    // is authoritative — it is NOT treated as "missing" — so we never
+                    // re-read over a deliberate empty bake.
+                    //
+                    // Coerce ONCE here, byte-identical to pi's `bash.js:213`
+                    // (`commandPrefix ? \`${commandPrefix}\n${command}\` : command`): the
+                    // `raw ?` truthiness gate mirrors pi (falsy `0`/`""`/`false`/`null`/
+                    // absent → bare command), and `String(raw)` mirrors the template
+                    // coercion pi applies to any truthy value (`123`→`123`, `true`→`true`,
+                    // `{…}`→`[object Object]`, `["a","b"]`→`a,b`). Using `String(raw)`
+                    // rather than a bare `${raw}` keeps this well-typed on `unknown`.
+                    const raw = snapshotted
+                        ? mergedPrefixRaw(layers)
+                        : mergedPrefixRaw(await resolveShellPrefixLayers({ global: undefined, project: undefined }, ctx));
+                    // The `[object Object]` / `a,b` default stringification is DELIBERATE
+                    // here — it is exactly what pi's `${commandPrefix}` template bakes for a
+                    // non-string prefix, and disclosing pi's actual bytes is the whole point.
+                    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+                    detailSource = raw ? `${String(raw)}\n${command}` : command;
+                }
+                const detail = sanitizeApprovalDetail(detailSource);
+                const title = toolName === 'subagent' ? 'Allow delegated subagent tool access?' : `Allow ${toolName}?`;
+                // Bind the dialog to the active agent operation. Pi's selector only
+                // resolves on Ctrl+C/abort when the extension forwards this signal;
+                // otherwise the UI can disappear while this awaited tool_call hook
+                // remains pending and keeps the whole tool batch suspended.
+                const choice = await ctx.ui.select(`${title}\n\n  ${detail}`, ['Yes', 'Always (this session)', 'No'], {
+                    signal: ctx.signal,
+                });
+                if (choice === 'Yes') {
+                    return undefined;
+                }
+                if (choice === 'Always (this session)') {
+                    sessionAllowed.add(toolName);
+                    return undefined;
+                }
+                // 'No', a dismissed dialog (undefined), or anything unexpected:
+                // fail closed.
+                return { block: true, reason: 'Blocked by user' };
+            });
+        },
+    };
+}

package/dist/extensions/subagent.d.ts

@@ -0,0 +1,82 @@
+/**
+ * MLX port of pi's official `examples/extensions/subagent` extension.
+ *
+ * The upstream example starts a fresh pi process per task. MLX instead creates
+ * an in-process `AgentSession` for each task so all delegated sessions reuse
+ * the parent's registered provider and its single `MlxModelHost`. Each task
+ * still has isolated conversation/compaction state and its own cwd/tools:
+ *
+ * - at most four task loops run concurrently; the host serializes inference,
+ * - sessions inherit the parent's current local model/model registry,
+ * - context files and skills load, while extensions/prompts/themes do not,
+ * - the parent permission gate approves delegated tool access once up front.
+ *
+ * Upstream source: @earendil-works/pi-coding-agent 0.80.6,
+ * examples/extensions/subagent (MIT).
+ */
+import type { ExtensionContext, InlineExtension } from '@earendil-works/pi-coding-agent';
+type AgentScope = 'user' | 'project' | 'both';
+type AgentSource = 'builtin' | 'user' | 'project' | 'unknown';
+export type SubagentMode = 'single' | 'parallel' | 'chain';
+export interface SubagentConfig {
+    name: string;
+    description: string;
+    tools?: string[];
+    model?: string;
+    systemPrompt: string;
+    source: Exclude<AgentSource, 'unknown'>;
+    filePath: string;
+}
+export interface InProcessSubagentSession {
+    subscribe(listener: (event: unknown) => void): () => void;
+    prompt(text: string): Promise<void>;
+    abort(): Promise<void>;
+    dispose(): void;
+}
+export interface SubagentSessionCreateOptions {
+    cwd: string;
+    model: NonNullable<ExtensionContext['model']>;
+    modelRegistry: ExtensionContext['modelRegistry'];
+    tools?: string[];
+    systemPrompt: string;
+}
+export interface SubagentExtensionOptions {
+    /** Test/programmatic seam. Production uses pi's in-process SDK. */
+    createSession?: (options: SubagentSessionCreateOptions) => Promise<InProcessSubagentSession>;
+}
+export interface SubagentCompactionSettings {
+    enabled: boolean;
+    reserveTokens: number;
+    keepRecentTokens: number;
+}
+/**
+ * Fit pi's compaction budgets to the model's effective physical context.
+ *
+ * Pi's defaults (16,384 reserved + 20,000 recent) assume a context larger
+ * than some dynamically sized MLX KV pools. Preserve explicitly smaller user
+ * values, but keep the summary reserve at most 25%, retained history at most
+ * 50%, and their combined budget at most 75% of the usable window.
+ */
+export declare function scaleSubagentCompactionSettings(contextWindow: number, current: SubagentCompactionSettings): SubagentCompactionSettings;
+export declare function discoverSubagents(cwd: string, scope: AgentScope): {
+    agents: SubagentConfig[];
+    projectAgentsDir: string | null;
+};
+interface SubagentRequestShape {
+    agent?: string;
+    task?: string;
+    tasks?: unknown[];
+    chain?: unknown[];
+}
+/**
+ * Select the mode with the same precedence used by execution. Permission UI
+ * imports this helper so a stray top-level field can never hide the queued
+ * agents that will actually receive delegated tool access.
+ */
+export declare function normalizeSubagentMode(input: SubagentRequestShape): {
+    mode: SubagentMode;
+    modeCount: number;
+};
+export declare function createSubagentExtension(options?: SubagentExtensionOptions): InlineExtension;
+export {};
+//# sourceMappingURL=subagent.d.ts.map

package/dist/extensions/subagent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent.d.ts","sourceRoot":"","sources":["../../src/extensions/subagent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAQH,OAAO,KAAK,EAAgB,gBAAgB,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAUvG,KAAK,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAC9C,KAAK,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;AAC9D,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,UAAU,GAAG,OAAO,CAAC;AAE3D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAiCD,MAAM,WAAW,wBAAwB;IACvC,SAAS,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAC1D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,4BAA4B;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,WAAW,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9C,aAAa,EAAE,gBAAgB,CAAC,eAAe,CAAC,CAAC;IACjD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,mEAAmE;IACnE,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,4BAA4B,KAAK,OAAO,CAAC,wBAAwB,CAAC,CAAC;CAC9F;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAMD;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAC7C,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,0BAA0B,GAClC,0BAA0B,CAoB5B;AA6GD,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,UAAU,GAChB;IACD,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC,CASA;AAqCD,UAAU,oBAAoB;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,oBAAoB,GAAG;IAClE,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB,CAQA;AAwND,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,wBAA6B,GAAG,eAAe,CAsJ/F"}