@aragon-agent/cli 0.5.12 → 0.6.2

package/dist/session/store.js

@@ -0,0 +1,442 @@
+/**
+ * The id-keyed session store behind `aragon exec` (cli-integration-surface
+ * section 3.4 / 4.3).
+ *
+ * ASCII ONLY - `src/session/**` is inside the glyph scanner's scope from this
+ * feature onward (R-3 / AC-25). `session/` was outside the predicate BEFORE this
+ * change too, so adding it is closing a pre-existing hole rather than extending
+ * a guard to new code.
+ *
+ * `persist.ts` KEEPS THE FILE FORMAT; this module owns identity, listing,
+ * retention and mutual exclusion. The two exist separately because the format is
+ * shared with the TUI's `/save` and must not acquire exec-shaped opinions.
+ *
+ * THE DIRECTORY IS SHARED WITH `/save`, AND EVERY LISTING RULE HERE FOLLOWS FROM
+ * THAT (P1-5 / R-16). `resolveSessionPath` puts every bare-name and default
+ * `/save` target in `getSessionsDir()`, so a naive `prune` would delete
+ * conversations a human saved by hand - unrecoverable loss, from a maintenance
+ * command the docs recommend. `list` and `prune` therefore see only files
+ * carrying `meta.id`; `show` and `rm` accept any id, because the user named it.
+ */
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, unlinkSync, writeFileSync, writeSync, } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import process from 'node:process';
+import { getSessionsDir } from '../config/app-paths.js';
+import { loadSession, saveSession } from './persist.js';
+/**
+ * The id is a FILENAME under the user's home directory, and the caller supplying
+ * it is frequently the least trusted input in the pipeline (a branch name, a
+ * ticket id, a webhook field). Rejecting `/`, `\`, `..` and a leading dot is a
+ * SECURITY REQUIREMENT, not tidiness (R-7 / AC-8).
+ *
+ * A leading dot is excluded by the first character class rather than by a
+ * separate check, which is also what keeps `.last.json` unreachable as an id.
+ */
+export const SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+export function isValidSessionId(id) {
+    return SESSION_ID_RE.test(id);
+}
+/**
+ * 10 minutes, matching `UPDATE_LIMITS.lockTtlMs`.
+ *
+ * The TTL is the WORST CASE for a wedge, so a long one is not the safe choice:
+ * without the liveness probe below, a CI job killed mid-run would hold its
+ * `--session-id` for the whole window and every retry would return
+ * `session_busy` - a hang wearing an exit code, in the one environment this
+ * feature exists for.
+ */
+export const SESSION_LOCK_TTL_MS = 600_000;
+/** The `--continue` pointer. A CACHE, with a documented scan fallback (R-9). */
+const POINTER_FILE = '.last.json';
+export function sessionsDir() {
+    return getSessionsDir();
+}
+/**
+ * THE CHOKE POINT. Every string that becomes a session filename passes here.
+ *
+ * `isValidSessionId` is applied HERE rather than only at `--session-id`, because
+ * that flag is not the only way a caller-supplied string reaches this function:
+ * `--resume <id|path>` derives an id from the resumed FILE, `sessions rm` /
+ * `sessions show` take one straight from argv, and a session file can carry any
+ * `meta.id` at all. Guarding each caller instead would mean the boundary holds
+ * only for the callers someone remembered - and `join()` silently normalises
+ * `../..` away, so an escape leaves no trace to notice later. Validating at the
+ * single point that builds the path is what makes R-7 a property of the module
+ * rather than a habit of its callers.
+ *
+ * THROWS rather than coercing to a "safe" name: a caller who asked for one file
+ * and silently got another is a worse failure than a loud one, and every caller
+ * that can be handed untrusted input validates first and reports exit 2 itself.
+ */
+function assertSessionId(id) {
+    if (!isValidSessionId(id)) {
+        throw new Error(`Invalid session id "${id}": expected 1-64 characters matching ` +
+            '[A-Za-z0-9][A-Za-z0-9._-]* (no "/", "\\", ".." or a leading dot).');
+    }
+    return id;
+}
+export function sessionPathFor(id) {
+    return join(getSessionsDir(), `${assertSessionId(id)}.json`);
+}
+/**
+ * The id a RESUMED session writes back under.
+ *
+ * `--resume` accepts `<id|path>`, so the value the caller typed is NOT usable as
+ * an id: `--resume ./sessions/hand-saved.json` would otherwise make the path
+ * itself the id, and every later `sessionPathFor` / lock call would build a
+ * filename out of it - outside the sessions directory whenever the path was
+ * relative. That is the same write primitive `--session-id` is validated to
+ * prevent, arriving through the flag next to it. `meta.id` is no safer: it comes
+ * out of a file, and files are inputs.
+ *
+ * The order is the one that keeps every legitimate resume landing where the user
+ * expects: an exec-written session names itself, a TUI `/save` is named by its
+ * file, and anything else gets a fresh id rather than a guess - reported back in
+ * `system.init.sessionId` and `result.sessionId`, so the caller is never left
+ * wondering which session it just wrote.
+ */
+export function resumedSessionId(path, saved) {
+    const declared = saved.meta?.id;
+    if (typeof declared === 'string' && isValidSessionId(declared))
+        return declared;
+    const base = basenameId(path);
+    if (isValidSessionId(base))
+        return base;
+    return randomUUID();
+}
+function ensureDir() {
+    const dir = getSessionsDir();
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    return dir;
+}
+// ---------------------------------------------------------------------------
+// Read / write
+// ---------------------------------------------------------------------------
+/** Read one file, or `null` for anything unreadable. NEVER THROWS. */
+export function readSessionFile(path) {
+    try {
+        return loadSession(path);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve `--resume <id|path>` to a file that exists, or `null`.
+ *
+ * A value containing a separator, or an absolute one, is a PATH; anything else
+ * is an id. That split is the same one `resolveSessionPath` makes for `/save`,
+ * so the two spellings agree about what "a name" means.
+ */
+export function resolveSessionRef(idOrPath, cwd) {
+    const value = idOrPath.trim();
+    if (value.length === 0)
+        return null;
+    const looksLikePath = isAbsolute(value) || value.includes('/') || value.includes('\\') || value.endsWith('.json');
+    const path = looksLikePath
+        ? resolve(cwd, value)
+        : isValidSessionId(value)
+            ? sessionPathFor(value)
+            : null;
+    if (!path)
+        return null;
+    return existsSync(path) ? path : null;
+}
+/**
+ * Write a session and refresh the `--continue` pointer.
+ *
+ * THE POINTER IS UPDATED AFTER THE FILE, never before: a crash between the two
+ * leaves a pointer naming a file that is one run stale, which the fallback scan
+ * corrects. The other order would leave a pointer naming a file that does not
+ * exist yet.
+ */
+export function writeSession(input) {
+    ensureDir();
+    const path = sessionPathFor(input.id);
+    saveSession(path, {
+        model: input.session.model,
+        messages: input.session.messages,
+        entries: input.session.entries,
+        todos: input.session.todos ?? [],
+        meta: input.meta,
+    });
+    writePointer(input.meta.cwd, input.id, input.meta.updatedAt);
+    return path;
+}
+export function removeSession(id) {
+    // An id that cannot name a session in this directory has not "failed to be
+    // deleted" - there was never a file of that name to delete. `sessions rm`
+    // validates first and reports the reason, so this stays a boolean.
+    if (!isValidSessionId(id))
+        return false;
+    const path = sessionPathFor(id);
+    try {
+        unlinkSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Listing
+// ---------------------------------------------------------------------------
+function describe(path, session) {
+    const meta = session.meta;
+    const id = meta?.id ?? basenameId(path);
+    return {
+        id,
+        path,
+        savedAt: session.savedAt ?? 0,
+        updatedAt: meta?.updatedAt ?? session.savedAt ?? 0,
+        cwd: meta?.cwd ?? '',
+        turns: meta?.turns ?? 0,
+        provider: meta?.provider ?? session.model?.providerId ?? '',
+        model: meta?.model ?? session.model?.modelId ?? '',
+        managed: typeof meta?.id === 'string' && meta.id.length > 0,
+    };
+}
+function basenameId(path) {
+    const name = path.replace(/\\/g, '/').split('/').pop() ?? path;
+    return name.endsWith('.json') ? name.slice(0, -'.json'.length) : name;
+}
+/**
+ * Every session in the directory, newest first.
+ *
+ * `all: false` (the default) keeps ONLY exec-managed files. `.last.json` and
+ * `*.lock` are excluded by name on both paths, because neither is a session in
+ * any sense and listing them would invite `sessions rm` on the pointer.
+ */
+export function listSessions(opts = {}) {
+    const dir = getSessionsDir();
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of safeReaddir(dir)) {
+        if (name === POINTER_FILE || name.endsWith('.lock') || !name.endsWith('.json'))
+            continue;
+        const path = join(dir, name);
+        const session = readSessionFile(path);
+        if (!session)
+            continue;
+        const entry = describe(path, session);
+        if (!opts.all && !entry.managed)
+            continue;
+        out.push(entry);
+    }
+    return out.sort((a, b) => b.updatedAt - a.updatedAt);
+}
+function safeReaddir(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/** `--dry-run` reports and deletes nothing; nothing is ever pruned automatically. */
+export function pruneSessions(opts = {}) {
+    const now = (opts.now ?? Date.now)();
+    const cutoff = opts.olderThanDays === undefined ? now : now - opts.olderThanDays * 24 * 60 * 60 * 1000;
+    const doomed = listSessions({ ...(opts.all ? { all: true } : {}) }).filter((entry) => entry.updatedAt <= cutoff);
+    if (opts.dryRun)
+        return doomed;
+    for (const entry of doomed) {
+        try {
+            unlinkSync(entry.path);
+        }
+        catch {
+            // A file that vanished under us, or one the OS has pinned. Neither is a
+            // reason to abandon the rest of the sweep.
+        }
+    }
+    return doomed;
+}
+// ---------------------------------------------------------------------------
+// `--continue`: the pointer, and the scan that makes it safe to keep
+// ---------------------------------------------------------------------------
+function cwdKey(cwd) {
+    return createHash('sha256').update(resolve(cwd)).digest('hex').slice(0, 16);
+}
+function readPointer() {
+    try {
+        const parsed = JSON.parse(readFileSync(join(getSessionsDir(), POINTER_FILE), 'utf-8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writePointer(cwd, id, updatedAt) {
+    try {
+        const pointer = readPointer();
+        pointer[cwdKey(cwd)] = { id, updatedAt };
+        // Not atomic, and it does not need to be: a torn write yields unparseable
+        // JSON, `readPointer` returns `{}`, and `latestSessionForCwd` falls back to
+        // the directory scan. The failure mode is one slower `--continue`.
+        writeFileSync(join(getSessionsDir(), POINTER_FILE), `${JSON.stringify(pointer)}\n`, 'utf-8');
+    }
+    catch {
+        // The pointer is a cache. Failing to write it must never fail a run whose
+        // session file is already safely on disk.
+    }
+}
+/**
+ * The newest exec session whose `meta.cwd` matches, or `null`.
+ *
+ * THE POINTER IS A CACHE AND IS TREATED AS ONE (R-9 / AC-9). If it is missing,
+ * unparseable, or names a file that is gone, this falls through to reading the
+ * directory - so a desync SELF-HEALS instead of stranding the user, which is the
+ * property that makes it safe to keep a denormalised index at all.
+ */
+export function latestSessionForCwd(cwd) {
+    const hinted = readPointer()[cwdKey(cwd)];
+    if (hinted && isValidSessionId(hinted.id)) {
+        const path = sessionPathFor(hinted.id);
+        const session = existsSync(path) ? readSessionFile(path) : null;
+        if (session?.meta && sameCwd(session.meta.cwd, cwd))
+            return describe(path, session);
+    }
+    const target = resolve(cwd);
+    for (const entry of listSessions()) {
+        if (sameCwd(entry.cwd, target))
+            return entry;
+    }
+    return null;
+}
+function sameCwd(a, b) {
+    if (!a || !b)
+        return false;
+    const norm = (p) => resolve(p).replace(/\\/g, '/').replace(/\/+$/, '');
+    const left = norm(a);
+    const right = norm(b);
+    // Case-insensitive on Windows only: two paths differing in case are the same
+    // directory there and two different directories on Linux.
+    return process.platform === 'win32'
+        ? left.toLowerCase() === right.toLowerCase()
+        : left === right;
+}
+/**
+ * `ESRCH` means gone. `EPERM` means the process EXISTS but belongs to another
+ * user - treating that as dead would let one user steal another's lock, so it
+ * reports ALIVE. Verbatim from `update/install-lock.ts`, which took it from
+ * `skills/lock.ts`.
+ */
+function defaultIsProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code !== 'ESRCH';
+    }
+}
+function readLock(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        if (typeof parsed.pid !== 'number' || typeof parsed.startedAt !== 'number')
+            return null;
+        if (typeof parsed.uuid !== 'string' || typeof parsed.host !== 'string')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** `wx` - atomic exclusive create. THIS SINGLE CALL IS THE MUTUAL EXCLUSION. */
+function tryCreate(path, payload) {
+    let fd;
+    try {
+        fd = openSync(path, 'wx');
+    }
+    catch {
+        return false;
+    }
+    try {
+        writeSync(fd, JSON.stringify(payload));
+    }
+    finally {
+        // Closed IMMEDIATELY: on Windows an open handle blocks `unlink`, so holding
+        // it would make our own release fail and turn every lock into a ten-minute
+        // stall for the next process.
+        closeSync(fd);
+    }
+    return true;
+}
+/**
+ * Take the lock for one `--session-id`, or report that someone else has it.
+ * NEVER SLEEPS, NEVER THROWS (D-11).
+ *
+ * ONE ATTEMPT, NO RETRY. A second process exits 2 with `session_busy` rather
+ * than waiting, because a wrapper that wants a queue can build one and a CLI
+ * that blocks for an unbounded time on a lock it cannot show the user is a hang.
+ * `skills/lock.ts::acquireRootLock` busy-waits through `Atomics.wait` and
+ * throws, which is right for a human who typed `aragon skills install` and wrong
+ * for a background caller; `update/install-lock.ts` already made that split.
+ */
+export function tryAcquireSessionLock(id, opts = {}) {
+    const now = opts.now ?? Date.now;
+    const isAlive = opts.isProcessAlive ?? defaultIsProcessAlive;
+    ensureDir();
+    // Same boundary as `sessionPathFor` - a lock is a file in this directory too,
+    // and an id that may not name a session may not name its lock either.
+    const path = join(getSessionsDir(), `${assertSessionId(id)}.lock`);
+    const payload = {
+        pid: process.pid,
+        host: hostname(),
+        startedAt: now(),
+        uuid: randomUUID(),
+    };
+    if (tryCreate(path, payload))
+        return makeHandle(path, payload);
+    const holder = readLock(path);
+    // An unreadable lock is indistinguishable from one mid-creation (create and
+    // write are two syscalls), so it is NOT evidence of abandonment and is left
+    // alone. The TTL still collects it eventually.
+    if (holder === null)
+        return null;
+    const stale = now() - holder.startedAt > SESSION_LOCK_TTL_MS ||
+        (holder.host === payload.host && !isAlive(holder.pid));
+    if (!stale)
+        return null;
+    try {
+        unlinkSync(path);
+    }
+    catch {
+        // Another process won the race to clean it up. Not ours this tick.
+        return null;
+    }
+    return tryCreate(path, payload) ? makeHandle(path, payload) : null;
+}
+function makeHandle(path, payload) {
+    let released = false;
+    return {
+        path,
+        release() {
+            if (released)
+                return;
+            released = true;
+            try {
+                const holder = readLock(path);
+                // THE UUID CHECK IS NOT DEFENSIVE PADDING. If this process was judged
+                // stale and preempted, an unconditional `unlink` here would delete the
+                // NEW holder's lock and open a second concurrency window - the classic
+                // file-lock bug, and one that only shows up under exactly the contention
+                // the lock exists to handle.
+                if (holder?.uuid !== payload.uuid)
+                    return;
+                unlinkSync(path);
+            }
+            catch {
+                // A failed release costs at most one TTL of waiting for the next
+                // process. Letting it throw would end a SUCCESSFUL run in an error.
+            }
+        },
+    };
+}

package/dist/team/runtime.d.ts

@@ -20,6 +20,7 @@
 import type { ProviderRegistry, SkillRegistry, ToolPolicyDecision, ToolPolicyVerdict } from '@aragon-agent/core';
 import type { AgentMode } from '../agent/agent-mode.js';
 import type { CliConfig } from '../config/schema.js';
+import type { ToolPermission } from '../exec/permission.js';
 import type { TeamHumanQueue } from './human-queue.js';
 import { type SubagentAgentFactory, type SubagentDeps } from './subagent.js';
 import type { DispatchOutcome, SubagentSpec, TeamEventListener, TeamSnapshot } from './types.js';
@@ -33,6 +34,17 @@ export interface TeamRuntimeDeps {
     skillRegistry?: SkillRegistry;
     alwaysBlock?: () => string;
     toolPolicy?: () => ToolPolicyDecision;
+    /**
+     * The lead's `aragon exec` tool policy, carried BESIDE `toolPolicy` and never
+     * folded into it (cli-integration-surface §4.2 invariant 3 / R-4).
+     *
+     * They answer different questions: `toolPolicy` is the skills CEILING, which
+     * refuses at call time and changes per turn; this REMOVES the tool from the
+     * child's array. A child that inherits one and not the other is a policy that
+     * holds for the lead and not for the fan-out, which is the security control
+     * silently not holding (AC-12).
+     */
+    permission?: ToolPermission;
     onChildToolPolicyEvent?: (e: {
         label: string;
         tool: string;

package/dist/team/runtime.js

@@ -119,6 +119,12 @@ export class TeamRuntime {
             ...(this.deps.skillRegistry ? { skillRegistry: this.deps.skillRegistry } : {}),
             ...(this.deps.alwaysBlock ? { alwaysBlock: this.deps.alwaysBlock() } : {}),
             ...(this.deps.toolPolicy ? { toolPolicy: this.deps.toolPolicy } : {}),
+            // Site two of two for the policy. Declaring it on `TeamRuntimeDeps` and
+            // forgetting this line type-checks and forwards nothing — the
+            // `recordChange` / `recordOutput` failure mode `tools/index.ts` records in
+            // its own words, here with a security consequence rather than a cosmetic
+            // one (R-5).
+            ...(this.deps.permission ? { permission: this.deps.permission } : {}),
             ...(this.deps.onChildToolPolicyEvent
                 ? { onChildToolPolicyEvent: this.deps.onChildToolPolicyEvent }
                 : {}),

package/dist/team/subagent.d.ts

@@ -13,6 +13,7 @@
 import { type AgentConfig, type AgentEvent, type AgentTool, type ModelRef, type ProviderRegistry, type SkillRegistry, type ThinkingLevel, type TokenUsage, type ToolPolicyDecision, type ToolPolicyVerdict } from '@aragon-agent/core';
 import type { AgentMode } from '../agent/agent-mode.js';
 import type { CliConfig } from '../config/schema.js';
+import type { ToolPermission } from '../exec/permission.js';
 import type { FastTierName } from '../fast/types.js';
 import { TeamBus } from './bus.js';
 import type { TeamHumanQueue, WatchdogPausable } from './human-queue.js';
@@ -51,6 +52,17 @@ export interface SubagentDeps {
     /** The lead's always-on skill bodies, spliced into every child's prompt. */
     alwaysBlock?: string;
     toolPolicy?: () => ToolPolicyDecision;
+    /**
+     * The lead's `aragon exec` tool policy (cli-integration-surface §4.2
+     * invariant 3). TIGHTENING ONLY, exactly as `spec.readOnly` is: there is no
+     * field anywhere that gives a child more permission than the session it was
+     * spawned from.
+     *
+     * `team_send` / `team_wait` survive it unconditionally — the exemption lives
+     * inside `ToolPermission.isAllowed`, not here, so every caller gets it and no
+     * second list of the same two names exists (P1-3).
+     */
+    permission?: ToolPermission;
     /** Already label-decorating; see `TeamRuntime` (§3.11 / P1-3). */
     onChildToolPolicyEvent?: (e: {
         label: string;

package/dist/team/subagent.js

@@ -107,6 +107,10 @@ export function buildSubagentTools(spec, deps, getAgent) {
         // a mid-dispatch Shift+Tab to PLAN tightens every running child at its next
         // tool call.
         agentMode: () => (spec.readOnly ? 'plan' : deps.getMode()),
+        // Site three of three for the policy (`ControllerDeps` -> `TeamRuntimeDeps`
+        // -> here). Spread, so a child built without one gets today's options bag
+        // byte for byte and `buildSubagentTools`'s existing tests are untouched.
+        ...(deps.permission ? { permission: deps.permission } : {}),
         ...(deps.toolPolicy
             ? {
                 toolPolicy: deps.toolPolicy,

package/dist/tools/index.d.ts

@@ -10,6 +10,7 @@
  */
 import { type AgentTool, type ToolPolicyDecision, type ToolPolicyVerdict } from '@aragon-agent/core';
 import type { AgentMode } from '../agent/agent-mode.js';
+import type { ToolPermission } from '../exec/permission.js';
 import type { FilePatch } from './patch.js';
 export interface ConfirmRequest {
     tool: string;
@@ -163,6 +164,25 @@ export interface BuiltinToolsOptions {
      * re-applies the lead's policy to children to avoid.
      */
     policyExempt?: ReadonlySet<string>;
+    /**
+     * The non-interactive tool policy of `aragon exec`
+     * (cli-integration-surface §4.2). A denied tool is NOT REGISTERED AT ALL, so
+     * the model never sees it and never plans around it (D-4).
+     *
+     * OMITTING IT MUST LEAVE THE ARRAY UNTOUCHED, PROVEN BY IDENTITY (P1-2 /
+     * AC-28). Every optional in this bag follows that house rule and `AC-G17`
+     * already enforces it for `--no-skills` in those words. An unconditional
+     * `tools.filter(...)` would type-check, behave identically, and quietly
+     * allocate a new array on every existing path — forfeiting the ability to
+     * PROVE that `-p`, the TUI and every subagent are unchanged.
+     *
+     * IT IS A THIRD MECHANISM, NOT A RENAME OF THE OTHER TWO. `toolPolicy` is the
+     * skills ceiling (refuses at call time, per turn); `agentMode` is the plan
+     * gate (refuses at call time, per mode); this REMOVES the tool. `policyExempt`
+     * belongs to the first of those and is unrelated to the comm-tool exemption
+     * `ToolPermission.isAllowed` applies for itself.
+     */
+    permission?: ToolPermission;
 }
 /**
  * Tools the ceiling always permits (D-G6). The ONLY place that knows which of

package/dist/tools/index.js

@@ -252,6 +252,32 @@ export function createBuiltinTools(options) {
     if (options.teamTools && options.teamTools.length > 0) {
         tools = [...tools, ...options.teamTools];
     }
+    // --- The `aragon exec` permission filter (cli-integration-surface §4.2). ---
+    //
+    // ITS OWN `if`, AFTER THE LAST APPEND AND BEFORE THE `toolPolicy` WRAPPER, and
+    // both tail returns below are left byte-identical (P1-1 / R-6).
+    //
+    // AFTER THE APPENDS so `skillTools` / `planTools` / `todoTools` / `teamTools`
+    // are all subject to it. BEFORE THE WRAPPERS so neither of the two independent
+    // guards at the end of this function has to move: the v1 instruction "applied
+    // last, after the plan gate" was unimplementable (the function ends in TWO
+    // returns, so there is no position after both that is not after the whole
+    // function) and reaching for one pushes an implementer into restructuring the
+    // exact tail whose comment records the `--no-skills --plan` bug.
+    //
+    // ORDERING IS A PROPERTY OF WRAPPERS, NOT OF FILTERS. The rule below is about
+    // NESTING at call time - which gate runs before which, and therefore who pays
+    // for a human wait. A filter removes array elements and has no call-time
+    // position at all; every wrapper preserves `.name` through `{...tool}`, so
+    // `filter . map === map . filter` here and this placement is chosen for the
+    // two structural reasons above rather than for a semantic one.
+    //
+    // THE GUARD IS WHAT MAKES AC-28 CHECKABLE. Omitting `permission` must leave
+    // the tool OBJECTS untouched, provable by identity - the `AC-G17` discipline.
+    if (options.permission) {
+        const permission = options.permission;
+        tools = tools.filter((t) => permission.isAllowed(t.name));
+    }
     // No decision provider (`--no-skills`, or a caller that never enabled the
     // policy) means the ceiling adds nothing.
     //

package/dist/ui/ActivityLine.d.ts

@@ -41,6 +41,22 @@
 import React from 'react';
 import type { Theme } from './theme.js';
 import type { TermCapabilities } from './capabilities.js';
+/**
+ * The animated spinner this row draws while it is live, or `null` when it would
+ * be STATIC — an ASCII terminal, or a user who asked for stillness.
+ *
+ * A FACTORY, NOT A COMPONENT, and the distinction is load-bearing. A
+ * `<LiveSpinner/>` element whose own render returned `null` would still be
+ * truthy at the call site — the exact trap `BottomStatusRow`'s `update` prop
+ * documents at length. Callers test the RETURN VALUE and get a real answer.
+ *
+ * It is exported so `BottomStatusRow` can put the bare glyph beside a toast
+ * without importing `ink-spinner` itself: `spinner-census.test.ts` enumerates
+ * every file under `src/ui/**` that imports it, and that list is the checklist
+ * for "who is allowed to animate". One more importer is one more site a future
+ * reader has to reason about; one more caller of this function is not.
+ */
+export declare function liveSpinner(reducedMotion: boolean, caps: TermCapabilities): React.ReactElement | null;
 export interface ActivityLineProps {
     /** Epoch ms the current run began — the phrase sequence's seed. */
     startedAt: number;

package/dist/ui/ActivityLine.js

@@ -3,6 +3,24 @@ import { Box, Text } from 'ink';
 import Spinner from 'ink-spinner';
 import { pickGlyphs } from './glyphs.js';
 import { pickActivityPhrase } from './activity-phrases.js';
+/**
+ * The animated spinner this row draws while it is live, or `null` when it would
+ * be STATIC — an ASCII terminal, or a user who asked for stillness.
+ *
+ * A FACTORY, NOT A COMPONENT, and the distinction is load-bearing. A
+ * `<LiveSpinner/>` element whose own render returned `null` would still be
+ * truthy at the call site — the exact trap `BottomStatusRow`'s `update` prop
+ * documents at length. Callers test the RETURN VALUE and get a real answer.
+ *
+ * It is exported so `BottomStatusRow` can put the bare glyph beside a toast
+ * without importing `ink-spinner` itself: `spinner-census.test.ts` enumerates
+ * every file under `src/ui/**` that imports it, and that list is the checklist
+ * for "who is allowed to animate". One more importer is one more site a future
+ * reader has to reason about; one more caller of this function is not.
+ */
+export function liveSpinner(reducedMotion, caps) {
+    return caps.unicode && !reducedMotion ? _jsx(Spinner, { type: "dots" }) : null;
+}
 export function ActivityLine({ startedAt, elapsedMs, reducedMotion, runningTool, theme, caps, }) {
     const glyphs = pickGlyphs(caps);
     // PURE AND DERIVED FROM `(startedAt, now)`, so the sequence does not need to
@@ -17,6 +35,10 @@ export function ActivityLine({ startedAt, elapsedMs, reducedMotion, runningTool,
     // The IDENTICAL branch `Transcript.tsx` uses for the assistant role marker, and
     // it must stay identical: braille dots are both an animation AND a Unicode-only
     // glyph, so reduced motion and an ASCII terminal fall back to the same marker.
-    const spinner = caps.unicode && !reducedMotion ? _jsx(Spinner, { type: "dots" }) : glyphs.spinnerStill;
+    //
+    // Through `liveSpinner` rather than inline, so this row and the glyph
+    // `BottomStatusRow` composes beside a toast can never disagree about WHEN the
+    // spinner is live — the same reason `App` names its mount condition once.
+    const spinner = liveSpinner(reducedMotion, caps) ?? glyphs.spinnerStill;
     return (_jsx(Box, { flexShrink: 0, children: _jsxs(Text, { wrap: "truncate", color: theme.thinking, children: [' ', spinner, " ", label] }) }));
 }

package/dist/ui/App.d.ts

@@ -50,6 +50,19 @@ export interface AppProps {
      *  is off: inline mode, `--no-mouse`, a non-TTY, or a filter that failed to
      *  build (mouse-wheel-region-routing §4.2). */
     mouseSource?: MouseSource;
+    /**
+     * Present ONLY on a console that can deliver neither `CSI Z` nor a mouse
+     * report — a Windows console whose Node predates `UV_TTY_MODE_RAW_VT`
+     * (`ui/win-vt-input.ts`). Absent everywhere else, which is what makes every
+     * unaffected machine byte-identical to a build without this prop.
+     *
+     * DECIDED BY `cli.tsx`, not here, and by the SAME expression that gates
+     * `mouseSource`: the two must never disagree about whether this terminal
+     * reports anything.
+     */
+    vtInputWarning?: {
+        nodeVersion: string;
+    };
     /**
      * The auto-updater's late-arrival channel (cli-auto-update §3.8).
      *
@@ -60,4 +73,4 @@ export interface AppProps {
      */
     updateBridge?: UpdateBridge;
 }
-export declare function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, updateBridge, }: AppProps): React.ReactElement;
+export declare function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, vtInputWarning, updateBridge, }: AppProps): React.ReactElement;