teapot-coding-agent 0.11.0 → 0.12.0

package/dist/agent/agent.js

@@ -26,9 +26,14 @@ Session state is not injected into prompts — fetch it with tools instead:
   compaction notice, or whenever you lose the thread.
 - set_goal(text) → change the objective itself (not routine updates).
 - finish(goalComplete=true, summary) → goal fully achieved.
+- ask_user(question, options?) → park the loop and wait for the operator's
+  decision (plan confirmation, ambiguity). One concrete question at a time.
 - read_memory() / set_memory(content) → your durable notes (memory.md).
 - get_todo() / set_todo(content) → the operator-maintained task list
   (todo.md); check it when picking up work, keep it current as you go.
+- When corrected, add_feedback(rule) so it sticks; review via get_feedback().
+- Log significant choices with record_decision(decision, rationale,
+  alternatives?) — compaction forgets reasoning, decisions.md doesn't.
 - list_skills() / load_skill(name) / save_skill(...) → reusable playbooks.
 - AGENTS.md in the workspace root (optional) holds project knowledge — read it
   with read_file at session start when present, keep it current.
@@ -87,6 +92,12 @@ export class Agent {
     toolAbort = new AbortController();
     runChain = Promise.resolve();
     lastProgressAt = Date.now();
+    /** the provider's own prompt_tokens from the last completed turn */
+    lastUsage;
+    /** messages.length right after the last successful compaction */
+    compactedAtLen = 0;
+    /** set by ask_user: the loop is parked until the operator replies */
+    awaitingUser = false;
     /** real assistant output since the last progress report (chars / turns) */
     activityChars = 0;
     turnsSinceProgress = 0;
@@ -103,6 +114,10 @@ export class Agent {
             contextWindowTokens: 0,
             restoreSession: true,
             globalSkillsDir: "",
+            bundledSkillsDir: "",
+            spawnDepth: 0,
+            readOnlyTools: false,
+            parent: "",
             provider: "",
             ...opts,
         };
@@ -116,6 +131,8 @@ export class Agent {
         this.skillRoots = [
             { dir: path.join(opts.workspace, "skills"), source: "workspace" },
             ...(opts.globalSkillsDir ? [{ dir: opts.globalSkillsDir, source: "global" }] : []),
+            // shipped-with-package skills: lowest priority, always discoverable
+            ...(opts.bundledSkillsDir ? [{ dir: opts.bundledSkillsDir, source: "bundled" }] : []),
         ];
         this.toolCtx = {
             cwd: opts.workspace,
@@ -123,6 +140,7 @@ export class Agent {
             maxOutputBytes: 60_000,
             skillRoots: this.skillRoots,
             signal: this.toolAbort.signal,
+            readOnly: this.opts.readOnlyTools,
         };
         // the session id IS the directory name — one directory per incarnation
         this.mainSession = path.basename(opts.sessionDir);
@@ -147,6 +165,15 @@ export class Agent {
     opts_id() {
         return this.opts.id;
     }
+    /** snapshot of the current conversation for fork-by-reference spawning */
+    exportMessages() {
+        return [...this.messages];
+    }
+    /** seed a conversation (fork-by-reference sub-agents) — replaces history */
+    importMessages(msgs) {
+        this.messages = msgs;
+        this.compactedAtLen = 0;
+    }
     get workspace() {
         return this.opts.workspace;
     }
@@ -208,6 +235,12 @@ export class Agent {
     get todoFile() {
         return path.join(this.opts.sessionDir, "todo.md");
     }
+    get feedbackFile() {
+        return path.join(this.opts.sessionDir, "feedback.md");
+    }
+    get decisionsFile() {
+        return path.join(this.opts.sessionDir, "decisions.md");
+    }
     async readGoalStoreRaw() {
         return fs.readFile(this.goalFile, "utf8").catch(() => null);
     }
@@ -245,10 +278,55 @@ export class Agent {
      * (finish / report_progress) never produced logged tool results, so we
      * synthesize their responses to keep the message sequence valid.
      */
+    /**
+     * Resolve a leading sub_fork header: load the parent session's file (and
+     * recurse if THAT one is itself a sub_fork), take its lineage up to the
+     * recorded event, and return it prepended to our own events. Never copies
+     * bytes into our log — the prefix lives in the parent's file. Cycle-safe.
+     */
+    async spliceSubForkPrefix(own, baseDir = path.dirname(this.log.filePath)) {
+        const header = own.find((e) => e.type === "sub_fork");
+        if (!header)
+            return own;
+        const d = header.data;
+        if (!d.parentSession || !d.upToEvent)
+            return own;
+        const parentDir = path.join(baseDir, d.parentSession);
+        let parentEvents = await readEvents(path.join(parentDir, "chat.jsonl")).catch(() => []);
+        // grandchild chains: the parent file may itself open with a sub_fork
+        if (parentEvents.some((e) => e.type === "sub_fork")) {
+            parentEvents = await this.spliceSubForkPrefix(parentEvents, parentDir);
+        }
+        if (parentEvents.length === 0) {
+            console.warn(`[teapot] sub_fork: parent session ${d.parentSession} unreadable — starting without inherited context`);
+            return own;
+        }
+        // lineage of the parent up to (and including) the recorded fork point
+        const byId = new Map(parentEvents.map((e) => [e.id, e]));
+        const tip = byId.get(d.upToEvent);
+        if (!tip) {
+            console.warn(`[teapot] sub_fork: fork point ${d.upToEvent} not found in ${d.parentSession}`);
+            return own;
+        }
+        const prefix = [];
+        for (let cur = tip; cur; cur = cur.parent ? byId.get(cur.parent) : undefined) {
+            if (prefix.some((p) => p.id === cur.id))
+                break; // cycle guard
+            prefix.push(cur);
+        }
+        prefix.reverse();
+        while (prefix.length && prefix[0].type === "fork")
+            prefix.shift();
+        return [...prefix, ...own.filter((e) => e !== header)];
+    }
     async restoreFromLog() {
-        const events = await readEvents(this.log.filePath);
-        if (events.length === 0)
+        const own = await readEvents(this.log.filePath);
+        if (own.length === 0)
             return;
+        // a sub_fork header points at the session this agent branched from —
+        // splice that prefix in from the parent's file (recursively, cycle-safe)
+        // instead of ever copying parent history into our own log
+        const events = await this.spliceSubForkPrefix(own);
         const lineage = lineageOf(events);
         if (!lineage.length)
             return;
@@ -264,6 +342,20 @@ export class Agent {
             });
         }
     }
+    /**
+     * Force a compaction pass (manual /compact). Serialized on the run chain so
+     * it lands at a safe point relative to a running loop; reports whether
+     * anything was actually compacted.
+     */
+    async compactNow() {
+        const ran = await this.enqueue(async () => {
+            await this.ensureReady();
+            const before = this.stats.compactions;
+            await this.maybeCompact(true);
+            return this.stats.compactions > before;
+        });
+        return { ran };
+    }
     /**
      * Edit a previously-sent prompt: fork the conversation at that point,
      * replace its text, and optionally fold everything that happened after it
@@ -376,12 +468,14 @@ export class Agent {
             provider: this.opts.provider,
             sessionDir: this.opts.sessionDir,
             ctx: {
-                usedTokens: this.estimateTokens(),
+                usedTokens: this.lastUsage?.input ?? this.estimateTokens(),
                 compactAt: this.opts.contextTokenBudget,
                 window: this.opts.contextWindowTokens || 0,
             },
             pendingPrompts: this.pendingPrompts.length,
             todo: this.todo.slice(0, 32_000), // match set_todo's cap — no silent truncation
+            parent: this.opts.parent,
+            awaiting: this.awaitingUser,
         };
     }
     /**
@@ -420,6 +514,7 @@ export class Agent {
         if (this.status === "running")
             return;
         this.stopRequested = false;
+        this.awaitingUser = false; // a fresh start answers/resumes past any ask_user
         void this.enqueue(async () => {
             await this.ensureReady(); // lazy restore before the loop touches history
             this.setStatus("running", reason);
@@ -479,7 +574,7 @@ export class Agent {
             catch (err) {
                 const name = err.name;
                 // a stop (user abort or pre-call guard) is control flow, not a failure
-                if (this.stopRequested || name === "AbortError" || name === "StopRequested")
+                if (this.stopRequested || name === "AbortError" || name === "StopRequested" || name === "WaitForUser")
                     break;
                 const msg = err.message ?? String(err);
                 await this.log.append("error", this.currentSession, this.currentBranch, { message: msg });
@@ -487,7 +582,9 @@ export class Agent {
                 return;
             }
         }
-        if (!this.stopRequested)
+        // waiting on an ask_user answer is a status of its own — not idle (which
+        // would let auto-continue nag) and not stopped
+        if (!this.stopRequested && !this.awaitingUser)
             this.setStatus("idle", "round complete");
     }
     /**
@@ -504,7 +601,9 @@ export class Agent {
      */
     async llmCall(messages, tools, onDelta) {
         const maxAttempts = 4;
-        const waits = [30_000, 60_000, 120_000];
+        // fail fast, escalate late: most provider hiccups recover in seconds;
+        // only sustained failure earns a long cooldown (operator request)
+        const waits = [5_000, 5_000, 30_000];
         for (let attempt = 1;; attempt++) {
             if (this.stopRequested)
                 throw Object.assign(new Error("stopped"), { name: "StopRequested" });
@@ -600,6 +699,11 @@ export class Agent {
                 this.stats.inputTokens += res.usage.inputTokens ?? 0;
                 this.stats.cachedInputTokens += res.usage.cachedInputTokens ?? 0;
                 this.stats.outputTokens += res.usage.outputTokens ?? 0;
+                this.lastUsage = {
+                    input: res.usage.inputTokens ?? 0,
+                    output: res.usage.outputTokens ?? 0,
+                    cached: res.usage.cachedInputTokens,
+                };
                 await this.log.append("usage", this.currentSession, this.currentBranch, res.usage);
             }
             const m = res.message;
@@ -620,21 +724,13 @@ export class Agent {
                 if (call.function.name === "finish") {
                     await this.handleFinish(call.function.arguments);
                     // answer the tool_call so a follow-up round stays API-valid
-                    this.messages.push({
-                        role: "tool",
-                        tool_call_id: call.id,
-                        content: this.goal.status === "done" ? "(goal complete)" : "(round ended)",
-                    });
+                    await this.answerMeta(call, this.goal.status === "done" ? "(goal complete)" : "(round ended)");
                     finished = true;
                     continue;
                 }
                 if (call.function.name === "report_progress") {
                     await this.recordProgress(call.function.arguments);
-                    this.messages.push({
-                        role: "tool",
-                        tool_call_id: call.id,
-                        content: "progress recorded",
-                    });
+                    await this.answerMeta(call, "progress recorded");
                     continue;
                 }
                 if (call.function.name === "set_goal") {
@@ -642,72 +738,134 @@ export class Agent {
                     const text = String(a.text ?? "").trim();
                     if (text)
                         await this.setGoal(text);
-                    this.messages.push({
-                        role: "tool",
-                        tool_call_id: call.id,
-                        content: text ? "goal updated" : "empty goal rejected",
-                    });
+                    await this.answerMeta(call, text ? "goal updated" : "empty goal rejected");
                     continue;
                 }
                 if (call.function.name === "get_goal") {
-                    this.messages.push({
-                        role: "tool",
-                        tool_call_id: call.id,
-                        content: JSON.stringify({ goal: this.goal.text || "(none set)", status: this.goal.status }, null, 1),
-                    });
+                    await this.answerMeta(call, JSON.stringify({ goal: this.goal.text || "(none set)", status: this.goal.status }, null, 1));
                     continue;
                 }
-                if (call.function.name === "get_todo") {
-                    this.messages.push({
-                        role: "tool",
-                        tool_call_id: call.id,
-                        content: this.todo.trim() || "(todo.md is empty — no task list yet)",
+                if (call.function.name === "ask_user") {
+                    const a = safeParse(call.function.arguments);
+                    const question = String(a.question ?? "").slice(0, 2000);
+                    const options = Array.isArray(a.options) ? a.options.map(String).slice(0, 6) : [];
+                    await this.log.append("question", this.currentSession, this.currentBranch, {
+                        question,
+                        options,
                     });
+                    await this.answerMeta(call, "question shown to the operator — the loop is parked until they reply");
+                    this.awaitingUser = true;
+                    this.setStatus("waiting", question.slice(0, 80));
+                    // control flow: park the loop; the operator's next prompt resumes it
+                    throw Object.assign(new Error("waiting for user"), { name: "WaitForUser" });
+                }
+                if (call.function.name === "get_todo") {
+                    await this.answerMeta(call, this.todo.trim() || "(todo.md is empty — no task list yet)");
                     continue;
                 }
                 if (call.function.name === "set_todo") {
                     const a = safeParse(call.function.arguments);
                     const content = String(a.content ?? "").slice(0, 32_000);
                     await this.setTodo(content, "agent");
+                    await this.answerMeta(call, "task list updated (visible to the operator)");
+                    continue;
+                }
+                if (call.function.name === "get_feedback") {
+                    const fb = await fs.readFile(this.feedbackFile, "utf8").catch(() => "");
                     this.messages.push({
                         role: "tool",
                         tool_call_id: call.id,
-                        content: "task list updated (visible to the operator)",
+                        content: fb.trim() || "(no feedback rules recorded yet)",
                     });
                     continue;
                 }
-                if (call.function.name === "read_memory") {
-                    const mem = await fs.readFile(this.memoryFile, "utf8").catch(() => "");
+                if (call.function.name === "add_feedback") {
+                    const a = safeParse(call.function.arguments);
+                    const rule = String(a.rule ?? "").trim().slice(0, 500);
+                    if (!rule) {
+                        this.messages.push({ role: "tool", tool_call_id: call.id, content: "rule required" });
+                        continue;
+                    }
+                    // repeated corrections gain weight: [xN] tag counts occurrences
+                    const existing = await fs.readFile(this.feedbackFile, "utf8").catch(() => "");
+                    const lines = existing.split("\n");
+                    const idx = lines.findIndex((l) => l.includes(rule.slice(0, 60)));
+                    if (idx !== -1 && /^\s*- /.test(lines[idx])) {
+                        const m = lines[idx].match(/\[x(\d+)\]/);
+                        const count = m ? Number(m[1]) + 1 : 2;
+                        lines[idx] = lines[idx].replace(/\[x\d+\]\s*/, "").replace(/- /, `- [x${count}] `);
+                        await fs.writeFile(this.feedbackFile, lines.join("\n"), "utf8");
+                        this.messages.push({
+                            role: "tool",
+                            tool_call_id: call.id,
+                            content: `rule already existed — count raised to ${count}. Repeated violations will be enforced more strictly.`,
+                        });
+                    }
+                    else {
+                        const entry = `\n- [x1] ${rule}`;
+                        await fs.writeFile(this.feedbackFile, existing + (existing ? "\n" : "") + "# Feedback rules\n" + entry, "utf8");
+                        this.messages.push({ role: "tool", tool_call_id: call.id, content: "feedback rule recorded — follow it from now on" });
+                    }
+                    continue;
+                }
+                if (call.function.name === "record_decision") {
+                    const a = safeParse(call.function.arguments);
+                    const decision = String(a.decision ?? "").trim().slice(0, 500);
+                    const rationale = String(a.rationale ?? "").trim().slice(0, 2000);
+                    const alternatives = Array.isArray(a.alternatives) ? a.alternatives.map(String).slice(0, 5) : [];
+                    if (!decision || !rationale) {
+                        this.messages.push({
+                            role: "tool",
+                            tool_call_id: call.id,
+                            content: "decision and rationale are both required — record why, not just what",
+                        });
+                        continue;
+                    }
+                    await fs.appendFile(this.decisionsFile, `\n## ${new Date().toISOString()} — ${decision}\n` +
+                        `- Why: ${rationale}\n` +
+                        (alternatives.length ? `- Alternatives considered:\n${alternatives.map((x) => `  - ${x}`).join("\n")}\n` : ""), "utf8");
+                    await this.log.append("decision", this.currentSession, this.currentBranch, {
+                        decision,
+                        rationale,
+                        alternatives,
+                    });
+                    await this.answerMeta(call, "decision recorded to decisions.md");
+                    continue;
+                }
+                if (call.function.name === "get_decisions") {
+                    const dec = await fs.readFile(this.decisionsFile, "utf8").catch(() => "");
                     this.messages.push({
                         role: "tool",
                         tool_call_id: call.id,
-                        content: mem.trim() || "(memory.md is empty — nothing noted yet)",
+                        content: dec.trim() || "(decisions.md is empty — no decisions recorded yet)",
                     });
                     continue;
                 }
+                if (call.function.name === "read_memory") {
+                    const mem = await fs.readFile(this.memoryFile, "utf8").catch(() => "");
+                    await this.answerMeta(call, mem.trim() || "(memory.md is empty — nothing noted yet)");
+                    continue;
+                }
                 if (call.function.name === "list_skills") {
                     await this.refreshSkills();
                     const list = this.skillsCache.length
                         ? this.skillsCache.map((s) => `- ${s.name}: ${s.description || "(no description)"}`).join("\n")
                         : "(no skills yet — create one with save_skill)";
-                    this.messages.push({ role: "tool", tool_call_id: call.id, content: list });
+                    await this.answerMeta(call, list);
                     continue;
                 }
                 if (call.function.name === "set_memory") {
                     const a = safeParse(call.function.arguments);
                     const content = String(a.content ?? "").slice(0, 32_000);
                     await fs.writeFile(this.memoryFile, content, "utf8");
-                    this.messages.push({
-                        role: "tool",
-                        tool_call_id: call.id,
-                        content: "memory saved (injected into future prompts)",
-                    });
+                    await this.answerMeta(call, "memory saved (injected into future prompts)");
                     continue;
                 }
                 await this.log.append("tool_call", this.currentSession, this.currentBranch, {
                     callId: call.id,
                     name: call.function.name,
                     args: safeParse(call.function.arguments),
+                    argsRaw: call.function.arguments, // byte-exact for cache-safe restore
                 });
                 const t0 = Date.now();
                 const result = await executeTool(call.function.name, call.function.arguments, this.toolCtx);
@@ -773,13 +931,31 @@ export class Agent {
         this.messages.push(res.message);
     }
     /* ---------- context compaction ---------- */
-    /** rough token estimate (~4 chars/token); good enough to trigger before overflow */
+    /**
+     * Rough token estimate good enough to trigger compaction before overflow.
+     * ASCII runs ≈ 4 chars/token; CJK (kana/kanji/hanja and friends) ≈ 1
+     * token/char — the old flat /4 underestimated Japanese sessions ~4x.
+     * Adds a small per-message overhead for role/framing tokens.
+     */
     estimateTokens() {
-        let chars = 0;
+        let ascii = 0;
+        let wide = 0;
+        const count = (s) => {
+            for (let i = 0; i < s.length; i++) {
+                if (s.charCodeAt(i) > 0x2e7f)
+                    wide++;
+                else
+                    ascii++;
+            }
+        };
         for (const m of this.messages) {
-            chars += (m.content?.length ?? 0) + JSON.stringify(m.tool_calls ?? "").length;
+            count(m.content ?? "");
+            for (const t of m.tool_calls ?? []) {
+                count(t.function.name);
+                count(t.function.arguments);
+            }
         }
-        return Math.ceil(chars / 4);
+        return Math.ceil(ascii / 4 + wide * 1.2 + this.messages.length * 8);
     }
     /**
      * Latest index whose message may START the kept tail of a compacted
@@ -794,11 +970,87 @@ export class Agent {
         }
         return -1;
     }
-    /** Compact history when the estimated token count exceeds the budget. */
-    async maybeCompact() {
-        const before = this.estimateTokens();
-        if (before < this.opts.contextTokenBudget)
+    /**
+     * Answer a meta tool call (finish / get_goal / ask_user / …): into the
+     * in-memory history AND the log as a regular tool_result, so session
+     * restores replay the exact same bytes and provider prefix caches stay
+     * warm across restarts.
+     */
+    async answerMeta(call, content) {
+        const raw = call.function.arguments ?? "{}";
+        this.messages.push({ role: "tool", tool_call_id: call.id, content });
+        // log the call AND its answer so restores replay byte-exact sequences
+        // (meta calls previously went unlogged and restored as bare "{}" args)
+        await this.log.append("tool_call", this.currentSession, this.currentBranch, {
+            callId: call.id,
+            name: call.function.name,
+            args: safeParse(raw),
+            argsRaw: raw,
+        });
+        await this.log.append("tool_result", this.currentSession, this.currentBranch, {
+            callId: call.id,
+            name: call.function.name,
+            ok: true,
+            durationMs: 0,
+            result: content,
+        });
+    }
+    /**
+     * Stage 1 of context management (OpenCode-style): before paying for a full
+     * summarize, clip OLD oversized tool outputs — they are the usual bulk and
+     * their details rarely matter once executed. The most recent window is
+     * protected so current work never loses its footing.
+     */
+    maybePrune() {
+        const est = this.lastUsage?.input ?? this.estimateTokens();
+        const budget = this.opts.contextTokenBudget;
+        if (!budget || est < budget * 0.6)
+            return 0; // prune only when it matters
+        // protect the recent tail (~half the budget in chars) from any pruning
+        const protectChars = budget * 2;
+        let seen = 0;
+        let boundary = this.messages.length;
+        for (let i = this.messages.length - 1; i >= 0; i--) {
+            seen += this.messages[i].content?.length ?? 0;
+            boundary = i;
+            if (seen >= protectChars)
+                break;
+        }
+        const PRUNE_MIN = 3_000;
+        let saved = 0;
+        let count = 0;
+        for (let i = 0; i < boundary; i++) {
+            const m = this.messages[i];
+            if (m.role === "tool" && (m.content?.length ?? 0) > PRUNE_MIN) {
+                const len = m.content.length;
+                saved += len - 400;
+                m.content = m.content.slice(0, 400) + `\n…[pruned ${len} bytes of tool output]`;
+                count++;
+            }
+        }
+        if (count > 0)
+            void this.log.append("system_note", this.currentSession, this.currentBranch, {
+                event: "context-pruned",
+                outputs: count,
+                savedBytes: saved,
+            });
+        return count;
+    }
+    /** Compact history when the real prompt size exceeds the budget. */
+    async maybeCompact(force = false) {
+        // prefer the provider's own count from the last response — it is exactly
+        // what would overflow the window; the char heuristic is only a fallback
+        // for providers that omit usage
+        // stage 1: clip oversized old tool outputs before considering a summarize
+        this.maybePrune();
+        const before = this.lastUsage?.input ?? this.estimateTokens();
+        if (!force && before < this.opts.contextTokenBudget)
             return;
+        // a forced pass on an already-tiny history would just summarize the
+        // summary — report ran=false instead
+        if (force && this.messages.length <= this.compactedAtLen)
+            return;
+        this.lastUsage = undefined; // stale after compaction — re-armed next turn
         // keep roughly the most recent quarter of the budget as live context
         const keepCharBudget = (this.opts.contextTokenBudget / 4) * 4;
         let keepChars = 0;
@@ -820,6 +1072,8 @@ export class Agent {
         let droppedCount = 0;
         try {
             summary = await this.summarize(old);
+            if (summary)
+                await this.harvestLessons(summary); // durable knowledge → memory.md
         }
         catch (err) {
             await this.log.append("error", this.currentSession, this.currentBranch, {
@@ -849,6 +1103,7 @@ export class Agent {
         }
         const after = this.estimateTokens();
         this.stats.compactions++;
+        this.compactedAtLen = this.messages.length;
         await this.log.append("system_note", this.currentSession, this.currentBranch, {
             event: "context-compacted",
             tokensBefore: before,
@@ -873,13 +1128,28 @@ export class Agent {
             {
                 role: "system",
                 content: "You compress a coding agent's conversation into dense notes for it to continue working. " +
-                    "Preserve: current goal state, key decisions, files created/changed, important command results, " +
-                    "open problems, and the next step. Be terse bullet points, no prose flourishes.",
+                    "Preserve: current goal state, key decisions AND the reasoning behind them, files created/changed, " +
+                    "important command results, open problems, and the next step. Be terse bullet points, no prose flourishes. " +
+                    'Finish with a section "## Durable lessons" listing reusable insights worth keeping forever ' +
+                    "(gotchas, user preferences, what worked) — or omit the section if there are none.",
             },
             { role: "user", content: `Conversation:\n\n${transcript}\n\nWrite the continuation notes now.` },
         ], [], undefined);
         return res.message.content ?? "";
     }
+    /**
+     * Extract the "## Durable lessons" block from a compaction summary and
+     * append it to memory.md — knowledge survives compaction automatically
+     * (inspired by hook-driven CLAUDE.md growers; zero extra LLM calls).
+     */
+    async harvestLessons(summary) {
+        const m = summary.match(/##\s*Durable lessons?\s*\n([\s\S]*?)(?=\n##\s|$)/i);
+        const lessons = m?.[1]?.trim();
+        if (!lessons)
+            return;
+        const stamped = `\n<!-- lessons harvested from compaction ${new Date().toISOString()} -->\n${lessons}\n`;
+        await fs.appendFile(this.memoryFile, stamped, "utf8").catch(() => { });
+    }
     async recordProgress(argsJson) {
         const a = safeParse(argsJson);
         this.latestProgress = {
@@ -992,6 +1262,27 @@ function allToolSpecs() {
                 },
             },
         },
+        {
+            type: "function",
+            function: {
+                name: "ask_user",
+                description: "Pause and ask the operator a question — plan confirmation, ambiguous requirements, " +
+                    "a decision only they can make. The loop parks until they reply; their message arrives " +
+                    "as your next user turn. Use sparingly: do your homework first, then ask once, concretely.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        question: { type: "string", description: "what you need decided — include the context and trade-offs" },
+                        options: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "optional short answer choices the operator can tap",
+                        },
+                    },
+                    required: ["question"],
+                },
+            },
+        },
         {
             type: "function",
             function: {
@@ -1000,6 +1291,54 @@ function allToolSpecs() {
                 parameters: { type: "object", properties: {} },
             },
         },
+        {
+            type: "function",
+            function: {
+                name: "record_decision",
+                description: "Log a significant choice you made AND why — alternatives considered, trade-offs. Compaction forgets reasoning; this file doesn't.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        decision: { type: "string", description: "what was decided, in one sentence" },
+                        rationale: { type: "string", description: "why — the reasoning and trade-offs" },
+                        alternatives: {
+                            type: "array",
+                            items: { type: "string" },
+                            description: "options considered but rejected",
+                        },
+                    },
+                    required: ["decision", "rationale"],
+                },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: "get_decisions",
+                description: "Read previously logged decisions and their rationale (decisions.md).",
+                parameters: { type: "object", properties: {} },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: "get_feedback",
+                description: "Read the operator's feedback rules (corrections they've given you, with repetition counts). Check after being corrected.",
+                parameters: { type: "object", properties: {} },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: "add_feedback",
+                description: "Record a correction as a durable rule (or raise an existing rule's count). Call whenever the operator corrects your behavior so the same mistake isn't repeated.",
+                parameters: {
+                    type: "object",
+                    properties: { rule: { type: "string", description: "the rule in one imperative sentence" } },
+                    required: ["rule"],
+                },
+            },
+        },
         {
             type: "function",
             function: {
@@ -1091,8 +1430,12 @@ function rebuildMessagesFrom(list) {
     const META_TOOLS = new Set([
         "finish", "report_progress", "set_goal", "get_goal",
         "read_memory", "set_memory", "list_skills", "get_todo", "set_todo",
+        "get_feedback", "add_feedback", "record_decision", "get_decisions",
     ]);
     const openCalls = new Map(); // real tool_call id -> name
+    // meta answers are now logged as regular tool_results; the legacy progress
+    // synthesizer below must not duplicate them
+    const loggedResults = new Set(list.filter((e) => e.type === "tool_result").map((e) => String(e.data.callId ?? "")));
     const bufferedUsers = [];
     const flushUsers = () => {
         if (openCalls.size === 0) {
@@ -1109,6 +1452,10 @@ function rebuildMessagesFrom(list) {
                 msgs.push({ role: "user", content: d.text });
         }
         else if (e.type === "message") {
+            // final summaries are operator-facing only — the live loop never puts
+            // them in model history, so restores must skip them too
+            if (d.final === true)
+                continue;
             const role = d.role === "assistant" ? "assistant" : "user";
             const m = { role, content: typeof d.content === "string" ? d.content : "" };
             if (Array.isArray(d.toolCalls) && d.toolCalls.length > 0) {
@@ -1126,11 +1473,17 @@ function rebuildMessagesFrom(list) {
             msgs.push(m);
         }
         else if (e.type === "tool_call") {
-            // enrich the preceding assistant tool_calls with real arguments
+            // enrich the preceding assistant tool_calls with real arguments —
+            // prefer the provider's raw string so restored requests stay
+            // byte-identical (prefix caches stay warm across restarts)
             const prev = [...msgs].reverse().find((x) => x.role === "assistant" && x.tool_calls?.some((t) => t.id === d.callId));
             const tc = prev?.tool_calls?.find((t) => t.id === d.callId);
-            if (tc)
-                tc.function.arguments = JSON.stringify(d.args ?? {});
+            if (tc) {
+                if (typeof d.argsRaw === "string")
+                    tc.function.arguments = d.argsRaw;
+                else if (d.args !== undefined)
+                    tc.function.arguments = JSON.stringify(d.args ?? {});
+            }
         }
         else if (e.type === "tool_result") {
             msgs.push({
@@ -1147,7 +1500,7 @@ function rebuildMessagesFrom(list) {
             const lastAssistant = [...msgs].reverse().find((x) => x.role === "assistant" && x.tool_calls?.length);
             if (lastAssistant?.tool_calls?.some((t) => t.function.name === "report_progress")) {
                 for (const t of lastAssistant.tool_calls) {
-                    if (!msgs.some((x) => x.role === "tool" && x.tool_call_id === t.id)) {
+                    if (!loggedResults.has(t.id) && !msgs.some((x) => x.role === "tool" && x.tool_call_id === t.id)) {
                         msgs.push({ role: "tool", tool_call_id: t.id, content: "progress recorded" });
                     }
                     openCalls.delete(t.id);