steward-cli 0.25.0 → 0.26.1

package/dist/cli.js

@@ -41285,7 +41285,7 @@ var require_dist = __commonJS(function(exports) {
 });
 
 // src/app/app.ts
-import { existsSync as existsSync17 } from "node:fs";
+import { existsSync as existsSync19 } from "node:fs";
 
 // src/packages/tui/src/engine/HistoryStore.ts
 class HistoryStore {
@@ -47154,6 +47154,9 @@ class TerminalEngine {
 }
 var TerminalEngine_default = TerminalEngine;
 
+// src/packages/agents/src/engine/agent-session.ts
+import { randomUUID as randomUUID7 } from "node:crypto";
+
 // src/packages/services/src/session/store.ts
 import { randomUUID } from "node:crypto";
 import {
@@ -55998,10 +56001,21 @@ import { isIP } from "node:net";
 // package.json
 var package_default = {
   name: "steward-cli",
-  version: "0.25.0",
+  version: "0.26.1",
   description: "Interactive AI engineering assistant for the terminal.",
   author: "sapirrior",
   license: "MIT",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/sapirrior/steward.git"
+  },
+  bugs: {
+    url: "https://github.com/sapirrior/steward/issues"
+  },
+  homepage: "https://github.com/sapirrior/steward#readme",
+  publishConfig: {
+    access: "public"
+  },
   files: [
     "dist"
   ],
@@ -56964,6 +56978,723 @@ function getEnvConfig() {
     }
   };
 }
+// src/packages/plugins/src/hooks/types.ts
+var HOOK_EVENT_NAMES = [
+  "SessionStart",
+  "UserPromptSubmit",
+  "BeforeToolUse",
+  "AfterToolUse",
+  "ToolUseFailure",
+  "AgentStop"
+];
+var DEFAULT_HOOK_TIMEOUT_MS = 5000;
+var MIN_HOOK_TIMEOUT_MS = 100;
+var MAX_HOOK_TIMEOUT_MS = 30000;
+var MAX_HOOK_INPUT_BYTES = 256 * 1024;
+var MAX_HOOK_STDOUT_BYTES = 32 * 1024;
+var MAX_HOOK_STDERR_BYTES = 16 * 1024;
+var MAX_HOOK_CONTEXT_CHARS = 8 * 1024;
+var MAX_AGENT_STOP_CONTINUATIONS = 1;
+// src/packages/plugins/src/hooks/config.ts
+import { existsSync as existsSync12, readFileSync as readFileSync9 } from "node:fs";
+import { join as join13 } from "node:path";
+import { homedir as homedir8 } from "node:os";
+
+// src/packages/plugins/src/hooks/match.ts
+var EVENTS_SUPPORTING_MATCHER = [
+  "SessionStart",
+  "BeforeToolUse",
+  "AfterToolUse",
+  "ToolUseFailure"
+];
+function supportsMatcher(event) {
+  return EVENTS_SUPPORTING_MATCHER.includes(event);
+}
+function compileMatcher(event, rawMatcher) {
+  if (!supportsMatcher(event)) {
+    return {};
+  }
+  const trimmed = rawMatcher?.trim();
+  if (!trimmed || trimmed === "*") {
+    return { allTools: true };
+  }
+  const parts = trimmed.split("|").map((p) => p.trim()).filter(Boolean);
+  if (parts.length === 0 || parts.includes("*")) {
+    return { allTools: true };
+  }
+  return {
+    allTools: false,
+    matcherSet: new Set(parts)
+  };
+}
+function hasHooksForEvent(hooks, event) {
+  for (let i = 0;i < hooks.length; i++) {
+    const h = hooks[i];
+    if (h.enabled && h.event === event) {
+      return true;
+    }
+  }
+  return false;
+}
+function matchesHook(hook, payload) {
+  if (!hook.enabled || hook.event !== payload.hook_event_name) {
+    return false;
+  }
+  switch (payload.hook_event_name) {
+    case "SessionStart": {
+      if (hook.allTools || !hook.matcherSet || hook.matcherSet.size === 0) {
+        return true;
+      }
+      return hook.matcherSet.has(payload.source);
+    }
+    case "BeforeToolUse":
+    case "AfterToolUse":
+    case "ToolUseFailure": {
+      if (hook.allTools || !hook.matcherSet || hook.matcherSet.size === 0) {
+        return true;
+      }
+      const toolName = payload.tool_name;
+      return hook.matcherSet.has(toolName);
+    }
+    case "UserPromptSubmit":
+    case "AgentStop":
+      return true;
+    default:
+      return false;
+  }
+}
+
+// src/packages/plugins/src/hooks/config.ts
+var rawHookDefinitionSchema = object({
+  name: string2().min(1, "Hook name must not be empty."),
+  command: string2().min(1, "Hook command must not be empty."),
+  matcher: string2().optional(),
+  timeoutMs: number2().int().min(MIN_HOOK_TIMEOUT_MS, `timeoutMs must be at least ${MIN_HOOK_TIMEOUT_MS}ms.`).max(MAX_HOOK_TIMEOUT_MS, `timeoutMs must not exceed ${MAX_HOOK_TIMEOUT_MS}ms.`).optional(),
+  enabled: boolean2().optional(),
+  description: string2().optional()
+}).strict();
+var rawHooksConfigSchema = object({
+  version: literal(1, {
+    errorMap: () => ({ message: "Hooks config version must be 1." })
+  }),
+  hooks: object({
+    SessionStart: array(rawHookDefinitionSchema).optional(),
+    UserPromptSubmit: array(rawHookDefinitionSchema).optional(),
+    BeforeToolUse: array(rawHookDefinitionSchema).optional(),
+    AfterToolUse: array(rawHookDefinitionSchema).optional(),
+    ToolUseFailure: array(rawHookDefinitionSchema).optional(),
+    AgentStop: array(rawHookDefinitionSchema).optional()
+  }).strict().optional()
+}).strict();
+function compileHooksConfig(rawConfig, source, sourcePath) {
+  const parseResult = rawHooksConfigSchema.safeParse(rawConfig);
+  if (!parseResult.success) {
+    const errorMsg = parseResult.error.issues.map((i) => `${i.path.join(".") || "root"}: ${i.message}`).join("; ");
+    return { hooks: [], error: `Invalid hooks configuration: ${errorMsg}` };
+  }
+  const validConfig = parseResult.data;
+  const compiled = [];
+  if (!validConfig.hooks) {
+    return { hooks: compiled };
+  }
+  for (const eventName of HOOK_EVENT_NAMES) {
+    const hookDefs = validConfig.hooks[eventName];
+    if (!hookDefs || !Array.isArray(hookDefs)) {
+      continue;
+    }
+    for (let index = 0;index < hookDefs.length; index++) {
+      const def = hookDefs[index];
+      if (def.matcher !== undefined && !supportsMatcher(eventName)) {
+        return {
+          hooks: [],
+          error: `Hook "${def.name}" on event "${eventName}" cannot define a matcher; matchers are only supported on SessionStart, BeforeToolUse, AfterToolUse, and ToolUseFailure.`
+        };
+      }
+      const { allTools, matcherSet } = compileMatcher(eventName, def.matcher);
+      compiled.push({
+        source,
+        sourcePath,
+        event: eventName,
+        name: def.name,
+        command: def.command,
+        matcher: def.matcher,
+        allTools,
+        matcherSet,
+        timeoutMs: def.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS,
+        enabled: def.enabled ?? true,
+        description: def.description
+      });
+    }
+  }
+  return { hooks: compiled };
+}
+function getUserHooksPath() {
+  const dir = process.env.STEWARD_SETTINGS_DIR || join13(homedir8(), ".steward");
+  return join13(dir, "hooks.json");
+}
+function getProjectHooksPath(projectDir) {
+  return join13(projectDir, ".steward", "hooks.json");
+}
+function loadHooksConfigFile(filePath, source) {
+  if (!existsSync12(filePath)) {
+    return { hooks: [] };
+  }
+  let content;
+  try {
+    content = readFileSync9(filePath, "utf-8");
+  } catch (err) {
+    return {
+      hooks: [],
+      error: `Failed to read hooks configuration from ${filePath}: ${err.message}`
+    };
+  }
+  const trimmed = content.trim();
+  if (!trimmed) {
+    return { hooks: [] };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch (err) {
+    return {
+      hooks: [],
+      error: `Failed to parse JSON in hooks configuration from ${filePath}: ${err.message}`
+    };
+  }
+  return compileHooksConfig(parsed, source, filePath);
+}
+// src/packages/plugins/src/hooks/execute.ts
+import { spawn as spawn2 } from "node:child_process";
+var BLOCKING_EVENTS = new Set(["UserPromptSubmit", "BeforeToolUse", "AgentStop"]);
+function killProcessTree(pid, child) {
+  if (!pid)
+    return;
+  try {
+    child.stdin?.destroy();
+  } catch {}
+  if (process.platform === "win32") {
+    try {
+      spawn2("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" });
+    } catch {
+      try {
+        child.kill("SIGKILL");
+      } catch {}
+    }
+  } else {
+    try {
+      process.kill(-pid, "SIGKILL");
+    } catch (err) {
+      if (err.code !== "ESRCH") {
+        try {
+          child.kill("SIGKILL");
+        } catch {}
+      }
+    }
+    try {
+      child.kill("SIGKILL");
+    } catch {}
+  }
+}
+async function executeHook(options) {
+  const { hook, payload, abortSignal } = options;
+  if (hook.builtinHandler) {
+    try {
+      const result = await hook.builtinHandler(payload);
+      return { result };
+    } catch (err) {
+      return {
+        diagnostic: {
+          hookName: hook.name,
+          source: hook.source,
+          event: hook.event,
+          error: `Built-in hook threw error: ${err.message}`
+        }
+      };
+    }
+  }
+  if (abortSignal?.aborted) {
+    return {
+      diagnostic: {
+        hookName: hook.name,
+        source: hook.source,
+        event: hook.event,
+        error: "Execution aborted before spawning."
+      }
+    };
+  }
+  let serializedPayload;
+  try {
+    serializedPayload = JSON.stringify(payload);
+  } catch (err) {
+    return {
+      diagnostic: {
+        hookName: hook.name,
+        source: hook.source,
+        event: hook.event,
+        error: `Failed to serialize payload: ${err.message}`
+      }
+    };
+  }
+  if (Buffer.byteLength(serializedPayload, "utf-8") > MAX_HOOK_INPUT_BYTES) {
+    return {
+      diagnostic: {
+        hookName: hook.name,
+        source: hook.source,
+        event: hook.event,
+        error: `Payload exceeds max input limit of ${MAX_HOOK_INPUT_BYTES} bytes.`
+      }
+    };
+  }
+  const env = {
+    ...getFilteredChildEnv(),
+    STEWARD_PROJECT_DIR: payload.project_dir,
+    STEWARD_CWD: payload.cwd,
+    STEWARD_SESSION_ID: payload.session_id,
+    STEWARD_TURN_ID: payload.turn_id ?? "",
+    STEWARD_HOOK_EVENT: payload.hook_event_name,
+    STEWARD_HOOK_NAME: hook.name
+  };
+  const { shell, args } = getPlatformShell();
+  const childArgs = [...args, hook.command];
+  return new Promise((resolve) => {
+    let child;
+    let timer = null;
+    let stdoutBuffer = "";
+    let stderrBuffer = "";
+    let hasExited = false;
+    let abortListener = null;
+    try {
+      child = spawn2(shell, childArgs, {
+        cwd: payload.project_dir,
+        env,
+        stdio: ["pipe", "pipe", "pipe"],
+        detached: process.platform !== "win32"
+      });
+    } catch (err) {
+      return resolve({
+        diagnostic: {
+          hookName: hook.name,
+          source: hook.source,
+          event: hook.event,
+          error: `Failed to spawn process: ${err.message}`
+        }
+      });
+    }
+    const cleanup = () => {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      if (abortListener && abortSignal) {
+        abortSignal.removeEventListener("abort", abortListener);
+        abortListener = null;
+      }
+    };
+    timer = setTimeout(() => {
+      if (hasExited)
+        return;
+      hasExited = true;
+      cleanup();
+      killProcessTree(child.pid, child);
+      resolve({
+        diagnostic: {
+          hookName: hook.name,
+          source: hook.source,
+          event: hook.event,
+          error: `Hook timed out after ${hook.timeoutMs}ms.`,
+          stderr: stderrBuffer
+        }
+      });
+    }, hook.timeoutMs);
+    if (abortSignal) {
+      abortListener = () => {
+        if (hasExited)
+          return;
+        hasExited = true;
+        cleanup();
+        killProcessTree(child.pid, child);
+        resolve({
+          diagnostic: {
+            hookName: hook.name,
+            source: hook.source,
+            event: hook.event,
+            error: "Hook execution aborted by signal.",
+            stderr: stderrBuffer
+          }
+        });
+      };
+      abortSignal.addEventListener("abort", abortListener, { once: true });
+    }
+    child.stdin?.on("error", () => {});
+    child.stdout?.on("error", () => {});
+    child.stderr?.on("error", () => {});
+    child.stdout?.on("data", (chunk) => {
+      if (stdoutBuffer.length < MAX_HOOK_STDOUT_BYTES) {
+        stdoutBuffer += chunk.toString("utf-8");
+        if (stdoutBuffer.length > MAX_HOOK_STDOUT_BYTES) {
+          stdoutBuffer = stdoutBuffer.slice(0, MAX_HOOK_STDOUT_BYTES);
+        }
+      }
+    });
+    child.stderr?.on("data", (chunk) => {
+      if (stderrBuffer.length < MAX_HOOK_STDERR_BYTES) {
+        stderrBuffer += chunk.toString("utf-8");
+        if (stderrBuffer.length > MAX_HOOK_STDERR_BYTES) {
+          stderrBuffer = stderrBuffer.slice(0, MAX_HOOK_STDERR_BYTES);
+        }
+      }
+    });
+    try {
+      child.stdin?.write(serializedPayload, "utf-8", () => {
+        try {
+          child.stdin?.end();
+        } catch {}
+      });
+    } catch {
+      try {
+        child.stdin?.end();
+      } catch {}
+    }
+    const onExit = (code) => {
+      if (hasExited)
+        return;
+      hasExited = true;
+      cleanup();
+      const trimmedStdout = stdoutBuffer.trim();
+      const trimmedStderr = stderrBuffer.trim();
+      let parsedJsonResult;
+      let jsonParseError;
+      if (trimmedStdout.length > 0) {
+        try {
+          const parsed = JSON.parse(trimmedStdout);
+          if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const decision = parsed.decision === "block" || parsed.decision === "allow" ? parsed.decision : undefined;
+            const reason = typeof parsed.reason === "string" ? parsed.reason : undefined;
+            let additionalContext = typeof parsed.additionalContext === "string" ? parsed.additionalContext : undefined;
+            if (additionalContext && additionalContext.length > MAX_HOOK_CONTEXT_CHARS) {
+              additionalContext = additionalContext.slice(0, MAX_HOOK_CONTEXT_CHARS);
+            }
+            parsedJsonResult = {
+              decision,
+              reason,
+              additionalContext
+            };
+          } else {
+            jsonParseError = "Stdout was not a valid JSON object.";
+          }
+        } catch (err) {
+          jsonParseError = `Failed to parse stdout JSON: ${err.message}`;
+        }
+      }
+      if (code === 0) {
+        if (jsonParseError) {
+          return resolve({
+            diagnostic: {
+              hookName: hook.name,
+              source: hook.source,
+              event: hook.event,
+              error: jsonParseError,
+              exitCode: code,
+              stderr: trimmedStderr
+            }
+          });
+        }
+        return resolve({ result: parsedJsonResult ?? {} });
+      }
+      if (code === 2 && BLOCKING_EVENTS.has(payload.hook_event_name)) {
+        if (parsedJsonResult && parsedJsonResult.decision === "block") {
+          return resolve({ result: parsedJsonResult });
+        }
+        const blockReason = parsedJsonResult?.reason || (trimmedStderr.length > 0 ? trimmedStderr.slice(0, 500) : `Hook "${hook.name}" blocked the action.`);
+        return resolve({
+          result: {
+            decision: "block",
+            reason: blockReason,
+            additionalContext: parsedJsonResult?.additionalContext
+          },
+          diagnostic: trimmedStderr ? {
+            hookName: hook.name,
+            source: hook.source,
+            event: hook.event,
+            error: `Hook exited with code 2: ${trimmedStderr}`,
+            exitCode: code,
+            stderr: trimmedStderr
+          } : undefined
+        });
+      }
+      return resolve({
+        diagnostic: {
+          hookName: hook.name,
+          source: hook.source,
+          event: hook.event,
+          error: trimmedStderr.length > 0 ? `Hook exited with code ${code}: ${trimmedStderr}` : `Hook exited with code ${code}.`,
+          exitCode: code,
+          stderr: trimmedStderr
+        }
+      });
+    };
+    child.on("exit", (code) => onExit(code));
+    child.on("close", (code) => onExit(code));
+    child.on("error", (err) => {
+      if (hasExited)
+        return;
+      hasExited = true;
+      cleanup();
+      resolve({
+        diagnostic: {
+          hookName: hook.name,
+          source: hook.source,
+          event: hook.event,
+          error: `Process execution error: ${err.message}`
+        }
+      });
+    });
+  });
+}
+// src/packages/plugins/src/builtins/index.ts
+function createConfigHealthBuiltin(options = {}) {
+  return {
+    source: "builtin",
+    event: "SessionStart",
+    name: "HookConfigHealth",
+    command: "builtin:hook-config-health",
+    allTools: true,
+    timeoutMs: 1000,
+    enabled: true,
+    description: "Surfaces hook configuration health and loaded hook counts on session start.",
+    builtinHandler: (payload) => {
+      const startPayload = payload;
+      if (options.configErrors && options.configErrors.length > 0) {
+        const errorLines = options.configErrors.map((e) => `- [${e.source}] ${e.error}`).join(`
+`);
+        return {
+          additionalContext: `[Hook Configuration Diagnostics]
+The following hook configuration warnings were encountered during ${startPayload.source}:
+${errorLines}`
+        };
+      }
+      return {};
+    }
+  };
+}
+
+// src/packages/plugins/src/hooks/runtime.ts
+class HookRuntime {
+  hooks;
+  isTrusted;
+  pendingSessionContext = [];
+  stopHookContinuationsUsed = 0;
+  constructor(options = {}) {
+    this.isTrusted = options.isTrusted ?? false;
+    this.hooks = Object.freeze([...options.hooks ?? []]);
+  }
+  static load(options) {
+    const {
+      projectDir,
+      isTrusted,
+      userHooksPath = getUserHooksPath(),
+      projectHooksPath = getProjectHooksPath(projectDir),
+      pluginHooks = [],
+      builtins = []
+    } = options;
+    const configErrors = [];
+    const orderedHooks = [];
+    for (const b of builtins) {
+      orderedHooks.push(b);
+    }
+    if (isTrusted) {
+      const userRes = loadHooksConfigFile(userHooksPath, "user");
+      if (userRes.error) {
+        configErrors.push({ source: `User: ${userHooksPath}`, error: userRes.error });
+      } else {
+        for (const h of userRes.hooks) {
+          orderedHooks.push(h);
+        }
+      }
+      const projRes = loadHooksConfigFile(projectHooksPath, "project");
+      if (projRes.error) {
+        configErrors.push({ source: `Project: ${projectHooksPath}`, error: projRes.error });
+      } else {
+        for (const h of projRes.hooks) {
+          orderedHooks.push(h);
+        }
+      }
+      for (const p of pluginHooks) {
+        orderedHooks.push(p);
+      }
+    }
+    const healthBuiltin = createConfigHealthBuiltin({
+      configErrors,
+      loadedHooksCount: orderedHooks.length
+    });
+    orderedHooks.unshift(healthBuiltin);
+    return new HookRuntime({
+      hooks: orderedHooks,
+      isTrusted
+    });
+  }
+  get compiledHooks() {
+    return this.hooks;
+  }
+  get trusted() {
+    return this.isTrusted;
+  }
+  hasHooksForEvent(event) {
+    return hasHooksForEvent(this.hooks, event);
+  }
+  getPendingSessionContext() {
+    return [...this.pendingSessionContext];
+  }
+  consumePendingSessionContext() {
+    const ctx = [...this.pendingSessionContext];
+    this.pendingSessionContext = [];
+    return ctx;
+  }
+  canContinueAgentStop() {
+    return this.stopHookContinuationsUsed < MAX_AGENT_STOP_CONTINUATIONS;
+  }
+  recordAgentStopContinuation() {
+    this.stopHookContinuationsUsed++;
+  }
+  resetTurnContinuationState() {
+    this.stopHookContinuationsUsed = 0;
+  }
+  async executeLifecycle(payload, abortSignal) {
+    if (!this.hasHooksForEvent(payload.hook_event_name)) {
+      return {
+        blocked: false,
+        context: [],
+        errors: []
+      };
+    }
+    const matchingHooks = this.hooks.filter((h) => matchesHook(h, payload));
+    if (matchingHooks.length === 0) {
+      return {
+        blocked: false,
+        context: [],
+        errors: []
+      };
+    }
+    let blocked = false;
+    let firstBlockReason;
+    const contextList = [];
+    const errorDiagnostics = [];
+    for (const hook of matchingHooks) {
+      if (abortSignal?.aborted) {
+        break;
+      }
+      const execResult = await executeHook({
+        hook,
+        payload,
+        abortSignal
+      });
+      if (execResult.diagnostic) {
+        errorDiagnostics.push(execResult.diagnostic);
+      }
+      if (execResult.result) {
+        if (execResult.result.decision === "block") {
+          blocked = true;
+          if (!firstBlockReason) {
+            firstBlockReason = execResult.result.reason || `Hook "${hook.name}" blocked the action.`;
+          }
+        }
+        if (execResult.result.additionalContext && execResult.result.additionalContext.trim()) {
+          contextList.push(execResult.result.additionalContext.trim());
+        }
+      }
+    }
+    return {
+      blocked,
+      firstBlockReason,
+      context: contextList,
+      errors: errorDiagnostics
+    };
+  }
+  async runSessionStart(params) {
+    const payload = {
+      hook_event_name: "SessionStart",
+      session_id: params.sessionId,
+      project_dir: params.projectDir,
+      cwd: params.cwd,
+      source: params.source
+    };
+    const result = await this.executeLifecycle(payload, params.abortSignal);
+    if (result.context.length > 0) {
+      this.pendingSessionContext.push(...result.context);
+    }
+    return result;
+  }
+  async runUserPromptSubmit(params) {
+    this.resetTurnContinuationState();
+    const payload = {
+      hook_event_name: "UserPromptSubmit",
+      session_id: params.sessionId,
+      turn_id: params.turnId,
+      project_dir: params.projectDir,
+      cwd: params.cwd,
+      prompt: params.prompt
+    };
+    return this.executeLifecycle(payload, params.abortSignal);
+  }
+  async runBeforeToolUse(params) {
+    const payload = {
+      hook_event_name: "BeforeToolUse",
+      session_id: params.sessionId,
+      turn_id: params.turnId,
+      project_dir: params.projectDir,
+      cwd: params.cwd,
+      tool_call_id: params.toolCallId,
+      tool_name: params.toolName,
+      tool_input: params.toolInput
+    };
+    return this.executeLifecycle(payload, params.abortSignal);
+  }
+  async runAfterToolUse(params) {
+    const payload = {
+      hook_event_name: "AfterToolUse",
+      session_id: params.sessionId,
+      turn_id: params.turnId,
+      project_dir: params.projectDir,
+      cwd: params.cwd,
+      tool_call_id: params.toolCallId,
+      tool_name: params.toolName,
+      tool_input: params.toolInput,
+      tool_output: params.toolOutput,
+      is_error: params.isError,
+      duration_ms: params.durationMs
+    };
+    return this.executeLifecycle(payload, params.abortSignal);
+  }
+  async runToolUseFailure(params) {
+    const payload = {
+      hook_event_name: "ToolUseFailure",
+      session_id: params.sessionId,
+      turn_id: params.turnId,
+      project_dir: params.projectDir,
+      cwd: params.cwd,
+      tool_call_id: params.toolCallId,
+      tool_name: params.toolName,
+      tool_input: params.toolInput,
+      error: params.error,
+      duration_ms: params.durationMs
+    };
+    return this.executeLifecycle(payload, params.abortSignal);
+  }
+  async runAgentStop(params) {
+    const payload = {
+      hook_event_name: "AgentStop",
+      session_id: params.sessionId,
+      turn_id: params.turnId,
+      project_dir: params.projectDir,
+      cwd: params.cwd,
+      stop_reason: params.stopReason,
+      finish_reason: params.finishReason,
+      assistant_text: params.assistantText,
+      stop_hook_active: params.stopHookActive
+    };
+    return this.executeLifecycle(payload, params.abortSignal);
+  }
+}
 // src/packages/agents/src/engine/constants.ts
 var SAFETY_STEP_CEILING = 50;
 
@@ -56980,9 +57711,12 @@ async function runAgentTurn(options) {
   const toolResults = [];
   const turnStartedAt = new Date().toISOString();
   const turnStartMonotonic = performance.now();
+  let baseInstructions = options.instructions ?? "";
+  let pendingStepContext = [];
+  let stopHookContinuations = 0;
   const activeMessages = [...options.messages];
-  if (options.instructions) {
-    activeMessages.unshift({ role: "system", content: options.instructions });
+  if (baseInstructions) {
+    activeMessages.unshift({ role: "system", content: baseInstructions });
   }
   const accumulatedUsage = {
     inputTokens: 0,
@@ -57002,6 +57736,29 @@ async function runAgentTurn(options) {
       if (options.abortSignal?.aborted) {
         break;
       }
+      if (pendingStepContext.length > 0) {
+        const extraSection = `
+
+[Hook Context]
+` + pendingStepContext.join(`
+`);
+        pendingStepContext = [];
+        const systemMsgIdx = activeMessages.findIndex((m) => m.role === "system");
+        if (systemMsgIdx >= 0) {
+          const currentSys = activeMessages[systemMsgIdx];
+          const currentContent = typeof currentSys.content === "string" ? currentSys.content : Array.isArray(currentSys.content) ? currentSys.content.filter((c) => c.type === "text").map((c) => c.text).join(`
+`) : "";
+          activeMessages[systemMsgIdx] = {
+            role: "system",
+            content: currentContent + extraSection
+          };
+        } else {
+          activeMessages.unshift({
+            role: "system",
+            content: extraSection.trim()
+          });
+        }
+      }
       const inferenceRequest = {
         model: {
           ...options.model,
@@ -57086,6 +57843,21 @@ async function runAgentTurn(options) {
         usage: stepResult.usage
       });
       if (stepToolCalls.length === 0) {
+        if (options.callbacks?.agentStop && !options.abortSignal?.aborted && stopHookContinuations === 0) {
+          const stopOutcome = await options.callbacks.agentStop({
+            stopReason: "natural",
+            finishReason: finalFinishReason,
+            assistantText: accumulatedText,
+            stopHookActive: false
+          });
+          if (stopOutcome.blocked && stopHookContinuations === 0 && stepIndex < maxSteps) {
+            stopHookContinuations++;
+            const retryGuidance = stopOutcome.reason || "AgentStop requested continuation. Please continue your turn.";
+            pendingStepContext.push(`[AgentStop Continuation]
+${retryGuidance}`);
+            continue;
+          }
+        }
         break;
       }
       const toolResultsForStep = [];
@@ -57093,6 +57865,44 @@ async function runAgentTurn(options) {
         if (options.abortSignal?.aborted) {
           break;
         }
+        let isBlocked = false;
+        let blockReason;
+        if (options.callbacks?.beforeToolUse) {
+          const beforeRes = await options.callbacks.beforeToolUse({
+            toolCallId: call.id,
+            toolName: call.name,
+            toolInput: call.arguments ?? {}
+          });
+          if (beforeRes.blocked) {
+            isBlocked = true;
+            blockReason = beforeRes.reason || `Tool execution blocked by hook.`;
+          }
+        }
+        if (isBlocked) {
+          const blockedResultInfo = {
+            id: call.id,
+            name: call.name,
+            args: call.arguments,
+            result: `Tool "${call.name}" blocked: ${blockReason}`,
+            isError: true,
+            durationMs: 0,
+            startedAt: new Date().toISOString(),
+            finishedAt: new Date().toISOString()
+          };
+          toolResults.push(blockedResultInfo);
+          options.onEvent?.({
+            type: "tool-result",
+            toolResult: blockedResultInfo
+          });
+          toolResultsForStep.push({
+            type: "tool-result",
+            toolCallId: call.id,
+            toolName: call.name,
+            output: blockedResultInfo.result,
+            isError: true
+          });
+          continue;
+        }
         if (options.toolExecutor) {
           const resultInfo = await options.toolExecutor(call);
           toolResults.push(resultInfo);
@@ -57107,6 +57917,35 @@ async function runAgentTurn(options) {
             output: resultInfo.result,
             isError: resultInfo.isError
           });
+          if (resultInfo.isError) {
+            if (options.callbacks?.toolUseFailure) {
+              const errorText = typeof resultInfo.result === "object" && resultInfo.result !== null ? JSON.stringify(resultInfo.result) : String(resultInfo.result);
+              const failureRes = await options.callbacks.toolUseFailure({
+                toolCallId: call.id,
+                toolName: call.name,
+                toolInput: call.arguments ?? {},
+                error: errorText,
+                durationMs: resultInfo.durationMs ?? 0
+              });
+              if (failureRes?.context && failureRes.context.length > 0) {
+                pendingStepContext.push(...failureRes.context);
+              }
+            }
+          } else {
+            if (options.callbacks?.afterToolUse) {
+              const afterRes = await options.callbacks.afterToolUse({
+                toolCallId: call.id,
+                toolName: call.name,
+                toolInput: call.arguments ?? {},
+                toolOutput: resultInfo.result,
+                isError: false,
+                durationMs: resultInfo.durationMs ?? 0
+              });
+              if (afterRes?.context && afterRes.context.length > 0) {
+                pendingStepContext.push(...afterRes.context);
+              }
+            }
+          }
         }
       }
       if (toolResultsForStep.length > 0) {
@@ -57218,28 +58057,28 @@ var PendingJournalSchema = union([
 import { createHash as createHash2, randomUUID as randomUUID3 } from "node:crypto";
 import {
   closeSync as closeSync4,
-  existsSync as existsSync12,
+  existsSync as existsSync13,
   fsyncSync as fsyncSync3,
   mkdirSync as mkdirSync7,
   openSync as openSync4,
-  readFileSync as readFileSync9,
+  readFileSync as readFileSync10,
   renameSync as renameSync3,
   unlinkSync as unlinkSync3,
   writeSync as writeSync3
 } from "node:fs";
-import { homedir as homedir8 } from "node:os";
-import { join as join13 } from "node:path";
+import { homedir as homedir9 } from "node:os";
+import { join as join14 } from "node:path";
 function getCheckpointsRootDir() {
   if (process.env.STEWARD_CHECKPOINTS_DIR) {
     return process.env.STEWARD_CHECKPOINTS_DIR;
   }
-  return join13(homedir8(), ".steward", "checkpoints");
+  return join14(homedir9(), ".steward", "checkpoints");
 }
 function getWorkspaceCasDir(workspaceHash) {
-  return join13(getCheckpointsRootDir(), workspaceHash, "cas");
+  return join14(getCheckpointsRootDir(), workspaceHash, "cas");
 }
 function getBlobPath(workspaceHash, sha256) {
-  return join13(getWorkspaceCasDir(workspaceHash), sha256);
+  return join14(getWorkspaceCasDir(workspaceHash), sha256);
 }
 function computeSha256(data) {
   const hash = createHash2("sha256");
@@ -57250,14 +58089,14 @@ function writeCasBlob(workspaceHash, content) {
   const buffer = Buffer.isBuffer(content) ? content : typeof content === "string" ? Buffer.from(content, "utf-8") : Buffer.from(content);
   const sha256 = computeSha256(buffer);
   const casDir = getWorkspaceCasDir(workspaceHash);
-  if (!existsSync12(casDir)) {
+  if (!existsSync13(casDir)) {
     mkdirSync7(casDir, { recursive: true });
   }
   const targetPath = getBlobPath(workspaceHash, sha256);
-  if (existsSync12(targetPath)) {
+  if (existsSync13(targetPath)) {
     return { sha256, path: targetPath, size: buffer.length };
   }
-  const tmpPath = join13(casDir, `.tmp-${sha256}-${randomUUID3().slice(0, 8)}`);
+  const tmpPath = join14(casDir, `.tmp-${sha256}-${randomUUID3().slice(0, 8)}`);
   let fd = null;
   try {
     fd = openSync4(tmpPath, "w", 384);
@@ -57273,7 +58112,7 @@ function writeCasBlob(workspaceHash, content) {
         closeSync4(fd);
       } catch {}
     }
-    if (existsSync12(tmpPath)) {
+    if (existsSync13(tmpPath)) {
       try {
         unlinkSync3(tmpPath);
       } catch {}
@@ -57283,10 +58122,10 @@ function writeCasBlob(workspaceHash, content) {
 }
 function readCasBlob(workspaceHash, sha256) {
   const targetPath = getBlobPath(workspaceHash, sha256);
-  if (!existsSync12(targetPath)) {
+  if (!existsSync13(targetPath)) {
     throw new Error(`CAS blob not found: ${sha256} in workspace ${workspaceHash}`);
   }
-  const buffer = readFileSync9(targetPath);
+  const buffer = readFileSync10(targetPath);
   const actualHash = computeSha256(buffer);
   if (actualHash !== sha256) {
     throw new Error(`CAS blob corruption detected for ${sha256}: computed hash is ${actualHash}`);
@@ -57347,24 +58186,24 @@ var globalMutationLockManager = new MutationLockManager;
 import { randomUUID as randomUUID4 } from "node:crypto";
 import {
   closeSync as closeSync5,
-  existsSync as existsSync13,
+  existsSync as existsSync14,
   fsyncSync as fsyncSync4,
   mkdirSync as mkdirSync8,
   openSync as openSync5,
-  readFileSync as readFileSync10,
+  readFileSync as readFileSync11,
   renameSync as renameSync4,
   unlinkSync as unlinkSync4,
   writeSync as writeSync4
 } from "node:fs";
-import { join as join14 } from "node:path";
+import { join as join15 } from "node:path";
 function getSessionCheckpointDir(workspaceHash, sessionId) {
-  return join14(getCheckpointsRootDir(), workspaceHash, "sessions", sessionId);
+  return join15(getCheckpointsRootDir(), workspaceHash, "sessions", sessionId);
 }
 function getManifestPath(workspaceHash, sessionId) {
-  return join14(getSessionCheckpointDir(workspaceHash, sessionId), "manifest.json");
+  return join15(getSessionCheckpointDir(workspaceHash, sessionId), "manifest.json");
 }
 function getPendingJournalPath(workspaceHash, sessionId) {
-  return join14(getSessionCheckpointDir(workspaceHash, sessionId), "pending.json");
+  return join15(getSessionCheckpointDir(workspaceHash, sessionId), "pending.json");
 }
 
 class SessionStoreSerializer {
@@ -57389,8 +58228,8 @@ class SessionStoreSerializer {
 }
 var storeSerializer = new SessionStoreSerializer;
 function atomicWriteJson(targetPath, data) {
-  const dir = join14(targetPath, "..");
-  if (!existsSync13(dir)) {
+  const dir = join15(targetPath, "..");
+  if (!existsSync14(dir)) {
     mkdirSync8(dir, { recursive: true });
   }
   const tmpPath = `${targetPath}.tmp-${randomUUID4().slice(0, 8)}`;
@@ -57410,7 +58249,7 @@ function atomicWriteJson(targetPath, data) {
         closeSync5(fd);
       } catch {}
     }
-    if (existsSync13(tmpPath)) {
+    if (existsSync14(tmpPath)) {
       try {
         unlinkSync4(tmpPath);
       } catch {}
@@ -57420,23 +58259,23 @@ function atomicWriteJson(targetPath, data) {
 }
 function quarantineCheckpointFile(filePath) {
   try {
-    if (!existsSync13(filePath))
+    if (!existsSync14(filePath))
       return;
-    const dir = join14(filePath, "..", ".quarantine");
-    if (!existsSync13(dir)) {
+    const dir = join15(filePath, "..", ".quarantine");
+    if (!existsSync14(dir)) {
       mkdirSync8(dir, { recursive: true });
     }
     const fileName = `${filePath.split("/").pop()}-${Date.now()}-${randomUUID4().slice(0, 6)}`;
-    renameSync4(filePath, join14(dir, fileName));
+    renameSync4(filePath, join15(dir, fileName));
   } catch {}
 }
 function loadCheckpointManifest(workspaceHash, sessionId) {
   const targetPath = getManifestPath(workspaceHash, sessionId);
-  if (!existsSync13(targetPath)) {
+  if (!existsSync14(targetPath)) {
     return null;
   }
   try {
-    const raw = readFileSync10(targetPath, "utf-8");
+    const raw = readFileSync11(targetPath, "utf-8");
     const parsed = JSON.parse(raw);
     const result = SessionCheckpointManifestSchema.safeParse(parsed);
     if (result.success) {
@@ -57458,11 +58297,11 @@ async function saveCheckpointManifest(workspaceHash, sessionId, manifest) {
 }
 function loadPendingJournal(workspaceHash, sessionId) {
   const targetPath = getPendingJournalPath(workspaceHash, sessionId);
-  if (!existsSync13(targetPath)) {
+  if (!existsSync14(targetPath)) {
     return null;
   }
   try {
-    const raw = readFileSync10(targetPath, "utf-8");
+    const raw = readFileSync11(targetPath, "utf-8");
     const parsed = JSON.parse(raw);
     const result = PendingJournalSchema.safeParse(parsed);
     if (result.success) {
@@ -57486,7 +58325,7 @@ async function deletePendingJournal(workspaceHash, sessionId) {
   const key = `${workspaceHash}:${sessionId}`;
   await storeSerializer.run(key, () => {
     const targetPath = getPendingJournalPath(workspaceHash, sessionId);
-    if (existsSync13(targetPath)) {
+    if (existsSync14(targetPath)) {
       try {
         unlinkSync4(targetPath);
       } catch {}
@@ -57515,7 +58354,7 @@ async function commitTurnCheckpoint(workspaceHash, sessionId, workspaceRoot, tur
     const manifestPath = getManifestPath(workspaceHash, sessionId);
     atomicWriteJson(manifestPath, manifest);
     const pendingPath = getPendingJournalPath(workspaceHash, sessionId);
-    if (existsSync13(pendingPath)) {
+    if (existsSync14(pendingPath)) {
       try {
         unlinkSync4(pendingPath);
       } catch {}
@@ -57523,7 +58362,7 @@ async function commitTurnCheckpoint(workspaceHash, sessionId, workspaceRoot, tur
   });
 }
 // src/packages/services/src/checkpoint/tracker.ts
-import { existsSync as existsSync14, lstatSync as lstatSync3, readFileSync as readFileSync11, statSync as statSync5 } from "node:fs";
+import { existsSync as existsSync15, lstatSync as lstatSync3, readFileSync as readFileSync12, statSync as statSync5 } from "node:fs";
 class MutationCheckpointTracker {
   workspaceRoot;
   workspaceHash;
@@ -57578,7 +58417,7 @@ class MutationCheckpointTracker {
         };
       }
       let preState;
-      if (existsSync14(canonicalPath)) {
+      if (existsSync15(canonicalPath)) {
         const lstat = lstatSync3(canonicalPath);
         if (lstat.isDirectory()) {
           throw new Error(`Target path is a directory: ${canonicalPath}`);
@@ -57587,7 +58426,7 @@ class MutationCheckpointTracker {
           throw new Error(`Target path is not a regular file: ${canonicalPath}`);
         }
         const stat = statSync5(canonicalPath);
-        const buffer = readFileSync11(canonicalPath);
+        const buffer = readFileSync12(canonicalPath);
         const { sha256, size } = writeCasBlob(this.workspaceHash, buffer);
         preState = {
           kind: "file",
@@ -57628,9 +58467,9 @@ class MutationCheckpointTracker {
       throw new Error(`Mutation completed for untracked path: ${canonicalPath}`);
     }
     let postState;
-    if (existsSync14(canonicalPath)) {
+    if (existsSync15(canonicalPath)) {
       const stat = statSync5(canonicalPath);
-      const buffer = readFileSync11(canonicalPath);
+      const buffer = readFileSync12(canonicalPath);
       const { sha256, size } = writeCasBlob(this.workspaceHash, buffer);
       postState = {
         kind: "file",
@@ -57696,24 +58535,24 @@ class MutationCheckpointTracker {
 import {
   chmodSync as chmodSync2,
   closeSync as closeSync6,
-  existsSync as existsSync15,
+  existsSync as existsSync16,
   fsyncSync as fsyncSync5,
   mkdirSync as mkdirSync9,
   openSync as openSync6,
-  readFileSync as readFileSync12,
+  readFileSync as readFileSync13,
   renameSync as renameSync5,
   statSync as statSync6,
   unlinkSync as unlinkSync5,
   writeSync as writeSync5
 } from "node:fs";
-import { dirname as dirname6, join as join15, resolve as resolve10 } from "node:path";
+import { dirname as dirname6, join as join16, resolve as resolve10 } from "node:path";
 import { randomUUID as randomUUID5 } from "node:crypto";
 function getFileStateOnDisk(absPath) {
-  if (!existsSync15(absPath)) {
+  if (!existsSync16(absPath)) {
     return { kind: "missing" };
   }
   const stat = statSync6(absPath);
-  const buf = readFileSync12(absPath);
+  const buf = readFileSync13(absPath);
   const sha256 = computeSha256(buf);
   return {
     kind: "file",
@@ -57724,17 +58563,17 @@ function getFileStateOnDisk(absPath) {
 }
 function restoreFileStateToDisk(workspaceHash, absPath, state) {
   if (state.kind === "missing") {
-    if (existsSync15(absPath)) {
+    if (existsSync16(absPath)) {
       unlinkSync5(absPath);
     }
     return;
   }
   const dir = dirname6(absPath);
-  if (!existsSync15(dir)) {
+  if (!existsSync16(dir)) {
     mkdirSync9(dir, { recursive: true });
   }
   const blobBytes = readCasBlob(workspaceHash, state.sha256);
-  const tmpPath = join15(dir, `.tmp-restore-${state.sha256.slice(0, 8)}-${randomUUID5().slice(0, 8)}`);
+  const tmpPath = join16(dir, `.tmp-restore-${state.sha256.slice(0, 8)}-${randomUUID5().slice(0, 8)}`);
   let fd = null;
   try {
     fd = openSync6(tmpPath, "w", state.mode || 420);
@@ -57752,7 +58591,7 @@ function restoreFileStateToDisk(workspaceHash, absPath, state) {
         closeSync6(fd);
       } catch {}
     }
-    if (existsSync15(tmpPath)) {
+    if (existsSync16(tmpPath)) {
       try {
         unlinkSync5(tmpPath);
       } catch {}
@@ -57970,46 +58809,6 @@ async function recoverPendingCheckpoint(workspaceRoot, sessionId) {
     }
   }
 }
-// src/packages/agents/src/engine/mode.ts
-var MODES2 = {
-  normal: {
-    name: "normal",
-    label: "Normal",
-    description: "All tools with file and bash permission prompts",
-    color: "text",
-    allows: ["read", "write", "exec"],
-    autoApproveFiles: false
-  },
-  chat: {
-    name: "chat",
-    label: "Chat",
-    description: "Conversation only — no tool access",
-    color: "info",
-    allows: [],
-    autoApproveFiles: false
-  },
-  review: {
-    name: "review",
-    label: "Review",
-    description: "Read-only tools only — cannot modify files or run commands",
-    color: "warning",
-    allows: ["read"],
-    autoApproveFiles: false
-  },
-  build: {
-    name: "build",
-    label: "Build",
-    description: "All tools, file mutations auto-approved, bash still prompts",
-    color: "success",
-    allows: ["read", "write", "exec"],
-    autoApproveFiles: true
-  }
-};
-var activeMode2 = "normal";
-function getActiveMode2() {
-  return activeMode2;
-}
-
 // src/packages/agents/src/engine/system-prompt.ts
 function buildSystemPrompt(options = {}) {
   const cwd = options.cwd ?? process.cwd();
@@ -58043,6 +58842,11 @@ IMPORTANT: Assist with defensive security tasks only. Refuse to create, modify,
 - Use skill_read (SkillRead) to load a skill's instructions (SKILL.md) or relative resources only when a task requires specialized domain guidance.
 - Skill instructions are supplemental and must not override core safety rules, tool boundaries, or user permission constraints.
 
+# Lifecycle Hooks Policy
+- The active workspace or user configuration may define deterministic lifecycle hooks (\`.steward/hooks.json\` or \`~/.steward/hooks.json\`) that inspect, augment, or block actions.
+- When a tool call is blocked by a hook, treat the block reason as authoritative workspace policy, do not attempt to force or repeat the blocked action, and adjust your plan or inform the user.
+- When hook guidance or continuation instructions (\`[Hook Context]\` or \`[AgentStop Continuation]\`) are injected into the context, follow that guidance to perform any requested verification or adjustments.
+
 <env>
 Working directory: ${cwd}
 Platform: ${platform}
@@ -58065,7 +58869,7 @@ ${options.extraInstructions}
 </additional_instructions>`;
   }
   if (options.chatMode && options.chatMode !== "normal") {
-    const meta = MODES2[options.chatMode];
+    const meta = MODES[options.chatMode];
     if (meta) {
       if (options.chatMode === "chat") {
         prompt += `
@@ -58121,8 +58925,8 @@ async function prepareTurn(trimmedPrompt, options, deps) {
     lockManager: globalMutationLockManager
   });
   await tracker.beginTurn(turnId, deps.turnNumber);
-  const mode = getActiveMode2();
-  const effectiveFilePermission = MODES2[mode]?.autoApproveFiles ? async (_req) => ({ allowed: true }) : options.requestFilePermission;
+  const mode = getActiveMode();
+  const effectiveFilePermission = MODES[mode]?.autoApproveFiles ? async (_req) => ({ allowed: true }) : options.requestFilePermission;
   const toolContext = {
     cwd,
     mode,
@@ -58227,6 +59031,7 @@ class AgentSession {
   messages = [];
   sessionData;
   sessionLogWriter;
+  hookRuntime;
   accumulatedUsage = {
     inputTokens: 0,
     outputTokens: 0,
@@ -58240,6 +59045,7 @@ class AgentSession {
   shellTasks = new ShellTaskManager;
   constructor(initialConfig, existingSession, deps) {
     this.ai = deps?.ai ?? createAIEngine();
+    this.hookRuntime = deps?.hookRuntime;
     if (existingSession) {
       this.sessionData = existingSession;
       this.config = {
@@ -58285,6 +59091,26 @@ class AgentSession {
   get session() {
     return this.sessionData;
   }
+  getHookRuntime() {
+    return this.hookRuntime;
+  }
+  async initializeHooks(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const isTrusted = options.isTrusted ?? isFolderTrusted(cwd);
+    const source = options.source ?? "startup";
+    if (!this.hookRuntime) {
+      this.hookRuntime = HookRuntime.load({
+        projectDir: cwd,
+        isTrusted
+      });
+    }
+    await this.hookRuntime.runSessionStart({
+      sessionId: this.sessionData.id,
+      projectDir: cwd,
+      cwd,
+      source
+    });
+  }
   setModel(selection, persist = true) {
     this.config.provider = selection.provider;
     this.config.modelId = selection.modelId;
@@ -58346,8 +59172,39 @@ class AgentSession {
     if (!trimmedPrompt) {
       throw new Error("Prompt cannot be empty.");
     }
+    const cwd = options.cwd ?? process.cwd();
+    if (!this.hookRuntime) {
+      await this.initializeHooks({
+        cwd,
+        isTrusted: isFolderTrusted(cwd),
+        source: "startup"
+      });
+    }
+    const previewTurnId = randomUUID7();
+    const promptHookResult = await this.hookRuntime.runUserPromptSubmit({
+      sessionId: this.sessionData.id,
+      turnId: previewTurnId,
+      projectDir: cwd,
+      cwd,
+      prompt: trimmedPrompt
+    });
+    if (promptHookResult.blocked) {
+      const blockReason = promptHookResult.firstBlockReason || "UserPromptSubmit hook blocked the prompt.";
+      throw new Error(`Prompt blocked: ${blockReason}`);
+    }
     this.isGenerating = true;
-    const prep = await prepareTurn(trimmedPrompt, options, {
+    const consumedSessionStartCtx = this.hookRuntime.consumePendingSessionContext();
+    const combinedHookContext = [...consumedSessionStartCtx, ...promptHookResult.context];
+    const hookInstructionText = combinedHookContext.length > 0 ? `[Hook Instructions]
+` + combinedHookContext.join(`
+`) : undefined;
+    const effectiveExtraInstructions = [options.extraInstructions, hookInstructionText].filter(Boolean).join(`
+
+`) || undefined;
+    const prep = await prepareTurn(trimmedPrompt, {
+      ...options,
+      extraInstructions: effectiveExtraInstructions
+    }, {
       sessionId: this.sessionData.id,
       shellTasks: this.shellTasks,
       sessionLogWriter: this.sessionLogWriter,
@@ -58390,6 +59247,66 @@ class AgentSession {
         };
       }
     };
+    const callbacks = {
+      beforeToolUse: async (params) => {
+        const res = await this.hookRuntime.runBeforeToolUse({
+          sessionId: this.sessionData.id,
+          turnId: prep.turnId,
+          projectDir: prep.toolContext.cwd,
+          cwd: prep.toolContext.cwd,
+          toolCallId: params.toolCallId,
+          toolName: params.toolName,
+          toolInput: params.toolInput,
+          abortSignal: prep.abortController.signal
+        });
+        return { blocked: res.blocked, reason: res.firstBlockReason };
+      },
+      afterToolUse: async (params) => {
+        const res = await this.hookRuntime.runAfterToolUse({
+          sessionId: this.sessionData.id,
+          turnId: prep.turnId,
+          projectDir: prep.toolContext.cwd,
+          cwd: prep.toolContext.cwd,
+          toolCallId: params.toolCallId,
+          toolName: params.toolName,
+          toolInput: params.toolInput,
+          toolOutput: params.toolOutput,
+          isError: params.isError,
+          durationMs: params.durationMs,
+          abortSignal: prep.abortController.signal
+        });
+        return { context: res.context };
+      },
+      toolUseFailure: async (params) => {
+        const res = await this.hookRuntime.runToolUseFailure({
+          sessionId: this.sessionData.id,
+          turnId: prep.turnId,
+          projectDir: prep.toolContext.cwd,
+          cwd: prep.toolContext.cwd,
+          toolCallId: params.toolCallId,
+          toolName: params.toolName,
+          toolInput: params.toolInput,
+          error: params.error,
+          durationMs: params.durationMs,
+          abortSignal: prep.abortController.signal
+        });
+        return { context: res.context };
+      },
+      agentStop: async (params) => {
+        const res = await this.hookRuntime.runAgentStop({
+          sessionId: this.sessionData.id,
+          turnId: prep.turnId,
+          projectDir: prep.toolContext.cwd,
+          cwd: prep.toolContext.cwd,
+          stopReason: params.stopReason,
+          finishReason: params.finishReason,
+          assistantText: params.assistantText,
+          stopHookActive: params.stopHookActive,
+          abortSignal: prep.abortController.signal
+        });
+        return { blocked: res.blocked, reason: res.firstBlockReason };
+      }
+    };
     try {
       summary = await runAgentTurn({
         ai: this.ai,
@@ -58398,6 +59315,7 @@ class AgentSession {
         instructions: prep.instructions,
         tools: prep.activeTools,
         toolExecutor,
+        callbacks,
         maxSteps: this.config.maxSteps,
         temperature: this.config.temperature,
         reasoningEffort: this.config.reasoningEffort,
@@ -58532,6 +59450,14 @@ class AgentSession {
       effort: this.config.reasoningEffort ?? "medium"
     });
     this.sessionLogWriter = new SessionLogWriter(this.sessionData.date || getCurrentDateString(), this.sessionData.id);
+    if (this.hookRuntime) {
+      await this.hookRuntime.runSessionStart({
+        sessionId: this.sessionData.id,
+        projectDir: process.cwd(),
+        cwd: process.cwd(),
+        source: "reset"
+      });
+    }
   }
   getUsage() {
     return { ...this.accumulatedUsage };
@@ -58559,6 +59485,77 @@ var clearCommand = {
   }
 };
 
+// src/app/commands/copy/index.ts
+import { spawn as spawn3 } from "node:child_process";
+import { existsSync as existsSync17 } from "node:fs";
+function extractAssistantText(msg) {
+  if (msg.role !== "assistant")
+    return "";
+  if (typeof msg.content === "string")
+    return msg.content.trim();
+  if (!Array.isArray(msg.content))
+    return "";
+  return msg.content.filter((b) => b?.type === "text" && typeof b.text === "string").map((b) => b.text.trim()).filter(Boolean).join(`
+
+`);
+}
+async function copyToClipboard(text) {
+  const isTermux = Boolean(process.env.TERMUX_VERSION || existsSync17("/data/data/com.termux/files/usr/bin/termux-clipboard-set"));
+  const [cmd, ...args] = isTermux ? ["termux-clipboard-set"] : process.platform === "darwin" ? ["pbcopy"] : process.platform === "win32" ? ["clip.exe"] : process.env.WAYLAND_DISPLAY ? ["wl-copy"] : ["xclip", "-selection", "clipboard"];
+  const sendOSC52 = () => {
+    try {
+      process.stdout.write(`\x1B]52;c;${Buffer.from(text, "utf8").toString("base64")}\x07`);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  return new Promise((resolve) => {
+    let resolved = false;
+    const finish = (ok) => {
+      if (resolved)
+        return;
+      resolved = true;
+      clearTimeout(timer);
+      resolve(ok || sendOSC52());
+    };
+    const timer = setTimeout(() => finish(false), 1200);
+    try {
+      const proc = spawn3(cmd, args, { stdio: ["pipe", "ignore", "ignore"] });
+      proc.on("error", () => finish(false));
+      proc.on("close", (code) => finish(code === 0));
+      proc.stdin?.on("error", () => finish(false));
+      proc.stdin?.end(text);
+    } catch {
+      finish(false);
+    }
+  });
+}
+var copyCommand = {
+  name: "copy",
+  description: "Copies the last AI response to the clipboard",
+  usage: "/copy",
+  async execute(_args, context) {
+    if (context.session.isBusy) {
+      return { handled: true, message: "Cannot copy while the agent is generating a response." };
+    }
+    const history = context.session.getHistory();
+    let targetText = "";
+    for (let i = history.length - 1;i >= 0; i--) {
+      const text = extractAssistantText(history[i]);
+      if (text) {
+        targetText = text;
+        break;
+      }
+    }
+    if (!targetText) {
+      return { handled: true, message: "No previous AI response found to copy." };
+    }
+    await copyToClipboard(targetText);
+    return { handled: true, message: "Copied last AI response to clipboard." };
+  }
+};
+
 // src/app/commands/effort/index.ts
 var EFFORT_HELP = `Reasoning Effort Levels:
   none   : disable reasoning/thinking
@@ -59028,6 +60025,7 @@ class CommandRegistry {
   }
 }
 var builtInCommands = [
+  copyCommand,
   rewindCommand,
   modelCommand,
   loginCommand,
@@ -59048,7 +60046,7 @@ for (const cmd of builtInCommands) {
 }
 
 // src/app/ui/components/Header.tsx
-import { homedir as homedir9 } from "node:os";
+import { homedir as homedir10 } from "node:os";
 
 // src/packages/tui/src/engine/Component.ts
 class Component {
@@ -59627,7 +60625,7 @@ class Header extends Component_default {
   formatCwd(rawPath) {
     if (!rawPath)
       return "~";
-    const home = homedir9();
+    const home = homedir10();
     if (rawPath.startsWith(home)) {
       return `~${rawPath.slice(home.length)}`;
     }
@@ -63153,13 +64151,13 @@ class UpdateCheckerService {
   }
 }
 // src/app/utils/open-url.ts
-import { spawn as spawn2 } from "node:child_process";
-import { existsSync as existsSync16 } from "node:fs";
+import { spawn as spawn4 } from "node:child_process";
+import { existsSync as existsSync18 } from "node:fs";
 function openUrl(url) {
   const platform = process.platform;
   try {
-    if (process.env.TERMUX_VERSION || existsSync16("/data/data/com.termux/files/usr/bin/termux-open-url")) {
-      const child = spawn2("termux-open-url", [url], {
+    if (process.env.TERMUX_VERSION || existsSync18("/data/data/com.termux/files/usr/bin/termux-open-url")) {
+      const child = spawn4("termux-open-url", [url], {
         detached: true,
         stdio: "ignore"
       });
@@ -63167,7 +64165,7 @@ function openUrl(url) {
       return;
     }
     if (platform === "win32") {
-      const child = spawn2("cmd.exe", ["/c", "start", '""', url], {
+      const child = spawn4("cmd.exe", ["/c", "start", '""', url], {
         detached: true,
         stdio: "ignore"
       });
@@ -63175,14 +64173,14 @@ function openUrl(url) {
       return;
     }
     if (platform === "darwin") {
-      const child = spawn2("open", [url], {
+      const child = spawn4("open", [url], {
         detached: true,
         stdio: "ignore"
       });
       child.unref();
       return;
     }
-    const child = spawn2("xdg-open", [url], {
+    const child = spawn4("xdg-open", [url], {
       detached: true,
       stdio: "ignore"
     });
@@ -64976,7 +65974,7 @@ async function applyCommandResult(text, cmdResult, ctx) {
 }
 
 // src/app/utils/bash.ts
-import { spawn as spawn3 } from "node:child_process";
+import { spawn as spawn5 } from "node:child_process";
 async function executeDirectBash(options) {
   const { command, cwd = process.cwd(), abortSignal, onChunk } = options;
   const { shell, args } = getPlatformShell();
@@ -64989,7 +65987,7 @@ async function executeDirectBash(options) {
     let output = "";
     let isSettled = false;
     try {
-      child = spawn3(shell, childArgs, {
+      child = spawn5(shell, childArgs, {
         cwd,
         env: process.env,
         stdio: ["pipe", "pipe", "pipe"],
@@ -65083,6 +66081,10 @@ class TUIApp {
     this.session = options.initialSession ?? new AgentSession;
     this.onExitCallback = options.onExit;
     this.engine = new TerminalEngine_default;
+    const savedMode = getSavedMode();
+    if (savedMode) {
+      setActiveMode(savedMode);
+    }
     const model = this.session.getModel();
     this.header = new Header({
       version: options.version,
@@ -65198,8 +66200,13 @@ class TUIApp {
   }
   proceedStart() {
     this.engine.ensureAlternateScreen();
+    this.session.initializeHooks({
+      cwd: this.cwd,
+      isTrusted: true,
+      source: this.session.session.turns.length > 0 ? "resume" : "startup"
+    });
     const logPath = getSessionLogPath(this.session.session.date, this.session.session.id);
-    if (this.session.session.turns.length > 0 || existsSync17(logPath)) {
+    if (this.session.session.turns.length > 0 || existsSync19(logPath)) {
       renderTranscript(this.engine, this.session.session, this.header);
     } else {
       this.engine.commit("header", this.header.render());