feat: add bootstrap hook and soul-evil hook

src/agents/bootstrap-hooks.test.ts

@@ -0,0 +1,41 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { applyBootstrapHookOverrides } from "./bootstrap-hooks.js";
+import {
+  clearInternalHooks,
+  registerInternalHook,
+  type AgentBootstrapHookContext,
+} from "../hooks/internal-hooks.js";
+import { DEFAULT_SOUL_FILENAME, type WorkspaceBootstrapFile } from "./workspace.js";
+
+function makeFile(name = DEFAULT_SOUL_FILENAME): WorkspaceBootstrapFile {
+  return {
+    name,
+    path: `/tmp/${name}`,
+    content: "base",
+    missing: false,
+  };
+}
+
+describe("applyBootstrapHookOverrides", () => {
+  beforeEach(() => clearInternalHooks());
+  afterEach(() => clearInternalHooks());
+
+  it("returns updated files when a hook mutates the context", async () => {
+    registerInternalHook("agent:bootstrap", (event) => {
+      const context = event.context as AgentBootstrapHookContext;
+      context.bootstrapFiles = [
+        ...context.bootstrapFiles,
+        { name: "EXTRA.md", path: "/tmp/EXTRA.md", content: "extra", missing: false },
+      ];
+    });
+
+    const updated = await applyBootstrapHookOverrides({
+      files: [makeFile()],
+      workspaceDir: "/tmp",
+    });
+
+    expect(updated).toHaveLength(2);
+    expect(updated[1]?.name).toBe("EXTRA.md");
+  });
+});

src/agents/bootstrap-hooks.ts

@@ -0,0 +1,31 @@
+import type { ClawdbotConfig } from "../config/config.js";
+import { createInternalHookEvent, triggerInternalHook } from "../hooks/internal-hooks.js";
+import type { AgentBootstrapHookContext } from "../hooks/internal-hooks.js";
+import { resolveAgentIdFromSessionKey } from "../routing/session-key.js";
+import type { WorkspaceBootstrapFile } from "./workspace.js";
+
+export async function applyBootstrapHookOverrides(params: {
+  files: WorkspaceBootstrapFile[];
+  workspaceDir: string;
+  config?: ClawdbotConfig;
+  sessionKey?: string;
+  sessionId?: string;
+  agentId?: string;
+}): Promise<WorkspaceBootstrapFile[]> {
+  const sessionKey = params.sessionKey ?? params.sessionId ?? "unknown";
+  const agentId =
+    params.agentId ??
+    (params.sessionKey ? resolveAgentIdFromSessionKey(params.sessionKey) : undefined);
+  const context: AgentBootstrapHookContext = {
+    workspaceDir: params.workspaceDir,
+    bootstrapFiles: params.files,
+    cfg: params.config,
+    sessionKey: params.sessionKey,
+    sessionId: params.sessionId,
+    agentId,
+  };
+  const event = createInternalHookEvent("agent", "bootstrap", sessionKey, context);
+  await triggerInternalHook(event);
+  const updated = (event.context as AgentBootstrapHookContext).bootstrapFiles;
+  return Array.isArray(updated) ? updated : params.files;
+}

src/agents/cli-runner.ts

@@ -7,6 +7,7 @@ import { createSubsystemLogger } from "../logging.js";
 import { runCommandWithTimeout } from "../process/exec.js";
 import { resolveUserPath } from "../utils.js";
 import { resolveSessionAgentIds } from "./agent-scope.js";
+import { applyBootstrapHookOverrides } from "./bootstrap-hooks.js";
 import { resolveCliBackendConfig } from "./cli-backends.js";
 import {
   appendImagePathsToPrompt,
@@ -76,8 +77,15 @@ export async function runCliAgent(params: {
     await loadWorkspaceBootstrapFiles(workspaceDir),
     params.sessionKey ?? params.sessionId,
   );
+  const hookAdjustedBootstrapFiles = await applyBootstrapHookOverrides({
+    files: bootstrapFiles,
+    workspaceDir,
+    config: params.config,
+    sessionKey: params.sessionKey,
+    sessionId: params.sessionId,
+  });
   const sessionLabel = params.sessionKey ?? params.sessionId;
-  const contextFiles = buildBootstrapContextFiles(bootstrapFiles, {
+  const contextFiles = buildBootstrapContextFiles(hookAdjustedBootstrapFiles, {
     maxChars: resolveBootstrapMaxChars(params.config),
     warn: (message) => log.warn(`${message} (sessionKey=${sessionLabel})`),
   });

src/agents/pi-embedded-runner/compact.ts

@@ -16,6 +16,7 @@ import { isReasoningTagProvider } from "../../utils/provider-utils.js";
 import { resolveUserPath } from "../../utils.js";
 import { resolveClawdbotAgentDir } from "../agent-paths.js";
 import { resolveSessionAgentIds } from "../agent-scope.js";
+import { applyBootstrapHookOverrides } from "../bootstrap-hooks.js";
 import type { ExecElevatedDefaults } from "../bash-tools.js";
 import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "../defaults.js";
 import { getApiKeyForModel, resolveModelAuthMode } from "../model-auth.js";
@@ -182,11 +183,21 @@ export async function compactEmbeddedPiSession(params: {
           await loadWorkspaceBootstrapFiles(effectiveWorkspace),
           params.sessionKey ?? params.sessionId,
         );
-        const sessionLabel = params.sessionKey ?? params.sessionId;
-        const contextFiles: EmbeddedContextFile[] = buildBootstrapContextFiles(bootstrapFiles, {
-          maxChars: resolveBootstrapMaxChars(params.config),
-          warn: (message) => log.warn(`${message} (sessionKey=${sessionLabel})`),
+        const hookAdjustedBootstrapFiles = await applyBootstrapHookOverrides({
+          files: bootstrapFiles,
+          workspaceDir: effectiveWorkspace,
+          config: params.config,
+          sessionKey: params.sessionKey,
+          sessionId: params.sessionId,
         });
+        const sessionLabel = params.sessionKey ?? params.sessionId;
+        const contextFiles: EmbeddedContextFile[] = buildBootstrapContextFiles(
+          hookAdjustedBootstrapFiles,
+          {
+            maxChars: resolveBootstrapMaxChars(params.config),
+            warn: (message) => log.warn(`${message} (sessionKey=${sessionLabel})`),
+          },
+        );
         const runAbortController = new AbortController();
         const toolsRaw = createClawdbotCodingTools({
           exec: {

src/agents/pi-embedded-runner/run/attempt.ts

@@ -17,6 +17,7 @@ import { isSubagentSessionKey } from "../../../routing/session-key.js";
 import { resolveUserPath } from "../../../utils.js";
 import { resolveClawdbotAgentDir } from "../../agent-paths.js";
 import { resolveSessionAgentIds } from "../../agent-scope.js";
+import { applyBootstrapHookOverrides } from "../../bootstrap-hooks.js";
 import { resolveModelAuthMode } from "../../model-auth.js";
 import {
   buildBootstrapContextFiles,
@@ -124,8 +125,15 @@ export async function runEmbeddedAttempt(
       await loadWorkspaceBootstrapFiles(effectiveWorkspace),
       params.sessionKey ?? params.sessionId,
     );
+    const hookAdjustedBootstrapFiles = await applyBootstrapHookOverrides({
+      files: bootstrapFiles,
+      workspaceDir: effectiveWorkspace,
+      config: params.config,
+      sessionKey: params.sessionKey,
+      sessionId: params.sessionId,
+    });
     const sessionLabel = params.sessionKey ?? params.sessionId;
-    const contextFiles = buildBootstrapContextFiles(bootstrapFiles, {
+    const contextFiles = buildBootstrapContextFiles(hookAdjustedBootstrapFiles, {
       maxChars: resolveBootstrapMaxChars(params.config),
       warn: (message) => log.warn(`${message} (sessionKey=${sessionLabel})`),
     });
@@ -251,7 +259,7 @@ export async function runEmbeddedAttempt(
         return { mode: runtime.mode, sandboxed: runtime.sandboxed };
       })(),
       systemPrompt: appendPrompt,
-      bootstrapFiles,
+      bootstrapFiles: hookAdjustedBootstrapFiles,
       injectedFiles: contextFiles,
       skillsPrompt,
       tools,