maqcli 0.4.0 → 0.5.0

package/dist/core/capabilities.d.ts

@@ -21,6 +21,8 @@ export interface TieredModel {
     tier: CapabilityTier;
     vision?: boolean;
     longContext?: boolean;
+    /** Roles this model is suited for (plan|code|review|summarize|fan-out). */
+    goodFor?: string[];
 }
 /**
  * Heuristic classifier for a raw model id when we have no catalog tag (e.g. a

package/dist/core/cli-probe.d.ts

@@ -0,0 +1,44 @@
+/**
+ * cli-probe — actually USE the user's own AI CLIs to learn what they can do.
+ *
+ * The launcher's option (1) registers installed CLIs, but a name alone tells us
+ * nothing about capability. Here we hand each authenticated CLI the
+ * CAPABILITY_PROBE_INSTRUCTION (via its headless mode, at $0 marginal cost —
+ * the user's existing subscription pays) and parse its self-reported tier /
+ * strengths / context / good-for. That report is what we store into the
+ * Headroom knowledge doc so the master can route work to the right model.
+ *
+ * The model call is injectable (`complete`) so this is unit-testable offline
+ * without spawning a real CLI.
+ */
+import { type CapabilityTier } from "./capabilities.js";
+export interface CliCapability {
+    name: string;
+    maqProvider: string;
+    tier: CapabilityTier;
+    strengths: string[];
+    goodFor: string[];
+    contextTokens?: number;
+    vision?: boolean;
+    /** Whether the report came from the CLI itself vs a heuristic fallback. */
+    probed: boolean;
+}
+export type CompleteFn = (prompt: string) => Promise<string>;
+/**
+ * Probe a single CLI. `complete` defaults to the cli:<name> provider; pass a
+ * stub in tests. Never throws — on any failure it returns a heuristic default
+ * so onboarding always proceeds.
+ */
+export declare function probeCliCapability(name: string, opts?: {
+    complete?: CompleteFn;
+    timeoutMs?: number;
+}): Promise<CliCapability>;
+/**
+ * Probe every authenticated CLI (or a provided list). Runs in parallel; each
+ * probe is independently best-effort.
+ */
+export declare function probeInstalledClis(opts?: {
+    names?: string[];
+    complete?: CompleteFn;
+    timeoutMs?: number;
+}): Promise<CliCapability[]>;

package/dist/core/cli-probe.js

@@ -0,0 +1,85 @@
+/**
+ * cli-probe — actually USE the user's own AI CLIs to learn what they can do.
+ *
+ * The launcher's option (1) registers installed CLIs, but a name alone tells us
+ * nothing about capability. Here we hand each authenticated CLI the
+ * CAPABILITY_PROBE_INSTRUCTION (via its headless mode, at $0 marginal cost —
+ * the user's existing subscription pays) and parse its self-reported tier /
+ * strengths / context / good-for. That report is what we store into the
+ * Headroom knowledge doc so the master can route work to the right model.
+ *
+ * The model call is injectable (`complete`) so this is unit-testable offline
+ * without spawning a real CLI.
+ */
+import { getProvider } from "./model.js";
+import { detectAgents } from "./registry.js";
+import { CAPABILITY_PROBE_INSTRUCTION, parseCapabilityReply, classifyModel, } from "./capabilities.js";
+/**
+ * Probe a single CLI. `complete` defaults to the cli:<name> provider; pass a
+ * stub in tests. Never throws — on any failure it returns a heuristic default
+ * so onboarding always proceeds.
+ */
+export async function probeCliCapability(name, opts = {}) {
+    const maqProvider = `cli:${name}`;
+    const fallback = {
+        name,
+        maqProvider,
+        tier: classifyModel(name),
+        strengths: [],
+        goodFor: ["code"],
+        probed: false,
+    };
+    const complete = opts.complete ??
+        (async (prompt) => {
+            const provider = getProvider(maqProvider, { strict: true });
+            const res = await provider.complete({
+                model: maqProvider,
+                messages: [{ role: "user", content: prompt }],
+                maxTokens: 300,
+            });
+            return res.text;
+        });
+    try {
+        const timeoutMs = opts.timeoutMs ?? 45000;
+        const reply = await withTimeout(complete(CAPABILITY_PROBE_INSTRUCTION), timeoutMs);
+        const parsed = parseCapabilityReply(reply);
+        if (!parsed)
+            return fallback;
+        return {
+            name,
+            maqProvider,
+            tier: parsed.tier,
+            strengths: parsed.strengths,
+            goodFor: parsed.goodFor.length ? parsed.goodFor : ["code"],
+            contextTokens: parsed.contextTokens,
+            vision: parsed.vision,
+            probed: true,
+        };
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Probe every authenticated CLI (or a provided list). Runs in parallel; each
+ * probe is independently best-effort.
+ */
+export async function probeInstalledClis(opts = {}) {
+    const names = opts.names ??
+        detectAgents()
+            .filter((a) => a.installed && a.authenticated)
+            .map((a) => a.name);
+    return Promise.all(names.map((n) => probeCliCapability(n, { complete: opts.complete, timeoutMs: opts.timeoutMs })));
+}
+function withTimeout(p, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("capability probe timed out")), ms);
+        p.then((v) => {
+            clearTimeout(timer);
+            resolve(v);
+        }).catch((e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+    });
+}

package/dist/core/launcher.d.ts

@@ -31,6 +31,12 @@ export declare function browserOpenCommand(url: string, platform?: NodeJS.Platfo
 export declare function openBrowser(url: string): void;
 /** The Megalodon splash. `color=false` yields a plain-text version. */
 export declare function megalodonSplash(color?: boolean): string;
+/**
+ * Frames of the megalodon swimming in from the left (red fin, white body). The
+ * last frame is the settled splash. Used only on a TTY; tests use the pure
+ * megalodonSplash above.
+ */
+export declare function megalodonFrames(color?: boolean): string[];
 export interface OnboardingChoices {
     /** Registered worker/master models (already tiered). */
     models: TieredModel[];

package/dist/core/launcher.js

@@ -21,18 +21,10 @@ import { spawn } from "node:child_process";
 import { randomInt } from "node:crypto";
 import { loadConfig, saveConfig } from "./config-store.js";
 import { detectAgents } from "./registry.js";
-import { PROVIDER_CATALOG, detectAvailableProviders, getCatalogProvider, } from "./providers-catalog.js";
+import { PROVIDER_CATALOG, detectAvailableProviders, getCatalogProvider, providerGoodFor, } from "./providers-catalog.js";
 import { classifyModel, pickEfficient } from "./capabilities.js";
 import { buildKnowledge, saveKnowledge, roleForModel } from "./onboarding.js";
-/** Preferred lightest master invocation per detected CLI agent ($0 marginal). */
-const CLI_MASTER_HINT = {
-    gemini: "cli:gemini",
-    "claude-code": "cli:claude-code",
-    codex: "cli:codex",
-    opencode: "cli:opencode",
-    "amazon-q": "cli:amazon-q",
-    aider: "cli:aider",
-};
+import { probeCliCapability } from "./cli-probe.js";
 /* --------------------------- pure, testable ---------------------------- */
 /** A user-facing 9-digit pairing/auth key (100000000–999999999). */
 export function generateAuthKey() {
@@ -85,6 +77,45 @@ export function megalodonSplash(color = true) {
         "",
     ].join("\n");
 }
+/**
+ * Frames of the megalodon swimming in from the left (red fin, white body). The
+ * last frame is the settled splash. Used only on a TTY; tests use the pure
+ * megalodonSplash above.
+ */
+export function megalodonFrames(color = true) {
+    const r = color ? RED : "";
+    const w = color ? WHITE : "";
+    const x = color ? RST : "";
+    const shark = (pad) => {
+        const p = " ".repeat(pad);
+        return [
+            "",
+            "",
+            `${p}${w}          ,${x}`,
+            `${p}${w}        ,'|   ${r}▄▄${x}`,
+            `${p}${r}≈≈≈≈≈≈≈${w},'__|${r}████████▀${x}`,
+            `${p}${w}        \`.|${r}████▀${x}`,
+            `${p}${w}          \`.${r}▀${x}`,
+            "",
+            "",
+        ].join("\n");
+    };
+    return [shark(0), shark(6), shark(14), shark(24), megalodonSplash(color)];
+}
+async function animateSplash(color) {
+    if (!process.stdout.isTTY) {
+        line(megalodonSplash(color));
+        return;
+    }
+    const frames = megalodonFrames(color);
+    for (let i = 0; i < frames.length; i++) {
+        process.stdout.write("\x1b[2J\x1b[H"); // clear + home
+        process.stdout.write(frames[i]);
+        if (i < frames.length - 1)
+            await new Promise((res) => setTimeout(res, 110));
+    }
+    process.stdout.write("\n");
+}
 /**
  * Persist an onboarding outcome: pick the efficient model if none was chosen,
  * write config (provider/model/tiers/permission/onboarded) and the Headroom
@@ -121,7 +152,7 @@ export function applyOnboarding(choices) {
                 : m.tier === "heavy"
                     ? "reviewer"
                     : "worker";
-        return roleForModel(m, role, choices.source);
+        return roleForModel(m, role, choices.source, m.goodFor ?? []);
     });
     const knowledge = buildKnowledge({
         providers,
@@ -144,7 +175,7 @@ function line(s = "") {
  * (piped stdin), it prints guidance and returns without blocking.
  */
 export async function runLauncher(cwd) {
-    line(megalodonSplash(useColor()));
+    await animateSplash(useColor());
     if (!process.stdin.isTTY) {
         line("maq: guided setup needs an interactive terminal.");
         line("  • run `maq start` in a real terminal, or");
@@ -242,15 +273,22 @@ async function registerClis(rl) {
         line("or pick option 3 (API providers). Continuing with none for now.");
         return { models: [], source: "cli" };
     }
-    line("\nFound these authenticated CLIs (registered as $0 workers):");
+    line("\nFound these authenticated CLIs. Asking each one to self-report its capabilities (uses your own subscription, $0)…");
     const models = [];
     for (const a of ready) {
-        const masterModel = CLI_MASTER_HINT[a.name] ?? `cli:${a.name}`;
-        // A CLI reused as a master is treated as a mid-tier worker for tiering.
-        models.push({ id: masterModel, provider: a.name, maqProvider: masterModel, tier: "mid" });
-        line(`  • ${a.name}  → ${masterModel}`);
+        const cap = await probeCliCapability(a.name, { timeoutMs: 45000 });
+        models.push({
+            id: cap.maqProvider,
+            provider: a.name,
+            maqProvider: cap.maqProvider,
+            tier: cap.tier,
+            vision: cap.vision,
+            goodFor: cap.goodFor,
+        });
+        const how = cap.probed ? `self-reported ${cap.tier}` : `${cap.tier} (probe unavailable)`;
+        const gf = cap.goodFor.length ? `  good for: ${cap.goodFor.join(", ")}` : "";
+        line(`  • ${a.name.padEnd(12)} → ${cap.maqProvider}   [${how}]${gf}`);
     }
-    line(`\n(To register each CLI's own model list, MAQ will ask it "/models" on first use.)`);
     return { models, source: "cli" };
 }
 async function registerSingleApi(rl) {
@@ -269,7 +307,7 @@ async function registerSingleApi(rl) {
     const model = chosen.models[mpick - 1] ?? chosen.models[0];
     line("\nNote: a single model can't fan out — parallel/safe modes are disabled until you add more.");
     return {
-        models: [{ id: model.id, provider: chosen.id, maqProvider: chosen.maqProvider, tier: model.tier }],
+        models: [{ id: model.id, provider: chosen.id, maqProvider: chosen.maqProvider, tier: model.tier, goodFor: providerGoodFor(chosen.id) }],
         source: "api",
     };
 }
@@ -292,6 +330,9 @@ async function registerMultiApi(rl) {
         provider: d.provider.id,
         maqProvider: d.provider.maqProvider,
         tier: m.tier ?? classifyModel(m.id),
+        vision: m.vision,
+        longContext: m.longContext,
+        goodFor: providerGoodFor(d.provider.id),
     })));
     line(`\nRegistered ${models.length} models across ${active.length} active provider(s).`);
     return { models, source: "api" };
@@ -312,7 +353,7 @@ async function connectMobile(rl) {
 async function launchUi(authKey) {
     // Reuse the daemon; open its landing page. Import lazily to avoid a cycle.
     const { createDaemon } = await import("../server/daemon.js");
-    const daemon = createDaemon({ token: authKey, version: "0.4.0" });
+    const daemon = createDaemon({ token: authKey, version: "0.5.0" });
     try {
         const { host, port } = await daemon.listen();
         const url = `http://${host}:${port}/`;

package/dist/core/orchestrator.d.ts

@@ -70,6 +70,11 @@ export interface OrchestrationOptions {
     onEvent?: (e: MaqEvent) => void;
     signal?: AbortSignal;
     checkpoint?: () => Promise<void>;
+    /**
+     * Permission gate consulted before MAJOR steps (moderate mode). Resolves
+     * true to proceed, false to hold. When absent, everything proceeds.
+     */
+    requestPermission?: (action: string, detail: string, risk: "low" | "major" | "destructive") => Promise<boolean>;
     /** Override any collaborator (tests inject deterministic ones). */
     deps?: Partial<OrchestratorDeps>;
 }

package/dist/core/orchestrator.js

@@ -209,6 +209,14 @@ async function engineSafe(goal, deps, opts, emit) {
     // 2. MERGE the parts via a (single) integration step on a strong model.
     await opts.checkpoint?.();
     emit(makeEvent("phase.started", { phase: "safe-merge", mode: "safe" }));
+    // Merging integrates everyone's work — a MAJOR action, so it passes through
+    // the permission gate (moderate mode may hold it for approval).
+    const allowMerge = opts.requestPermission ? await opts.requestPermission("merge", "integrate all sub-results into the final solution", "major") : true;
+    if (!allowMerge) {
+        emit(makeEvent("agent.event", { note: "merge held by permission policy (request-box)", phase: "safe-merge" }));
+        emit(makeEvent("phase.done", { phase: "safe-merge", held: true }));
+        return { goal, mode: "safe", rounds: 1, subtasks: partResults, verified: false, summary: "merge held pending approval" };
+    }
     const merged = await deps.merge(goal, partResults, { onEvent: emit, signal: opts.signal });
     emit(makeEvent("phase.done", { phase: "safe-merge", verified: merged.verified, status: merged.status }));
     // 3. Final validation pass over everything.

package/dist/core/permissions.d.ts

@@ -0,0 +1,80 @@
+/**
+ * permissions — the "request box" the spec describes.
+ *
+ * A single Headroom master controls everything, but it never performs work
+ * itself; its ants (workers) do. So permission is about gating the ants' major
+ * actions, not the master. Two postures:
+ *
+ *   full     — everything is allowed; the box stays empty.
+ *   moderate — every MAJOR or DESTRUCTIVE action stops and is filed as a
+ *              request. A goal-aware policy (the Headroom check) auto-approves
+ *              actions that clearly serve the stated goal and holds the rest for
+ *              an explicit approve/deny (by the master or a human via the UI).
+ *
+ * Requests are held in an in-memory box; each pending request exposes a promise
+ * (`await`) that resolves when it is decided. Low-risk actions never queue.
+ */
+export type PermissionMode = "full" | "moderate";
+export type Risk = "low" | "major" | "destructive";
+export type RequestStatus = "pending" | "approved" | "denied";
+export interface PermissionRequest {
+    id: string;
+    action: string;
+    detail: string;
+    risk: Risk;
+    goal?: string;
+    status: RequestStatus;
+    reason: string;
+    ts: string;
+    decidedBy?: string;
+}
+/** Classify an action string into a risk level (deterministic, pattern-based). */
+export declare function classifyRisk(action: string, detail?: string): Risk;
+export interface Policy {
+    (req: Pick<PermissionRequest, "action" | "detail" | "risk" | "goal">): {
+        allow: boolean;
+        reason: string;
+    };
+}
+/**
+ * The Headroom check: allow when the action plainly serves the goal.
+ *  - low risk           → always allow
+ *  - destructive        → never auto-allow (must be approved explicitly)
+ *  - major              → allow only if it aligns with the goal (keyword overlap)
+ */
+export declare function goalAwarePolicy(req: Pick<PermissionRequest, "action" | "detail" | "risk" | "goal">): {
+    allow: boolean;
+    reason: string;
+};
+export declare class PermissionBroker {
+    private mode;
+    private policy;
+    private box;
+    private waiters;
+    constructor(mode?: PermissionMode, opts?: {
+        policy?: Policy;
+    });
+    getMode(): PermissionMode;
+    /**
+     * File a request. Returns the (possibly already-decided) request. In `full`
+     * mode everything is approved immediately; in `moderate` mode the policy runs
+     * and only holds what it cannot justify.
+     */
+    request(action: string, detail: string, ctx?: {
+        risk?: Risk;
+        goal?: string;
+    }): PermissionRequest;
+    /** Resolve once the request is decided. Already-decided requests resolve now. */
+    await(id: string): Promise<boolean>;
+    /** Convenience: file + await in one call. */
+    gate(action: string, detail: string, ctx?: {
+        risk?: Risk;
+        goal?: string;
+    }): Promise<boolean>;
+    approve(id: string, by?: string): boolean;
+    deny(id: string, by?: string): boolean;
+    private decide;
+    pending(): PermissionRequest[];
+    list(): PermissionRequest[];
+    get(id: string): PermissionRequest | undefined;
+}

package/dist/core/permissions.js

@@ -0,0 +1,147 @@
+/**
+ * permissions — the "request box" the spec describes.
+ *
+ * A single Headroom master controls everything, but it never performs work
+ * itself; its ants (workers) do. So permission is about gating the ants' major
+ * actions, not the master. Two postures:
+ *
+ *   full     — everything is allowed; the box stays empty.
+ *   moderate — every MAJOR or DESTRUCTIVE action stops and is filed as a
+ *              request. A goal-aware policy (the Headroom check) auto-approves
+ *              actions that clearly serve the stated goal and holds the rest for
+ *              an explicit approve/deny (by the master or a human via the UI).
+ *
+ * Requests are held in an in-memory box; each pending request exposes a promise
+ * (`await`) that resolves when it is decided. Low-risk actions never queue.
+ */
+import { randomUUID } from "node:crypto";
+/** Classify an action string into a risk level (deterministic, pattern-based). */
+export function classifyRisk(action, detail = "") {
+    const s = `${action} ${detail}`.toLowerCase();
+    if (/(rm\s+-rf|rmdir\s+\/s|drop\s+(table|database)|truncate|del\s+\/|format\s|mkfs|:\s*>\s|force[-\s]?push|--force\b|\bpush\b.*\s-f\b|reset\s+--hard|git\s+clean\s+-|delete\s+from|shutdown|reboot)/.test(s)) {
+        return "destructive";
+    }
+    if (/(write|create|modify|edit|install|npm\s+i|pip\s+install|deploy|publish|push|commit|merge|migrate|chmod|chown|mv\s|move|rename|apply|patch)/.test(s)) {
+        return "major";
+    }
+    return "low";
+}
+/**
+ * The Headroom check: allow when the action plainly serves the goal.
+ *  - low risk           → always allow
+ *  - destructive        → never auto-allow (must be approved explicitly)
+ *  - major              → allow only if it aligns with the goal (keyword overlap)
+ */
+export function goalAwarePolicy(req) {
+    if (req.risk === "low")
+        return { allow: true, reason: "low-risk action" };
+    if (req.risk === "destructive")
+        return { allow: false, reason: "destructive action requires explicit approval" };
+    // major: align against the goal.
+    const goal = (req.goal ?? "").toLowerCase();
+    if (!goal)
+        return { allow: false, reason: "no goal context to justify a major action" };
+    const words = new Set((req.action + " " + req.detail).toLowerCase().split(/\W+/).filter((w) => w.length >= 4));
+    const goalWords = new Set(goal.split(/\W+/).filter((w) => w.length >= 4));
+    let overlap = 0;
+    for (const w of words)
+        if (goalWords.has(w))
+            overlap++;
+    return overlap > 0
+        ? { allow: true, reason: `major action aligns with the goal (${overlap} matching term(s))` }
+        : { allow: false, reason: "major action does not clearly serve the stated goal" };
+}
+export class PermissionBroker {
+    mode;
+    policy;
+    box = new Map();
+    waiters = new Map();
+    constructor(mode = "moderate", opts = {}) {
+        this.mode = mode;
+        this.policy = opts.policy ?? goalAwarePolicy;
+    }
+    getMode() {
+        return this.mode;
+    }
+    /**
+     * File a request. Returns the (possibly already-decided) request. In `full`
+     * mode everything is approved immediately; in `moderate` mode the policy runs
+     * and only holds what it cannot justify.
+     */
+    request(action, detail, ctx = {}) {
+        const risk = ctx.risk ?? classifyRisk(action, detail);
+        const req = {
+            id: randomUUID(),
+            action,
+            detail,
+            risk,
+            goal: ctx.goal,
+            status: "pending",
+            reason: "",
+            ts: new Date().toISOString(),
+        };
+        if (this.mode === "full") {
+            req.status = "approved";
+            req.reason = "full-permission mode";
+            this.box.set(req.id, req);
+            return req;
+        }
+        const verdict = this.policy({ action, detail, risk, goal: ctx.goal });
+        if (verdict.allow) {
+            req.status = "approved";
+            req.reason = verdict.reason;
+        }
+        else {
+            req.status = "pending";
+            req.reason = verdict.reason;
+        }
+        this.box.set(req.id, req);
+        return req;
+    }
+    /** Resolve once the request is decided. Already-decided requests resolve now. */
+    await(id) {
+        const req = this.box.get(id);
+        if (!req)
+            return Promise.resolve(false);
+        if (req.status !== "pending")
+            return Promise.resolve(req.status === "approved");
+        return new Promise((resolve) => {
+            const list = this.waiters.get(id) ?? [];
+            list.push({ resolve });
+            this.waiters.set(id, list);
+        });
+    }
+    /** Convenience: file + await in one call. */
+    async gate(action, detail, ctx = {}) {
+        const req = this.request(action, detail, ctx);
+        return this.await(req.id);
+    }
+    approve(id, by = "user") {
+        return this.decide(id, "approved", by);
+    }
+    deny(id, by = "user") {
+        return this.decide(id, "denied", by);
+    }
+    decide(id, status, by) {
+        const req = this.box.get(id);
+        if (!req || req.status !== "pending")
+            return false;
+        req.status = status;
+        req.decidedBy = by;
+        req.reason = `${status} by ${by}`;
+        const waiters = this.waiters.get(id) ?? [];
+        for (const w of waiters)
+            w.resolve(status === "approved");
+        this.waiters.delete(id);
+        return true;
+    }
+    pending() {
+        return [...this.box.values()].filter((r) => r.status === "pending");
+    }
+    list() {
+        return [...this.box.values()];
+    }
+    get(id) {
+        return this.box.get(id);
+    }
+}

package/dist/core/providers-catalog.d.ts

@@ -50,6 +50,7 @@ export interface CatalogProvider {
  */
 export declare const PROVIDER_CATALOG: CatalogProvider[];
 export declare function getCatalogProvider(id: string): CatalogProvider | undefined;
+export declare function providerGoodFor(id: string): string[];
 /**
  * Detect which catalog providers are usable RIGHT NOW from the environment
  * only — no network, no tokens. Local providers (Ollama) are reported as

package/dist/core/providers-catalog.js

@@ -156,6 +156,24 @@ export const PROVIDER_CATALOG = [
 export function getCatalogProvider(id) {
     return PROVIDER_CATALOG.find((p) => p.id === id);
 }
+/**
+ * The role each provider tends to play in the pipeline (fed into the Headroom
+ * knowledge doc). Roles: plan | code | review | summarize | fan-out.
+ */
+const PROVIDER_GOOD_FOR = {
+    openai: ["plan", "code", "review"],
+    anthropic: ["plan", "code", "review", "summarize"],
+    gemini: ["summarize", "code", "fan-out"],
+    groq: ["fan-out", "summarize"],
+    xai: ["plan", "code"],
+    deepseek: ["code", "review"],
+    mistral: ["code", "summarize"],
+    ollama: ["fan-out", "summarize"],
+    litellm: ["plan", "code", "review"],
+};
+export function providerGoodFor(id) {
+    return PROVIDER_GOOD_FOR[id] ?? ["code"];
+}
 /**
  * Detect which catalog providers are usable RIGHT NOW from the environment
  * only — no network, no tokens. Local providers (Ollama) are reported as

package/dist/core/session.d.ts

@@ -66,6 +66,8 @@ export interface CreateOptions {
     maxRounds?: number;
     maxIterations?: number;
     maxConcurrency?: number;
+    /** Permission gate for major orchestration steps (moderate mode). */
+    requestPermission?: (action: string, detail: string, risk: "low" | "major" | "destructive") => Promise<boolean>;
 }
 type Listener = (e: MaqEvent) => void;
 /** Thrown through the pipeline checkpoint when a session is cancelled. */

package/dist/core/session.js

@@ -160,6 +160,7 @@ export class SessionRegistry {
                 onEvent,
                 signal: control.abort.signal,
                 checkpoint,
+                requestPermission: opts.requestPermission,
             }).then((orchestration) => {
                 if (session.status === "cancelled")
                     return;

package/dist/index.js

@@ -43,7 +43,7 @@ import { runInit } from "./core/init-wizard.js";
 import { CostTracker } from "./core/cost-tracker.js";
 import { runLauncher } from "./core/launcher.js";
 import { runOrchestration } from "./core/orchestrator.js";
-const VERSION = "0.4.0";
+const VERSION = "0.5.0";
 async function main(argv) {
     const [command, ...rest] = argv;
     switch (command) {

package/dist/server/daemon.js

@@ -34,6 +34,8 @@ import { execSafe } from "../core/exec.js";
 import { commandCatalog, maqCommands } from "../core/command-catalog.js";
 import { InteractiveRegistry } from "../core/interactive-registry.js";
 import { webuiHtml } from "./webui.js";
+import { PermissionBroker } from "../core/permissions.js";
+import { loadConfig } from "../core/config-store.js";
 /** Generate a URL-safe token. */
 export function generateToken() {
     return randomBytes(24).toString("base64url");
@@ -49,11 +51,17 @@ export function createDaemon(opts = {}) {
     const host = opts.host ?? process.env.MAQ_HOST ?? "127.0.0.1";
     const port = opts.port ?? Number(process.env.MAQ_PORT ?? 7717);
     const token = opts.token ?? process.env.MAQ_TOKEN ?? generateToken();
-    const version = opts.version ?? "0.4.0";
+    const version = opts.version ?? "0.5.0";
     const corsOrigin = opts.corsOrigin ?? process.env.MAQ_CORS_ORIGIN;
     const registry = opts.registry ?? new SessionRegistry();
     const interactive = new InteractiveRegistry();
     const startedAt = Date.now();
+    // The request-box. Posture comes from config (set by the guided launcher).
+    const permissionMode = (() => {
+        const m = loadConfig().permissionMode;
+        return m === "full" ? "full" : "moderate";
+    })();
+    const broker = new PermissionBroker(permissionMode);
     // Track live SSE responses so shutdown can end them deterministically.
     // Without this, server.close() blocks forever on the long-lived event
     // streams (they only emit a keep-alive ping every 15s and never end on their
@@ -123,6 +131,28 @@ export function createDaemon(opts = {}) {
             sendJson(res, 200, commandCatalog());
             return;
         }
+        // The permission request-box.
+        if (path === "/v1/requests" && method === "GET") {
+            sendJson(res, 200, { mode: broker.getMode(), pending: broker.pending(), requests: broker.list() });
+            return;
+        }
+        const reqMatch = /^\/v1\/requests\/([^/]+)$/.exec(path);
+        if (reqMatch && method === "POST") {
+            const id = decodeURIComponent(reqMatch[1]);
+            const body = await readJson(req);
+            const action = String(body.action ?? "");
+            let ok = false;
+            if (action === "approve")
+                ok = broker.approve(id, "web");
+            else if (action === "deny")
+                ok = broker.deny(id, "web");
+            else {
+                sendJson(res, 400, { error: "action must be approve|deny" });
+                return;
+            }
+            sendJson(res, ok ? 202 : 409, { id, action, ok, request: broker.get(id) });
+            return;
+        }
         // Whitelisted CLI runner — powers the app's Master (terminal) edition.
         // Only known `maq` subcommands run; never arbitrary shell.
         if (path === "/v1/exec" && method === "POST") {
@@ -209,6 +239,9 @@ export function createDaemon(opts = {}) {
                 maxRounds: typeof body.maxRounds === "number" ? body.maxRounds : undefined,
                 maxIterations: typeof body.maxIterations === "number" ? body.maxIterations : undefined,
                 maxConcurrency: typeof body.maxConcurrency === "number" ? body.maxConcurrency : undefined,
+                // Major orchestration steps pass through the request-box, judged
+                // against this session's goal.
+                requestPermission: (action, detail, risk) => broker.gate(action, detail, { risk, goal: task }),
             });
             sendJson(res, 201, registry.summarize(s));
             return;

package/dist/server/webui.js

@@ -90,6 +90,20 @@ export function webuiHtml(version) {
   pre{white-space:pre-wrap;word-break:break-word;font-size:12px;color:var(--ink)}
   .rhead{display:flex;align-items:center;justify-content:space-between;padding:10px 12px;border-bottom:1px solid var(--edge)}
   a{color:var(--blue2)}
+  .overlay{position:fixed;inset:0;background:var(--bg);z-index:60;display:none;flex-direction:column}
+  .overlay.show{display:flex}
+  .grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(230px,1fr));gap:12px;padding:16px;overflow:auto;align-content:start}
+  .fcard{background:var(--panel);border:1px solid var(--edge);border-radius:12px;padding:14px;cursor:pointer}
+  .fcard:hover{border-color:var(--blue);box-shadow:0 0 0 1px var(--blue) inset}
+  .fcard h4{margin:0 0 4px;color:var(--ink);font-size:14px}
+  .fcard .cat{font-size:10px;color:var(--blue2);text-transform:uppercase;letter-spacing:1px}
+  .fcard p{margin:6px 0 0;font-size:12px;color:var(--mut)}
+  .req{padding:9px 12px;border-bottom:1px solid #0f1626}
+  .req .a{font-size:12.5px;color:var(--ink)} .req .r{font-size:11px;color:var(--mut);margin:2px 0 6px}
+  .req.destructive{box-shadow:inset 3px 0 0 var(--red)} .req.major{box-shadow:inset 3px 0 0 var(--warn)}
+  .req .btns{display:flex;gap:6px}
+  .req button{border:none;border-radius:6px;padding:4px 10px;cursor:pointer;font-size:11px}
+  .ok-btn{background:var(--ok);color:#00231a} .no-btn{background:var(--red);color:#2a0007}
 </style></head>
 <body>
 <header>
@@ -98,6 +112,7 @@ export function webuiHtml(version) {
   <span class="e-mut" style="font-size:12px">megalodon · v${version}</span>
   <span class="grow"></span>
   <div class="switch">
+    <button onclick="openFeatures()">&#9776; Features</button>
     <button onclick="feat('agents')">Agents</button>
     <button onclick="feat('connectivity')">Connectivity</button>
     <button onclick="feat('doctor')">Doctor</button>
@@ -107,6 +122,8 @@ export function webuiHtml(version) {
 </header>
 <main id="main">
   <div class="col left">
+    <div class="sec">Request box <span id="reqCount" class="badge"></span></div>
+    <div id="requests"><div class="empty">No pending requests.</div></div>
     <div class="sec">Sessions &amp; history</div>
     <div id="sessions"><div class="empty">No sessions yet.</div></div>
     <div class="sec">Agents</div>
@@ -139,6 +156,15 @@ export function webuiHtml(version) {
     <div id="preview" style="padding:12px"><div class="empty">Select a session to inspect its result.</div></div>
   </div>
 </main>
+<div class="overlay" id="features">
+  <div class="rhead" style="padding:14px 16px">
+    <button class="ghost" onclick="closeFeatures()">&#8592; Back to home</button>
+    <b style="margin-left:12px">All features</b>
+    <span class="grow"></span>
+    <span class="e-mut" style="font-size:12px">everything MAQ can do — click to run</span>
+  </div>
+  <div class="grid" id="featureGrid"><div class="empty">loading…</div></div>
+</div>
 <script>
 "use strict";
 var base = location.origin;
@@ -312,7 +338,57 @@ function renderAgents(agents){
   });
 }
 
-renderModes(); refreshSessions(); feat('agents'); setInterval(refreshSessions, 5000);
+async function openFeatures(){
+  document.getElementById('features').classList.add('show');
+  var grid=document.getElementById('featureGrid'); grid.innerHTML='loading…';
+  try{
+    var cat=await (await api('/v1/commands')).json();
+    var cmds=(cat.maq||[]); grid.innerHTML='';
+    cmds.forEach(function(c){
+      var card=h('div','fcard');
+      card.innerHTML='<div class="cat">'+c.category+'</div><h4>'+c.name+'</h4><p>'+c.summary+'</p>';
+      card.onclick=function(){ runFeature(c); };
+      grid.appendChild(card);
+    });
+  }catch(e){ grid.innerHTML='<div class="empty">'+e+'</div>'; }
+}
+function closeFeatures(){ document.getElementById('features').classList.remove('show'); }
+function runFeature(c){
+  closeFeatures();
+  if(c.needsInput==='task'||c.needsInput==='query'){
+    var g=document.getElementById('goal'); g.focus();
+    if(c.name==='orchestrate'){ mode='parallel'; renderModes(); }
+    g.placeholder='['+c.name+'] '+c.summary;
+  } else {
+    feat(c.name);
+  }
+}
+
+async function loadRequests(){
+  try{
+    var d=await (await api('/v1/requests')).json();
+    var box=document.getElementById('requests'); var pend=(d.pending||[]);
+    document.getElementById('reqCount').textContent=pend.length?String(pend.length):'';
+    if(!pend.length){ box.innerHTML='<div class="empty">No pending requests.</div>'; return; }
+    box.innerHTML='';
+    pend.forEach(function(r){
+      var it=h('div','req '+r.risk);
+      var a=h('div','a'); a.textContent=r.action+' — '+(r.detail||'');
+      var reason=h('div','r'); reason.textContent=r.risk+' · '+(r.reason||'');
+      var btns=h('div','btns');
+      var ok=h('button','ok-btn','Approve'); ok.onclick=function(){ decideReq(r.id,'approve'); };
+      var no=h('button','no-btn','Deny'); no.onclick=function(){ decideReq(r.id,'deny'); };
+      btns.appendChild(ok); btns.appendChild(no);
+      it.appendChild(a); it.appendChild(reason); it.appendChild(btns); box.appendChild(it);
+    });
+  }catch(e){}
+}
+async function decideReq(id,action){
+  try{ await api('/v1/requests/'+id,{method:'POST',body:JSON.stringify({action:action})}); loadRequests(); }catch(e){}
+}
+
+renderModes(); refreshSessions(); feat('agents'); loadRequests();
+setInterval(refreshSessions, 5000); setInterval(loadRequests, 3000);
 document.getElementById('goal').addEventListener('keydown', function(e){ if((e.metaKey||e.ctrlKey)&&e.key==='Enter')startTask(); });
 </script>
 </body></html>`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maqcli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "MAQ master orchestrator — a token-efficient, agent-agnostic supervisor CLI that sits on top of any worker CLI (AI or not) via a Scout -> Plan -> Execute -> Verify pipeline.",
   "type": "module",
   "bin": {