muonroi-cli 1.7.2 → 1.8.1

package/dist/src/tools/native-tools.js

@@ -26,6 +26,7 @@ import { SETUP_GUIDE_TEXT } from "../mcp/setup-guide-text.js";
 export const NATIVE_MUONROI_TOOL_NAMES = [
     "ee_health",
     "ee_feedback",
+    "ee_write",
     "usage_forensics",
     "lsp_query",
     "setup_guide",
@@ -103,6 +104,61 @@ export function registerNativeMuonroiTools(tools, opts = {}) {
             }
         },
     });
+    tools.ee_write = dynamicTool({
+        description: "Save a NEW lesson to the Experience Engine brain so you and future sessions recall it. Call this the MOMENT " +
+            "you hit a mistake / error / dead-end and find the working fix: record the pitfall AND the fix in one concise, " +
+            "generalizable lesson (1-3 sentences — what to do or avoid next time, NOT a play-by-play of this turn). The " +
+            "lesson is embedded immediately and becomes recallable via ee_query in THIS and future sessions. Use ee_query " +
+            "first when unsure if a lesson already exists. collection defaults to experience-behavioral (use " +
+            "experience-principles only for a broad, project-independent principle).",
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+                lesson: {
+                    type: "string",
+                    description: "The lesson: the mistake/pitfall AND the fix, concise and generalizable.",
+                },
+                title: { type: "string", description: "Optional short title (<=120 chars)." },
+                collection: {
+                    type: "string",
+                    enum: ["experience-behavioral", "experience-principles"],
+                    description: "Target tier; default experience-behavioral.",
+                },
+            },
+            required: ["lesson"],
+            additionalProperties: false,
+        }),
+        execute: async (input) => {
+            const lesson = typeof input?.lesson === "string" ? input.lesson.trim() : "";
+            if (lesson.length < 12) {
+                return errLine("invalid_args", "ee_write requires a non-empty, substantive lesson (>=12 chars)");
+            }
+            // Cap oversized bodies (EE import-quality rule: bare points >1500 chars are
+            // status-dumps, not lessons).
+            const text = lesson.length > 1500 ? `${lesson.slice(0, 1497)}...` : lesson;
+            const collection = input?.collection === "experience-principles" ? "experience-principles" : "experience-behavioral";
+            const title = typeof input?.title === "string" && input.title.trim() ? input.title.trim().slice(0, 120) : undefined;
+            try {
+                const { writeExperienceEE } = await import("../ee/search.js");
+                const path = await import("node:path");
+                const cwd = opts.cwd ?? process.cwd();
+                // confidence 0.65 (above the import default 0.6): an agent-asserted lesson
+                // is deliberate but unproven — the ee_feedback loop then tunes it.
+                const result = await writeExperienceEE(text, {
+                    collection,
+                    title,
+                    projectSlug: path.basename(cwd),
+                    confidence: 0.65,
+                });
+                if (!result.ok)
+                    return errLine("write_failed", result.error ?? "import-memory POST failed");
+                return json({ ok: true, id: result.id, collection, recallable: "now — same session via ee_query" });
+            }
+            catch (e) {
+                return errLine("write_failed", e instanceof Error ? e.message : String(e));
+            }
+        },
+    });
     // ── Self-diagnostics: usage_forensics ─────────────────────────────────────
     tools.usage_forensics = dynamicTool({
         description: "Per-session token-cost forensics by session-id prefix: peak input, cache-hit ratio, per-event breakdown.",
@@ -180,6 +236,7 @@ export function registerNativeMuonroiTools(tools, opts = {}) {
                 goal: { type: "string" },
                 llm: { type: "string" },
                 turns: { type: "number" },
+                mockLlmDir: { type: "string", description: "Use 'none' to run child TUI against real LLM APIs" },
             },
             required: ["mode"],
         }),
@@ -191,7 +248,15 @@ export function registerNativeMuonroiTools(tools, opts = {}) {
                 const { getModelInfo } = await import("../models/registry.js");
                 if (!getModelInfo(input.llm))
                     return errLine("unknown_model", `llm '${input.llm}' is not in catalog.json`);
-                return json({ runId: jm.start({ kind: "agentic", goal: input.goal, llm: input.llm, turns: input.turns }) });
+                return json({
+                    runId: jm.start({
+                        kind: "agentic",
+                        goal: input.goal,
+                        llm: input.llm,
+                        turns: input.turns,
+                        mockLlmDir: input.mockLlmDir,
+                    }),
+                });
             }
             return json({
                 runId: jm.start({ kind: "tier1", since: input?.since, max: input?.max, emit: input?.emit, out: input?.out }),

package/dist/src/tools/registry-bash-empty-command.test.js

@@ -26,7 +26,8 @@ describe("bash tool — empty/missing command corrective guard", () => {
         const bash = new BashTool(os.tmpdir());
         const tools = createBuiltinTools(bash, "agent");
         const out = await runBash(tools, {});
-        expect(out).toMatch(/ERROR/);
+        // Guard uses "BLOCKED (empty-bash):" prefix — more semantic than bare "ERROR".
+        expect(out).toMatch(/BLOCKED/);
         expect(out).toMatch(/non-empty/i);
         expect(out).toMatch(/command/i);
     });
@@ -34,14 +35,14 @@ describe("bash tool — empty/missing command corrective guard", () => {
         const bash = new BashTool(os.tmpdir());
         const tools = createBuiltinTools(bash, "agent");
         const out = await runBash(tools, { command: "" });
-        expect(out).toMatch(/ERROR/);
+        expect(out).toMatch(/BLOCKED/);
         expect(out).toMatch(/non-empty/i);
     });
     it("returns the corrective error for a whitespace-only command", async () => {
         const bash = new BashTool(os.tmpdir());
         const tools = createBuiltinTools(bash, "agent");
         const out = await runBash(tools, { command: "   " });
-        expect(out).toMatch(/ERROR/);
+        expect(out).toMatch(/BLOCKED/);
         expect(out).toMatch(/non-empty/i);
     });
     it("does NOT block a real command", async () => {

package/dist/src/tools/registry-git-safety.test.js

@@ -12,11 +12,11 @@ import { BashTool } from "./bash.js";
 import { clearBashOutputCache } from "./bash-output-cache.js";
 import { __resetGitSafetyState, recordCommandOutcome } from "./git-safety.js";
 import { createBuiltinTools } from "./registry.js";
-async function runBash(tools, args) {
+async function runBash(tools, args, extra) {
     const t = tools.bash;
     if (!t?.execute)
         throw new Error("bash tool has no execute");
-    const out = await t.execute(args);
+    const out = await t.execute(args, extra);
     return typeof out === "string" ? out : JSON.stringify(out);
 }
 describe("git-safety wiring in bash tool", () => {
@@ -28,6 +28,7 @@ describe("git-safety wiring in bash tool", () => {
     });
     afterEach(() => {
         delete process.env.MUONROI_ALLOW_PUSH_ON_RED;
+        delete globalThis.__muonroiSafetyApproved;
     });
     it("BLOCKS git push (without executing) after a verification failed this session", async () => {
         const bash = new BashTool(os.tmpdir());
@@ -35,7 +36,7 @@ describe("git-safety wiring in bash tool", () => {
         // Simulate a failed test earlier in the session.
         recordCommandOutcome("GS1", "npm test", false);
         const out = await runBash(tools, { command: "git push origin main", timeout: 10_000 });
-        expect(out).toMatch(/^BLOCKED:/);
+        expect(out).toMatch(/^BLOCKED \(git-safety\):/);
         expect(out).toMatch(/npm test/);
         // The distinctive block message proves git push never ran (a real push in
         // tmpdir would fail with a git error like "not a git repository", not this).
@@ -72,16 +73,26 @@ describe("git-safety wiring in bash tool", () => {
         // Fresh anon registry (simulates the per-turn rebuild).
         const toolsB = createBuiltinTools(bash, "agent"); // no sessionId
         const pushOut = await runBash(toolsB, { command: "git push origin main", timeout: 10_000 });
-        expect(pushOut).toMatch(/^BLOCKED:/);
+        expect(pushOut).toMatch(/^BLOCKED \(git-safety\):/);
     }, 30_000);
-    it("appends a sensitive-path WARNING on a broad git add when secrets exist", async () => {
+    it("uses command-matched safety approval when the retry has a new toolCallId", async () => {
+        const bash = new BashTool(os.tmpdir());
+        const tools = createBuiltinTools(bash, "agent", { sessionId: "GS-APPROVE" });
+        recordCommandOutcome("GS-APPROVE", "npm test", false);
+        globalThis.__muonroiSafetyApproved = new Map([
+            ["blocked-tool-call-id", { kind: "once", command: "git push origin main" }],
+        ]);
+        const out = await runBash(tools, { command: "git push origin main", timeout: 10_000 }, { toolCallId: "retry-tool-call-id" });
+        expect(out).not.toMatch(/^BLOCKED/);
+    }, 20_000);
+    it("blocks broad git add when sensitive paths exist", async () => {
         const dir = mkdtempSync(join(os.tmpdir(), "gs-stage-"));
         writeFileSync(join(dir, ".env"), "API_KEY=secret");
         try {
             const bash = new BashTool(dir);
             const tools = createBuiltinTools(bash, "agent", { sessionId: "GS4" });
             const out = await runBash(tools, { command: "git add -A", timeout: 10_000 });
-            expect(out).toMatch(/\[WARNING:/);
+            expect(out).toMatch(/^BLOCKED \(git-safety\):/);
             expect(out).toMatch(/\.env/);
         }
         finally {

package/dist/src/tools/registry.d.ts

@@ -13,7 +13,9 @@ interface ToolRegistryOpts {
     runDelegation?: (request: TaskRequest, abortSignal?: AbortSignal) => Promise<ToolResult>;
     readDelegation?: (id: string) => Promise<ToolResult>;
     listDelegations?: () => Promise<ToolResult>;
+    killDelegation?: (id: string) => Promise<ToolResult>;
     modelId?: string;
+    consultParentSession?: (question: string) => Promise<string>;
     /**
      * When false, the 3 vision-proxy tools (analyze_image, ask_vision_proxy,
      * list_vision_cache) are omitted even for vision-proxy models. Used by the
@@ -51,6 +53,10 @@ interface BashRepeatEntry {
 }
 declare global {
     var __muonroiBashRepeatState: Map<string, BashRepeatEntry> | undefined;
+    var __muonroiSafetyApproved: Map<string, {
+        kind: "once" | "session";
+        command: string;
+    }> | undefined;
 }
 export declare const MAX_TOOL_OUTPUT_CHARS: number;
 export declare function truncateOutput(text: string, maxChars?: number): string;

package/dist/src/tools/registry.js

@@ -12,10 +12,16 @@ import { needsVisionProxy } from "../providers/vision-proxy.js";
 import { getBashRun, sliceBashOutput } from "./bash-output-cache.js";
 import { editFile, readFile, writeFile } from "./file.js";
 import { FileTracker } from "./file-tracker.js";
-import { analyzeGitCommand, checkPushGate, pushBlockedMessage, recordCommandOutcome, stagingWarning, } from "./git-safety.js";
+import { analyzeGitCommand, checkPushGate, checkSensitiveStaging, commitBlockedMessage, pushBlockedMessage, recordCommandOutcome, } from "./git-safety.js";
 import { executeGrep } from "./grep.js";
 import { registerNativeMuonroiTools } from "./native-tools.js";
 import { VISION_TOOL_NAMES } from "./vision-gate.js";
+function getSafetyApprovedMap() {
+    if (!globalThis.__muonroiSafetyApproved) {
+        globalThis.__muonroiSafetyApproved = new Map();
+    }
+    return globalThis.__muonroiSafetyApproved;
+}
 function getBashRepeatState() {
     if (!globalThis.__muonroiBashRepeatState) {
         globalThis.__muonroiBashRepeatState = new Map();
@@ -80,7 +86,7 @@ export function createBuiltinTools(bash, mode, opts) {
     const fileTracker = new FileTracker();
     // read_file
     tools.read_file = dynamicTool({
-        description: "Read file contents with optional start_line/end_line for iterative reading.",
+        description: "Read file contents. For large files, you MUST use start_line and end_line to extract only the needed sections (e.g. specific functions). Reading full large files will quickly exhaust your context budget. Use grep or lsp first to find line numbers.",
         inputSchema: jsonSchema({
             type: "object",
             properties: {
@@ -97,7 +103,7 @@ export function createBuiltinTools(bash, mode, opts) {
     });
     // grep
     tools.grep = dynamicTool({
-        description: "Fast regex content search across the codebase using ripgrep. Returns matching lines with file paths and line numbers.",
+        description: "Fast regex content search across the codebase using ripgrep. Returns matching lines with file paths and line numbers. Use this to find precise line numbers before calling read_file with start_line/end_line.",
         inputSchema: jsonSchema({
             type: "object",
             properties: {
@@ -135,11 +141,17 @@ export function createBuiltinTools(bash, mode, opts) {
     // else a single process-stable key. Over-sharing here is the safe direction
     // (it can only over-block a push, never wrongly allow one).
     const gitSafetyKey = opts?.sessionId && opts.sessionId.length > 0 ? opts.sessionId : `__proc_default__:${process.pid}`;
+    // Per-session empty-bash streak counter: escalates from guidance (strike 1-2)
+    // to hard block (strike 3+) so a cheap model that repeatedly emits `bash: {}`
+    // cannot loop indefinitely (live: deepseek session bf58d0f46b51 — 8+ empty calls).
+    const _emptyBashStreak = new Map();
+    const _prefixBlock = (kind, msg) => `BLOCKED (${kind}): ${msg}`;
     tools.bash = dynamicTool({
         description: "Execute a shell command. Output is automatically cached — every call returns a " +
             "run_id you can re-query via bash_output_get(run_id, mode=tail|head|grep|lines). " +
             "Do NOT pipe `| tail`, `| head`, `| grep`, or `> file` — that hides output from " +
-            "the cache. Run unpiped and slice via bash_output_get instead. For collecting system info (OS, versions, cwd layout, git, disk, processes) batch with ; or && in ONE call, e.g. 'uname -a; node -v; bun --version; ls -la | head -15; git status --short; df -h .; ps aux | head -5'. Set background=true for long-running processes (dev servers, watchers).",
+            "the cache. Run unpiped and slice via bash_output_get instead. For collecting system info (OS, versions, cwd layout, git, disk, processes) batch with ; or && in ONE call, e.g. 'uname -a; node -v; bun --version; ls -la | head -15; git status --short; df -h .; ps aux | head -5'. Set background=true for long-running processes (dev servers, watchers). " +
+            'Avoid nesting double-quotes inline for database queries/scripts (e.g. executing raw SQL via `sqlite3 db "SELECT..."`) since they can fail parsing in shell environments; write query scripts to a temporary file first and run them.',
         inputSchema: jsonSchema({
             type: "object",
             properties: {
@@ -149,7 +161,10 @@ export function createBuiltinTools(bash, mode, opts) {
             },
             required: ["command"],
         }),
-        execute: async (input) => {
+        // Phase 8 — safety-blocked commands queue, keyed by sessionId + toolCallId.
+        // When the orchestrator intercepts a blocked result, the approval handler
+        // stores the approved command here so bash.execute() can retry it.
+        execute: async (input, extra) => {
             // Corrective guard for malformed calls: a cheap model sometimes emits a
             // bash call with a missing / empty `command` (live: deepseek sent `{}`
             // repeatedly until the loop-guard fired). Passing undefined to
@@ -158,9 +173,41 @@ export function createBuiltinTools(bash, mode, opts) {
             // both look like progress and feed the loop. Return a crisp instruction
             // so the next step supplies a real command instead of repeating.
             if (typeof input.command !== "string" || input.command.trim() === "") {
-                return 'ERROR: the `bash` tool requires a non-empty "command" string, but the call had empty arguments. Provide the shell command to run, e.g. {"command":"ls -la"}.';
+                // Track empty-bash streak per session; escalate from guidance to hard block.
+                const _ebKey = gitSafetyKey ?? "no-session";
+                let _eb = _emptyBashStreak.get(_ebKey) ?? 0;
+                _eb++;
+                _emptyBashStreak.set(_ebKey, _eb);
+                if (_eb >= 3) {
+                    return ('BLOCKED (empty-bash): the `bash` tool has been called with an empty/missing "command" 3+ times in a row. ' +
+                        "Bash is now DISABLED for the remainder of this session — use read_file, grep, or other tools instead. " +
+                        "If you need to run a shell command, state the blocker explicitly and the CLI will enable it again on the next turn.");
+                }
+                if (_eb >= 2) {
+                    return ('BLOCKED (empty-bash): ERROR (2nd consecutive empty bash call): the `bash` tool requires a non-empty "command" string ' +
+                        "but this is the 2nd call in a row with empty arguments. One more empty call will BLOCK bash for the session. " +
+                        'Provide a real command, e.g. {"command":"ls -la"}.');
+                }
+                return 'BLOCKED (empty-bash): the `bash` tool requires a non-empty "command" string, but the call had empty arguments. Provide the shell command to run, e.g. {"command":"ls -la"}.';
             }
+            // Reset the empty-bash streak on any successful command.
+            _emptyBashStreak.delete(gitSafetyKey ?? "no-session");
             const cmd = typeof input.command === "string" ? input.command : "";
+            // Safety override check: approval is granted after a blocked call, but
+            // the model's retry receives a new toolCallId. Match by id first, then
+            // by exact command so allow-once survives the retry boundary.
+            const _approvedMap = getSafetyApprovedMap();
+            const _approvalKey = extra?.toolCallId && _approvedMap.has(extra.toolCallId)
+                ? extra.toolCallId
+                : [..._approvedMap.entries()].find(([, approval]) => approval.command === cmd)?.[0];
+            const _approvalEntry = _approvalKey ? _approvedMap.get(_approvalKey) : undefined;
+            if (_approvalEntry) {
+                if (_approvalEntry.kind === "once") {
+                    _approvedMap.delete(_approvalKey);
+                }
+                const result = await bash.execute(input.command, input.timeout ?? 30000);
+                return formatResult(result);
+            }
             // Git safety (pre-execution). Block `git push` while a verification
             // command failed this session and was not re-run green; warn on broad
             // `git add -A` / `git commit -a` when sensitive paths exist. Applied to
@@ -169,16 +216,46 @@ export function createBuiltinTools(bash, mode, opts) {
             // (or the real sessionId) — unlike repeatKey, whose anon fallback changes
             // on every registry rebuild and would silently drop the gate across turns.
             const gitShape = analyzeGitCommand(cmd);
-            const stageWarn = gitShape.isBroadStage ? stagingWarning(bash.getCwd()) : "";
+            // Hard-block broad staging when sensitive files are present.
+            // This runs PRE-EXECUTION (before bash.execute) regardless of permission mode.
+            if (gitShape.isBroadStage) {
+                const stagingBlock = checkSensitiveStaging(bash.getCwd());
+                if (stagingBlock.blocked) {
+                    return _prefixBlock("git-safety", stagingBlock.message);
+                }
+            }
             if (gitShape.isPush) {
                 const gate = checkPushGate(gitSafetyKey);
                 if (gate.blocked) {
-                    return `${pushBlockedMessage(gate.failed)}${stageWarn}`;
+                    return _prefixBlock("git-safety", pushBlockedMessage(gate.failed));
+                }
+            }
+            // G1 follow-up: a raw bash `git commit` must not bypass the LSP commit
+            // gate that the `git_commit` tool + auto-commit backstop enforce. Derive
+            // the to-be-committed paths from git state and block (pre-exec, never run
+            // the commit) if any staged source file has a severity-1 LSP error. The
+            // gate is fail-OPEN (LSP slow/down → allow) and self-disables under
+            // MUONROI_COMMIT_GATE=0 / the unit-test suite. Lazy-import keeps the
+            // LSP-heavy module off the hot bash path (mirrors git_commit below).
+            if (gitShape.isCommit) {
+                const { gateStagedPaths, isCommitGateEnabled, pathsForCommitGate } = await import("../orchestrator/auto-commit.js");
+                if (isCommitGateEnabled()) {
+                    const commitCwd = bash.getCwd();
+                    const paths = await pathsForCommitGate(commitCwd, {
+                        broadAdd: gitShape.isBroadAdd,
+                        commitAll: gitShape.isCommitAll,
+                    });
+                    if (paths.length > 0) {
+                        const gate = await gateStagedPaths(commitCwd, paths);
+                        if (!gate.ok) {
+                            return _prefixBlock("git-safety", commitBlockedMessage(gate.summary));
+                        }
+                    }
                 }
             }
             if (input.background) {
                 const result = await bash.startBackground(input.command);
-                return `${formatResult(result)}${stageWarn}`;
+                return formatResult(result);
             }
             // 3-3: compute canonical form BEFORE running so we can attach an
             // inline reminder if it matches the previous bash call.
@@ -213,9 +290,9 @@ export function createBuiltinTools(bash, mode, opts) {
                 const hint = chars >= 4_000
                     ? ` — ${chars} chars cached; use bash_output_get(run_id, mode=tail|head|grep|lines) to re-query`
                     : "";
-                return `${formatted}\n\n[bash_run_id: ${result.bashRunId}${hint}]${reminder}${stageWarn}`;
+                return `${formatted}\n\n[bash_run_id: ${result.bashRunId}${hint}]${reminder}`;
             }
-            return `${formatted}${stageWarn}`;
+            return formatted;
         },
     });
     // bash_output_get — re-query the cached full output of a previous bash run.
@@ -344,6 +421,58 @@ export function createBuiltinTools(bash, mode, opts) {
                 };
             },
         });
+        // git_commit — the agent commits its OWN work with a message IT writes.
+        tools.git_commit = dynamicTool({
+            description: "Commit the files you have created/edited so far, with a commit message YOU write. Use this to commit each " +
+                "cohesive, working chunk the moment it is finished — and after EACH step of a multi-step plan — instead of " +
+                "leaving everything for one commit at the end. message: a clear conventional subject describing WHAT changed " +
+                "(e.g. 'feat(auth): add token refresh'), optionally followed by a body — NOT a restatement of the request. " +
+                "Only files you wrote via write_file/edit_file are staged (secrets + CLI artifacts are excluded, and the " +
+                "'Coding by - Muonroi-CLI' attribution line is appended automatically). No-op if none of your written files " +
+                "have uncommitted changes.",
+            inputSchema: jsonSchema({
+                type: "object",
+                properties: {
+                    message: {
+                        type: "string",
+                        description: "Conventional commit subject (optionally + body) describing what changed, authored by you.",
+                    },
+                },
+                required: ["message"],
+            }),
+            execute: async (input) => {
+                const message = typeof input?.message === "string" ? input.message.trim() : "";
+                if (message.length < 3) {
+                    return { success: false, output: "git_commit requires a non-empty commit message." };
+                }
+                const written = fileTracker.writtenPaths();
+                if (written.length === 0) {
+                    return {
+                        success: false,
+                        output: "Nothing to commit — you have not created or edited any file via write_file/edit_file this session.",
+                    };
+                }
+                try {
+                    const { commitSpecificPaths } = await import("../orchestrator/auto-commit.js");
+                    const result = await commitSpecificPaths(bash.getCwd(), written, message);
+                    if (!result.committed) {
+                        // G1: when the LSP quality gate blocked the commit, surface the
+                        // per-file errors so the agent can fix them and call git_commit again.
+                        // Tell the agent to FIX the errors — do NOT advertise the bypass
+                        // env here (that is a USER escape hatch; surfacing it to the agent
+                        // just invites it to circumvent the gate instead of fixing).
+                        const detail = result.reason === "lsp-errors"
+                            ? `\nStaged files have errors — fix them and call git_commit again:\n${result.detail ?? ""}`
+                            : "";
+                        return { success: false, output: `No commit made (${result.reason}).${detail}` };
+                    }
+                    return { success: true, output: `Committed ${result.fileCount} file(s) → ${result.sha}` };
+                }
+                catch (e) {
+                    return { success: false, output: `git_commit failed: ${e instanceof Error ? e.message : String(e)}` };
+                }
+            },
+        });
         // task
         if (opts?.runTask) {
             const runTask = opts.runTask;
@@ -358,15 +487,45 @@ export function createBuiltinTools(bash, mode, opts) {
                         },
                         description: { type: "string", description: "Short description of the task" },
                         prompt: { type: "string", description: "Detailed instructions for the sub-agent" },
+                        maxToolRounds: {
+                            type: "number",
+                            description: "Optional maximum tool execution rounds (default is 12 for foreground tasks)",
+                        },
                     },
                     required: ["agent", "description", "prompt"],
                 }),
                 execute: async (input) => {
-                    const result = await runTask({ agent: input.agent, description: input.description, prompt: input.prompt });
+                    const result = await runTask({
+                        agent: input.agent,
+                        description: input.description,
+                        prompt: input.prompt,
+                        maxToolRounds: input.maxToolRounds,
+                    });
                     return formatResult(result);
                 },
             });
         }
+        // consult_parent_session
+        if (opts?.consultParentSession) {
+            const consultParentSession = opts.consultParentSession;
+            tools.consult_parent_session = dynamicTool({
+                description: "Consult the parent session for supervision or guidance when stuck, when needing clarification on the overall goal, or when encountering critical errors. ONLY available in sub-sessions.",
+                inputSchema: jsonSchema({
+                    type: "object",
+                    properties: {
+                        question: {
+                            type: "string",
+                            description: "The specific question or issue you need the parent session to advise on.",
+                        },
+                    },
+                    required: ["question"],
+                }),
+                execute: async (input) => {
+                    const result = await consultParentSession(input.question);
+                    return result;
+                },
+            });
+        }
         // delegate
         if (opts?.runDelegation) {
             const runDelegation = opts.runDelegation;
@@ -378,6 +537,10 @@ export function createBuiltinTools(bash, mode, opts) {
                         agent: { type: "string", description: "Sub-agent type (usually 'explore')" },
                         description: { type: "string", description: "Short description of the research task" },
                         prompt: { type: "string", description: "Detailed research instructions" },
+                        maxToolRounds: {
+                            type: "number",
+                            description: "Optional maximum tool execution rounds (default is 60 for explore delegations)",
+                        },
                     },
                     required: ["agent", "description", "prompt"],
                 }),
@@ -386,6 +549,7 @@ export function createBuiltinTools(bash, mode, opts) {
                         agent: input.agent,
                         description: input.description,
                         prompt: input.prompt,
+                        maxToolRounds: input.maxToolRounds,
                     });
                     return formatResult(result);
                 },
@@ -424,6 +588,24 @@ export function createBuiltinTools(bash, mode, opts) {
                 },
             });
         }
+        // delegation_kill
+        if (opts?.killDelegation) {
+            const killDelegation = opts.killDelegation;
+            tools.delegation_kill = dynamicTool({
+                description: "Terminate a running background delegation/subagent by ID.",
+                inputSchema: jsonSchema({
+                    type: "object",
+                    properties: {
+                        id: { type: "string", description: "Delegation ID to terminate" },
+                    },
+                    required: ["id"],
+                }),
+                execute: async (input) => {
+                    const result = await killDelegation(input.id);
+                    return formatResult(result);
+                },
+            });
+        }
         // ee_query — semantic recall over the Experience Engine brain. This is the
         // in-CLI counterpart of the MCP `ee.query` tool (src/mcp/ee-tools.ts):
         // without it, the Agent Operating Contract + checkpoint reminders instruct
@@ -493,7 +675,13 @@ export function createBuiltinTools(bash, mode, opts) {
                             return "[ee_unavailable] Experience Engine returned no response (server down, timeout, circuit open, or unconfigured) and the artifact is not in this session's local cache. Proceed without EE recall — re-read the source directly if you need the elided content.";
                         }
                         recordRehydration("ee");
-                        return truncateOutput(JSON.stringify(resp));
+                        const points = resp.points ?? [];
+                        const bestHit = points[0];
+                        if (bestHit) {
+                            const matchedId = query.match(/(?:id\s*=\s*|id\s*\b)([a-zA-Z0-9_:-]+)/i)?.[1] ?? "unknown";
+                            return truncateOutput(`[tool-artifact id=${matchedId} — rehydrated from Experience Engine]\n${bestHit.text}`);
+                        }
+                        return `[tool-artifact — not found in Experience Engine]`;
                     }
                     // General recall → /api/recall (recallMode, [id col] index + surface).
                     const { recallEE, formatRecallForAgent } = await import("../ee/search.js");
@@ -503,6 +691,20 @@ export function createBuiltinTools(bash, mode, opts) {
                     if (resp === null) {
                         return "[ee_unavailable] Experience Engine returned no response (server down, timeout, circuit open, or unconfigured). Proceed without EE recall — re-read the source directly if you need the elided content.";
                     }
+                    // Record recalled entries as pending feedback debt in the same in-process
+                    // ledger the native ee_feedback builtin clears, so an in-CLI active recall
+                    // accrues a verdict obligation exactly like the external MCP ee.query does
+                    // (mcp/ee-tools.ts). Layer 3 surfaces this debt as a reminder on the next
+                    // enriched turn; without it the in-CLI recall arm was write-only and
+                    // ee_feedback.clear() was a no-op.
+                    try {
+                        const { sessionRecallLedger, isRecallLedgerEnabled } = await import("../ee/recall-ledger.js");
+                        if (isRecallLedgerEnabled())
+                            sessionRecallLedger.record(resp.entries, query);
+                    }
+                    catch (err) {
+                        console.error(`[tools:ee_query] recall-ledger record failed: ${err?.message}`);
+                    }
                     // Compact ranked `[id col]` index, not a JSON dump — the recallMode text
                     // is ~30k (wide net), so JSON.stringify wasted the budget on escaping.
                     return truncateOutput(formatRecallForAgent(resp, {

package/dist/src/types/index.d.ts

@@ -33,6 +33,7 @@ export interface TaskRequest {
     agent: BuiltinSubagentId | string;
     description: string;
     prompt: string;
+    maxToolRounds?: number;
 }
 export interface TaskRun {
     agent: string;
@@ -207,6 +208,7 @@ export interface ChatEntry {
     toolResult?: ToolResult;
     toolGroup?: ToolGroup;
     structuredResponse?: StructuredResponse;
+    reasoning?: string;
 }
 export interface PaymentPrecheck {
     security?: string;
@@ -221,13 +223,17 @@ export interface StructuredResponse {
     taskType: string;
     data: Record<string, unknown>;
 }
-export type CouncilQuestionPhase = "clarify" | "preflight" | "plan-confirm" | "post-debate" | "pil-interview" | "pil-acceptance" | "tool-loop-cap";
+export type CouncilQuestionPhase = "clarify" | "preflight" | "plan-confirm" | "post-debate" | "pil-interview" | "pil-acceptance" | "tool-loop-cap" | "safety-override";
 export type CouncilOptionKind = "choice" | "freetext" | "chat";
 export interface CouncilQuestionOption {
     label: string;
     description?: string;
     value: string;
     kind: CouncilOptionKind;
+    /** Model-driven: if true, picking this cancels the whole interaction (discovery) */
+    isCancel?: boolean;
+    /** Model-driven: if true, picking this triggers a re-interview round (discovery) */
+    isAdjust?: boolean;
 }
 export interface CouncilQuestionData {
     questionId: string;
@@ -413,7 +419,7 @@ export interface ModelInfo {
     supportsVision?: boolean;
 }
 export type AgentMode = "agent" | "plan" | "ask";
-export type SessionStatus = "active" | "completed" | "archived";
+export type SessionStatus = "active" | "completed" | "archived" | "abandoned";
 export type UsageSource = "message" | "title" | "task" | "delegation" | "council" | "other";
 export interface WorkspaceInfo {
     id: string;

package/dist/src/ui/app.d.ts

@@ -14,6 +14,7 @@ import "./slash/council.js";
 import "./slash/ideal.js";
 import "./slash/export.js";
 import "./slash/status.js";
+import "./slash/ponytail.js";
 import type { AppProps } from "./types.js";
 export type { AppStartupConfig } from "./types.js";
 export declare function App({ agent, startupConfig, initialMessage, onExit, onRelaunch }: AppProps): import("react").ReactNode;

package/dist/src/ui/components/council-question-card.js

@@ -8,6 +8,7 @@ const PHASE_LABEL = {
     "pil-interview": "Understanding",
     "pil-acceptance": "Confirm Intent",
     "tool-loop-cap": "Tool-loop guard",
+    "safety-override": "Safety override",
 };
 /**
  * AskUserQuestion-style card. Controlled component — parent owns the state