selftune 0.2.20 → 0.2.22

package/cli/selftune/hooks-shared/hook-output.ts

@@ -0,0 +1,105 @@
+/**
+ * Shared output helpers for platform-agnostic hook responses.
+ *
+ * Hooks communicate with their host agent through stdout (context injection),
+ * stderr (advisory messages), and exit codes (allow/block decisions). The
+ * exact format varies by platform — this module abstracts those differences.
+ *
+ * Claude Code conventions (the primary platform):
+ *   - stdout JSON with hookSpecificOutput.additionalContext for context injection
+ *   - stderr for advisory suggestions
+ *   - exit 0 = allow, exit 2 = block with message
+ */
+
+import type { HookPlatform, HookResponse } from "./types.js";
+
+/**
+ * Format a HookResponse for a specific platform's expected output format.
+ *
+ * For Claude Code: produces JSON with hookSpecificOutput wrapper.
+ * For other platforms: produces a simplified JSON response.
+ *
+ * @param response  The platform-agnostic hook response
+ * @param platform  The target platform
+ * @returns         Formatted string ready to write to stdout
+ */
+export function formatResponseForPlatform(response: HookResponse, platform: HookPlatform): string {
+  if (platform === "claude-code" || platform === "codex") {
+    // Claude Code / Codex use hookSpecificOutput wrapper
+    const output: Record<string, unknown> = {};
+
+    if (response.context) {
+      output.hookSpecificOutput = {
+        additionalContext: response.context,
+      };
+    }
+
+    if (response.updated_input) {
+      output.updatedInput = response.updated_input;
+    }
+
+    if (response.decision) {
+      output.decision = response.decision;
+    }
+
+    return JSON.stringify(output);
+  }
+
+  // Generic JSON format for other platforms
+  return JSON.stringify({
+    modified: response.modified,
+    decision: response.decision,
+    message: response.message,
+    context: response.context,
+    updated_input: response.updated_input,
+  });
+}
+
+/**
+ * Write an advisory suggestion to stderr.
+ *
+ * Stderr messages appear as system messages to the host agent in Claude Code.
+ * Other platforms may handle stderr differently, but writing to stderr is
+ * universally safe (it never affects the hook's exit code or stdout response).
+ *
+ * @param message  The suggestion text to display
+ */
+export function writeSuggestion(message: string): void {
+  process.stderr.write(`${message}\n`);
+}
+
+/**
+ * Write context injection to stdout.
+ *
+ * For Claude Code, this injects content into Claude's context via the
+ * hookSpecificOutput.additionalContext mechanism. The output is JSON-formatted
+ * to match Claude Code's expected hook output schema.
+ *
+ * @param context  The context string to inject
+ */
+export function writeContext(context: string): void {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        additionalContext: context,
+      },
+    }),
+  );
+}
+
+/**
+ * Exit with a platform-appropriate exit code for allow/block decisions.
+ *
+ * Claude Code convention:
+ *   - exit 0 = allow the tool call
+ *   - exit 2 = block the tool call (with stderr message)
+ *
+ * Other platforms use the same convention unless they specify otherwise.
+ *
+ * @param decision  "allow" or "block"
+ * @param _platform  The target platform (reserved for future per-platform codes)
+ */
+export function exitWithDecision(decision: "allow" | "block", _platform: HookPlatform): never {
+  const code = decision === "block" ? 2 : 0;
+  process.exit(code);
+}

package/cli/selftune/hooks-shared/normalize.ts

@@ -0,0 +1,196 @@
+/**
+ * Normalizers that convert platform-specific hook payloads to UnifiedHookEvent.
+ *
+ * Each platform adapter maps its native payload shape and event names
+ * to the shared UnifiedHookEvent interface. The normalizers are intentionally
+ * lenient — unknown fields are ignored, missing fields become undefined.
+ *
+ * Fail-open: any parsing error returns a minimal event with what we have.
+ */
+
+import type { HookEventType, HookPlatform, UnifiedHookEvent } from "./types.js";
+import { PLATFORM_EVENT_MAP } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Reverse lookup: native event name -> HookEventType
+// ---------------------------------------------------------------------------
+
+/** Build a reverse map from native event string to HookEventType for a platform. */
+function buildReverseLookup(platform: HookPlatform): Map<string, HookEventType> {
+  const forward = PLATFORM_EVENT_MAP[platform];
+  const reverse = new Map<string, HookEventType>();
+  for (const [hookType, nativeName] of Object.entries(forward)) {
+    if (nativeName) {
+      reverse.set(nativeName, hookType as HookEventType);
+    }
+  }
+  return reverse;
+}
+
+const reverseLookups = new Map<HookPlatform, Map<string, HookEventType>>();
+
+/** Resolve a native event type string to the normalized HookEventType. */
+function resolveEventType(
+  platform: HookPlatform,
+  nativeEventType: string,
+): HookEventType | undefined {
+  let lookup = reverseLookups.get(platform);
+  if (!lookup) {
+    lookup = buildReverseLookup(platform);
+    reverseLookups.set(platform, lookup);
+  }
+  return lookup.get(nativeEventType);
+}
+
+// ---------------------------------------------------------------------------
+// Shared field extraction helpers
+// ---------------------------------------------------------------------------
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" ? v : undefined;
+}
+
+function obj(v: unknown): Record<string, unknown> | undefined {
+  return typeof v === "object" && v !== null ? (v as Record<string, unknown>) : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Per-platform field extraction config
+// ---------------------------------------------------------------------------
+
+/**
+ * Describes how to extract prompt and last_message fields from a platform's
+ * payload. Most platforms use the same field names; Claude Code has a
+ * user_prompt fallback, and some use last_assistant_message vs last_message.
+ */
+interface PlatformFieldConfig {
+  /** Default event_type when resolution fails */
+  fallbackEvent: HookEventType;
+  /** Fields to try for prompt (in order, first non-undefined wins) */
+  promptFields: string[];
+  /** Field name for session-end last message */
+  lastMessageField: string;
+  /** Field name for post_tool_use output (e.g., "tool_response" or "tool_output") */
+  toolOutputField: string;
+}
+
+const FIELD_CONFIG: Record<HookPlatform, PlatformFieldConfig> = {
+  "claude-code": {
+    fallbackEvent: "prompt_submit",
+    promptFields: ["prompt", "user_prompt"],
+    lastMessageField: "last_assistant_message",
+    toolOutputField: "tool_response",
+  },
+  codex: {
+    fallbackEvent: "prompt_submit",
+    promptFields: ["prompt"],
+    lastMessageField: "last_assistant_message",
+    toolOutputField: "tool_response",
+  },
+  opencode: {
+    fallbackEvent: "session_end",
+    promptFields: ["prompt"],
+    lastMessageField: "last_message",
+    toolOutputField: "tool_output",
+  },
+  cline: {
+    fallbackEvent: "session_end",
+    promptFields: ["prompt"],
+    lastMessageField: "last_message",
+    toolOutputField: "tool_output",
+  },
+  pi: {
+    fallbackEvent: "session_end",
+    promptFields: ["prompt"],
+    lastMessageField: "last_message",
+    toolOutputField: "tool_output",
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Unified normalizer
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize a platform-specific hook payload to UnifiedHookEvent.
+ *
+ * This single function replaces per-platform normalizers by using
+ * FIELD_CONFIG to handle platform-specific field names.
+ */
+function normalizeForPlatform(
+  platform: HookPlatform,
+  payload: unknown,
+  eventType: string,
+): UnifiedHookEvent {
+  const raw = obj(payload) ?? {};
+  const config = FIELD_CONFIG[platform];
+  const resolved = resolveEventType(platform, eventType);
+
+  const base: UnifiedHookEvent = {
+    platform,
+    event_type: resolved ?? config.fallbackEvent,
+    session_id: str(raw.session_id) ?? "unknown",
+    cwd: str(raw.cwd),
+    transcript_path: str(raw.transcript_path),
+    raw_payload: payload,
+  };
+
+  if (resolved === "pre_tool_use" || resolved === "post_tool_use") {
+    base.tool_name = str(raw.tool_name);
+    base.tool_input = obj(raw.tool_input);
+    if (resolved === "post_tool_use") {
+      base.tool_output = obj(raw[config.toolOutputField]);
+    }
+  } else if (resolved === "prompt_submit") {
+    for (const field of config.promptFields) {
+      const v = str(raw[field]);
+      if (v) {
+        base.prompt = v;
+        break;
+      }
+    }
+  } else if (resolved === "session_end") {
+    base.last_message = str(raw[config.lastMessageField]);
+  }
+
+  return base;
+}
+
+// ---------------------------------------------------------------------------
+// Public API — named exports for backward compatibility + unified entry point
+// ---------------------------------------------------------------------------
+
+export function normalizeClaudeCode(payload: unknown, eventType: string): UnifiedHookEvent {
+  return normalizeForPlatform("claude-code", payload, eventType);
+}
+
+export function normalizeCodex(payload: unknown, eventType: string): UnifiedHookEvent {
+  return normalizeForPlatform("codex", payload, eventType);
+}
+
+export function normalizeOpenCode(payload: unknown, eventType: string): UnifiedHookEvent {
+  return normalizeForPlatform("opencode", payload, eventType);
+}
+
+export function normalizeCline(payload: unknown, eventType: string): UnifiedHookEvent {
+  return normalizeForPlatform("cline", payload, eventType);
+}
+
+export function normalizePi(payload: unknown, eventType: string): UnifiedHookEvent {
+  return normalizeForPlatform("pi", payload, eventType);
+}
+
+/**
+ * Auto-detect platform and normalize a hook payload to UnifiedHookEvent.
+ *
+ * @param payload          Raw payload (typically parsed from stdin JSON)
+ * @param platform         The host platform
+ * @param nativeEventType  The platform-native event type string
+ */
+export function normalizeHookEvent(
+  payload: unknown,
+  platform: HookPlatform,
+  nativeEventType: string,
+): UnifiedHookEvent {
+  return normalizeForPlatform(platform, payload, nativeEventType);
+}

package/cli/selftune/hooks-shared/session-state.ts

@@ -0,0 +1,76 @@
+/**
+ * Generic session state persistence for hooks.
+ *
+ * Extracted from the duplicate patterns in auto-activate.ts (loadSessionState/saveSessionState)
+ * and skill-change-guard.ts (loadGuardState/saveGuardState). Both follow the same pattern:
+ *
+ *   1. Read a JSON file keyed by session_id
+ *   2. If session_id matches, return persisted state; otherwise return defaults
+ *   3. Write state back after updates
+ *
+ * This module generalizes that pattern with a type-safe generic interface.
+ * Fail-open: corrupt or missing files return fresh defaults.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import type { SessionState } from "./types.js";
+
+/**
+ * Load session state from a JSON file.
+ *
+ * The file is located at `{dir}/{prefix}-{sessionId}.json`. If the file does not
+ * exist, is corrupt, or belongs to a different session, fresh defaults are returned.
+ *
+ * @param dir        Directory to store state files (e.g., SELFTUNE_CONFIG_DIR)
+ * @param prefix     Filename prefix (e.g., "session-state", "guard-state")
+ * @param sessionId  Current session ID — state is invalidated when it changes
+ * @param defaults   Factory function returning fresh default state data
+ */
+export function loadSessionState<T extends Record<string, unknown>>(
+  dir: string,
+  prefix: string,
+  sessionId: string,
+  defaults: () => T,
+): SessionState<T> {
+  const safeName = sessionId.replace(/[^a-zA-Z0-9_-]/g, "_");
+  const filePath = join(dir, `${prefix}-${safeName}.json`);
+
+  try {
+    const raw = JSON.parse(readFileSync(filePath, "utf-8")) as SessionState<T>;
+    if (raw.session_id === sessionId && typeof raw.data === "object" && raw.data !== null) {
+      return raw;
+    }
+  } catch {
+    // ENOENT (missing) or corrupt JSON -- return fresh defaults
+  }
+
+  return {
+    session_id: sessionId,
+    created_at: new Date().toISOString(),
+    data: defaults(),
+  };
+}
+
+/**
+ * Save session state to a JSON file.
+ *
+ * The file is written to `{dir}/{prefix}-{state.session_id}.json`.
+ * The directory is created if it does not exist.
+ *
+ * @param dir     Directory to store state files
+ * @param prefix  Filename prefix (must match what was used in loadSessionState)
+ * @param state   The session state to persist
+ */
+export function saveSessionState<T extends Record<string, unknown>>(
+  dir: string,
+  prefix: string,
+  state: SessionState<T>,
+): void {
+  const safeName = state.session_id.replace(/[^a-zA-Z0-9_-]/g, "_");
+  const filePath = join(dir, `${prefix}-${safeName}.json`);
+
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(state, null, 2), "utf-8");
+}

package/cli/selftune/hooks-shared/skill-paths.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared skill name and path extraction utilities for hooks.
+ *
+ * Extracted from duplicated logic in:
+ *   - skill-eval.ts: extractSkillName (checks SKILL.MD basename)
+ *   - skill-change-guard.ts: isSkillMdWrite, extractSkillNameFromPath
+ *   - evolution-guard.ts: isSkillMdWrite, extractSkillName (identical copies)
+ *
+ * All three files independently implement the same SKILL.md detection pattern.
+ * This module provides a single source of truth.
+ */
+
+import { basename, dirname } from "node:path";
+
+/**
+ * Extract the skill folder name from a file path that ends in SKILL.md.
+ *
+ * The convention is that skill definitions live at `<skill-name>/SKILL.md`,
+ * so the parent directory name is the skill name.
+ *
+ * @param filePath  Absolute or relative path to check
+ * @returns         Skill folder name, or null if the path does not end in SKILL.md
+ */
+export function extractSkillName(filePath: string): string | null {
+  if (!isSkillMdFile(filePath)) return null;
+  return basename(dirname(filePath)) || "unknown";
+}
+
+/**
+ * Check if a file path points to a SKILL.md file (case-insensitive).
+ *
+ * @param filePath  Path to check
+ */
+export function isSkillMdFile(filePath: string): boolean {
+  return basename(filePath).toUpperCase() === "SKILL.MD";
+}
+
+/**
+ * Check if a tool call is a Write or Edit operation targeting a SKILL.md file.
+ *
+ * Used by guard hooks (skill-change-guard, evolution-guard) to detect
+ * when an agent is about to modify a skill definition.
+ *
+ * @param toolName  The tool being called (e.g., "Write", "Edit", "Read")
+ * @param filePath  The file_path from tool_input
+ */
+export function isSkillMdWrite(toolName: string, filePath: string): boolean {
+  if (toolName !== "Write" && toolName !== "Edit") return false;
+  return isSkillMdFile(filePath);
+}

package/cli/selftune/hooks-shared/stdin-dispatch.ts

@@ -0,0 +1,59 @@
+/**
+ * Generalized stdin preview and keyword filtering for hooks.
+ *
+ * Hooks receive payloads via stdin. Most hooks only care about specific
+ * event types (e.g., skill-eval only handles PostToolUse). The existing
+ * stdin-preview.ts provides a fast-path optimization: read stdin once,
+ * check a preview slice for keywords, and skip JSON.parse entirely when
+ * the keyword is absent.
+ *
+ * This module wraps that pattern into a single readAndFilter call that
+ * combines the preview check with JSON parsing, returning null when
+ * the payload is irrelevant (caller should exit 0 immediately).
+ *
+ * Re-exports readStdinWithPreview for backward compatibility.
+ */
+
+export { readStdinWithPreview } from "../hooks/stdin-preview.js";
+
+/** Default preview size in characters (covers envelope fields). */
+const DEFAULT_PREVIEW_BYTES = 4096;
+
+/**
+ * Read stdin with fast-path keyword filtering.
+ *
+ * Reads all of stdin, checks the leading preview slice for the presence of
+ * ALL required keywords. If any keyword is missing, returns null (the caller
+ * should exit early). Otherwise, parses the full payload as JSON and returns it.
+ *
+ * This is the recommended way to read hook payloads when you know which
+ * keywords must appear in the envelope (e.g., event name, tool name).
+ *
+ * @param requiredKeywords  Strings that must ALL appear in the preview slice.
+ *                          Typically quoted JSON values like '"PostToolUse"'.
+ * @param previewBytes      Number of leading characters to check (default 4096).
+ * @returns                 Parsed payload and raw string, or null if keywords don't match.
+ *
+ * @example
+ * ```ts
+ * const result = await readAndFilter<PostToolUsePayload>(['"PostToolUse"', '"Read"']);
+ * if (!result) process.exit(0);
+ * const { payload } = result;
+ * ```
+ */
+export async function readAndFilter<T = unknown>(
+  requiredKeywords: string[],
+  previewBytes: number = DEFAULT_PREVIEW_BYTES,
+): Promise<{ payload: T; raw: string } | null> {
+  const raw = await Bun.stdin.text();
+  const preview = raw.slice(0, previewBytes);
+
+  for (const keyword of requiredKeywords) {
+    if (!preview.includes(keyword)) {
+      return null;
+    }
+  }
+
+  const payload = JSON.parse(raw) as T;
+  return { payload, raw };
+}

package/cli/selftune/hooks-shared/types.ts

@@ -0,0 +1,90 @@
+/**
+ * Universal hook types for multi-agent abstraction.
+ * All platform adapters normalize their native events to these types.
+ */
+
+/** Supported agent platforms */
+export type HookPlatform = "claude-code" | "codex" | "opencode" | "cline" | "pi";
+
+/** Normalized event types across all platforms */
+export type HookEventType = "pre_tool_use" | "post_tool_use" | "prompt_submit" | "session_end";
+
+/**
+ * Platform-agnostic hook event. Each adapter normalizes its native payload to this shape.
+ * Fields are optional because not all platforms provide all data.
+ */
+export interface UnifiedHookEvent {
+  platform: HookPlatform;
+  event_type: HookEventType;
+  session_id: string;
+  cwd?: string;
+  transcript_path?: string;
+
+  // Tool-related (pre_tool_use / post_tool_use)
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+  tool_output?: Record<string, unknown>;
+
+  // Prompt-related (prompt_submit)
+  prompt?: string;
+
+  // Session-related (session_end)
+  last_message?: string;
+
+  /** Original platform-specific payload, preserved for platform-specific logic */
+  raw_payload?: unknown;
+}
+
+/**
+ * Hook response returned to the host agent.
+ * Adapters translate this back to platform-specific format.
+ */
+export interface HookResponse {
+  /** Whether the hook modified the input */
+  modified: boolean;
+  /** Decision for PreToolUse guards */
+  decision?: "allow" | "block" | "skip";
+  /** Modified tool input (for pre_tool_use hooks that modify commands) */
+  updated_input?: Record<string, unknown>;
+  /** Advisory message (stderr suggestions) */
+  message?: string;
+  /** Additional context to inject (stdout JSON for Claude Code) */
+  context?: string;
+}
+
+/** Generic session state for dedup/tracking across hook invocations */
+export interface SessionState<T extends Record<string, unknown> = Record<string, unknown>> {
+  session_id: string;
+  created_at: string;
+  data: T;
+}
+
+/** Platform event mapping reference */
+export const PLATFORM_EVENT_MAP: Record<HookPlatform, Partial<Record<HookEventType, string>>> = {
+  "claude-code": {
+    pre_tool_use: "PreToolUse",
+    post_tool_use: "PostToolUse",
+    prompt_submit: "UserPromptSubmit",
+    session_end: "Stop",
+  },
+  codex: {
+    pre_tool_use: "PreToolUse",
+    post_tool_use: "PostToolUse",
+    prompt_submit: "SessionStart",
+    session_end: "Stop",
+  },
+  opencode: {
+    pre_tool_use: "tool.execute.before",
+    post_tool_use: "tool.execute.after",
+    session_end: "session.idle",
+  },
+  cline: {
+    post_tool_use: "PostToolUse",
+    session_end: "TaskComplete",
+  },
+  pi: {
+    pre_tool_use: "tool_call",
+    post_tool_use: "tool_result",
+    session_end: "session_shutdown",
+  },
+};

package/cli/selftune/index.ts

@@ -30,6 +30,9 @@
  *   selftune telemetry          — Manage anonymous usage analytics (status, enable, disable)
  *   selftune alpha <subcommand> — Alpha program management (upload)
  *   selftune hook <name>        — Run a hook by name (prompt-log, session-stop, etc.)
+ *   selftune codex <subcommand> — Codex platform hooks (hook, install)
+ *   selftune opencode <sub>     — OpenCode platform hooks (hook, install)
+ *   selftune cline <subcommand> — Cline platform hooks (hook, install)
  */
 
 import { CLIError, handleCLIError } from "./utils/cli-error.js";
@@ -73,20 +76,26 @@ Commands:
   alpha <subcommand> Alpha program management (upload)
   telemetry          Manage anonymous usage analytics (status, enable, disable)
   hook <name>        Run a hook by name (prompt-log, session-stop, etc.)
+  codex <sub>        Codex platform hooks (hook, install)
+  opencode <sub>     OpenCode platform hooks (hook, install)
+  cline <sub>        Cline platform hooks (hook, install)
 
 Run 'selftune <command> --help' for command-specific options.`);
   process.exit(0);
 }
 
-// Track command usage (lazy import — avoids loading crypto/os on --help or no-op paths)
-if (command && command !== "--help" && command !== "-h") {
+// Fast-path commands (real-time hooks) — skip analytics and auto-update to minimize latency
+const FAST_COMMANDS: ReadonlySet<string> = new Set(["hook", "codex", "opencode", "cline"]);
+
+// Track command usage (lazy import — skip for hooks and --help to avoid loading crypto/os)
+if (command && !FAST_COMMANDS.has(command) && command !== "--help" && command !== "-h") {
   import("./analytics.js")
     .then(({ trackEvent }) => trackEvent("command_run", { command }))
     .catch(() => {});
 }
 
-// Auto-update check (skip for hooks — they must be fast — and --help)
-if (command && command !== "hook" && command !== "--help" && command !== "-h") {
+// Auto-update check (skip for hooks and platform hook commands — they must be fast — and --help)
+if (command && !FAST_COMMANDS.has(command) && command !== "--help" && command !== "-h") {
   const { autoUpdate } = await import("./auto-update.js");
   await autoUpdate();
 }
@@ -815,6 +824,49 @@ Output:
     process.exit(result.status ?? 1);
     break;
   }
+  // ── Platform hook adapters ─────────────────────────────────────────
+
+  case "codex":
+  case "opencode":
+  case "cline": {
+    const platform = command;
+    const displayName = { codex: "Codex", opencode: "OpenCode", cline: "Cline" }[platform];
+    const sub = process.argv[2];
+    if (!sub || sub === "--help" || sub === "-h") {
+      console.log(`selftune ${platform} — ${displayName} platform hooks
+
+Usage:
+  selftune ${platform} <subcommand> [options]
+
+Subcommands:
+  hook       Handle a real-time hook event from ${displayName}
+  install    Install or remove selftune hooks in ${displayName} config
+
+Run 'selftune ${platform} <subcommand> --help' for subcommand-specific options.`);
+      process.exit(0);
+    }
+    process.argv = [process.argv[0], process.argv[1], ...process.argv.slice(3)];
+    switch (sub) {
+      case "hook": {
+        const { cliMain } = await import(`./adapters/${platform}/hook.js`);
+        await cliMain();
+        break;
+      }
+      case "install": {
+        const { cliMain } = await import(`./adapters/${platform}/install.js`);
+        await cliMain();
+        break;
+      }
+      default:
+        throw new CLIError(
+          `Unknown ${platform} subcommand: ${sub}`,
+          "UNKNOWN_COMMAND",
+          `selftune ${platform} --help`,
+        );
+    }
+    break;
+  }
+
   default:
     throw new CLIError(`Unknown command: ${command}`, "UNKNOWN_COMMAND", "selftune --help");
 }