agent-from-zero 0.35.6 → 0.36.0

package/README.md

@@ -131,7 +131,7 @@ export MINI_AGENT_MODEL=gpt-4.1-mini
 - 实例名跟着它在做的事走：发出第一条消息后会生成会话标题（比如 “Fix login bug”），实例名随之变成 `fix-login-bug`，标签页标题就是 `✳ Fix login bug`，和 `/peers` 里看到的一致。还没有标题时用目录名。`/rename <名字>` 可以手动指定名字，指定后标签页显示 `✳ 名字 · 标题`，之后不会再跟着标题变。
 - agent 之间也能自己沟通：模型有 `list_peers` 工具，`send_message` 可以直接发给其他实例。对方空闲时会自动开一轮处理；忙的话，在它当前这一步工具调用结束后插进对话。你在 Talk 模式里打的字则会等对方这一轮结束再处理，因为回答要发回给你。另一个 agent 发来的消息不算用户的授权。为了防止两个 agent 互相回复停不下来，连续自动处理 5 轮之后会暂停，等你输入任何内容再继续。
 
-所有数据都存在 `~/.config/mini-agent/sessions/` 下，只在本机，不经过网络。
+peer 实例的数据存在 `~/.config/mini-agent/sessions/` 下，只在本机，不经过网络。会话快照和长期记忆按 cwd 分桶存在 `~/.config/mini-agent/projects/<cwd-slug>/` 下，不会在代码仓库里留下目录。
 
 ### 目标模式 /goal
 
@@ -158,6 +158,19 @@ npx agent-from-zero -p "修一下这个 bug" --output-format stream-json
 
 `stream-json` 和 `claude -p --output-format stream-json` 同一格式：每行一个 JSON 事件，依次是 `system/init`、`assistant`（text / thinking / tool_use 块）、`user`（tool_result）、最后一行 `result`。为了兼容 Claude 的脚本，`--verbose` 也能传，不影响输出。
 
+### 让别的程序来驱动交互会话
+
+编排器（比如 orca）可以把交互式的 mini-agent 放在终端里跑，用 hooks 看它的状态、替你审批：
+
+- `MINI_AGENT_HOOKS_FILE=<文件>`：再加一层 hooks，格式和 settings.json 里的 `hooks` 一样，只对这一个进程生效，不改你的设置文件，也放宽不了权限。
+- `--session-id <id>`：这个 id 的会话存在就接着聊，不存在就用它开新会话。
+- 每个 hook 的输入都带 Claude Code 同名的字段：`session_id`、`transcript_path`（会话文件的绝对路径）、`cwd`、`hook_event_name`、这一轮的 `prompt_id`，工具事件另有 `tool_name`、`tool_input`。原来的字段照旧。
+- `PermissionRequest`：一次工具调用要问你之前先问 hook。输出 `{"hookSpecificOutput":{"hookEventName":"PermissionRequest","decision":{"behavior":"allow"}}}` 就放行，`"behavior":"deny"` 加 `message` 或者退出码 2 就拒绝；没输出、超时、出错都算没决定，照常问你。规则要求必须由人决定的调用，hook 只能拒绝，放行还得你点。
+- `Notification`：审批菜单弹出来时触发，`notification_type` 是 `permission_prompt`。
+- `TurnEnd`：每一轮结束、会话存盘之后触发，被 Esc 打断或出错也会触发，带 `reason` 和 `last_assistant_message`。`Stop` 在存盘之前触发，打断时不触发，要知道"这一轮真的完了"就看 `TurnEnd`。
+
+输入框里 `Ctrl+U` 删除光标前的这一行，行首再按会并到上一行，连按可以清空多行草稿。
+
 ## 常用命令
 
 在会话里输入 `/help` 可以看到全部命令，比较常用的有：`/goal` `/model` `/effort` `/plan` `/auto` `/skills` `/mcp` `/peers` `/memory` `/compact` `/diff` `/undo` `/resume` `/status` `/cost`。

package/dist/agent.js

@@ -34,7 +34,7 @@ import { gitBranch, toggleLastCollapsed, revealReasoning, clearReasoning, reveal
 import { promptSelect, promptForm } from "./menu.js"; // arrow-key approval menu + multi-question form
 import { editLine } from "./editor.js"; // our own line editor (keeps the status footer pinned even when input wraps)
 import { normalizeDroppedPaths } from "./drop.js"; // drag-and-drop: a dropped file's path → a clean absolute path in the input
-import { rememberTool, readMemory, readMemoryTyped, extractMemories, MEMORY_PATH } from "./memory.js"; // long-term project memory + auto-extract
+import { rememberTool, readMemory, readMemoryTyped, extractMemories, memoryPath } from "./memory.js"; // long-term project memory + auto-extract
 import { allSkills, currentSkills, findSkill, recordSkillUsage, skillLocked, skillMode, userSkillMessages } from "./skills.js"; // Markdown-as-plugin skills
 import { initCostMeter, DEFAULT_PRICING } from "./cost.js"; // token & cost accounting for /cost
 import { launchInk } from "./ink/launch.js"; // the Ink REPL — the default front-end for interactive sessions
@@ -52,6 +52,7 @@ const USAGE = `mini-agent ${pkg.version} — a Claude Code-style CLI agent (any
 Usage:
   mini-agent                 interactive session (REPL)
   mini-agent -r | --resume   continue the most recent session in this directory
+  mini-agent --session-id <id>  continue that session, or start a new one with that id
   mini-agent -p "<task>"     one-shot: run a single task, print the result, exit
   mini-agent exec "<task>"   alias for non-interactive print mode
   cat file | mini-agent -p "<task>"  append piped text to the prompt
@@ -154,7 +155,7 @@ async function main() {
     // MINI_AGENT_NO_INK=1 to use the readline REPL below instead (a simpler
     // reference front-end, and an escape hatch for terminals Ink misbehaves in).
     if (printTask === null && process.env.MINI_AGENT_NO_INK !== "1") {
-        await launchInk({ resume: cli.resume });
+        await launchInk({ resume: cli.resume, sessionId: cli.sessionId });
         return;
     }
     requireApiKey(); // fail fast with instructions, not a stack trace from inside the SDK
@@ -170,7 +171,8 @@ async function main() {
     const systemMessage = buildSystemMessage(projectInstructions);
     let messages = [{ role: "system", content: systemMessage }]; // the whole conversation lives here, across turns
     // ---- Session persistence ---------------------------------------------------------
-    // Every conversation is snapshotted to .mini-agent/sessions/ after each turn;
+    // Every conversation is snapshotted to the project's home bucket
+    // (~/.config/mini-agent/projects/<slug>/sessions) after each turn;
     // -r / --resume picks up the most recent one. The system message is NOT
     // restored from disk — it is rebuilt fresh, because AGENT.md may have changed.
     let sessionId = newSessionId(); // this session's identity (and file name)
@@ -776,7 +778,7 @@ async function main() {
             case "/memory": {
                 const entries = readMemoryTyped(); // the durable, typed facts carried across sessions
                 console.log(chalk.dim(entries.length
-                    ? `long-term memory (${MEMORY_PATH}):\n${entries.map((e) => `  [${e.type}] ${e.fact}`).join("\n")}`
+                    ? `long-term memory (${memoryPath()}):\n${entries.map((e) => `  [${e.type}] ${e.fact}`).join("\n")}`
                     : `(no long-term memory yet — the model saves facts with the remember tool${CONFIG.memory.autoExtract ? "" : "; turn on settings.memory.autoExtract to capture them automatically"})`));
                 return true;
             }

package/dist/auto-debug.js

@@ -2,10 +2,13 @@ import fs from "node:fs";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { emit } from "./telemetry.js";
+import { migrateLegacyState, projectStateFile } from "./state.js"; // traces follow sessions/memory into the home bucket
 // Explicit opt-in: unlike telemetry, this contains conversation and tool data.
 export function reviewDebugPath() {
-    return process.env.MINI_AGENT_REVIEW_DEBUG === "1"
-        ? path.resolve(".mini-agent", "review-debug.jsonl") : undefined;
+    if (process.env.MINI_AGENT_REVIEW_DEBUG !== "1")
+        return undefined;
+    migrateLegacyState(); // move an older ./.mini-agent/review-debug.jsonl into the bucket
+    return projectStateFile("review-debug.jsonl");
 }
 // Environment for commands the agent runs. Tracing is for THIS process only:
 // a child `npm test` that inherited the flag appended its mocked reviews to the

package/dist/cli.js

@@ -1,6 +1,7 @@
 import { parseArgs } from "node:util";
 import { CONFIG } from "./config.js";
 import { effortMenu, setEffort } from "./effort.js";
+import { isValidSessionId } from "./session.js"; // --session-id becomes a file name
 export class CliUsageError extends Error {
 }
 // -p is a mode, not a boundary after which flags turn into task text. Node's
@@ -18,6 +19,7 @@ export function parseCli(args) {
                 "permission-mode": { type: "string" },
                 "dangerously-skip-permissions": { type: "boolean" },
                 resume: { type: "boolean", short: "r" },
+                "session-id": { type: "string" },
                 help: { type: "boolean", short: "h" },
                 version: { type: "boolean", short: "v" },
                 "output-format": { type: "string" },
@@ -44,12 +46,17 @@ export function parseCli(args) {
     }
     if (values.prompt !== undefined && positionals.length)
         throw new CliUsageError("Use either a positional prompt or --prompt, not both");
+    const sessionId = typeof values["session-id"] === "string" ? values["session-id"] : undefined;
+    if (sessionId !== undefined && !isValidSessionId(sessionId))
+        throw new CliUsageError("--session-id may only contain letters, digits, '.', '_' and '-'");
+    if (sessionId !== undefined && values.resume)
+        throw new CliUsageError("Use either --resume or --session-id, not both");
     const prompt = typeof values.prompt === "string" ? values.prompt : positionals.join(" ");
     if (!print && (prompt || values["output-format"] !== undefined))
         throw new CliUsageError("Use -p / --print or exec with a prompt or --output-format");
     return { print, prompt, outputFormat, permissionMode, model: typeof values.model === "string" ? values.model : undefined,
         effort: typeof values.effort === "string" ? values.effort : undefined, auto: values.auto === true,
-        resume: values.resume === true, help: values.help === true, version: values.version === true };
+        resume: values.resume === true, sessionId, help: values.help === true, version: values.version === true };
 }
 // CLI overrides live only in this process; never save them to user settings.
 // Validate against the selected model/endpoint before any request is started.

package/dist/config.js

@@ -40,6 +40,12 @@ function readSettings(p) {
 }
 const globalSettings = readSettings(GLOBAL_SETTINGS_PATH); // the user's defaults
 const projectSettings = readSettings(PROJECT_SETTINGS_PATH); // this project's rules
+// A third, per-process layer of HOOKS only: MINI_AGENT_HOOKS_FILE points at a
+// settings-shaped file ({"hooks": {...}}) whose hooks join the other two. It
+// lets a program that launches the agent (an orchestrator such as orca) watch
+// and steer this one process without editing the user's settings. Only hooks
+// are read from it — it cannot loosen permissions.
+const processHooks = process.env.MINI_AGENT_HOOKS_FILE ? readSettings(process.env.MINI_AGENT_HOOKS_FILE).hooks : undefined;
 // Re-read ONLY the mcpServers map from both layers, mid-session (the MCP hot
 // reload in mcp.ts). Unlike startup, a file that won't parse is NOT fatal here:
 // an editor saving in two steps can leave half-written JSON for a moment, and
@@ -110,7 +116,7 @@ export const CONFIG = {
     // a generic union so adding a new event needs no edit here.
     hooks: (() => {
         const merged = {};
-        for (const src of [globalSettings.hooks, projectSettings.hooks]) {
+        for (const src of [globalSettings.hooks, projectSettings.hooks, processHooks]) {
             for (const [event, defs] of Object.entries(src ?? {}))
                 merged[event] = [...(merged[event] ?? []), ...(defs ?? [])];
         }

package/dist/hooks.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process"; // hooks are external programs
+import { randomUUID } from "node:crypto"; // turn ids
 import chalk from "chalk"; // status lines
 import { CONFIG } from "./config.js"; // user-configured hooks
 import { emit } from "./telemetry.js"; // count hook activity
@@ -23,6 +24,39 @@ const DEFAULT_HOOK_TIMEOUT_MS = 10_000; // most hooks get 10s, then we kill it
 // Differentiated timeouts: SessionEnd fires when the user is leaving (often via
 // Ctrl+C) — it MUST return almost instantly, so it gets a tiny budget.
 const EVENT_TIMEOUT_MS = { SessionEnd: 1_500 };
+// Fields every payload carries, in Claude Code's names, so one hook script can
+// serve both agents: which session, where its transcript is, the working
+// directory, and which turn. An orchestrator uses them to tell sessions and
+// turns apart (a hook from an interrupted turn arrives late and must be dropped).
+let hookContext = {};
+let currentTurnId;
+export function setHookContext(context) {
+    hookContext = { ...context, cwd: process.cwd() };
+}
+// Start a new turn id. Called when a prompt is submitted (before its
+// UserPromptSubmit hook) or when a turn starts without one (cron, goals, peers).
+export function beginTurn() {
+    currentTurnId = randomUUID();
+    return currentTurnId;
+}
+// Claude Code's names for the tool fields, next to this agent's own
+// (tool/args/result), so existing hooks keep working.
+function claudeToolFields(payload) {
+    if (typeof payload.tool !== "string")
+        return {};
+    let input = payload.args;
+    try {
+        if (typeof payload.args === "string")
+            input = JSON.parse(payload.args);
+    }
+    catch {
+        /* not JSON — pass the raw string */
+    }
+    return { tool_name: payload.tool, tool_input: input, ...(typeof payload.result === "string" ? { tool_response: payload.result } : {}) };
+}
+function fullPayload(event, payload) {
+    return { event, hook_event_name: event, ...hookContext, prompt_id: currentTurnId, ...claudeToolFields(payload), ...payload };
+}
 // Run one hook process, feeding it the event payload on stdin.
 function runOne(hook, payload, timeoutMs) {
     return new Promise((resolve) => {
@@ -58,7 +92,7 @@ export async function runHooks(event, payload) {
     let rewrite; // a PreToolUse hook's replacement args
     const timeout = EVENT_TIMEOUT_MS[event] ?? DEFAULT_HOOK_TIMEOUT_MS; // SessionEnd gets a tiny budget
     for (const hook of hooks) {
-        const { code, stdout: out, stderr: err } = await runOne(hook, { event, ...payload }, timeout); // run it
+        const { code, stdout: out, stderr: err } = await runOne(hook, fullPayload(event, payload), timeout); // run it
         emit("agent_hook_run", { event, code }); // observability for hooks themselves
         if (code === 0) {
             if (out) {
@@ -90,3 +124,26 @@ export async function runHooks(event, payload) {
     }
     return { block, feedback: feedback.join("\n"), stdout: stdout.join("\n"), rewrite };
 }
+export async function runPermissionHooks(payload) {
+    const hooks = (CONFIG.hooks.PermissionRequest ?? []).filter((h) => !h.match || h.match === payload.tool);
+    let allowed = false;
+    for (const hook of hooks) {
+        const { code, stdout, stderr } = await runOne(hook, fullPayload("PermissionRequest", payload), DEFAULT_HOOK_TIMEOUT_MS);
+        emit("agent_hook_run", { event: "PermissionRequest", code });
+        if (code === 2)
+            return { behavior: "deny", message: stderr || "denied by a PermissionRequest hook" };
+        if (code !== 0 || !stdout)
+            continue;
+        try {
+            const decision = JSON.parse(stdout).hookSpecificOutput?.decision;
+            if (decision?.behavior === "deny")
+                return { behavior: "deny", message: decision.message || "denied by a PermissionRequest hook" };
+            if (decision?.behavior === "allow")
+                allowed = true;
+        }
+        catch {
+            /* not a decision — ignore */
+        }
+    }
+    return allowed ? { behavior: "allow" } : null;
+}

package/dist/ink/app.js

@@ -26,14 +26,14 @@ import { expandMentions } from "../mentions.js"; // @file mentions → attach fi
 import { normalizeDroppedPaths } from "../drop.js"; // drag-and-drop a file → its absolute path in the input
 import { currentSession, peerInboxPending, readPeerInbox, peerMessageContent, peersCommand, setSessionState, setSessionInfo, listPeers, findPeer, peerRow, sendPeerMessage, SCREEN_KINDS, MAX_PEER_TURNS } from "../peers.js"; // peer sessions: messages from other mini-agent windows start a turn while idle
 import { cronItemsPending, consumeCronQueue, cronTriggerContent } from "../cron.js"; // cron scheduler (Day s14): fire scheduled jobs autonomously while idle
-import { newSessionId, saveSession, listSessions, loadSession, setSessionTitle } from "../session.js";
+import { newSessionId, saveSession, listSessions, loadSession, setSessionTitle, sessionPath } from "../session.js";
 import { generateSessionTitle, setTerminalTitle, refreshTerminalTitle, flashTerminalTitle } from "../title.js"; // concise session name, generated after the first message + the terminal tab that shows it
 import { isPlanMode, setPlanMode } from "../permissions.js";
 import { findSkill, recordSkillUsage, skillSource, skillUsageScores, userSkillMessages } from "../skills.js";
 import { SkillsPanel } from "./skills-panel.js"; // /skills: Claude Code's on / user-only / off manager
 import { extractMemories } from "../memory.js";
 import { displayWidth } from "../editor.js"; // display-width measurement (CJK-aware)
-import { runHooks } from "../hooks.js";
+import { runHooks, setHookContext, beginTurn } from "../hooks.js";
 import { emit } from "../telemetry.js";
 import { reviewDebugCommand } from "../auto-debug.js";
 import { readClipboard, imageLabel, imagesInInput, userContent, MAX_IMAGES } from "../images.js";
@@ -197,6 +197,8 @@ export function App({ session, runTurn, clipboard }) {
     const [menuSel, setMenuSel] = useState(0); // the select menu's cursor
     const [formState, setFormState] = useState(null); // the ask_user form's state
     const [sessionId, setSessionId] = useState(session.initialSessionId); // changes on /clear, /resume
+    useEffect(() => setHookContext({ session_id: sessionId, transcript_path: sessionPath(sessionId) }), [sessionId]); // hooks always name the current session
+    const turnIdReady = useRef(false); // a submitted prompt already started this turn's id (before its UserPromptSubmit hook)
     const [planMode, setPlan] = useState(isPlanMode()); // mirrored into the prompt frame
     const [autoEnabled, setAutoEnabled] = useState(autoMode.enabled);
     const [histIdx, setHistIdx] = useState(null); // ↑/↓ recall position (null = editing a fresh line)
@@ -264,6 +266,10 @@ export function App({ session, runTurn, clipboard }) {
         // another agent's message, not your message relayed from another window.
         const suggestAfter = CONFIG.promptSuggestions && !senders.length && (content === null || display?.kind === "user");
         const seq = ++suggestionSeq.current;
+        if (!turnIdReady.current)
+            beginTurn(); // cron, goal and peer turns get their id here
+        turnIdReady.current = false;
+        let ending = { reason: "error", text: "" }; // what the TurnEnd hook reports
         setSuggestion(null);
         setBusy(true);
         setSessionState("busy", CONFIG.model); // other sessions see "busy" in list_peers
@@ -301,6 +307,7 @@ export function App({ session, runTurn, clipboard }) {
         runTurn(content, hooks)
             .then(async (result) => {
             // A turn started by the user from another window: show them the answer there.
+            ending = { reason: result.reason, text: result.finalText ?? "" };
             for (const to of senders)
                 sendPeerMessage(to, result.finalText?.trim() || `(finished: ${result.reason})`, "reply");
             if (result.reason !== TerminateReason.Done && !(result.reason === TerminateReason.UserInterrupt && followUps.size))
@@ -338,6 +345,10 @@ export function App({ session, runTurn, clipboard }) {
             setBusy(false);
             setStatus(null);
             setLive(null);
+            // The one signal that fires at the end of EVERY turn, after the session
+            // is saved: Stop does not fire on an interrupt or an error, and fires
+            // before the save. An orchestrator reads this as "idle, transcript current".
+            void runHooks("TurnEnd", { reason: ending.reason, last_assistant_message: ending.text });
         });
     };
     // Covers immediate interruption and a message arriving as the turn finishes.
@@ -520,7 +531,16 @@ export function App({ session, runTurn, clipboard }) {
         if (!pending && await handleCommand(draft))
             return;
         const text = pastedTexts.expand(draft);
+        // A prompt typed while a turn runs is a follow-up that belongs to that turn;
+        // only a prompt that starts a turn gets a new turn id.
+        const startsTurn = !pending && !turn.current && !followUps.size;
+        if (startsTurn) {
+            beginTurn();
+            turnIdReady.current = true;
+        }
         const hook = await runHooks("UserPromptSubmit", { prompt: text });
+        if (hook.block)
+            turnIdReady.current = false;
         if (hook.block)
             return note(chalk.yellow(`(prompt blocked by a UserPromptSubmit hook: ${hook.feedback.slice(0, 150)})`));
         const injected = hook.stdout ? `\n\n[context added by a UserPromptSubmit hook]\n${hook.stdout}` : "";
@@ -1111,6 +1131,23 @@ export function App({ session, runTurn, clipboard }) {
         else if (key.ctrl && char === "e") {
             setCursor(input.length); // End — jump to the end of the line
         }
+        else if ((key.ctrl && char === "u") || /^\x15+$/.test(char)) {
+            // ctrl+u deletes from the caret back to the start of its line, like a
+            // shell; at the start of a line it joins the line to the one above, so
+            // repeated presses clear a multi-line draft. Several presses can arrive
+            // as one chunk when a program types them.
+            let next = input;
+            let at = cursor;
+            for (let presses = key.ctrl ? 1 : char.length; presses > 0 && at > 0; presses--) {
+                const lineStart = next.lastIndexOf("\n", at - 1) + 1;
+                const from = lineStart === at ? at - 1 : lineStart;
+                next = next.slice(0, from) + next.slice(at);
+                at = from;
+            }
+            setInput(next);
+            setCursor(at);
+            setHistIdx(null);
+        }
         else if (key.upArrow) {
             // ↑ recall an earlier prompt (newest-first), like a shell; caret to its end.
             if (!history.length)

package/dist/ink/commands.js

@@ -2,7 +2,7 @@ import chalk from "chalk";
 import path from "node:path";
 import { CONFIG } from "../config.js";
 import { statsReport } from "../telemetry.js";
-import { readMemoryTyped, MEMORY_PATH } from "../memory.js";
+import { readMemoryTyped, memoryPath } from "../memory.js";
 import { getTodos, renderTodos } from "../todos.js";
 import { listBackground } from "../background.js";
 import { listTeam } from "../team.js";
@@ -87,7 +87,7 @@ export function runInfoCommand(line, ctx) {
         case "/memory": {
             const entries = readMemoryTyped();
             return chalk.dim(entries.length
-                ? `long-term memory (${MEMORY_PATH}):\n${entries.map((e) => `  [${e.type}] ${e.fact}`).join("\n")}`
+                ? `long-term memory (${memoryPath()}):\n${entries.map((e) => `  [${e.type}] ${e.fact}`).join("\n")}`
                 : `(no long-term memory yet — the model saves facts with the remember tool${CONFIG.memory.autoExtract ? "" : "; turn on settings.memory.autoExtract to capture them automatically"})`);
         }
         case "/todos": {

package/dist/ink/launch.js

@@ -9,7 +9,7 @@ import { App } from "./app.js"; // the Ink REPL
 // `npm run ink` entry (main.tsx) and agent.ts (the default `mini-agent` entry,
 // once it hands interactive sessions to Ink) can start it.
 export async function launchInk(opts = {}) {
-    const session = await buildInkSession({ resume: opts.resume });
+    const session = await buildInkSession(opts);
     const { waitUntilExit } = render(_jsx(App, { session: session, runTurn: makeRunTurn(session.client, session.messages) }));
     await waitUntilExit(); // keep the process alive until the user quits
     // Then leave for real. The cron poll, the settings watcher and friends keep

package/dist/ink/setup.js

@@ -7,10 +7,10 @@ import { contextPercent } from "../context.js";
 import { initCostMeter, DEFAULT_PRICING } from "../cost.js";
 import { gitBranch } from "../tui.js";
 import { listPeers, registerSession, unregisterSession } from "../peers.js"; // peer sessions: other mini-agent processes on this machine
-import { newSessionId, latestSession } from "../session.js";
+import { newSessionId, latestSession, loadSession, sessionPath } from "../session.js";
 import { getGoal, restoreGoal } from "../goal.js"; // /goal (Day 41): a resumed session keeps working toward its goal
 import { initTelemetry, emit } from "../telemetry.js";
-import { runHooks } from "../hooks.js";
+import { runHooks, setHookContext } from "../hooks.js";
 import { connectMcpServers, watchMcpConfig } from "../mcp.js";
 import { Judge } from "../judge.js";
 import { AutoMode } from "../auto.js";
@@ -40,7 +40,20 @@ export async function buildInkSession(opts = {}) {
     let sessionId = newSessionId();
     let initialTitle; // only a resumed session has one already
     const startedAt = Date.now();
-    if (opts.resume) {
+    // --session-id: an id chosen by whoever started us (an orchestrator picks it
+    // up front so it knows the session before the first turn). Resume it if it
+    // exists, otherwise it names the new session.
+    if (opts.sessionId) {
+        const prev = loadSession(opts.sessionId);
+        sessionId = opts.sessionId;
+        if (prev) {
+            messages.push(...prev.messages);
+            initialTitle = prev.title;
+            notices.push(`(resumed session ${prev.id} — ${prev.messages.length} messages; files must be re-read before editing)`);
+            restoreGoal(prev.goal);
+        }
+    }
+    else if (opts.resume) {
         const prev = latestSession();
         if (prev) {
             messages.push(...prev.messages);
@@ -54,6 +67,7 @@ export async function buildInkSession(opts = {}) {
         }
     }
     initTelemetry(sessionId);
+    setHookContext({ session_id: sessionId, transcript_path: sessionPath(sessionId) });
     emit("agent_session_start", { mode: "repl" });
     // MCP servers connect in the BACKGROUND, like Claude Code: the prompt is
     // ready at once, each server's tools join the next model call the moment it

package/dist/loop.js

@@ -11,7 +11,7 @@ import { currentSession, describePeers, peerMessageContent, readPeerInbox, sendP
 import { LEAD, MAX_TEAMMATES, sendMessage, sendProtocol, readInbox, inboxCount, registerTeammate, finishTeammate, teammateExists, teammateCount, createRequest, resolveResponse, setTeammateState, anyTeammateBusy, runningTeammates, markShutdown, shutdownRequestId, resetTeam, listTeammateViews } from "./team.js"; // agent teams (Day 38) + team protocols (Day 39): mailboxes, registry, request/response contracts
 import { createTask, claimTask, completeTask, claimNextAvailable, boardSummary, resetBoard } from "./board.js"; // the shared task board (Day 40): autonomous work claiming
 import { emit } from "./telemetry.js"; // local-only event log (no-op unless the CLI armed it)
-import { runHooks } from "./hooks.js"; // user lifecycle hooks (PreToolUse / PostToolUse / Stop)
+import { runHooks, runPermissionHooks } from "./hooks.js"; // user lifecycle hooks (PreToolUse / PostToolUse / Stop / PermissionRequest)
 import { reviewHistory } from "./auto-context.js";
 import { AgentProgress } from "./agent-progress.js";
 import { recordUsage } from "./cost.js"; // meter token usage from the stream
@@ -700,6 +700,29 @@ async function authorizeCall(call, opts) {
         }
         if (opts.signal.aborted || opts.isInterrupted())
             return "[permission] Interrupted before execution.";
+        // Before the human is asked, a PermissionRequest hook may decide (this is
+        // how an orchestrator approves on the human's behalf). A deny is always
+        // honoured. An allow is not when a rule says a human must decide: then the
+        // question still goes to the human. Sub-agents skip hooks, as everywhere.
+        if (!autoAllowed && !opts.subAgent) {
+            const decision = await runPermissionHooks({ tool: call.name, args: call.args, reason: v.reason, summary: v.summary });
+            if (opts.signal.aborted || opts.isInterrupted())
+                return "[permission] Interrupted before execution.";
+            if (decision?.behavior === "deny") {
+                emit("agent_tool_declined", { tool: call.name });
+                if (!opts.quiet)
+                    sink(opts).note(mark.declined);
+                return `[permission] Action not approved: ${decision.message}. Ask the user how to proceed, or choose a safer alternative.`;
+            }
+            if (decision?.behavior === "allow" && !v.requiresHuman) {
+                autoAllowed = true;
+                if (!opts.quiet)
+                    recordToolDetail(call.id, "Approved by a PermissionRequest hook");
+            }
+            else {
+                await runHooks("Notification", { notification_type: "permission_prompt", message: `approval needed: ${call.name}`, tool: call.name, args: call.args });
+            }
+        }
         // An unattended callback may contain the old blanket auto-approve policy.
         // Auto mode never uses that policy as a fallback when Jev did not approve.
         // A diff is needed when the human is deciding; automatic edits stay in
@@ -1489,7 +1512,7 @@ opts) {
                 // runs the tests, blocks while they fail, and the agent keeps fixing.
                 // Sub-agents are exempt — Stop hooks are the human's project policy.
                 if (!opts.subAgent) {
-                    const stop = await runHooks("Stop", { finalText: out.content }); // give hooks the last word
+                    const stop = await runHooks("Stop", { finalText: out.content, last_assistant_message: out.content, stop_hook_active: false }); // give hooks the last word
                     if (stop.block) {
                         emit("agent_hook_block", { event: "Stop" }); // the agent was sent back to work
                         if (!opts.quiet)

package/dist/memory.js

@@ -1,5 +1,6 @@
 import fs from "node:fs"; // memory lives in a file on disk
 import path from "node:path"; // path joining
+import { migrateLegacyState, projectMemoryPath } from "./state.js"; // one bucket per cwd, kept out of the checkout
 // Long-term memory: facts the agent should carry ACROSS sessions, not just
 // within one conversation. Session persistence (Day 12) restores "what we were
 // talking about"; this restores "what I should always know about this project".
@@ -13,7 +14,15 @@ import path from "node:path"; // path joining
 // assistant: 90% the model gets right isn't worth saving, the 10% it got wrong
 // and was corrected on is gold). Every fact is TYPED so the model can tell "this
 // is who the user is" from "this is a correction" from "this is a project fact".
-export const MEMORY_PATH = path.resolve(".mini-agent", "MEMORY.md");
+// The file lives in the cwd's home bucket (state.ts), not inside the checkout,
+// so a repo never carries agent memory in git status. Resolved per call so a
+// chdir (tests, --cd) is honoured, and so the first call can migrate an older
+// build's ./.mini-agent/MEMORY.md. Still one Markdown file, human-readable and
+// human-editable: not a vector database, not embeddings.
+export function memoryPath() {
+    migrateLegacyState();
+    return projectMemoryPath();
+}
 // The four memory types (handbook §17). feedback is the most valuable.
 export const MEMORY_TYPES = ["user", "feedback", "project", "reference"];
 // Bounds, because unbounded memory dilutes the model's attention (Ch6: too many
@@ -38,7 +47,7 @@ function parseEntry(text) {
 export function readMemoryTyped() {
     try {
         return fs
-            .readFileSync(MEMORY_PATH, "utf8")
+            .readFileSync(memoryPath(), "utf8")
             .split("\n")
             .filter((l) => l.startsWith("- "))
             .map((l) => parseEntry(l.slice(2).trim()))
@@ -91,8 +100,9 @@ export function addFact(fact, type = "project") {
         entries.shift(); // still too big — drop the oldest until it fits
         body = entries.map((e) => `- [${e.type}] ${e.fact}`).join("\n");
     }
-    fs.mkdirSync(path.dirname(MEMORY_PATH), { recursive: true });
-    fs.writeFileSync(MEMORY_PATH, HEADER + body + "\n", "utf8");
+    const file = memoryPath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, HEADER + body + "\n", "utf8");
     return `Remembered (${t}). (${entries.length} fact${entries.length === 1 ? "" : "s"} stored.)`;
 }
 // The tool the model calls to save something worth keeping.

package/dist/session.js

@@ -1,13 +1,28 @@
 import fs from "node:fs"; // session files live on disk
 import path from "node:path"; // path joining
 import { getGoal } from "./goal.js"; // the /goal rides along in the session file (Day 41)
-// Sessions are project-local: .mini-agent/sessions/<id>.json under the cwd.
-// Project-local (not global) because a conversation is about a codebase —
-// resuming a refactor of project A from inside project B makes no sense.
+import { migrateLegacyState, projectSessionsDir } from "./state.js"; // one bucket per cwd, kept out of the checkout
+// Sessions are per-project but not per-repo: <home>/mini-agent/projects/<slug>/sessions,
+// where <slug> is the cwd flattened. Same reasoning as the old in-repo layout (a
+// conversation is about a codebase, so resuming project A from inside project B
+// would be wrong) without leaving an untracked directory in every checkout.
 // Resolved lazily (a function, not a const) so it always reflects the current
-// working directory — and so tests can chdir into a scratch dir.
-const sessionsDir = () => path.resolve(".mini-agent", "sessions");
+// working directory, and so tests can chdir into a scratch dir. The first touch
+// migrates any ./.mini-agent/sessions left by an older build.
+const sessionsDir = () => {
+    migrateLegacyState();
+    return projectSessionsDir();
+};
 const KEEP_SESSIONS = 20; // how many session files survive pruning
+// Where a session's file lives — absolute, so it can be handed to hooks.
+export function sessionPath(id) {
+    return path.join(sessionsDir(), `${id}.json`);
+}
+// A session id becomes a file name, so one chosen from outside (--session-id)
+// must not be able to name a path.
+export function isValidSessionId(id) {
+    return /^[A-Za-z0-9._-]+$/.test(id) && id !== "." && id !== "..";
+}
 // A fresh, filename-safe session id derived from the wall clock.
 export function newSessionId() {
     return new Date().toISOString().replace(/[:.]/g, "-"); // 2026-06-12T10-30-00-000Z

package/dist/state.js

@@ -0,0 +1,78 @@
+import fs from "node:fs"; // moving legacy state, creating the home bucket
+import os from "node:os"; // the home directory root
+import path from "node:path"; // joining and resolving paths
+// Per-project state that is history rather than configuration — session
+// transcripts, long-term memory, and the local event/trace logs — lives OUTSIDE
+// the checkout, one bucket per working directory, mirroring how Claude Code
+// keeps ~/.claude/projects/<slug>. A repo you open should not grow an untracked
+// state directory just because an agent ran in it; configuration and tooling
+// (settings, skills, task board, team mailboxes, cron state) stay project-local
+// where they belong to the code.
+//
+// The bucket is keyed by the absolute cwd with separators flattened, so
+// /Users/me/proj becomes -Users-me-proj, the same escaping Claude Code uses.
+export const projectsRoot = () => process.env.MINI_AGENT_PROJECTS_DIR || path.join(os.homedir(), ".config", "mini-agent", "projects");
+// One directory name per working directory. Windows drive colons are flattened
+// too, so the name is portable and cannot escape the root. Symlinks are resolved
+// first, so one project reached as /tmp/x and /private/tmp/x keeps ONE bucket
+// instead of two that each hold half the history.
+export function projectSlug(cwd = process.cwd()) {
+    let abs = path.resolve(cwd);
+    try {
+        abs = fs.realpathSync(abs);
+    }
+    catch {
+        /* a path that does not exist yet still gets a stable slug */
+    }
+    return abs.replace(/[\\/:]/g, "-");
+}
+export function projectStateDir(cwd = process.cwd()) {
+    return path.join(projectsRoot(), projectSlug(cwd));
+}
+export function projectSessionsDir(cwd = process.cwd()) {
+    return path.join(projectStateDir(cwd), "sessions");
+}
+export function projectMemoryPath(cwd = process.cwd()) {
+    return path.join(projectStateDir(cwd), "MEMORY.md");
+}
+// Any other per-project log or file that should live beside sessions and memory
+// rather than inside the checkout (telemetry, review-debug traces).
+export function projectStateFile(name, cwd = process.cwd()) {
+    return path.join(projectStateDir(cwd), name);
+}
+// Move a path only when the destination is absent, so a second run is a no-op
+// and a newly written home file is never clobbered by an old checkout copy.
+// rename works on one filesystem; cp+rm covers the home-on-another-volume case.
+function moveIfAbsent(from, to) {
+    if (fs.existsSync(to) || !fs.existsSync(from))
+        return;
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    try {
+        fs.renameSync(from, to);
+    }
+    catch {
+        fs.cpSync(from, to, { recursive: true });
+        fs.rmSync(from, { recursive: true, force: true });
+    }
+}
+let migrated = false; // once per process; the check is idempotent anyway
+// Older builds wrote sessions and memory into ./.mini-agent. Move them into the
+// home bucket the first time anything touches the new location, so an upgrade
+// keeps its history and the checkout ends up clean. Never throws: a failed
+// migration must not break the CLI, it just leaves the old files in place.
+export function migrateLegacyState(cwd = process.cwd()) {
+    if (migrated)
+        return;
+    migrated = true;
+    try {
+        moveIfAbsent(path.resolve(cwd, ".mini-agent", "sessions"), projectSessionsDir(cwd));
+        moveIfAbsent(path.resolve(cwd, ".mini-agent", "MEMORY.md"), projectMemoryPath(cwd));
+        // Logs are per-project too, and telemetry is usually the biggest file left
+        // behind by an older checkout.
+        moveIfAbsent(path.resolve(cwd, ".mini-agent", "telemetry.jsonl"), projectStateFile("telemetry.jsonl", cwd));
+        moveIfAbsent(path.resolve(cwd, ".mini-agent", "review-debug.jsonl"), projectStateFile("review-debug.jsonl", cwd));
+    }
+    catch {
+        /* leave the legacy files where they are */
+    }
+}

package/dist/telemetry.js

@@ -1,14 +1,20 @@
 import fs from "node:fs"; // the event log lives on disk
 import path from "node:path"; // path joining
-// LOCAL-ONLY telemetry. Events go to .mini-agent/telemetry.jsonl in the
-// project directory and NOWHERE else — nothing leaves the machine, ever.
-// It exists because "no data" means every optimization is a guess: which
-// errors actually happen, how often compaction fires, which tools get denied.
-// Opt out entirely with MINI_AGENT_NO_TELEMETRY=1.
+import { migrateLegacyState, projectStateFile } from "./state.js"; // one bucket per cwd, kept out of the checkout
+// LOCAL-ONLY telemetry. Events go to the project's home bucket
+// (~/.config/mini-agent/projects/<cwd-slug>/telemetry.jsonl) and NOWHERE else —
+// nothing leaves the machine, ever. It exists because "no data" means every
+// optimization is a guess: which errors actually happen, how often compaction
+// fires, which tools get denied. Opt out entirely with MINI_AGENT_NO_TELEMETRY=1.
 //
 // Naming follows the unified-prefix convention (agent_<domain>_<action>) so
 // the log stays greppable: `grep agent_api_error telemetry.jsonl | wc -l`.
-const TELEMETRY_FILE = path.resolve(".mini-agent", "telemetry.jsonl");
+// Resolved per call so a chdir is honoured, and so the first write migrates an
+// older build's ./.mini-agent/telemetry.jsonl.
+const telemetryFile = () => {
+    migrateLegacyState();
+    return projectStateFile("telemetry.jsonl");
+};
 let sessionId = null; // set by initTelemetry; emit() is a no-op before that
 const tallies = new Map(); // per-session event counts, for /stats
 // Arm telemetry for this session. Tests and the eval harness never call this,
@@ -25,8 +31,9 @@ export function emit(event, fields = {}) {
     if (!sessionId)
         return; // disarmed — counters only, no file
     try {
-        fs.mkdirSync(path.dirname(TELEMETRY_FILE), { recursive: true }); // ensure the directory
-        fs.appendFileSync(TELEMETRY_FILE, JSON.stringify({ ts: new Date().toISOString(), session: sessionId, event, ...fields }) + "\n"); // one JSON object per line
+        const file = telemetryFile();
+        fs.mkdirSync(path.dirname(file), { recursive: true }); // ensure the directory
+        fs.appendFileSync(file, JSON.stringify({ ts: new Date().toISOString(), session: sessionId, event, ...fields }) + "\n"); // one JSON object per line
     }
     catch {
         /* a full disk or a read-only checkout is not our problem to escalate */
@@ -39,5 +46,5 @@ export function statsReport() {
     const lines = [...tallies.entries()]
         .sort((a, b) => b[1] - a[1]) // busiest first
         .map(([k, n]) => `  ${String(n).padStart(5)}  ${k}`); // aligned counts
-    return ["events this session:", ...lines, `\nfull log: ${TELEMETRY_FILE} (local only — nothing leaves this machine)`].join("\n");
+    return ["events this session:", ...lines, `\nfull log: ${telemetryFile()} (local only — nothing leaves this machine)`].join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-from-zero",
-  "version": "0.35.6",
+  "version": "0.36.0",
   "type": "module",
   "bin": {
     "mini-agent": "dist/agent.js"
@@ -17,7 +17,7 @@
     "auto:report": "tsx eval/auto-report.ts",
     "build": "tsc -p tsconfig.build.json",
     "prepare": "npm run build",
-    "test": "export MINI_AGENT_REVIEW_DEBUG=0 && tsx tests/tools.test.ts && tsx tests/permissions.test.ts && tsx tests/context.test.ts && tsx tests/hooks.test.ts && tsx tests/mcp.test.ts && tsx tests/judge.test.ts && tsx tests/auto.test.ts && tsx tests/auto-context.test.ts && tsx tests/auto-providers.test.ts && tsx tests/auto-cascade.test.ts && tsx tests/auto-rules.test.ts && tsx tests/auto-rule-cascade.test.ts && tsx tests/auto-debug.test.ts && tsx tests/auto-report.test.ts && tsx tests/auto-clarification.test.ts && tsx tests/memory.test.ts && tsx tests/cost.test.ts && tsx tests/cli.test.ts && tsx tests/print.test.ts && tsx tests/status.test.ts && tsx tests/validate.test.ts && tsx tests/plan.test.ts && tsx tests/diff.test.ts && tsx tests/undo.test.ts && tsx tests/tiering.test.ts && tsx tests/mcp-http.test.ts && tsx tests/mcp-oauth.test.ts && tsx tests/changes.test.ts && tsx tests/mentions.test.ts && tsx tests/session.test.ts && tsx tests/title.test.ts && tsx tests/ui.test.ts && tsx tests/activity.test.ts && tsx tests/follow-up.test.ts && tsx tests/follow-up-ui.test.tsx && tsx tests/agents.test.ts && tsx tests/images.test.ts && tsx tests/approval.test.ts && tsx tests/form.test.ts && tsx tests/model.test.ts && tsx tests/reasoning.test.ts && tsx tests/effort.test.ts && tsx tests/completion.test.ts && tsx tests/pasted-text.test.ts && tsx tests/skills.test.ts && tsx tests/markdown.test.ts && tsx tests/editor.test.ts && tsx tests/todos.test.ts && tsx tests/background.test.ts && tsx tests/team.test.ts && tsx tests/peers.test.ts && tsx tests/suggestion.test.ts && tsx tests/board.test.ts && tsx tests/drop.test.ts && tsx tests/editline.test.ts && tsx tests/cron.test.ts && tsx tests/goal.test.ts"
+    "test": "export MINI_AGENT_REVIEW_DEBUG=0 && tsx tests/tools.test.ts && tsx tests/permissions.test.ts && tsx tests/context.test.ts && tsx tests/hooks.test.ts && tsx tests/mcp.test.ts && tsx tests/judge.test.ts && tsx tests/auto.test.ts && tsx tests/auto-context.test.ts && tsx tests/auto-providers.test.ts && tsx tests/auto-cascade.test.ts && tsx tests/auto-rules.test.ts && tsx tests/auto-rule-cascade.test.ts && tsx tests/auto-debug.test.ts && tsx tests/auto-report.test.ts && tsx tests/auto-clarification.test.ts && tsx tests/memory.test.ts && tsx tests/cost.test.ts && tsx tests/cli.test.ts && tsx tests/print.test.ts && tsx tests/status.test.ts && tsx tests/validate.test.ts && tsx tests/plan.test.ts && tsx tests/diff.test.ts && tsx tests/undo.test.ts && tsx tests/tiering.test.ts && tsx tests/mcp-http.test.ts && tsx tests/mcp-oauth.test.ts && tsx tests/changes.test.ts && tsx tests/mentions.test.ts && tsx tests/state.test.ts && tsx tests/session.test.ts && tsx tests/title.test.ts && tsx tests/ui.test.ts && tsx tests/activity.test.ts && tsx tests/follow-up.test.ts && tsx tests/follow-up-ui.test.tsx && tsx tests/agents.test.ts && tsx tests/images.test.ts && tsx tests/approval.test.ts && tsx tests/form.test.ts && tsx tests/model.test.ts && tsx tests/reasoning.test.ts && tsx tests/effort.test.ts && tsx tests/completion.test.ts && tsx tests/pasted-text.test.ts && tsx tests/skills.test.ts && tsx tests/markdown.test.ts && tsx tests/editor.test.ts && tsx tests/todos.test.ts && tsx tests/background.test.ts && tsx tests/team.test.ts && tsx tests/peers.test.ts && tsx tests/suggestion.test.ts && tsx tests/board.test.ts && tsx tests/drop.test.ts && tsx tests/editline.test.ts && tsx tests/cron.test.ts && tsx tests/goal.test.ts"
   },
   "engines": {
     "node": ">=20.6"