selftune 0.2.21 → 0.2.22

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");
 }

package/cli/selftune/utils/llm-call.ts

@@ -6,9 +6,9 @@
  * modules can reuse the same calling logic.
  */
 
-import { readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 
 import { AGENT_CANDIDATES } from "../constants.js";
 import { createLogger } from "./logging.js";
@@ -33,6 +33,40 @@ function resolveModelFlag(flag: string): string {
   return CLAUDE_MODEL_ALIASES[flag] ?? flag;
 }
 
+/**
+ * Map selftune model aliases to OpenCode provider/model format.
+ * OpenCode uses "provider/model" syntax (e.g. "anthropic/claude-sonnet-4-20250514").
+ */
+const OPENCODE_MODEL_MAP: Record<string, string> = {
+  haiku: "anthropic/claude-haiku-4-5-20251001",
+  sonnet: "anthropic/claude-sonnet-4-20250514",
+  opus: "anthropic/claude-opus-4-20250514",
+};
+
+/** Resolve a model alias to OpenCode's provider/model format. */
+function resolveOpenCodeModel(flag: string): string {
+  return OPENCODE_MODEL_MAP[flag] ?? flag;
+}
+
+// ---------------------------------------------------------------------------
+// Bundled agent file loading (for codex inline prompt injection)
+// ---------------------------------------------------------------------------
+
+const BUNDLED_AGENT_DIR = resolve(dirname(import.meta.path), "..", "..", "..", "skill", "agents");
+
+/**
+ * Read the bundled agent markdown file and return its body (without frontmatter).
+ * Used by codex path to inline agent instructions into the prompt since codex
+ * has no --agent flag.
+ */
+function loadAgentInstructions(agentName: string): string | null {
+  const filePath = join(BUNDLED_AGENT_DIR, `${agentName}.md`);
+  if (!existsSync(filePath)) return null;
+  const content = readFileSync(filePath, "utf-8");
+  // Strip YAML frontmatter
+  return content.replace(/^---\n[\s\S]*?\n---\n*/, "").trim();
+}
+
 // ---------------------------------------------------------------------------
 // Agent detection
 // ---------------------------------------------------------------------------
@@ -155,7 +189,11 @@ export async function callViaAgent(
     } else if (agent === "codex") {
       cmd = ["codex", "exec", "--skip-git-repo-check", promptContent];
     } else if (agent === "opencode") {
-      cmd = ["opencode", "-p", promptContent, "-f", "text", "-q"];
+      cmd = ["opencode", "run"];
+      if (modelFlag) {
+        cmd.push("--model", resolveOpenCodeModel(modelFlag));
+      }
+      cmd.push(promptContent);
     } else {
       throw new Error(`Unknown agent: ${agent}`);
     }
@@ -222,9 +260,9 @@ export async function callViaAgent(
 // Call LLM via named subagent (multi-turn, agentic)
 // ---------------------------------------------------------------------------
 
-/** Options for calling a named Claude Code subagent. */
+/** Options for calling a named subagent (Claude Code or OpenCode). */
 export interface SubagentCallOptions {
-  /** Name of the subagent (synced into ~/.claude/agents/ by selftune init/update). */
+  /** Name of the subagent (synced into ~/.claude/agents/ or opencode.json by selftune init/update). */
   agentName: string;
   /** The task prompt for the subagent. */
   prompt: string;
@@ -243,13 +281,13 @@ export interface SubagentCallOptions {
 }
 
 /**
- * Call a named Claude Code subagent in print mode. The subagent runs its
- * multi-turn workflow (reading files, running commands, etc.) and returns
- * the final text output.
+ * Call a named subagent in print mode. The subagent runs its multi-turn
+ * workflow (reading files, running commands, etc.) and returns the final
+ * text output.
  *
- * Unlike callViaAgent(), this does NOT use --bare (agents need discovery)
- * and passes --agent + --max-turns for agentic multi-turn behavior.
- * Only supports the claude CLI.
+ * Supports Claude Code (`claude --agent`), OpenCode (`opencode run --agent`),
+ * and Codex (`codex exec` with agent instructions inlined into the prompt).
+ * Auto-detects the available agent CLI.
  */
 export async function callViaSubagent(options: SubagentCallOptions): Promise<string> {
   const {
@@ -263,31 +301,58 @@ export async function callViaSubagent(options: SubagentCallOptions): Promise<str
     allowedTools,
   } = options;
 
-  const cmd: string[] = [
-    "claude",
-    "-p",
-    prompt,
-    "--agent",
-    agentName,
-    "--max-turns",
-    String(maxTurns),
-  ];
-
-  if (appendSystemPrompt) {
-    cmd.push("--append-system-prompt", appendSystemPrompt);
-  }
-  if (modelFlag) {
-    const resolved = resolveModelFlag(modelFlag);
-    cmd.push("--model", resolved);
+  const agent = detectAgent();
+  if (!agent || (agent !== "claude" && agent !== "opencode" && agent !== "codex")) {
+    throw new Error(
+      `Subagent calls require 'claude', 'opencode', or 'codex' CLI in PATH (detected: ${agent ?? "none"})`,
+    );
   }
-  if (effort) {
-    cmd.push("--effort", effort);
-  }
-  if (allowedTools && allowedTools.length > 0) {
-    cmd.push("--allowedTools", ...allowedTools);
+
+  let cmd: string[];
+
+  if (agent === "opencode") {
+    // OpenCode supports --agent and --model but not allowedTools, appendSystemPrompt, or maxTurns
+    if (allowedTools?.length || appendSystemPrompt) {
+      logger.warn(
+        `Subagent '${agentName}' on opencode: allowedTools and appendSystemPrompt are not supported and will be ignored`,
+      );
+    }
+    cmd = ["opencode", "run", "--agent", agentName];
+    if (modelFlag) {
+      cmd.push("--model", resolveOpenCodeModel(modelFlag));
+    }
+    cmd.push(prompt);
+  } else if (agent === "codex") {
+    // Codex has no --agent flag; inline the agent instructions into the prompt.
+    // allowedTools, appendSystemPrompt, maxTurns, and effort are not supported.
+    if (allowedTools?.length || appendSystemPrompt) {
+      logger.warn(
+        `Subagent '${agentName}' on codex: allowedTools and appendSystemPrompt are not supported and will be ignored`,
+      );
+    }
+    const agentInstructions = loadAgentInstructions(agentName);
+    const fullPrompt = agentInstructions ? `${agentInstructions}\n\n---\n\n${prompt}` : prompt;
+    cmd = ["codex", "exec", "--skip-git-repo-check", fullPrompt];
+  } else {
+    // Claude Code
+    cmd = ["claude", "-p", prompt, "--agent", agentName, "--max-turns", String(maxTurns)];
+
+    if (appendSystemPrompt) {
+      cmd.push("--append-system-prompt", appendSystemPrompt);
+    }
+    if (modelFlag) {
+      const resolved = resolveModelFlag(modelFlag);
+      cmd.push("--model", resolved);
+    }
+    if (effort) {
+      cmd.push("--effort", effort);
+    }
+    if (allowedTools && allowedTools.length > 0) {
+      cmd.push("--allowedTools", ...allowedTools);
+    }
+    // Skip permissions since this runs non-interactively in a pipeline
+    cmd.push("--dangerously-skip-permissions");
   }
-  // Skip permissions since this runs non-interactively in a pipeline
-  cmd.push("--dangerously-skip-permissions");
 
   const maxRetries = retryOpts?.maxRetries ?? DEFAULT_MAX_RETRIES;
   const initialBackoffMs = retryOpts?.initialBackoffMs ?? DEFAULT_INITIAL_BACKOFF_MS;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "selftune",
-  "version": "0.2.21",
+  "version": "0.2.22",
   "description": "Self-improving skills CLI for AI agents",
   "keywords": [
     "agent",

package/skill/SKILL.md

@@ -125,6 +125,14 @@ selftune uninstall          [--dry-run] [--keep-logs] [--npm-uninstall]
 # Hook dispatch (for debugging/manual invocation)
 selftune hook <name>   # prompt-log | session-stop | skill-eval | auto-activate | skill-change-guard | evolution-guard
 
+# Platform hooks (non-Claude-Code agents)
+selftune codex hook
+selftune codex install    [--dry-run] [--uninstall]
+selftune opencode hook
+selftune opencode install [--dry-run] [--uninstall]
+selftune cline hook
+selftune cline install    [--dry-run] [--uninstall]
+
 # Alpha enrollment (device-code flow — browser opens automatically)
 selftune init --alpha --alpha-email <email>
 selftune alpha upload [--dry-run]
@@ -169,6 +177,7 @@ selftune status                                                        # shows c
 | repair, rebuild usage, fix skill usage, trustworthy usage, repair-skill-usage                                                           | RepairSkillUsage  | Workflows/RepairSkillUsage.md         |
 | export canonical, canonical export, canonical telemetry, push payload                                                                   | ExportCanonical   | Workflows/ExportCanonical.md          |
 | hook, run hook, invoke hook, manual hook, debug hook                                                                                    | Hook              | Workflows/Hook.md                     |
+| codex hooks, codex install, codex setup, opencode hooks, opencode install, opencode setup, cline hooks, cline install, cline setup, multi-platform, platform hooks, non-claude hooks, multiple agents, multi-agent | PlatformHooks     | Workflows/PlatformHooks.md            |
 | export, dump, jsonl, export sqlite, debug export                                                                                        | Export            | _(direct command — no workflow file)_ |
 | status, health summary, skill health, how are skills, skills doing, run selftune                                                        | Status            | _(direct command — no workflow file)_ |
 | last, last session, recent session, what happened, what changed                                                                         | Last              | _(direct command — no workflow file)_ |
@@ -357,6 +366,7 @@ accomplish a task _using_ a skill, route to that skill instead.
 | `Workflows/CreatorContributions.md` | Manage bundled `selftune.contribute.json` configs   | When preparing a skill package for creator contributions |
 | `Workflows/ExportCanonical.md`      | Export canonical telemetry for downstream use       | When exporting data for external consumption    |
 | `Workflows/Hook.md`                 | Manual hook invocation for debugging                | When debugging or testing hooks manually        |
+| `Workflows/PlatformHooks.md`        | Non-Claude-Code platform hook install/config        | When setting up Codex, OpenCode, or Cline hooks |
 | `references/logs.md`                | Log file formats (telemetry, usage, queries, audit) | When parsing or debugging log files             |
 | `references/grading-methodology.md` | 3-tier grading model, evidence standards            | When grading sessions or interpreting grades    |
 | `references/invocation-taxonomy.md` | 4 invocation types, coverage analysis               | When analyzing trigger coverage                 |

package/skill/Workflows/Initialize.md

@@ -7,6 +7,7 @@ Bootstrap selftune for first-time use or after changing environments.
 - The user asks to set up selftune, configure selftune, or initialize selftune
 - The agent detects `~/.selftune/config.json` does not exist
 - The user has switched agent platforms (Claude Code, Codex, OpenCode)
+- The user wants to add hooks for additional platforms (multi-agent setup)
 
 ## Default Command
 
@@ -136,15 +137,49 @@ Code subagent calls stay up to date.
 | `PostToolUse` (Bash)       | `hooks/commit-track.ts`       | Track git commits for session traceability      | Fast-path: skips non-git Bash commands          |
 | `Stop`                     | `hooks/session-stop.ts`       | Capture session telemetry                       | Runs async (non-blocking), 60s timeout          |
 
-**Codex agents:**
+### 4b. Multi-Platform Hooks
 
-- Use `selftune ingest wrap-codex` for real-time telemetry capture (see `Workflows/Ingest.md`)
-- Or batch-ingest existing sessions with `selftune ingest codex`
+After Claude Code hooks are installed, check whether the user has **other** agent
+CLIs available. Run these checks:
 
-**OpenCode agents:**
+```bash
+which codex 2>/dev/null && echo "codex available"
+which opencode 2>/dev/null && echo "opencode available"
+ls ~/Documents/Cline/Hooks/ 2>/dev/null && echo "cline available"
+```
+
+If **any** additional platforms are detected, use `AskUserQuestion` listing only
+the platforms that were actually found:
+
+> I detected these agent platforms in addition to your primary one:
+> - [list only detected platforms, e.g. "Codex", "OpenCode"]
+>
+> Would you like to install selftune hooks for any of them? This enables
+> real-time skill tracking across all your agents.
+
+Options:
+- `Yes — install hooks for all detected platforms`
+- `Let me pick — show me the list` (then present only the detected platforms)
+- `No — skip for now` (they can always run `selftune <platform> install` later)
+
+For each platform the user selects, run the install command:
+
+```bash
+selftune codex install      # writes hooks.json entries
+selftune opencode install   # writes shell shim + config entries
+selftune cline install      # creates hook scripts
+```
+
+Use `--dry-run` first if the user wants to preview. See `Workflows/PlatformHooks.md`
+for platform-specific details.
+
+**Batch ingest** fallback for platforms without real-time hooks or to backfill history:
 
-- Use `selftune ingest opencode` to import sessions from the SQLite database
-- See `Workflows/Ingest.md` for details
+```bash
+selftune ingest codex       # import Codex rollout sessions
+selftune ingest opencode    # import OpenCode sessions from SQLite
+selftune ingest openclaw    # import OpenClaw sessions
+```
 
 ### 5. Initialize Memory Directory
 
@@ -387,6 +422,13 @@ retrying with `selftune init --alpha --alpha-email <email> --force`.
 > and optional display name in chat, then run `selftune init --alpha --alpha-email ...`.
 > The browser opens automatically for approval. No manual key management needed.
 
+**User uses multiple agents (Claude Code + Codex, etc.)**
+
+> Run `selftune init` for the primary agent, then offer to install hooks for
+> additional detected platforms. Run `selftune codex install`, `selftune opencode install`,
+> or `selftune cline install` as needed. All platforms write to the same shared
+> log schema — no extra config required.
+
 **Hooks not capturing data**
 
 > Run `selftune doctor` to check hook installation. Parse the JSON output

package/skill/Workflows/PlatformHooks.md

@@ -0,0 +1,93 @@
+# Platform Hooks Workflow
+
+## Purpose
+
+Install and configure selftune hooks for non-Claude-Code platforms (Codex, OpenCode, Cline).
+
+## When to Use
+
+- User wants selftune on Codex, OpenCode, or Cline
+- User asks about multi-platform support
+- User wants real-time skill tracking on a non-Claude-Code agent
+
+## Commands
+
+### Install hooks for a platform
+
+```bash
+selftune <platform> install [--dry-run] [--uninstall]
+```
+
+Supported platforms: `codex`, `opencode`, `cline`
+
+| Flag          | Description                                    |
+| ------------- | ---------------------------------------------- |
+| `--dry-run`   | Preview what would be installed without writing |
+| `--uninstall` | Remove selftune hooks from the platform         |
+| `--help, -h`  | Show usage help                                 |
+
+### Hook handler (called by the agent, not the user)
+
+```bash
+selftune <platform> hook
+```
+
+This is called automatically by the agent's hook system. Users don't run this directly.
+
+## Platform Details
+
+### Codex
+
+- Config: `~/.codex/hooks.json`
+- Events: SessionStart, PreToolUse, PostToolUse, Stop
+- Install creates hooks.json entries that prefer `$SELFTUNE_CLI_PATH codex hook`, otherwise `npx -y selftune@latest codex hook`
+
+### OpenCode
+
+- Config: `./opencode.json` or `~/.config/opencode/opencode.json`
+- Plugin dir: `~/.config/opencode/plugins/` (global) or `./.opencode/plugins/` (project)
+- Events: tool.execute.before, tool.execute.after, session.idle (via event handler)
+- Install writes a TypeScript plugin file (`selftune-opencode-plugin.ts`) into the plugins directory (auto-discovered by OpenCode at startup)
+- Agents are registered in the `agent` config key (identified by `[selftune]` description prefix)
+
+### Cline
+
+- Config: `~/Documents/Cline/Hooks/`
+- Events: PostToolUse, TaskComplete, TaskCancel
+- Install creates executable shell scripts in the hooks directory
+
+## Examples
+
+### Codex
+
+```bash
+selftune codex install              # Install hooks into ~/.codex/hooks.json
+selftune codex install --dry-run    # Preview changes without writing
+selftune codex install --uninstall  # Remove selftune hooks
+```
+
+### OpenCode
+
+```bash
+selftune opencode install              # Install plugin (selftune-opencode-plugin.ts) + config entries
+selftune opencode install --dry-run    # Preview changes without writing
+selftune opencode install --uninstall  # Remove selftune plugin and config entries
+```
+
+### Cline
+
+```bash
+selftune cline install              # Create hook scripts in ~/Documents/Cline/Hooks/
+selftune cline install --dry-run    # Preview what would be created
+selftune cline install --uninstall  # Remove selftune hook scripts
+```
+
+### Hook handler (agent-only, not user-facing)
+
+The hook subcommand is called automatically by the agent. Users do not run it directly:
+
+```bash
+printf '%s\n' "$PAYLOAD" | selftune codex hook
+printf '%s\n' "$PAYLOAD" | selftune opencode hook
+printf '%s\n' "$PAYLOAD" | selftune cline hook
+```