nexrall-code 0.5.166 → 0.5.168

package/dist/index.js

@@ -11355,7 +11355,7 @@ var require_memory = __commonJS({
     }();
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.AGENT_MEMORY_MAX_BYTES = exports2.AGENT_MEMORY_INJECT_MAX = exports2.MEMORY_ARCHIVE_MAX_BYTES = exports2.MEMORY_HARD_CAP_BYTES = exports2.MEMORY_COMPACT_TRIGGER_BYTES = exports2.MEMORY_MAX_BYTES = exports2.MEMORY_ENTRY_MAX_CHARS = void 0;
-    exports2.memoryFilePath = memoryFilePath;
+    exports2.memoryFilePath = memoryFilePath2;
     exports2.writeMemory = writeMemory2;
     exports2.readMemory = readMemory2;
     exports2.readAllMemory = readAllMemory2;
@@ -11374,7 +11374,7 @@ var require_memory = __commonJS({
     var crypto9 = __importStar(__require("crypto"));
     var MEMORY_ROOT = process.env.NEXRALL_MEMORY_DIR || path28.join(os17.homedir(), ".nexrall", "memory");
     var GLOBAL_FILE = path28.join(MEMORY_ROOT, "global.md");
-    function memoryFilePath(scope, workDir) {
+    function memoryFilePath2(scope, workDir) {
       if (scope === "global" || !workDir)
         return GLOBAL_FILE;
       const key = crypto9.createHash("sha1").update(path28.resolve(workDir)).digest("hex").slice(0, 16);
@@ -11468,7 +11468,7 @@ ${SUPERSEDED_HEADER}
         trimmed = trimmed.slice(0, budget - 1).trimEnd() + "\u2026";
       }
       const body = prefix2 && budget > 0 ? prefix2 + trimmed : trimmed;
-      const file = memoryFilePath(scope, workDir);
+      const file = memoryFilePath2(scope, workDir);
       return withLock(file, async () => {
         const existing = readMemoryFile(file);
         let { active, archived } = parseSections(existing);
@@ -11503,7 +11503,7 @@ ${SUPERSEDED_HEADER}
       });
     }
     function readMemory2(scope, workDir, opts = {}) {
-      const file = memoryFilePath(scope, workDir);
+      const file = memoryFilePath2(scope, workDir);
       const { active, archived } = parseSections(readMemoryFile(file));
       if (!opts.includeArchived)
         return active.length ? serializeSections(active, []).trim() : "";
@@ -11524,14 +11524,14 @@ ${projMem}`);
       return parts.join("\n\n");
     }
     function clearMemory2(scope, workDir) {
-      const file = memoryFilePath(scope, workDir);
+      const file = memoryFilePath2(scope, workDir);
       try {
         fs28.rmSync(file, { force: true });
       } catch {
       }
     }
     function memoryStats2(scope, workDir) {
-      const file = memoryFilePath(scope, workDir);
+      const file = memoryFilePath2(scope, workDir);
       const content = readMemoryFile(file);
       const { active, archived } = parseSections(content);
       return {
@@ -11545,7 +11545,7 @@ ${projMem}`);
       return reply.split("\n").map((l2) => l2.trimEnd()).filter((l2) => /^-\s\[\d{4}-\d{2}-\d{2}\]\s*\S/.test(l2));
     }
     async function compactMemoryIfNeeded2(scope, workDir, summarize) {
-      const file = memoryFilePath(scope, workDir);
+      const file = memoryFilePath2(scope, workDir);
       return withLock(file, async () => {
         const content = readMemoryFile(file);
         if (Buffer.byteLength(content, "utf-8") <= exports2.MEMORY_COMPACT_TRIGGER_BYTES)
@@ -106910,6 +106910,9 @@ var require_loop = __commonJS({
     }();
     Object.defineProperty(exports2, "__esModule", { value: true });
     exports2.VERIFY_CMD_RE = exports2.WRITE_TOOL_NAMES = exports2.ToolNotAllowedError = exports2.AGENT_MEMORY_TOOL_SCHEMA = exports2.AGENT_MEMORY_TOOL = exports2._stallLimits = exports2._emptyTurnRetry = exports2.bashNeedsRepoLock = void 0;
+    exports2.loadHooks = loadHooks;
+    exports2.parsePromptHookReply = parsePromptHookReply;
+    exports2.classifyStopFailure = classifyStopFailure;
     exports2.runLifecycleHooks = runLifecycleHooks;
     exports2.runPermissionRequestHooks = runPermissionRequestHooks2;
     exports2.fireNotificationHooks = fireNotificationHooks2;
@@ -107098,8 +107101,206 @@ var require_loop = __commonJS({
     async function runHookHandler(hook, payload, opts) {
       if (hook.type === "http")
         return httpHook(hook, payload, opts.timeoutMs);
+      if (hook.type === "prompt" || hook.type === "agent") {
+        return promptHook(hook, payload, { ...opts, envCtx: opts.hookEnv });
+      }
       return spawnHook(String(hook.command ?? ""), { cwd: opts.cwd, timeout: opts.timeoutMs, input: payload, env: opts.env });
     }
+    var HOOK_AGENT_TOOLS = [
+      {
+        name: "read_file",
+        description: "Read a file from the working directory.",
+        input_schema: {
+          type: "object",
+          properties: {
+            path: { type: "string", description: "File path, relative to the working directory." },
+            offset: { type: "number", description: "0-based line to start from." },
+            limit: { type: "number", description: "Maximum number of lines." }
+          },
+          required: ["path"]
+        }
+      },
+      {
+        name: "search_files",
+        description: "Search file contents (regex) or find files by name in the working directory.",
+        input_schema: {
+          type: "object",
+          properties: {
+            pattern: { type: "string", description: "Regex or literal string to search for." },
+            path: { type: "string", description: "Directory to search in." },
+            type: { type: "string", description: "files (paths only) | content (matching lines) | filename." }
+          },
+          required: ["pattern"]
+        }
+      },
+      {
+        name: "list_directory",
+        description: "List the files and directories at a path.",
+        input_schema: { type: "object", properties: { path: { type: "string" } } }
+      },
+      {
+        name: "glob",
+        description: 'Find files matching a glob pattern, e.g. "**/*.ts".',
+        input_schema: { type: "object", properties: { pattern: { type: "string" }, path: { type: "string" } }, required: ["pattern"] }
+      }
+    ];
+    var NO_TOOLS_MARKER = "\0hook-no-tools";
+    function parsePromptHookReply(reply) {
+      const text = String(reply ?? "");
+      const start = text.indexOf("{");
+      const end = text.lastIndexOf("}");
+      if (start < 0 || end <= start)
+        return null;
+      try {
+        const j = JSON.parse(text.slice(start, end + 1));
+        if (typeof j.ok !== "boolean" && typeof j.decision !== "string")
+          return null;
+        return {
+          ok: typeof j.ok === "boolean" ? j.ok : void 0,
+          reason: typeof j.reason === "string" ? j.reason : void 0,
+          additionalContext: typeof j.additionalContext === "string" ? j.additionalContext : void 0,
+          decision: typeof j.decision === "string" ? j.decision : void 0
+        };
+      } catch {
+        return null;
+      }
+    }
+    var PROMPT_HOOK_RULES = `You are a hook evaluator for a coding agent. The hook input JSON is given below, followed by the hook's own instruction. Decide whether the agent action described in the input should proceed. Reply with ONLY one JSON object and nothing else: {"ok":true} to allow, or {"ok":false,"reason":"short explanation"} to block.`;
+    async function promptHook(hook, payload, opts) {
+      const instruction = String(hook.prompt ?? "");
+      if (!instruction)
+        return { status: 1, stdout: "", stderr: 'prompt hook has no "prompt"' };
+      const body = instruction.replace(/\\\$ARGUMENTS/g, "
").replace(/\$ARGUMENTS/g, payload).replace(/\u0001/g, "$ARGUMENTS");
+      const ctl = { aborted: false };
+      const timer = setTimeout(() => {
+        ctl.aborted = true;
+      }, Math.max(1e3, opts.timeoutMs));
+      const outerPoll = opts.abortSignal ? setInterval(() => {
+        if (opts.abortSignal?.aborted)
+          ctl.aborted = true;
+      }, 100) : void 0;
+      if (opts.abortSignal?.aborted) {
+        clearTimeout(timer);
+        if (outerPoll)
+          clearInterval(outerPoll);
+        return { status: 1, stdout: "", stderr: "aborted" };
+      }
+      try {
+        return await runModel();
+      } finally {
+        clearTimeout(timer);
+        if (outerPoll)
+          clearInterval(outerPoll);
+      }
+      async function runModel() {
+        const messages = [{
+          role: "user",
+          content: [{ type: "text", text: `${PROMPT_HOOK_RULES}
+
+Hook input:
+${payload}
+
+Hook instruction:
+${body}` }]
+        }];
+        const isAgent = hook.type === "agent";
+        try {
+          let replyText = "";
+          for (let round = 0; round < (isAgent ? 6 : 1); round++) {
+            const msg = await (0, client_1.streamChat)(messages, {
+              model: hook.model ?? opts.model ?? "turbo",
+              env: opts.envCtx ?? { cwd: opts.cwd },
+              abortSignal: ctl,
+              // Wire the tools by allowlist rather than a separate channel: the backend
+              // filters builtins+extra against it, so an agent hook sees ONLY the four
+              // read-only tools and a prompt hook sees none (the marker matches nothing).
+              toolAllowlist: isAgent ? HOOK_AGENT_TOOLS.map((t2) => t2.name) : [NO_TOOLS_MARKER],
+              extraTools: isAgent ? HOOK_AGENT_TOOLS : void 0
+            }, () => {
+            });
+            const blocks = Array.isArray(msg.content) ? msg.content : [];
+            const toolUses = blocks.filter((b) => b.type === "tool_use");
+            if (!toolUses.length || !isAgent) {
+              replyText = blocks.filter((b) => b.type === "text" && typeof b.text === "string").map((b) => b.text).join("\n");
+              break;
+            }
+            messages.push({ role: "assistant", content: msg.content });
+            const results = [];
+            for (const tu of toolUses) {
+              let out;
+              try {
+                out = getHookToolExecutors().includes(String(tu.name)) ? await (0, executor_1.executeTool)(String(tu.name), tu.input ?? {}, ctl, void 0, opts.cwd) : { error: `Tool ${String(tu.name)} is not available to a hook \u2014 only ${getHookToolExecutors().join(", ")}.` };
+              } catch (err) {
+                out = { error: err.message || "tool failed" };
+              }
+              results.push({
+                type: "tool_result",
+                tool_use_id: String(tu.id),
+                content: out.error ? out.output ? `Error: ${out.error}
+
+${out.output}` : `Error: ${out.error}` : out.output ?? "",
+                is_error: out.error !== void 0
+              });
+            }
+            messages.push({ role: "user", content: results });
+          }
+          const parsed = parsePromptHookReply(replyText);
+          if (!parsed) {
+            return { status: 1, stdout: "", stderr: "prompt hook returned no decision" };
+          }
+          const decided = parsed.ok === false || parsed.decision === "block" || parsed.decision === "deny";
+          if (decided)
+            return { status: 2, stdout: "", stderr: parsed.reason || `Blocked by ${hook.type} hook` };
+          const passthrough2 = parsed.additionalContext ? JSON.stringify({ additionalContext: parsed.additionalContext }) : "";
+          return { status: 0, stdout: passthrough2, stderr: "" };
+        } catch (err) {
+          if (ctl.aborted)
+            return { status: 1, stdout: "", stderr: "prompt hook timed out" };
+          return { status: 1, stdout: "", stderr: `prompt hook failed: ${err.message}` };
+        }
+      }
+    }
+    function getHookToolExecutors() {
+      return ["read_file", "search_files", "list_directory", "glob"];
+    }
+    function hookRunOptsFor(options) {
+      return { model: options.model ?? "turbo", abortSignal: options.abortSignal, hookEnv: options.env };
+    }
+    function classifyStopFailure(err) {
+      const status = err?.status;
+      const code = err?.code;
+      const details = [status ? `HTTP ${status}` : "", code ? String(code) : ""].filter(Boolean).join(" ") || void 0;
+      if (status === 429)
+        return { error: "rate_limit", error_details: details };
+      if (status === 529)
+        return { error: "overloaded", error_details: details };
+      if (status === 401)
+        return { error: "authentication_failed", error_details: details };
+      if (status === 402)
+        return { error: "billing_error", error_details: details };
+      if (status === 403)
+        return { error: "authentication_failed", error_details: details };
+      if (status === 400 || status === 422)
+        return { error: "invalid_request", error_details: details };
+      if (status === 404)
+        return { error: "model_not_found", error_details: details };
+      if (typeof status === "number" && status >= 500)
+        return { error: "server_error", error_details: details };
+      return { error: "unknown", error_details: details };
+    }
+    function apiFailureForStopReason(stopReason) {
+      if (stopReason === "output-limit")
+        return { error: "max_output_tokens" };
+      if (stopReason === "no-balance")
+        return { error: "billing_error", error_details: "wallet empty (402)" };
+      if (stopReason === "no-team-budget")
+        return { error: "billing_error", error_details: "team pool empty (402)" };
+      if (stopReason === "reported-elsewhere")
+        return { error: "billing_error", error_details: "pre-flight 402" };
+      if (stopReason === "team-unavailable")
+        return { error: "account_on_hold", error_details: "team billing unusable (403)" };
+      return null;
+    }
     function hookTimeoutMs(hook, fallbackMs = 6e4) {
       if (typeof hook.timeout_ms === "number" && hook.timeout_ms > 0)
         return Math.min(hook.timeout_ms, 6e5);
@@ -107115,7 +107316,7 @@ var require_loop = __commonJS({
         return norm === toolName || norm === alt && toolName.includes(alt);
       });
     }
-    async function runToolHooks(entries, phase, toolName, input, workDir, result) {
+    async function runToolHooks(entries, phase, toolName, input, workDir, result, hookOpts) {
       const outcome = { block: false };
       if (!entries?.length)
         return outcome;
@@ -107129,11 +107330,7 @@ var require_loop = __commonJS({
         if (!hookMatches(entry.matcher, toolName))
           continue;
         for (const hook of entry.hooks ?? []) {
-          if (hook.type !== "command" && hook.type !== "http")
-            continue;
-          if (hook.type === "command" && !hook.command)
-            continue;
-          if (hook.type === "http" && !hook.url)
+          if (!isRunnableHook(hook))
             continue;
           const hookTimeout = hookTimeoutMs(hook, 6e4);
           const r2 = await runHookHandler(hook, payload, {
@@ -107144,7 +107341,8 @@ var require_loop = __commonJS({
               NEXRALL_TOOL_NAME: toolName,
               NEXRALL_TOOL_INPUT: JSON.stringify(input),
               NEXRALL_HOOK_PHASE: phase
-            }
+            },
+            ...hookOpts
           });
           const out = (r2.stdout ?? "").toString().trim();
           if (out.startsWith("{")) {
@@ -107169,17 +107367,13 @@ var require_loop = __commonJS({
       }
       return outcome;
     }
-    async function runSimpleHooks(defs, workDir, extraEnv) {
+    async function runSimpleHooks(defs, workDir, extraEnv, hookOpts) {
       if (!defs?.length)
         return;
       for (const hook of defs) {
-        if (hook.type !== "command" && hook.type !== "http")
-          continue;
-        if (hook.type === "command" && !hook.command)
+        if (!isRunnableHook(hook))
           continue;
-        if (hook.type === "http" && !hook.url)
-          continue;
-        await runHookHandler(hook, "", { cwd: workDir, timeoutMs: hookTimeoutMs(hook, 1e4), env: extraEnv ? { ...process.env, ...extraEnv } : void 0 });
+        await runHookHandler(hook, "", { cwd: workDir, timeoutMs: hookTimeoutMs(hook, 1e4), env: extraEnv ? { ...process.env, ...extraEnv } : void 0, ...hookOpts });
       }
     }
     function flattenHookDefs(items, matchValue) {
@@ -107190,26 +107384,34 @@ var require_loop = __commonJS({
           if (m2 && m2 !== "*" && matchValue !== void 0 && !m2.split("|").map((x2) => x2.trim()).includes(matchValue))
             continue;
           out.push(...it.hooks);
-        } else if (it && (it.type === "command" || it.type === "http"))
+        } else if (it && isKnownHandlerType(it.type))
           out.push(it);
       }
       return out;
     }
-    async function runLifecycleHooks(items, event, workDir, payload, matchValue) {
+    function isKnownHandlerType(t2) {
+      return t2 === "command" || t2 === "http" || t2 === "prompt" || t2 === "agent";
+    }
+    function isRunnableHook(hook) {
+      if (!isKnownHandlerType(hook.type))
+        return false;
+      if (hook.type === "command")
+        return !!hook.command;
+      if (hook.type === "http")
+        return !!hook.url;
+      return !!hook.prompt;
+    }
+    async function runLifecycleHooks(items, event, workDir, payload, matchValue, hookOpts) {
       const outcome = { block: false };
       const defs = flattenHookDefs(items, matchValue);
       if (!defs.length)
         return outcome;
       const input = JSON.stringify({ hook_event_name: event, cwd: workDir, ...payload });
       for (const hook of defs) {
-        if (hook.type !== "command" && hook.type !== "http")
-          continue;
-        if (hook.type === "command" && !hook.command)
+        if (!isRunnableHook(hook))
           continue;
-        if (hook.type === "http" && !hook.url)
-          continue;
-        const timeout = hookTimeoutMs(hook, 3e4);
-        const r2 = await runHookHandler(hook, input, { cwd: workDir, timeoutMs: timeout, env: { ...process.env, NEXRALL_HOOK_PHASE: event } });
+        const timeout = hookTimeoutMs(hook, hook.type === "agent" ? 6e4 : hook.type === "prompt" ? 3e4 : 3e4);
+        const r2 = await runHookHandler(hook, input, { cwd: workDir, timeoutMs: timeout, env: { ...process.env, NEXRALL_HOOK_PHASE: event }, ...hookOpts });
         const out = (r2.stdout ?? "").toString().trim();
         if (out.startsWith("{")) {
           try {
@@ -107229,6 +107431,10 @@ var require_loop = __commonJS({
             }
             if (typeof j.additionalContext === "string" && j.additionalContext)
               outcome.context = (outcome.context ? outcome.context + "\n" : "") + j.additionalContext;
+            if (event === "FileChanged" && Array.isArray(j.watchPaths))
+              outcome.watchPaths = j.watchPaths.filter((p) => typeof p === "string");
+            if (typeof j.systemMessage === "string" && j.systemMessage)
+              outcome.systemMessage = j.systemMessage;
           } catch {
           }
         } else if (out && (event === "SessionStart" || event === "UserPromptSubmit") && r2.status === 0) {
@@ -108089,7 +108295,7 @@ ${stats}${isoNote}`;
           const subAgentName = agent?.name ?? (typeof input.subagent_type === "string" && input.subagent_type ? input.subagent_type : "general-purpose");
           const startItems = loadHooks(options.workDir).SubagentStart;
           if (startItems?.length) {
-            const o = await runLifecycleHooks(startItems, "SubagentStart", options.workDir, { session_id: options.sessionId ?? "", agent_type: subAgentName, description: String(input.description ?? "") }, subAgentName).catch(() => ({ block: false }));
+            const o = await runLifecycleHooks(startItems, "SubagentStart", options.workDir, { session_id: options.sessionId ?? "", agent_type: subAgentName, description: String(input.description ?? "") }, subAgentName, hookRunOptsFor(options)).catch(() => ({ block: false }));
             if (o.context) {
               const last = subMessages[subMessages.length - 1];
               if (last && Array.isArray(last.content)) {
@@ -108649,7 +108855,7 @@ Do NOT call any tools and do NOT continue the task. Reply with text only: a conc
       if (cut < 2)
         return false;
       if ((options._depth ?? 0) === 0) {
-        await runLifecycleHooks(loadHooks(options.workDir).PreCompact, "PreCompact", options.workDir, { trigger: "auto", session_id: options.sessionId ?? "", messages_to_summarize: cut }, "auto").catch(() => void 0);
+        await runLifecycleHooks(loadHooks(options.workDir).PreCompact, "PreCompact", options.workDir, { trigger: "auto", session_id: options.sessionId ?? "", messages_to_summarize: cut }, "auto", hookRunOptsFor(options)).catch(() => void 0);
       }
       const beforeCompact = messages.length;
       const afterCompact = cut > 0 ? messages.length - cut + 1 : messages.length;
@@ -108662,7 +108868,7 @@ Do NOT call any tools and do NOT continue the task. Reply with text only: a conc
           options.onCompact?.({ trigger: "auto", before: beforeCompact, after: afterCompact });
         } catch {
         }
-        await runLifecycleHooks(loadHooks(options.workDir).PostCompact, "PostCompact", options.workDir, { trigger: "auto", session_id: options.sessionId ?? "", messages_summarized: cut }, "auto").catch(() => void 0);
+        await runLifecycleHooks(loadHooks(options.workDir).PostCompact, "PostCompact", options.workDir, { trigger: "auto", session_id: options.sessionId ?? "", messages_summarized: cut }, "auto", hookRunOptsFor(options)).catch(() => void 0);
       };
       const originalTask = originalTaskText(toSummarize);
       const summaryPrompt = `Summarize this coding-session transcript into concise bullet points the assistant needs to continue the work: key decisions, files changed (and how), commands run, unresolved problems, and user preferences. Max 400 words.
@@ -108910,6 +109116,26 @@ Continue the work from here.` }] });
       const messages = [...initialMessages];
       const model = options.model ?? "turbo";
       const hooks = options.disableHooks ? withAgentHooks({}, options._agentHooks) : withAgentHooks(loadHooks(options.workDir), options._agentHooks);
+      const fireStopFailure = async (failure) => {
+        if (depth !== 0)
+          return;
+        const items = hooks.StopFailure;
+        if (!items?.length)
+          return;
+        let last = "";
+        for (let i2 = messages.length - 1; i2 >= 0 && !last; i2--) {
+          const m2 = messages[i2];
+          if (m2?.role === "assistant" && Array.isArray(m2.content)) {
+            last = m2.content.filter((b) => b.type === "text").map((b) => b.text ?? "").join("\n").trim().slice(0, 2e3);
+          }
+        }
+        await runLifecycleHooks(items, "StopFailure", options.workDir, {
+          session_id: options.sessionId ?? "",
+          error: failure.error,
+          ...failure.error_details ? { error_details: failure.error_details } : {},
+          last_assistant_message: last
+        }, failure.error, hookRunOptsFor(options)).catch(() => void 0);
+      };
       const depth = options._depth ?? 0;
       const agentScope = options._agentScope ?? "root";
       const isMainAgent = depth === 0;
@@ -108930,13 +109156,13 @@ ${ctx}
         const sid = options.sessionId || PROCESS_BUDGET_KEY;
         if (isPrompt && !_sessionStarted.has(sid) && (hooks.SessionStart?.length ?? 0) > 0) {
           _sessionStarted.add(sid);
-          const o = await runLifecycleHooks(hooks.SessionStart, "SessionStart", options.workDir, { session_id: options.sessionId ?? "", source: messages.length > 1 ? "resume" : "startup" }, messages.length > 1 ? "resume" : "startup");
+          const o = await runLifecycleHooks(hooks.SessionStart, "SessionStart", options.workDir, { session_id: options.sessionId ?? "", source: messages.length > 1 ? "resume" : "startup" }, messages.length > 1 ? "resume" : "startup", hookRunOptsFor(options));
           if (o.context)
             addContext(o.context);
         } else if (isPrompt)
           _sessionStarted.add(sid);
         if (isPrompt && (hooks.UserPromptSubmit?.length ?? 0) > 0) {
-          const o = await runLifecycleHooks(hooks.UserPromptSubmit, "UserPromptSubmit", options.workDir, { session_id: options.sessionId ?? "", prompt: promptText });
+          const o = await runLifecycleHooks(hooks.UserPromptSubmit, "UserPromptSubmit", options.workDir, { session_id: options.sessionId ?? "", prompt: promptText }, void 0, hookRunOptsFor(options));
           if (o.block) {
             options.onText(`
 \u26D4 Prompt blocked by a UserPromptSubmit hook: ${o.reason ?? "no reason given"}
@@ -109204,7 +109430,8 @@ ${ctx}
               stopReason = "team-unavailable";
               break;
             }
-            await runSimpleHooks(hooks.OnError, options.workDir);
+            await runSimpleHooks(hooks.OnError, options.workDir, void 0, hookRunOptsFor(options));
+            await fireStopFailure(classifyStopFailure(err));
             throw new types_1.AgentTurnError(`Stream failed: ${err.message}`, trimToResumableBoundary(messages), completedRounds, err);
           }
           if (options.abortSignal?.aborted) {
@@ -109245,7 +109472,7 @@ ${ctx}
               continue;
             }
             if (depth === 0)
-              await runSimpleHooks(hooks.PostMessageComplete, options.workDir);
+              await runSimpleHooks(hooks.PostMessageComplete, options.workDir, void 0, hookRunOptsFor(options));
             stopReason = assistantMessage.stopReason === "max_tokens" ? "output-limit" : "empty-response";
             break;
           }
@@ -109329,7 +109556,7 @@ ${ctx}
               }
             }
             if (depth === 0)
-              await runSimpleHooks(hooks.PostMessageComplete, options.workDir);
+              await runSimpleHooks(hooks.PostMessageComplete, options.workDir, void 0, hookRunOptsFor(options));
             stopReason = "clean";
             break;
           }
@@ -109377,12 +109604,12 @@ ${ctx}
             } else if (name === "task") {
               const wantsBackground = input.run_in_background === true || input.run_in_background !== false && !!(0, agentTypes_1.findAgentType)(agentTypes, String(input.subagent_type ?? ""))?.background;
               const taskOptions = { ...auditOptions, _taskToolUseId: id };
-              const preTask = await runToolHooks(hooks.PreToolUse, "PreToolUse", name, input, options.workDir);
+              const preTask = await runToolHooks(hooks.PreToolUse, "PreToolUse", name, input, options.workDir, void 0, hookRunOptsFor(options));
               if (preTask.block) {
                 result = { error: `Blocked by PreToolUse hook: ${preTask.reason}` };
               } else {
                 result = wantsBackground && depth === 0 && options.backgroundAgents && !input.resume_agent_id ? dispatchBackgroundSubAgent(input, taskOptions, agentTypes, options.backgroundAgents) : await dispatchSubAgent(input, taskOptions, agentTypes);
-                const postTask = await runToolHooks(hooks.PostToolUse, "PostToolUse", name, input, options.workDir, result);
+                const postTask = await runToolHooks(hooks.PostToolUse, "PostToolUse", name, input, options.workDir, result, hookRunOptsFor(options));
                 const injectedTask = [preTask.context, postTask.context].filter(Boolean).join("\n");
                 if (injectedTask) {
                   if (result.error !== void 0)
@@ -109399,7 +109626,7 @@ ${ctx}
                 }
               }
             } else {
-              const pre = await runToolHooks(hooks.PreToolUse, "PreToolUse", name, input, options.workDir);
+              const pre = await runToolHooks(hooks.PreToolUse, "PreToolUse", name, input, options.workDir, void 0, hookRunOptsFor(options));
               if (pre.block) {
                 result = { error: `Blocked by PreToolUse hook: ${pre.reason}` };
               } else {
@@ -109445,9 +109672,9 @@ ${ctx}
                   const scope = input.scope === "global" ? "global" : "project";
                   void maybeCompactMemory(scope, options);
                 }
-                const post = await runToolHooks(hooks.PostToolUse, "PostToolUse", name, input, options.workDir, result);
+                const post = await runToolHooks(hooks.PostToolUse, "PostToolUse", name, input, options.workDir, result, hookRunOptsFor(options));
                 if (result.error !== void 0 && (hooks.PostToolUseFailure?.length ?? 0) > 0) {
-                  const f3 = await runLifecycleHooks(hooks.PostToolUseFailure, "PostToolUseFailure", options.workDir, { session_id: options.sessionId ?? "", tool_name: name, tool_input: input, error: String(result.error).slice(0, 4e3) }, name).catch(() => ({ block: false }));
+                  const f3 = await runLifecycleHooks(hooks.PostToolUseFailure, "PostToolUseFailure", options.workDir, { session_id: options.sessionId ?? "", tool_name: name, tool_input: input, error: String(result.error).slice(0, 4e3) }, name, hookRunOptsFor(options)).catch(() => ({ block: false }));
                   if (f3.context)
                     post.context = [post.context, f3.context].filter(Boolean).join("\n");
                   if (f3.block) {
@@ -109569,6 +109796,9 @@ ${result.output}` : `Error: ${result.error}` : result.output ?? "",
           stopReason = "budget";
         if (options.abortSignal?.aborted)
           stopReason = "aborted";
+        const apiFailure = apiFailureForStopReason(stopReason);
+        if (apiFailure)
+          await fireStopFailure(apiFailure);
         const notice = stopReasonNotice(stopReason, { budget, repeatError: stalledRepeatError });
         if (options._onStopReason)
           options._onStopReason(stopReason, notice || null);
@@ -109583,12 +109813,12 @@ ${result.output}` : `Error: ${result.error}` : result.output ?? "",
         throw new types_1.AgentTurnError(err?.message || "The turn ended unexpectedly", trimToResumableBoundary(messages), completedRounds, err);
       } finally {
         if (depth === 0 && (hooks.SessionEnd?.length ?? 0) > 0) {
-          await runLifecycleHooks(hooks.SessionEnd, "SessionEnd", options.workDir, { session_id: options.sessionId ?? "", reason: stopReason }, stopReason).catch(() => void 0);
+          await runLifecycleHooks(hooks.SessionEnd, "SessionEnd", options.workDir, { session_id: options.sessionId ?? "", reason: stopReason }, stopReason, hookRunOptsFor(options)).catch(() => void 0);
         }
         if (depth === 0)
-          await runSimpleHooks(hooks.OnStop, options.workDir);
+          await runSimpleHooks(hooks.OnStop, options.workDir, void 0, hookRunOptsFor(options));
         else
-          await runSimpleHooks(hooks.SubagentStop, options.workDir, { NEXRALL_AGENT_NAME: options._agentTypeName ?? "general-purpose" });
+          await runSimpleHooks(hooks.SubagentStop, options.workDir, { NEXRALL_AGENT_NAME: options._agentTypeName ?? "general-purpose" }, hookRunOptsFor(options));
       }
       return messages;
     }
@@ -109610,6 +109840,214 @@ ${result.output}` : `Error: ${result.error}` : result.output ?? "",
   }
 });
 
+// ../core/dist/agent/lifecycleHost.js
+var require_lifecycleHost = __commonJS({
+  "../core/dist/agent/lifecycleHost.js"(exports2) {
+    "use strict";
+    var __createBinding = exports2 && exports2.__createBinding || (Object.create ? function(o, m2, k, k2) {
+      if (k2 === void 0)
+        k2 = k;
+      var desc = Object.getOwnPropertyDescriptor(m2, k);
+      if (!desc || ("get" in desc ? !m2.__esModule : desc.writable || desc.configurable)) {
+        desc = { enumerable: true, get: function() {
+          return m2[k];
+        } };
+      }
+      Object.defineProperty(o, k2, desc);
+    } : function(o, m2, k, k2) {
+      if (k2 === void 0)
+        k2 = k;
+      o[k2] = m2[k];
+    });
+    var __setModuleDefault = exports2 && exports2.__setModuleDefault || (Object.create ? function(o, v) {
+      Object.defineProperty(o, "default", { enumerable: true, value: v });
+    } : function(o, v) {
+      o["default"] = v;
+    });
+    var __importStar = exports2 && exports2.__importStar || /* @__PURE__ */ function() {
+      var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function(o2) {
+          var ar = [];
+          for (var k in o2)
+            if (Object.prototype.hasOwnProperty.call(o2, k))
+              ar[ar.length] = k;
+          return ar;
+        };
+        return ownKeys(o);
+      };
+      return function(mod) {
+        if (mod && mod.__esModule)
+          return mod;
+        var result = {};
+        if (mod != null) {
+          for (var k = ownKeys(mod), i2 = 0; i2 < k.length; i2++)
+            if (k[i2] !== "default")
+              __createBinding(result, mod, k[i2]);
+        }
+        __setModuleDefault(result, mod);
+        return result;
+      };
+    }();
+    Object.defineProperty(exports2, "__esModule", { value: true });
+    exports2.fireInstructionsLoadedHooks = fireInstructionsLoadedHooks2;
+    exports2.startFileChangedWatcher = startFileChangedWatcher2;
+    var fs28 = __importStar(__require("fs"));
+    var path28 = __importStar(__require("path"));
+    var loop_1 = require_loop();
+    async function fireInstructionsLoadedHooks2(workDir, sessionId, files) {
+      if (!files.length)
+        return;
+      try {
+        const items = (0, loop_1.loadHooks)(workDir).InstructionsLoaded;
+        if (!items?.length)
+          return;
+        for (const f3 of files) {
+          await (0, loop_1.runLifecycleHooks)(items, "InstructionsLoaded", workDir, {
+            session_id: sessionId,
+            file_path: f3.file_path,
+            memory_type: f3.memory_type,
+            load_reason: f3.load_reason,
+            ...f3.globs ? { globs: f3.globs } : {}
+          }, f3.load_reason).catch(() => void 0);
+        }
+      } catch {
+      }
+    }
+    function isWatchableName(name) {
+      return !!name && !name.includes("/") && !name.includes("\\") && !name.includes("*") && !name.includes("?") && name !== "." && name !== "..";
+    }
+    function startFileChangedWatcher2(workDir, sessionId, opts) {
+      let items;
+      try {
+        items = (0, loop_1.loadHooks)(workDir).FileChanged;
+      } catch {
+        items = void 0;
+      }
+      if (!items?.length)
+        return null;
+      const staticNames = /* @__PURE__ */ new Set();
+      for (const it of items) {
+        if (it && Array.isArray(it.hooks)) {
+          const m2 = it.matcher;
+          if (!m2 || m2 === "*")
+            continue;
+          for (const raw of m2.split("|")) {
+            const name = raw.trim();
+            if (isWatchableName(name))
+              staticNames.add(name);
+          }
+        }
+      }
+      if (!staticNames.size)
+        return null;
+      const dynamicNames = /* @__PURE__ */ new Set();
+      const watched = () => /* @__PURE__ */ new Set([...staticNames, ...dynamicNames]);
+      const known = /* @__PURE__ */ new Set();
+      const seedKnown = (names) => {
+        for (const n of names) {
+          try {
+            if (fs28.existsSync(path28.join(workDir, n)))
+              known.add(n);
+          } catch {
+          }
+        }
+      };
+      seedKnown(staticNames);
+      const pending = /* @__PURE__ */ new Map();
+      let closed = false;
+      let watcher = null;
+      try {
+        watcher = fs28.watch(workDir, { persistent: false }, (_eventType, filename) => {
+          if (closed)
+            return;
+          const name = filename ? path28.basename(String(filename)) : "";
+          if (!name || !watched().has(name))
+            return;
+          const prev = pending.get(name);
+          if (prev)
+            clearTimeout(prev);
+          pending.set(name, setTimeout(() => {
+            pending.delete(name);
+            let exists = true;
+            try {
+              exists = fs28.existsSync(path28.join(workDir, name));
+            } catch {
+              exists = false;
+            }
+            const event = !exists ? "unlink" : known.has(name) ? "change" : "add";
+            if (exists)
+              known.add(name);
+            else
+              known.delete(name);
+            void fireChanged(workDir, sessionId, name, event, items, dynamicNames.has(name)).then((o) => {
+              if (!o)
+                return;
+              if (o.systemMessage && opts?.onSystemMessage) {
+                try {
+                  opts.onSystemMessage(o.systemMessage);
+                } catch {
+                }
+              }
+              if (o.watchPaths) {
+                dynamicNames.clear();
+                for (const p of o.watchPaths) {
+                  const n = isWatchableName(path28.basename(p)) ? path28.basename(p) : "";
+                  if (n)
+                    dynamicNames.add(n);
+                }
+                seedKnown(dynamicNames);
+              }
+            }).catch(() => {
+            });
+          }, 250));
+        });
+        watcher.on("error", () => {
+        });
+      } catch {
+        return null;
+      }
+      return {
+        stop() {
+          closed = true;
+          for (const t2 of pending.values())
+            clearTimeout(t2);
+          pending.clear();
+          try {
+            watcher?.close();
+          } catch {
+          }
+          watcher = null;
+        },
+        updateWatchPaths(paths) {
+          dynamicNames.clear();
+          for (const p of paths) {
+            const n = isWatchableName(path28.basename(p)) ? path28.basename(p) : "";
+            if (n)
+              dynamicNames.add(n);
+          }
+          seedKnown(dynamicNames);
+        },
+        watchedFiles() {
+          return [...watched()].sort();
+        }
+      };
+    }
+    async function fireChanged(workDir, sessionId, name, event, items, isDynamic) {
+      const abs = path28.join(workDir, name);
+      try {
+        const o = await (0, loop_1.runLifecycleHooks)(items, "FileChanged", workDir, {
+          session_id: sessionId,
+          file_path: abs,
+          event
+        }, isDynamic ? void 0 : name);
+        return { watchPaths: o.watchPaths, systemMessage: o.systemMessage };
+      } catch {
+        return null;
+      }
+    }
+  }
+});
+
 // ../core/dist/mcp/client.js
 var require_client2 = __commonJS({
   "../core/dist/mcp/client.js"(exports2) {
@@ -111826,6 +112264,7 @@ var require_dist3 = __commonJS({
     __exportStar(require_client(), exports2);
     __exportStar(require_executor(), exports2);
     __exportStar(require_loop(), exports2);
+    __exportStar(require_lifecycleHost(), exports2);
     __exportStar(require_modelCatalogue(), exports2);
     __exportStar(require_testIntegrity(), exports2);
     __exportStar(require_editCompleteness(), exports2);
@@ -169063,22 +169502,39 @@ var tryRead = (p) => {
     return null;
   }
 };
+var lastLoadedInstructions = [];
 function readNexrallMd(workDir) {
+  lastLoadedInstructions = [];
   if (noDiscovery)
     return void 0;
   const parts = [];
+  const noteLoaded = (file, memoryType) => {
+    try {
+      if (fs25.existsSync(file))
+        lastLoadedInstructions.push({ file_path: file, memory_type: memoryType, load_reason: "session_start" });
+    } catch {
+    }
+  };
   const memContent = (0, import_code_core16.readAllMemory)(workDir);
-  if (memContent)
+  if (memContent) {
     parts.push(memContent);
-  const globalContent = tryRead(path25.join(os15.homedir(), ".nexrall", "nexrall.md"));
-  if (globalContent)
+    noteLoaded((0, import_code_core16.memoryFilePath)("global"), "User");
+    if (workDir)
+      noteLoaded((0, import_code_core16.memoryFilePath)("project", workDir), "Project");
+  }
+  const globalNexrall = path25.join(os15.homedir(), ".nexrall", "nexrall.md");
+  const globalContent = tryRead(globalNexrall);
+  if (globalContent) {
     parts.push(`[Global instructions]
 ${globalContent}`);
+    noteLoaded(globalNexrall, "User");
+  }
   for (const candidate of NEXRALL_MD_CANDIDATES) {
     const content = tryRead(path25.join(workDir, candidate));
     if (content) {
       parts.push(`[Project instructions \u2014 ${candidate}]
 ${content}`);
+      noteLoaded(path25.join(workDir, candidate), "Project");
       break;
     }
   }
@@ -170646,6 +171102,18 @@ Resume it with: nex --worktree ${worktreeState.name}
   let sessionId = options.newSessionId ?? crypto7.randomBytes(8).toString("hex");
   activeSessionIdGetter = () => sessionId;
   let sessionTitle = options.sessionName ?? "";
+  const fileWatcher = noDiscovery ? null : (0, import_code_core16.startFileChangedWatcher)(workDir, sessionId, {
+    // A hook's {"systemMessage":"…"} is the event's one user-visible field.
+    onSystemMessage: (m2) => console.log(paint.dim(`  ${m2}`))
+  });
+  if (fileWatcher) {
+    const watching = fileWatcher.watchedFiles();
+    if (watching.length && !headless)
+      console.log(paint.dim(`  FileChanged hook: watching ${watching.join(", ")}`));
+    if (options.verbose)
+      process.stderr.write("[verbose] FileChanged hook: " + watching.join(", ") + "\n");
+  }
+  void (0, import_code_core16.fireInstructionsLoadedHooks)(workDir, sessionId, lastLoadedInstructions);
   const modeLocked = options.lockMode === true;
   let agentMode = modeLocked ? "plan" : options.initialMode ?? "auto";
   const refuseIfLocked = (what) => {
@@ -173400,6 +173868,7 @@ ${text}
     deliverBackgroundWhenIdle();
   });
   rl.on("close", () => {
+    fileWatcher?.stop();
     updateTitle();
     if (messages.length)
       saveSession2(sessionId, sessionTitle || "Untitled", workDir, messages);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexrall-code",
-  "version": "0.5.166",
+  "version": "0.5.168",
   "description": "Nexrall Code — AI coding assistant for your terminal (headless agent for scripts, CI and automation)",
   "keywords": [
     "ai",