goatcode-sh 0.0.1 → 0.1.2

package/src/hooks/todo-enforcer/handler.test.ts

@@ -0,0 +1,153 @@
+import { beforeEach, describe, expect, it } from "bun:test";
+import {
+  clearSessionStore,
+  getSessionState,
+  setSessionState,
+} from "../../features/session-state/session-store";
+import { createTodoEnforcerHandler } from "./handler";
+
+type MutableTodoState = {
+  todos?: Array<{
+    content: string;
+    status: "pending" | "in_progress" | "completed" | "cancelled";
+  }>;
+};
+
+type GenericHook = (input: unknown) => Promise<void>;
+
+function seedTodos(sessionID: string, todos: NonNullable<MutableTodoState["todos"]>): void {
+  setSessionState(sessionID, { status: "active" });
+  const state = getSessionState(sessionID) as unknown as MutableTodoState | undefined;
+  if (!state) return;
+  state.todos = todos;
+}
+
+describe("createTodoEnforcerHandler", () => {
+  beforeEach(() => {
+    clearSessionStore();
+  });
+
+  describe("#given a handler instance", () => {
+    describe("#when session.idle fires with pending todos", () => {
+      it("#then injects a continuation message referencing the next pending todo", async () => {
+        const sessionID = "ses-enforcer-pending";
+        seedTodos(sessionID, [
+          { content: "Run type-check", status: "pending" },
+          { content: "Deploy artifacts", status: "pending" },
+        ]);
+        const handler = createTodoEnforcerHandler() as unknown as GenericHook;
+        const input = {
+          event: {
+            type: "session.idle",
+            properties: { sessionID },
+          },
+        };
+
+        await handler(input);
+
+        const props = input.event.properties as Record<string, unknown>;
+        expect(typeof props.continuationMessage).toBe("string");
+        expect(String(props.continuationMessage)).toContain("Run type-check");
+        expect(String(props.continuationMessage)).toContain("todo-enforcer");
+      });
+    });
+
+    describe("#when session.idle fires with only completed/cancelled todos", () => {
+      it("#then does not inject a continuation message", async () => {
+        const sessionID = "ses-enforcer-done";
+        seedTodos(sessionID, [
+          { content: "Finished task", status: "completed" },
+          { content: "Dropped task", status: "cancelled" },
+        ]);
+        const handler = createTodoEnforcerHandler() as unknown as GenericHook;
+        const input = {
+          event: {
+            type: "session.idle",
+            properties: { sessionID },
+          },
+        };
+
+        await handler(input);
+
+        const props = input.event.properties as Record<string, unknown>;
+        expect(props.continuationMessage).toBeUndefined();
+      });
+    });
+
+    describe("#when event type is not session.idle", () => {
+      it("#then does nothing", async () => {
+        const sessionID = "ses-enforcer-wrong-event";
+        seedTodos(sessionID, [{ content: "Pending work", status: "pending" }]);
+        const handler = createTodoEnforcerHandler() as unknown as GenericHook;
+        const input = {
+          event: {
+            type: "session.error",
+            properties: { sessionID },
+          },
+        };
+
+        await handler(input);
+
+        const props = input.event.properties as Record<string, unknown>;
+        expect(props.continuationMessage).toBeUndefined();
+      });
+    });
+
+    describe("#when input is not a valid event envelope", () => {
+      it("#then does nothing for null input", async () => {
+        const handler = createTodoEnforcerHandler() as unknown as GenericHook;
+        await handler(null);
+      });
+
+      it("#then does nothing for input without event", async () => {
+        const handler = createTodoEnforcerHandler() as unknown as GenericHook;
+        const input = { something: "else" };
+        await handler(input);
+        expect((input as Record<string, unknown>).continuationMessage).toBeUndefined();
+      });
+    });
+
+    describe("#when session.idle fires with in_progress todos", () => {
+      it("#then treats in_progress as pending and injects continuation", async () => {
+        const sessionID = "ses-enforcer-inprogress";
+        seedTodos(sessionID, [
+          { content: "Write tests", status: "in_progress" },
+          { content: "Review PR", status: "completed" },
+        ]);
+        const handler = createTodoEnforcerHandler() as unknown as GenericHook;
+        const input = {
+          event: {
+            type: "session.idle",
+            properties: { sessionID },
+          },
+        };
+
+        await handler(input);
+
+        const props = input.event.properties as Record<string, unknown>;
+        expect(typeof props.continuationMessage).toBe("string");
+        expect(String(props.continuationMessage)).toContain("Write tests");
+      });
+    });
+
+    describe("#when sessionID is in info.id instead of properties.sessionID", () => {
+      it("#then resolves the session ID from info.id", async () => {
+        const sessionID = "ses-enforcer-info-id";
+        seedTodos(sessionID, [{ content: "Fix lint errors", status: "pending" }]);
+        const handler = createTodoEnforcerHandler() as unknown as GenericHook;
+        const input = {
+          event: {
+            type: "session.idle",
+            properties: { info: { id: sessionID } },
+          },
+        };
+
+        await handler(input);
+
+        const props = input.event.properties as Record<string, unknown>;
+        expect(typeof props.continuationMessage).toBe("string");
+        expect(String(props.continuationMessage)).toContain("Fix lint errors");
+      });
+    });
+  });
+});

package/src/hooks/todo-enforcer/handler.ts

@@ -0,0 +1,100 @@
+import { getSessionState } from "../../runtime";
+import { log } from "../../shared/logger";
+import type { PluginHookContributions } from "../../types/hook";
+
+type EventHook = NonNullable<PluginHookContributions["event"]>;
+
+type TodoStatus = "pending" | "in_progress" | "completed" | "cancelled";
+
+interface SessionTodo {
+  content: string;
+  status: TodoStatus;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isTodoStatus(value: unknown): value is TodoStatus {
+  return (
+    value === "pending" || value === "in_progress" || value === "completed" || value === "cancelled"
+  );
+}
+
+function extractPendingTodosFromState(sessionID: string): SessionTodo[] {
+  const state = getSessionState(sessionID);
+  if (!state) {
+    return [];
+  }
+
+  const todos = (state as unknown as { todos?: unknown }).todos;
+  if (!Array.isArray(todos)) {
+    return [];
+  }
+
+  return todos
+    .filter((todo): todo is SessionTodo => {
+      if (!isRecord(todo)) {
+        return false;
+      }
+      return typeof todo.content === "string" && isTodoStatus(todo.status);
+    })
+    .filter((todo) => todo.status === "pending" || todo.status === "in_progress");
+}
+
+function resolveSessionID(input: unknown): string | undefined {
+  if (!isRecord(input) || !isRecord(input.event)) {
+    return undefined;
+  }
+
+  const properties = isRecord(input.event.properties) ? input.event.properties : undefined;
+  const info = isRecord(properties?.info) ? properties.info : undefined;
+  const sessionID = properties?.sessionID;
+  const infoID = info?.id;
+
+  if (typeof sessionID === "string") {
+    return sessionID;
+  }
+  if (typeof infoID === "string") {
+    return infoID;
+  }
+  return undefined;
+}
+
+function appendContinuationMessageToEvent(input: unknown, message: string): void {
+  if (!isRecord(input) || !isRecord(input.event)) {
+    return;
+  }
+
+  const properties = isRecord(input.event.properties) ? input.event.properties : {};
+  properties.continuationMessage = message;
+  input.event.properties = properties;
+}
+
+export function createTodoEnforcerHandler(): EventHook {
+  return async (input: unknown, ..._rest: unknown[]) => {
+    if (!isRecord(input) || !isRecord(input.event) || input.event.type !== "session.idle") {
+      return;
+    }
+
+    const sessionID = resolveSessionID(input);
+    if (!sessionID) {
+      return;
+    }
+
+    const pendingTodos = extractPendingTodosFromState(sessionID);
+    if (pendingTodos.length === 0) {
+      return;
+    }
+
+    const nextTodo = pendingTodos[0];
+    const continuationMessage = `[todo-enforcer] Session is idle but todos remain. Continue with next todo: ${nextTodo.content}`;
+    appendContinuationMessageToEvent(input, continuationMessage);
+
+    log("[todo-enforcer] Injected continuation message on idle", {
+      sessionID,
+      pendingCount: pendingTodos.length,
+      nextTodo: nextTodo.content,
+    });
+  };
+}

package/src/hooks/todo-enforcer/index.ts

@@ -0,0 +1,2 @@
+export { todoEnforcerPlugin } from "./plugin";
+export { createTodoEnforcerHandler } from "./handler";

package/src/hooks/todo-enforcer/plugin.ts

@@ -0,0 +1,15 @@
+import { definePlugin } from "../../plugin-api/define-plugin";
+import { safeCreateHook } from "../../shared/safe-create-hook";
+import { createTodoEnforcerHandler } from "./handler";
+
+const sessionIdleEnforcer = safeCreateHook("todo-enforcer", createTodoEnforcerHandler);
+
+export const todoEnforcerPlugin = definePlugin({
+  name: "todo-enforcer",
+  version: "0.1.0",
+  hooks: sessionIdleEnforcer
+    ? {
+        event: sessionIdleEnforcer,
+      }
+    : {},
+});

package/src/hooks/todowrite-disabler/handler.test.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+  createTodowriteDisablerHandler,
+  SUBAGENT_TODOWRITE_BLOCK_MESSAGE,
+  BLOCKED_TOOLS,
+} from "./handler";
+
+describe("createTodowriteDisablerHandler", () => {
+  describe("#given a subagent context (agent is explore)", () => {
+    describe("#when TodoWrite is called", () => {
+      it("#then throws with the block message", async () => {
+        const handler = createTodowriteDisablerHandler("explore");
+        const input = { tool: "TodoWrite", sessionID: "s1", callID: "c1" };
+        const output = { args: {} };
+
+        await expect(handler(input, output)).rejects.toThrow(SUBAGENT_TODOWRITE_BLOCK_MESSAGE);
+      });
+    });
+
+    describe("#when TodoRead is called", () => {
+      it("#then throws with the block message", async () => {
+        const handler = createTodowriteDisablerHandler("explore");
+        const input = { tool: "TodoRead", sessionID: "s1", callID: "c1" };
+        const output = { args: {} };
+
+        await expect(handler(input, output)).rejects.toThrow(SUBAGENT_TODOWRITE_BLOCK_MESSAGE);
+      });
+    });
+
+    describe("#when a non-blocked tool is called", () => {
+      it("#then does not throw", async () => {
+        const handler = createTodowriteDisablerHandler("explore");
+        const input = { tool: "Read", sessionID: "s1", callID: "c1" };
+        const output = { args: {} };
+
+        await expect(handler(input, output)).resolves.toBeUndefined();
+      });
+    });
+  });
+
+  describe("#given a subagent context (agent is oracle)", () => {
+    describe("#when TodoWrite is called with lowercase tool name", () => {
+      it("#then throws because matching is case-insensitive", async () => {
+        const handler = createTodowriteDisablerHandler("oracle");
+        const input = { tool: "todowrite", sessionID: "s1", callID: "c1" };
+        const output = { args: {} };
+
+        await expect(handler(input, output)).rejects.toThrow(SUBAGENT_TODOWRITE_BLOCK_MESSAGE);
+      });
+    });
+
+    describe("#when TodoRead is called with mixed case", () => {
+      it("#then throws because matching is case-insensitive", async () => {
+        const handler = createTodowriteDisablerHandler("oracle");
+        const input = { tool: "TODOREAD", sessionID: "s1", callID: "c1" };
+        const output = { args: {} };
+
+        await expect(handler(input, output)).rejects.toThrow(SUBAGENT_TODOWRITE_BLOCK_MESSAGE);
+      });
+    });
+  });
+
+  describe("#given an orchestrator context", () => {
+    describe("#when TodoWrite is called", () => {
+      it("#then does not throw because orchestrator is allowed", async () => {
+        const handler = createTodowriteDisablerHandler("orchestrator");
+        const input = { tool: "TodoWrite", sessionID: "s1", callID: "c1" };
+        const output = { args: {} };
+
+        await expect(handler(input, output)).resolves.toBeUndefined();
+      });
+    });
+
+    describe("#when TodoRead is called", () => {
+      it("#then does not throw because orchestrator is allowed", async () => {
+        const handler = createTodowriteDisablerHandler("orchestrator");
+        const input = { tool: "TodoRead", sessionID: "s1", callID: "c1" };
+        const output = { args: {} };
+
+        await expect(handler(input, output)).resolves.toBeUndefined();
+      });
+    });
+  });
+
+  describe("#given no agent name (undefined)", () => {
+    describe("#when TodoWrite is called", () => {
+      it("#then does not throw because undefined is not a subagent", async () => {
+        const handler = createTodowriteDisablerHandler(undefined);
+        const input = { tool: "TodoWrite", sessionID: "s1", callID: "c1" };
+        const output = { args: {} };
+
+        await expect(handler(input, output)).resolves.toBeUndefined();
+      });
+    });
+  });
+
+  describe("#given a worker subagent context", () => {
+    describe("#when TodoWrite is called", () => {
+      it("#then throws because worker is not in ORCHESTRATOR_AGENTS", async () => {
+        const handler = createTodowriteDisablerHandler("worker");
+        const input = { tool: "TodoWrite", sessionID: "s1", callID: "c1" };
+        const output = { args: {} };
+
+        await expect(handler(input, output)).rejects.toThrow(SUBAGENT_TODOWRITE_BLOCK_MESSAGE);
+      });
+    });
+  });
+
+  describe("#given the BLOCKED_TOOLS constant", () => {
+    describe("#when checking the blocked list", () => {
+      it("#then includes TodoWrite and TodoRead", () => {
+        expect(BLOCKED_TOOLS).toContain("TodoWrite");
+        expect(BLOCKED_TOOLS).toContain("TodoRead");
+        expect(BLOCKED_TOOLS.length).toBe(2);
+      });
+    });
+  });
+});

package/src/hooks/todowrite-disabler/handler.ts

@@ -0,0 +1,50 @@
+import type { PluginHookContributions } from "../../types/hook";
+import { log } from "../../shared/logger";
+
+type PreToolUseHook = NonNullable<PluginHookContributions["tool.execute.before"]>;
+
+export const BLOCKED_TOOLS = ["TodoWrite", "TodoRead"];
+
+export const SUBAGENT_TODOWRITE_BLOCK_MESSAGE =
+  `TodoWrite/TodoRead are DISABLED in subagent contexts.\n\n` +
+  `Subagents must not manage the todo list directly. ` +
+  `Only the main orchestrator manages todos.\n\n` +
+  `If you need to track work, report your progress in your response text ` +
+  `so the orchestrator can update todos accordingly.`;
+
+const ORCHESTRATOR_AGENTS = ["orchestrator"];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isSubagentContext(agentName: string | undefined): boolean {
+  if (!agentName) return false;
+  return !ORCHESTRATOR_AGENTS.includes(agentName.toLowerCase());
+}
+
+export function createTodowriteDisablerHandler(agentName: string | undefined): PreToolUseHook {
+  return async (input: unknown, _output: unknown) => {
+    if (!isRecord(input)) {
+      return;
+    }
+
+    if (!isSubagentContext(agentName)) {
+      return;
+    }
+
+    const tool = input.tool;
+    if (typeof tool !== "string") {
+      return;
+    }
+
+    const isBlocked = BLOCKED_TOOLS.some((blocked) => blocked.toLowerCase() === tool.toLowerCase());
+
+    if (!isBlocked) {
+      return;
+    }
+
+    log("[todowrite-disabler] blocked TodoWrite in subagent context", { agentName, tool });
+    throw new Error(SUBAGENT_TODOWRITE_BLOCK_MESSAGE);
+  };
+}

package/src/hooks/todowrite-disabler/index.ts

@@ -0,0 +1,6 @@
+export { todowriteDisablerPlugin } from "./plugin";
+export {
+  createTodowriteDisablerHandler,
+  BLOCKED_TOOLS,
+  SUBAGENT_TODOWRITE_BLOCK_MESSAGE,
+} from "./handler";

package/src/hooks/todowrite-disabler/plugin.ts

@@ -0,0 +1,46 @@
+import type { PluginHookContributions } from "../../types/hook";
+import { definePlugin } from "../../plugin-api/define-plugin";
+import { safeCreateHook } from "../../shared/safe-create-hook";
+import { createTodowriteDisablerHandler } from "./handler";
+
+const handlersBySession = new Map<
+  string,
+  NonNullable<PluginHookContributions["tool.execute.before"]>
+>();
+
+export const todowriteDisablerPlugin = definePlugin({
+  name: "todowrite-disabler",
+  version: "0.1.0",
+  hooks: {
+    "chat.message": async (input, _output) => {
+      const typedInput = input as { sessionID?: string; agent?: string };
+      const sessionID = typedInput.sessionID;
+      const agent = typedInput.agent;
+      if (typeof sessionID === "string" && sessionID && typeof agent === "string" && agent) {
+        const handler = safeCreateHook("todowrite-disabler", () =>
+          createTodowriteDisablerHandler(agent),
+        );
+        if (handler) {
+          handlersBySession.set(sessionID, handler);
+        }
+      }
+    },
+    "tool.execute.before": async (input, output) => {
+      const typedInput = input as { sessionID?: string };
+      const sessionID = typedInput.sessionID;
+      const handler = typeof sessionID === "string" ? handlersBySession.get(sessionID) : undefined;
+      if (handler) {
+        await handler(input, output);
+      }
+    },
+    event: async (input) => {
+      const evt = (input as { event?: { type?: string; properties?: unknown } }).event;
+      if (evt?.type === "session.deleted") {
+        const props = evt.properties as Record<string, unknown> | undefined;
+        const sessionID = (props?.sessionID ??
+          (props?.info as Record<string, unknown> | undefined)?.id) as string | undefined;
+        if (sessionID) handlersBySession.delete(sessionID);
+      }
+    },
+  },
+});

package/src/hooks/tool-output-truncator/handler.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect } from "bun:test";
+import { createToolOutputTruncatorHandler } from "./handler";
+
+describe("createToolOutputTruncatorHandler", () => {
+  describe("#given a truncatable tool with output exceeding 2000 lines", () => {
+    describe("#when the handler processes the output", () => {
+      it("#then truncates the output and appends a truncation notice", async () => {
+        const handler = createToolOutputTruncatorHandler();
+        const lines = Array.from({ length: 3000 }, (_, i) => `line ${i + 1}: some content`);
+        const input = { tool: "grep", sessionID: "s1", callID: "c1", args: {} };
+        const output = {
+          title: "grep result",
+          output: lines.join("\n"),
+          metadata: {},
+        };
+
+        await handler(input, output);
+
+        const resultLines = output.output.split("\n");
+        expect(resultLines.length).toBeLessThan(3000);
+        expect(output.output).toContain("[Output truncated:");
+        expect(output.output).toContain("Full output written to");
+        expect(output.output).toContain("Use Read with offset/limit");
+      });
+    });
+  });
+
+  describe("#given a truncatable tool with output exceeding 51200 bytes via many lines", () => {
+    describe("#when the handler processes the output", () => {
+      it("#then truncates and appends a notice with byte count", async () => {
+        const handler = createToolOutputTruncatorHandler();
+        const lines = Array.from({ length: 2500 }, (_, i) => `${i}: ${"y".repeat(50)}`);
+        const bigOutput = lines.join("\n");
+        expect(Buffer.byteLength(bigOutput, "utf8")).toBeGreaterThan(51_200);
+        expect(lines.length).toBeGreaterThan(2_000);
+
+        const input = { tool: "bash", sessionID: "s1", callID: "c1", args: {} };
+        const output = {
+          title: "bash result",
+          output: bigOutput,
+          metadata: {},
+        };
+
+        await handler(input, output);
+
+        expect(output.output).toContain("[Output truncated:");
+        expect(output.output).toContain("bytes exceeded limit");
+        const resultLines = output.output.split("\n");
+        expect(resultLines.length).toBeLessThan(2500);
+      });
+    });
+  });
+
+  describe("#given a truncatable tool with output under the threshold", () => {
+    describe("#when the handler processes the output", () => {
+      it("#then leaves the output unchanged", async () => {
+        const handler = createToolOutputTruncatorHandler();
+        const original = "short output";
+        const input = { tool: "bash", sessionID: "s1", callID: "c1", args: {} };
+        const output = {
+          title: "bash result",
+          output: original,
+          metadata: {},
+        };
+
+        await handler(input, output);
+
+        expect(output.output).toBe(original);
+      });
+    });
+  });
+
+  describe("#given non-string output", () => {
+    describe("#when the handler processes the output", () => {
+      it("#then does not modify the output", async () => {
+        const handler = createToolOutputTruncatorHandler() as (
+          input: unknown,
+          output: unknown,
+        ) => Promise<void>;
+        const input = { tool: "bash", sessionID: "s1", callID: "c1" };
+        const output = {
+          title: "bash result",
+          output: 12345,
+          metadata: {},
+        };
+
+        await handler(input, output);
+
+        expect(output.output).toBe(12345);
+      });
+    });
+  });
+
+  describe("#given a tool not in the truncatable set", () => {
+    describe("#when the handler processes the output", () => {
+      it("#then leaves the output unchanged even if it exceeds limits", async () => {
+        const handler = createToolOutputTruncatorHandler();
+        const lines = Array.from({ length: 3000 }, (_, i) => `line ${i + 1}: content`);
+        const original = lines.join("\n");
+        const input = { tool: "Read", sessionID: "s1", callID: "c1", args: {} };
+        const output = {
+          title: "file content",
+          output: original,
+          metadata: {},
+        };
+
+        await handler(input, output);
+
+        expect(output.output).toBe(original);
+      });
+    });
+  });
+});