goatcode-sh 0.0.1 → 0.1.3

package/src/hooks/post-read-nudge/handler.ts

@@ -0,0 +1,64 @@
+import type { PluginHookContributions } from "../../types/hook";
+import { log } from "../../shared/logger";
+
+type PostToolUseHook = NonNullable<PluginHookContributions["tool.execute.after"]>;
+
+export const POST_READ_NUDGE =
+  "\n\n---\nWorkflow Reminder: delegate based on rules; if mentioning a specialist, launch it in this same turn.";
+
+const DELEGATION_NUDGE_THRESHOLD = 3;
+
+export const DELEGATION_ESCALATION_NUDGE =
+  "\n\n---\n[DELEGATION NUDGE] You have made multiple exploration calls without delegating. " +
+  "Stop reading files and delegate to a specialist agent NOW. " +
+  "Each read compounds context bloat from AGENTS.md injection. " +
+  "Use explorer for codebase discovery or deep-worker for thorough analysis.";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isReadTool(tool: string): boolean {
+  return tool.toLowerCase() === "read";
+}
+
+function isExplorationTool(tool: string): boolean {
+  const name = tool.toLowerCase();
+  return name === "read" || name === "grep" || name === "glob";
+}
+
+export function createPostReadNudgeHandler(): PostToolUseHook {
+  // Track exploration call count to escalate delegation nudges.
+  // Resets when the handler is recreated (new session).
+  let explorationCallCount = 0;
+
+  return async (input: unknown, output: unknown) => {
+    if (!isRecord(input) || !isRecord(output)) return;
+
+    const tool = input.tool;
+    const text = output.output;
+    if (typeof tool !== "string" || typeof text !== "string") return;
+
+    // Count all exploration tool calls (read, grep, glob)
+    if (isExplorationTool(tool)) {
+      explorationCallCount++;
+    }
+
+    // Only append nudges to read tool outputs
+    if (!isReadTool(tool)) return;
+    if (text.includes(POST_READ_NUDGE.trim())) return;
+
+    // After threshold, escalate to a stronger delegation nudge
+    if (explorationCallCount >= DELEGATION_NUDGE_THRESHOLD) {
+      if (!text.includes(DELEGATION_ESCALATION_NUDGE.trim())) {
+        output.output = `${text}${DELEGATION_ESCALATION_NUDGE}`;
+        log("[post-read-nudge] escalated to delegation nudge", {
+          explorationCallCount,
+        });
+      }
+      return;
+    }
+
+    output.output = `${text}${POST_READ_NUDGE}`;
+  };
+}

package/src/hooks/post-read-nudge/index.ts

@@ -0,0 +1,6 @@
+export {
+  createPostReadNudgeHandler,
+  POST_READ_NUDGE,
+  DELEGATION_ESCALATION_NUDGE,
+} from "./handler";
+export { postReadNudgePlugin } from "./plugin";

package/src/hooks/post-read-nudge/plugin.ts

@@ -0,0 +1,18 @@
+import { definePlugin } from "../../plugin-api";
+import { safeCreateHook } from "../../shared/safe-create-hook";
+import { createPostReadNudgeHandler } from "./handler";
+
+const postReadNudgeToolExecuteAfterHook = safeCreateHook(
+  "post-read-nudge",
+  createPostReadNudgeHandler,
+);
+
+export const postReadNudgePlugin = definePlugin({
+  name: "post-read-nudge",
+  version: "0.1.0",
+  hooks: postReadNudgeToolExecuteAfterHook
+    ? {
+        "tool.execute.after": postReadNudgeToolExecuteAfterHook,
+      }
+    : {},
+});

package/src/hooks/preemptive-compaction/handler.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, it, mock } from "bun:test";
+import { createPreemptiveCompactionHandler } from "./handler";
+
+describe("createPreemptiveCompactionHandler", () => {
+  describe("#given a handler with default 80% threshold", () => {
+    describe("#when token usage exceeds the threshold", () => {
+      it("#then triggers compaction for the session", async () => {
+        const compactSession = mock(() => Promise.resolve());
+        const handler = createPreemptiveCompactionHandler({ compactSession });
+
+        await handler({
+          sessionID: "ses-high",
+          usage: { totalTokens: 170_000 },
+          contextLimit: 200_000,
+        });
+
+        expect(compactSession).toHaveBeenCalledTimes(1);
+        expect(compactSession).toHaveBeenCalledWith("ses-high", {
+          usageRatio: 0.85,
+          usedTokens: 170_000,
+          contextLimit: 200_000,
+        });
+      });
+    });
+
+    describe("#when token usage is below the threshold", () => {
+      it("#then does not trigger compaction", async () => {
+        const compactSession = mock(() => Promise.resolve());
+        const handler = createPreemptiveCompactionHandler({ compactSession });
+
+        await handler({
+          sessionID: "ses-low",
+          usage: { totalTokens: 100_000 },
+          contextLimit: 200_000,
+        });
+
+        expect(compactSession).not.toHaveBeenCalled();
+      });
+    });
+
+    describe("#when no context limit is provided", () => {
+      it("#then does not trigger compaction", async () => {
+        const compactSession = mock(() => Promise.resolve());
+        const handler = createPreemptiveCompactionHandler({ compactSession });
+
+        await handler({
+          sessionID: "ses-nolimit",
+          usage: { totalTokens: 170_000 },
+        });
+
+        expect(compactSession).not.toHaveBeenCalled();
+      });
+    });
+  });
+
+  describe("#given a handler tracking per-session compaction state", () => {
+    describe("#when usage stays above threshold across multiple calls", () => {
+      it("#then only compacts once until usage drops below threshold", async () => {
+        const compactSession = mock(() => Promise.resolve());
+        const handler = createPreemptiveCompactionHandler({ compactSession });
+
+        await handler({
+          sessionID: "ses-dedup",
+          usage: { totalTokens: 170_000 },
+          contextLimit: 200_000,
+        });
+
+        await handler({
+          sessionID: "ses-dedup",
+          usage: { totalTokens: 180_000 },
+          contextLimit: 200_000,
+        });
+
+        expect(compactSession).toHaveBeenCalledTimes(1);
+
+        await handler({
+          sessionID: "ses-dedup",
+          usage: { totalTokens: 100_000 },
+          contextLimit: 200_000,
+        });
+
+        await handler({
+          sessionID: "ses-dedup",
+          usage: { totalTokens: 175_000 },
+          contextLimit: 200_000,
+        });
+
+        expect(compactSession).toHaveBeenCalledTimes(2);
+      });
+    });
+  });
+
+  describe("#given a handler with no sessionID", () => {
+    describe("#when input lacks a sessionID", () => {
+      it("#then does nothing", async () => {
+        const compactSession = mock(() => Promise.resolve());
+        const handler = createPreemptiveCompactionHandler({ compactSession });
+
+        await handler({
+          usage: { totalTokens: 190_000 },
+          contextLimit: 200_000,
+        });
+
+        expect(compactSession).not.toHaveBeenCalled();
+      });
+    });
+  });
+
+  describe("#given a handler with tokenUsage input format", () => {
+    describe("#when tokenUsage.total exceeds the threshold", () => {
+      it("#then triggers compaction using the alternate input shape", async () => {
+        const compactSession = mock(() => Promise.resolve());
+        const handler = createPreemptiveCompactionHandler({ compactSession });
+
+        await handler({
+          sessionID: "ses-alt",
+          tokenUsage: { total: 165_000 },
+          context: { limitTokens: 200_000 },
+        });
+
+        expect(compactSession).toHaveBeenCalledTimes(1);
+        expect(compactSession).toHaveBeenCalledWith("ses-alt", {
+          usageRatio: 0.825,
+          usedTokens: 165_000,
+          contextLimit: 200_000,
+        });
+      });
+    });
+  });
+});

package/src/hooks/preemptive-compaction/handler.ts

@@ -0,0 +1,84 @@
+import { log } from "../../shared/logger";
+
+type PreemptiveCompactionInput = {
+  sessionID?: string;
+  usage?: { inputTokens?: number; cacheReadTokens?: number; totalTokens?: number };
+  context?: { limitTokens?: number };
+  tokenUsage?: { input?: number; cacheRead?: number; total?: number };
+  contextLimit?: number;
+};
+
+type PreemptiveCompactionDeps = {
+  threshold?: number;
+  getTokenUsage?: (
+    input: PreemptiveCompactionInput,
+  ) => { usedTokens: number; contextLimit: number } | undefined;
+  compactSession?: (
+    sessionID: string,
+    info: { usageRatio: number; usedTokens: number; contextLimit: number },
+  ) => void | Promise<void>;
+};
+
+function resolveTokenUsage(
+  input: PreemptiveCompactionInput,
+): { usedTokens: number; contextLimit: number } | undefined {
+  const usageFromUsage = input.usage;
+  const usageFromTokenUsage = input.tokenUsage;
+
+  const usedTokens =
+    usageFromUsage?.totalTokens ??
+    usageFromTokenUsage?.total ??
+    (usageFromUsage
+      ? (usageFromUsage.inputTokens ?? 0) + (usageFromUsage.cacheReadTokens ?? 0)
+      : (usageFromTokenUsage?.input ?? 0) + (usageFromTokenUsage?.cacheRead ?? 0));
+
+  const contextLimit = input.context?.limitTokens ?? input.contextLimit;
+
+  if (!contextLimit || contextLimit <= 0) return undefined;
+  return { usedTokens, contextLimit };
+}
+
+export function createPreemptiveCompactionHandler(deps: PreemptiveCompactionDeps = {}) {
+  const threshold = deps.threshold ?? 0.8;
+  const compactedWhileAboveThreshold = new Set<string>();
+
+  return async (input: PreemptiveCompactionInput): Promise<void> => {
+    const sessionID = input.sessionID;
+    if (!sessionID) return;
+
+    const resolved = deps.getTokenUsage?.(input) ?? resolveTokenUsage(input);
+    if (!resolved) return;
+
+    const usageRatio = resolved.usedTokens / resolved.contextLimit;
+    if (usageRatio < threshold) {
+      compactedWhileAboveThreshold.delete(sessionID);
+      return;
+    }
+
+    if (compactedWhileAboveThreshold.has(sessionID)) return;
+
+    compactedWhileAboveThreshold.add(sessionID);
+
+    try {
+      await Promise.resolve(
+        deps.compactSession?.(sessionID, {
+          usageRatio,
+          usedTokens: resolved.usedTokens,
+          contextLimit: resolved.contextLimit,
+        }),
+      );
+      log("[preemptive-compaction] triggered compaction", {
+        sessionID,
+        usageRatio,
+        usedTokens: resolved.usedTokens,
+        contextLimit: resolved.contextLimit,
+      });
+    } catch (error) {
+      compactedWhileAboveThreshold.delete(sessionID);
+      log("[preemptive-compaction] compaction trigger failed", {
+        sessionID,
+        error: String(error),
+      });
+    }
+  };
+}

package/src/hooks/preemptive-compaction/index.ts

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

package/src/hooks/preemptive-compaction/plugin.ts

@@ -0,0 +1,15 @@
+import { definePlugin } from "../../plugin-api";
+import { safeCreateHook } from "../../shared/safe-create-hook";
+import { createPreemptiveCompactionHandler } from "./handler";
+
+const preemptiveCompactionMessageHook = safeCreateHook("preemptive-compaction", () =>
+  createPreemptiveCompactionHandler(),
+);
+
+export const preemptiveCompactionPlugin = definePlugin({
+  name: "preemptive-compaction",
+  version: "0.1.0",
+  hooks: preemptiveCompactionMessageHook
+    ? { "chat.message": preemptiveCompactionMessageHook }
+    : undefined,
+});

package/src/hooks/productivity.test.ts

@@ -0,0 +1,332 @@
+import { beforeEach, describe, expect, it } from "bun:test";
+import {
+  clearSessionMode,
+  createKeywordDetectorHandler,
+  getSessionMode,
+  setSessionMode,
+} from "./keyword-detector/handler";
+import { createThinkModeHandler } from "./think-mode/handler";
+import { createAnthropicEffortHandler } from "./anthropic-effort/handler";
+
+const SESSION_ID = "test-session";
+
+function makeChatMessageInput(sessionID: string = SESSION_ID) {
+  return { sessionID };
+}
+
+function makeChatMessageOutput(text: string) {
+  return {
+    message: {},
+    parts: [{ type: "text", text }],
+  };
+}
+
+function makeChatParamsInput(providerID: string, modelID: string, sessionID: string = SESSION_ID) {
+  return {
+    sessionID,
+    agent: "sisyphus",
+    model: { providerID, modelID },
+    provider: { id: providerID },
+    message: {},
+  };
+}
+
+function makeChatParamsOutput() {
+  return {
+    temperature: 0.1,
+    topP: 1,
+    topK: 0,
+    options: {} as Record<string, unknown>,
+  };
+}
+
+describe("keyword-detector", () => {
+  beforeEach(() => {
+    clearSessionMode(SESSION_ID);
+  });
+
+  describe("#given a message containing 'ultrawork'", () => {
+    describe("#when the handler processes the message", () => {
+      it("#then sets the session mode to 'ultrawork'", async () => {
+        const handler = createKeywordDetectorHandler();
+        const input = makeChatMessageInput();
+        const output = makeChatMessageOutput("Please ultrawork on this task now");
+
+        await handler(input, output);
+
+        expect(getSessionMode(SESSION_ID)).toBe("ultrawork");
+      });
+    });
+  });
+
+  describe("#given a message containing 'ulw' shorthand", () => {
+    describe("#when the handler processes the message", () => {
+      it("#then sets the session mode to 'ultrawork'", async () => {
+        const handler = createKeywordDetectorHandler();
+        const input = makeChatMessageInput();
+        const output = makeChatMessageOutput("ulw this task");
+
+        await handler(input, output);
+
+        expect(getSessionMode(SESSION_ID)).toBe("ultrawork");
+      });
+    });
+  });
+
+  describe("#given a message containing 'deep-think'", () => {
+    describe("#when the handler processes the message", () => {
+      it("#then sets the session mode to 'think'", async () => {
+        const handler = createKeywordDetectorHandler();
+        const input = makeChatMessageInput();
+        const output = makeChatMessageOutput("Please deep-think about this problem");
+
+        await handler(input, output);
+
+        expect(getSessionMode(SESSION_ID)).toBe("think");
+      });
+    });
+  });
+
+  describe("#given a message containing 'fast'", () => {
+    describe("#when the handler processes the message", () => {
+      it("#then sets the session mode to 'fast'", async () => {
+        const handler = createKeywordDetectorHandler();
+        const input = makeChatMessageInput();
+        const output = makeChatMessageOutput("fast response please");
+
+        await handler(input, output);
+
+        expect(getSessionMode(SESSION_ID)).toBe("fast");
+      });
+    });
+  });
+
+  describe("#given a message with no recognized keywords", () => {
+    describe("#when the handler processes the message", () => {
+      it("#then does not set a session mode", async () => {
+        const handler = createKeywordDetectorHandler();
+        const input = makeChatMessageInput();
+        const output = makeChatMessageOutput("just a normal request");
+
+        await handler(input, output);
+
+        expect(getSessionMode(SESSION_ID)).toBeUndefined();
+      });
+    });
+  });
+
+  describe("#given a keyword inside a code block", () => {
+    describe("#when the handler processes the message", () => {
+      it("#then does not set a session mode", async () => {
+        const handler = createKeywordDetectorHandler();
+        const input = makeChatMessageInput();
+        const output = makeChatMessageOutput("check this code: ```ultrawork()```");
+
+        await handler(input, output);
+
+        expect(getSessionMode(SESSION_ID)).toBeUndefined();
+      });
+    });
+  });
+});
+
+describe("think-mode", () => {
+  beforeEach(() => {
+    clearSessionMode(SESSION_ID);
+  });
+
+  describe("#given think mode is active for the session", () => {
+    describe("#when chat.params hook is called with an Anthropic Claude model", () => {
+      it("#then injects thinking parameters with budget_tokens", async () => {
+        setSessionMode(SESSION_ID, "think");
+        const handler = createThinkModeHandler();
+        const input = makeChatParamsInput("anthropic", "claude-sonnet-4-6");
+        const output = makeChatParamsOutput();
+
+        await handler(input, output);
+
+        expect(output.options.thinking).toEqual({
+          type: "enabled",
+          budget_tokens: 10000,
+        });
+      });
+    });
+  });
+
+  describe("#given think mode is active and model is github-copilot claude", () => {
+    describe("#when chat.params hook is called", () => {
+      it("#then injects thinking parameters", async () => {
+        setSessionMode(SESSION_ID, "think");
+        const handler = createThinkModeHandler();
+        const input = makeChatParamsInput("github-copilot", "claude-sonnet-4-6");
+        const output = makeChatParamsOutput();
+
+        await handler(input, output);
+
+        expect(output.options.thinking).toEqual({
+          type: "enabled",
+          budget_tokens: 10000,
+        });
+      });
+    });
+  });
+
+  describe("#given think mode is not active", () => {
+    describe("#when chat.params hook is called", () => {
+      it("#then does not inject thinking parameters", async () => {
+        const handler = createThinkModeHandler();
+        const input = makeChatParamsInput("anthropic", "claude-sonnet-4-6");
+        const output = makeChatParamsOutput();
+
+        await handler(input, output);
+
+        expect(output.options.thinking).toBeUndefined();
+      });
+    });
+  });
+
+  describe("#given think mode is active but model is not Anthropic Claude", () => {
+    describe("#when chat.params hook is called with an OpenAI model", () => {
+      it("#then does not inject thinking parameters", async () => {
+        setSessionMode(SESSION_ID, "think");
+        const handler = createThinkModeHandler();
+        const input = makeChatParamsInput("openai", "gpt-5.4");
+        const output = makeChatParamsOutput();
+
+        await handler(input, output);
+
+        expect(output.options.thinking).toBeUndefined();
+      });
+    });
+  });
+
+  describe("#given think mode is active but thinking is already set", () => {
+    describe("#when chat.params hook is called", () => {
+      it("#then does not overwrite existing thinking config", async () => {
+        setSessionMode(SESSION_ID, "think");
+        const handler = createThinkModeHandler();
+        const input = makeChatParamsInput("anthropic", "claude-sonnet-4-6");
+        const output = makeChatParamsOutput();
+        output.options.thinking = { type: "enabled", budget_tokens: 5000 };
+
+        await handler(input, output);
+
+        expect(output.options.thinking).toEqual({ type: "enabled", budget_tokens: 5000 });
+      });
+    });
+  });
+});
+
+describe("anthropic-effort", () => {
+  describe("#given effort level 'medium' and an Anthropic Claude model", () => {
+    describe("#when chat.params hook is called", () => {
+      it("#then injects thinking with budget_tokens=5000", async () => {
+        const handler = createAnthropicEffortHandler("medium");
+        const input = makeChatParamsInput("anthropic", "claude-sonnet-4-6");
+        const output = makeChatParamsOutput();
+
+        await handler(input, output);
+
+        expect(output.options.thinking).toEqual({
+          type: "enabled",
+          budget_tokens: 5000,
+        });
+      });
+    });
+  });
+
+  describe("#given effort level 'high' and an Anthropic Claude model", () => {
+    describe("#when chat.params hook is called", () => {
+      it("#then injects thinking with budget_tokens=10000", async () => {
+        const handler = createAnthropicEffortHandler("high");
+        const input = makeChatParamsInput("anthropic", "claude-sonnet-4-6");
+        const output = makeChatParamsOutput();
+
+        await handler(input, output);
+
+        expect(output.options.thinking).toEqual({
+          type: "enabled",
+          budget_tokens: 10000,
+        });
+      });
+    });
+  });
+
+  describe("#given effort level 'max' and an Anthropic Claude model", () => {
+    describe("#when chat.params hook is called", () => {
+      it("#then injects thinking with budget_tokens=32000", async () => {
+        const handler = createAnthropicEffortHandler("max");
+        const input = makeChatParamsInput("anthropic", "claude-sonnet-4-6");
+        const output = makeChatParamsOutput();
+
+        await handler(input, output);
+
+        expect(output.options.thinking).toEqual({
+          type: "enabled",
+          budget_tokens: 32000,
+        });
+      });
+    });
+  });
+
+  describe("#given effort level 'max' and Opus model", () => {
+    describe("#when chat.params hook is called", () => {
+      it("#then also injects effort='max' for opus", async () => {
+        const handler = createAnthropicEffortHandler("max");
+        const input = makeChatParamsInput("anthropic", "claude-opus-4-6");
+        const output = makeChatParamsOutput();
+
+        await handler(input, output);
+
+        expect(output.options.thinking).toEqual({
+          type: "enabled",
+          budget_tokens: 32000,
+        });
+        expect(output.options.effort).toBe("max");
+      });
+    });
+  });
+
+  describe("#given effort level 'low'", () => {
+    describe("#when chat.params hook is called", () => {
+      it("#then does not inject any parameters", async () => {
+        const handler = createAnthropicEffortHandler("low");
+        const input = makeChatParamsInput("anthropic", "claude-sonnet-4-6");
+        const output = makeChatParamsOutput();
+
+        await handler(input, output);
+
+        expect(output.options.thinking).toBeUndefined();
+      });
+    });
+  });
+
+  describe("#given an OpenAI model", () => {
+    describe("#when chat.params hook is called with effort 'high'", () => {
+      it("#then does not inject Anthropic-specific parameters", async () => {
+        const handler = createAnthropicEffortHandler("high");
+        const input = makeChatParamsInput("openai", "gpt-5.4");
+        const output = makeChatParamsOutput();
+
+        await handler(input, output);
+
+        expect(output.options.thinking).toBeUndefined();
+      });
+    });
+  });
+
+  describe("#given thinking is already configured in options", () => {
+    describe("#when chat.params hook is called with effort 'high'", () => {
+      it("#then does not overwrite existing thinking config", async () => {
+        const handler = createAnthropicEffortHandler("high");
+        const input = makeChatParamsInput("anthropic", "claude-sonnet-4-6");
+        const output = makeChatParamsOutput();
+        output.options.thinking = { type: "enabled", budget_tokens: 999 };
+
+        await handler(input, output);
+
+        expect(output.options.thinking).toEqual({ type: "enabled", budget_tokens: 999 });
+      });
+    });
+  });
+});