runwork 0.12.0 → 0.13.2

package/dist/agents/runtime-detection.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Runtime host-agent detection.
+ *
+ * Determines which AI agent the CLI was just invoked FROM (env vars,
+ * SessionStart hook info file, process tree). Used by `runwork share-convo`
+ * to locate the active conversation's native transcript file, and by
+ * `runwork resume` to bias the target agent toward "same as sender."
+ *
+ * This is distinct from install-time detection (./detection.ts), which
+ * answers "is agent X installed on this machine."
+ *
+ * Detection priority (highest to lowest fidelity):
+ *
+ *   1. SessionStart hook info file at ~/.runwork/sessions/<sessionId>.json,
+ *      keyed by the agent-provided session ID from env. Contains the
+ *      authoritative transcript_path plus rich metadata. Written by the
+ *      Runwork plugin's SessionStart hook script.
+ *
+ *   2. Env-var signals (CLAUDE_CODE_SESSION_ID, CODEX_THREAD_ID) plus a
+ *      filesystem walk to locate the JSONL/rollout for that session ID.
+ *
+ *   3. Heuristic env vars (CLAUDECODE=1, CODEX_CI=1) when we know we're
+ *      inside the agent but have no session ID. Falls back to mtime-newest
+ *      file in the agent's session directory.
+ *
+ *   4. None detected: caller may still proceed with `--source-agent` override
+ *      from the LLM (LLM passed `--native-file` and `--source-agent`).
+ */
+/** Slug values mirror packages/runwork-cli/src/agents/registry-data.ts AGENT_REGISTRY. */
+export type DetectedAgentSlug = 'claude-code' | 'claude-desktop' | 'codex' | 'codex-app' | 'gemini' | 'cursor' | 'windsurf' | 'cline';
+export interface RuntimeAgentDetection {
+    slug: DetectedAgentSlug;
+    sessionId: string | null;
+    /** Absolute path to the agent's native transcript file for this session, if known. */
+    sessionFilePath: string | null;
+    /** Source of the detection, useful for `runwork doctor --verbose` */
+    source: 'hook-info-file' | 'env-var' | 'heuristic';
+    /** Hook-info-file contents when source='hook-info-file' (richer metadata) */
+    hookInfo?: SessionHookInfo;
+}
+/**
+ * Shape of `~/.runwork/sessions/<sessionId>.json` files written by the
+ * SessionStart hook script.
+ */
+export interface SessionHookInfo {
+    writtenAt: string;
+    agent: DetectedAgentSlug;
+    sessionId: string;
+    transcriptPath?: string | null;
+    cwd?: string;
+    gitBranch?: string | null;
+    gitRemote?: string | null;
+    model?: string;
+    mcpServers?: string[];
+    plugins?: string[];
+    agentVersion?: string;
+    pid?: number;
+    originalPayload?: Record<string, unknown>;
+}
+/**
+ * Primary entrypoint. Returns the best-effort identification of the active
+ * host agent. `null` only if no signals at all are present.
+ */
+export declare function detectCurrentAgent(): RuntimeAgentDetection | null;
+/**
+ * Read the SessionStart hook's info file for a given session ID, if present.
+ * Returns null when the hook hasn't fired yet (first invocation in the session
+ * before the hook ran, or the user hasn't installed the hook).
+ */
+export declare function readHookSessionInfo(sessionId: string): SessionHookInfo | null;
+/**
+ * Walk ~/.claude/projects/*\/<sessionId>.jsonl for the matching file.
+ * Robust against the cwd-encoding rule changing or the recipient running from
+ * a different cwd than the sender.
+ */
+export declare function findClaudeCodeSessionFile(sessionId: string): string | null;
+/**
+ * Walk ~/.codex/sessions/YYYY/MM/DD/rollout-*-<UUID>.jsonl for the file
+ * matching this thread/session ID. The codex CLI itself does this scan,
+ * so dropping the file anywhere in the tree works for resume too.
+ */
+export declare function findCodexRolloutFile(threadId: string): string | null;

package/dist/agents/runtime-detection.js

@@ -0,0 +1,271 @@
+/**
+ * Runtime host-agent detection.
+ *
+ * Determines which AI agent the CLI was just invoked FROM (env vars,
+ * SessionStart hook info file, process tree). Used by `runwork share-convo`
+ * to locate the active conversation's native transcript file, and by
+ * `runwork resume` to bias the target agent toward "same as sender."
+ *
+ * This is distinct from install-time detection (./detection.ts), which
+ * answers "is agent X installed on this machine."
+ *
+ * Detection priority (highest to lowest fidelity):
+ *
+ *   1. SessionStart hook info file at ~/.runwork/sessions/<sessionId>.json,
+ *      keyed by the agent-provided session ID from env. Contains the
+ *      authoritative transcript_path plus rich metadata. Written by the
+ *      Runwork plugin's SessionStart hook script.
+ *
+ *   2. Env-var signals (CLAUDE_CODE_SESSION_ID, CODEX_THREAD_ID) plus a
+ *      filesystem walk to locate the JSONL/rollout for that session ID.
+ *
+ *   3. Heuristic env vars (CLAUDECODE=1, CODEX_CI=1) when we know we're
+ *      inside the agent but have no session ID. Falls back to mtime-newest
+ *      file in the agent's session directory.
+ *
+ *   4. None detected: caller may still proceed with `--source-agent` override
+ *      from the LLM (LLM passed `--native-file` and `--source-agent`).
+ */
+import { existsSync, readFileSync, statSync, readdirSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+const RUNWORK_SESSIONS_DIR = join(homedir(), '.runwork', 'sessions');
+/**
+ * Primary entrypoint. Returns the best-effort identification of the active
+ * host agent. `null` only if no signals at all are present.
+ */
+export function detectCurrentAgent() {
+    // 1. Env-var-based session IDs (highest signal): use them to look up the
+    //    hook info file first, then fall back to env+filesystem walk.
+    const claudeCodeSessionId = process.env.CLAUDE_CODE_SESSION_ID;
+    if (claudeCodeSessionId) {
+        const hookInfo = readHookSessionInfo(claudeCodeSessionId);
+        if (hookInfo) {
+            return {
+                slug: hookInfo.agent,
+                sessionId: claudeCodeSessionId,
+                sessionFilePath: hookInfo.transcriptPath ?? null,
+                source: 'hook-info-file',
+                hookInfo,
+            };
+        }
+        const filePath = findClaudeCodeSessionFile(claudeCodeSessionId);
+        return {
+            slug: 'claude-code',
+            sessionId: claudeCodeSessionId,
+            sessionFilePath: filePath,
+            source: 'env-var',
+        };
+    }
+    const codexThreadId = process.env.CODEX_THREAD_ID;
+    if (codexThreadId) {
+        const hookInfo = readHookSessionInfo(codexThreadId);
+        if (hookInfo) {
+            return {
+                slug: hookInfo.agent,
+                sessionId: codexThreadId,
+                sessionFilePath: hookInfo.transcriptPath ?? null,
+                source: 'hook-info-file',
+                hookInfo,
+            };
+        }
+        const filePath = findCodexRolloutFile(codexThreadId);
+        return {
+            slug: 'codex',
+            sessionId: codexThreadId,
+            sessionFilePath: filePath,
+            source: 'env-var',
+        };
+    }
+    // 2. Heuristic env vars - we know we're inside the agent but session ID
+    //    was not exposed. mtime-newest fallback.
+    if (process.env.CLAUDECODE === '1' || process.env.CLAUDECODE === 'true') {
+        const newest = findNewestClaudeCodeSession();
+        return {
+            slug: 'claude-code',
+            sessionId: newest?.sessionId ?? null,
+            sessionFilePath: newest?.path ?? null,
+            source: 'heuristic',
+        };
+    }
+    if (process.env.CODEX_CI === '1') {
+        const newest = findNewestCodexRollout();
+        return {
+            slug: 'codex',
+            sessionId: newest?.sessionId ?? null,
+            sessionFilePath: newest?.path ?? null,
+            source: 'heuristic',
+        };
+    }
+    return null;
+}
+/**
+ * Read the SessionStart hook's info file for a given session ID, if present.
+ * Returns null when the hook hasn't fired yet (first invocation in the session
+ * before the hook ran, or the user hasn't installed the hook).
+ */
+export function readHookSessionInfo(sessionId) {
+    const path = join(RUNWORK_SESSIONS_DIR, `${sessionId}.json`);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Walk ~/.claude/projects/*\/<sessionId>.jsonl for the matching file.
+ * Robust against the cwd-encoding rule changing or the recipient running from
+ * a different cwd than the sender.
+ */
+export function findClaudeCodeSessionFile(sessionId) {
+    const root = join(homedir(), '.claude', 'projects');
+    if (!existsSync(root))
+        return null;
+    let projectDirs;
+    try {
+        projectDirs = readdirSync(root);
+    }
+    catch {
+        return null;
+    }
+    for (const dir of projectDirs) {
+        const candidate = join(root, dir, `${sessionId}.jsonl`);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Walk ~/.codex/sessions/YYYY/MM/DD/rollout-*-<UUID>.jsonl for the file
+ * matching this thread/session ID. The codex CLI itself does this scan,
+ * so dropping the file anywhere in the tree works for resume too.
+ */
+export function findCodexRolloutFile(threadId) {
+    const root = join(homedir(), '.codex', 'sessions');
+    if (!existsSync(root))
+        return null;
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const full = join(dir, entry);
+            let s;
+            try {
+                s = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (s.isDirectory()) {
+                stack.push(full);
+            }
+            else if (s.isFile() && entry.includes(threadId) && entry.endsWith('.jsonl')) {
+                return full;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Fallback when no session ID env var is set: scan all project folders for
+ * the most recently modified .jsonl. Fragile with multiple concurrent
+ * Claude Code windows; documented as a known limitation.
+ */
+function findNewestClaudeCodeSession() {
+    const root = join(homedir(), '.claude', 'projects');
+    if (!existsSync(root))
+        return null;
+    let projectDirs;
+    try {
+        projectDirs = readdirSync(root);
+    }
+    catch {
+        return null;
+    }
+    let best = null;
+    for (const dir of projectDirs) {
+        const projectPath = join(root, dir);
+        let files;
+        try {
+            files = readdirSync(projectPath);
+        }
+        catch {
+            continue;
+        }
+        for (const file of files) {
+            if (!file.endsWith('.jsonl'))
+                continue;
+            const full = join(projectPath, file);
+            try {
+                const s = statSync(full);
+                if (!best || s.mtimeMs > best.mtime) {
+                    best = {
+                        sessionId: file.replace(/\.jsonl$/, ''),
+                        path: full,
+                        mtime: s.mtimeMs,
+                    };
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return best ? { sessionId: best.sessionId, path: best.path } : null;
+}
+function findNewestCodexRollout() {
+    const root = join(homedir(), '.codex', 'sessions');
+    if (!existsSync(root))
+        return null;
+    const stack = [root];
+    let best = null;
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const full = join(dir, entry);
+            let s;
+            try {
+                s = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (s.isDirectory()) {
+                stack.push(full);
+            }
+            else if (s.isFile() && entry.startsWith('rollout-') && entry.endsWith('.jsonl')) {
+                // Extract UUID from filename: rollout-YYYY-MM-DDThh-mm-ss-<uuid>.jsonl
+                const match = entry.match(/rollout-[\d-T:]+-([0-9a-f-]{36})\.jsonl$/);
+                if (!match)
+                    continue;
+                if (!best || s.mtimeMs > best.mtime) {
+                    best = {
+                        sessionId: match[1],
+                        path: full,
+                        mtime: s.mtimeMs,
+                    };
+                }
+            }
+        }
+    }
+    return best ? { sessionId: best.sessionId, path: best.path } : null;
+}

package/dist/agents/session-start-hook.d.ts

@@ -0,0 +1,37 @@
+/**
+ * SessionStart hook script for Claude Code (and any other agent that
+ * follows the same hook contract: stdin JSON with session_id and
+ * transcript_path).
+ *
+ * SAFETY CONTRACT - this hook MUST NEVER break the user's session.
+ *
+ * Failure modes a hook can cause in Claude Code:
+ *   - Non-zero exit -> Claude may surface an error or refuse to start
+ *   - Stdout contamination -> Claude may interpret it as a hook response
+ *   - Hanging -> Blocks the session indefinitely
+ *   - Stderr noise -> Pollutes the user's terminal
+ *
+ * Mitigations applied:
+ *   - No `set -e`. Every operation is fault-tolerant with || true.
+ *   - All stdout/stderr from internal operations are redirected to /dev/null.
+ *   - A hard wall-clock timeout via a backgrounded watchdog that SIGKILLs the
+ *     hook if it runs longer than 5 seconds.
+ *   - Wrapped in a "{...} </dev/null/stdin; echo nothing" pattern so failures
+ *     never propagate to Claude.
+ *   - Always exits 0, regardless of any internal failure.
+ *
+ * The hook does best-effort logging to a side-channel file
+ * (~/.runwork/sessions-hook-debug.log, last 50 entries) so we can debug
+ * issues without ever talking to Claude's stdio.
+ *
+ * Installed into the user's Claude Code plugin tree by sync. When Claude
+ * Code starts a new session, this script runs once and writes
+ * `~/.runwork/sessions/<sessionId>.json` with rich session metadata. The
+ * runwork CLI's runtime-detection module reads from that location.
+ *
+ * Hook installation locations:
+ *   - Claude Code (sync): ~/.claude/plugins/cache/runwork/<plugin>/<v>/hooks/
+ *                          + marketplace mirror
+ *   - Claude Desktop (Cowork): inside the runwork-plugin.zip the user uploads
+ */
+export declare const SESSION_START_HOOK_SCRIPT = "#!/usr/bin/env bash\n# Runwork SessionStart hook - SAFETY-FIRST design.\n#\n# Writes ~/.runwork/sessions/<sessionId>.json with rich session metadata.\n# Generated by the runwork CLI on sync; do not edit by hand.\n#\n# Hard guarantees:\n#   - Exits 0 no matter what.\n#   - Never writes to Claude's stdout (would corrupt the hook response).\n#   - Never hangs (5-second wall-clock kill via watchdog).\n#   - Never errors out into Claude's stderr.\n\n# Read full payload from stdin BEFORE we redirect anything; this is the one\n# thing we can't lose.\nPAYLOAD=\"\"\nif [ ! -t 0 ]; then\n  PAYLOAD=$(cat 2>/dev/null || true)\nfi\n\n# Suppress every potential side-channel: redirect stdout/stderr to /dev/null\n# for the rest of execution. Claude reads the hook's stdout as a structured\n# response, so any accidental print would be interpreted as protocol data.\nexec 1>/dev/null 2>/dev/null\n\n# Watchdog: kill this hook after 5 seconds no matter what.\n( sleep 5 && kill -9 $$ 2>/dev/null ) &\nWATCHDOG_PID=$!\n# Ensure the watchdog is cleaned up if we exit normally.\ntrap \"kill -9 $WATCHDOG_PID 2>/dev/null; exit 0\" EXIT INT TERM\n\n# Everything below runs in a \"best-effort, never-fail\" mode. We capture\n# extras via subshells with /dev/null redirection and || true so nothing\n# can escape.\n{\n  RUNWORK_DIR=\"${HOME:-/tmp}/.runwork\"\n  SESSIONS_DIR=\"$RUNWORK_DIR/sessions\"\n  DEBUG_LOG=\"$RUNWORK_DIR/sessions-hook-debug.log\"\n\n  mkdir -p \"$SESSIONS_DIR\" 2>/dev/null || exit 0\n\n  # Bail silently if no payload.\n  if [ -z \"$PAYLOAD\" ]; then\n    exit 0\n  fi\n\n  # Parse session_id and transcript_path. Prefer jq when available.\n  SESSION_ID=\"\"\n  TRANSCRIPT_PATH=\"\"\n  CWD=\"\"\n\n  if command -v jq >/dev/null 2>&1; then\n    SESSION_ID=$(echo \"$PAYLOAD\" | jq -r '.session_id // .sessionId // empty' 2>/dev/null || true)\n    TRANSCRIPT_PATH=$(echo \"$PAYLOAD\" | jq -r '.transcript_path // .transcriptPath // empty' 2>/dev/null || true)\n    CWD=$(echo \"$PAYLOAD\" | jq -r '.cwd // empty' 2>/dev/null || true)\n  else\n    # Minimal grep+sed fallback - intentionally permissive about formatting.\n    SESSION_ID=$(echo \"$PAYLOAD\" | grep -oE '\"session_id\"[[:space:]]*:[[:space:]]*\"[^\"]+\"' 2>/dev/null | head -1 | sed -E 's/.*\"([^\"]+)\"$/\\1/' || true)\n    TRANSCRIPT_PATH=$(echo \"$PAYLOAD\" | grep -oE '\"transcript_path\"[[:space:]]*:[[:space:]]*\"[^\"]+\"' 2>/dev/null | head -1 | sed -E 's/.*\"([^\"]+)\"$/\\1/' || true)\n    CWD=$(echo \"$PAYLOAD\" | grep -oE '\"cwd\"[[:space:]]*:[[:space:]]*\"[^\"]+\"' 2>/dev/null | head -1 | sed -E 's/.*\"([^\"]+)\"$/\\1/' || true)\n  fi\n\n  # Without a session ID we have nothing useful to write.\n  if [ -z \"$SESSION_ID\" ]; then\n    exit 0\n  fi\n\n  # Sanity check sessionId looks like a safe filename component\n  # (alphanumeric, hyphens, underscores only). Anything weird -> bail.\n  case \"$SESSION_ID\" in\n    *[!a-zA-Z0-9_-]*) exit 0 ;;\n  esac\n\n  EFFECTIVE_CWD=\"${CWD:-${PWD:-/}}\"\n\n  GIT_BRANCH=\"\"\n  GIT_REMOTE=\"\"\n  if [ -n \"$EFFECTIVE_CWD\" ] && [ -d \"$EFFECTIVE_CWD\" ]; then\n    GIT_BRANCH=$(git -C \"$EFFECTIVE_CWD\" rev-parse --abbrev-ref HEAD 2>/dev/null || true)\n    GIT_REMOTE=$(git -C \"$EFFECTIVE_CWD\" config --get remote.origin.url 2>/dev/null | sed -E 's#.*[:/]([^/:]+/[^/]+)(\\.git)?$#\\1#' 2>/dev/null || true)\n  fi\n\n  AGENT_VERSION=$(claude --version 2>/dev/null | head -1 || true)\n\n  OUT_PATH=\"$SESSIONS_DIR/${SESSION_ID}.json\"\n  TMP_PATH=\"${OUT_PATH}.tmp.$$\"\n\n  # Build JSON safely; values that may contain quotes/backslashes are escaped\n  # via a tiny helper. We avoid heredoc + interpolation pitfalls.\n  json_escape() {\n    # Escape backslash and double-quote, strip newlines.\n    printf '%s' \"$1\" | sed -e 's/\\\\/\\\\\\\\/g' -e 's/\"/\\\\\"/g' | tr -d '\\n'\n  }\n\n  TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || true)\n\n  {\n    printf '{\\n'\n    printf '  \"writtenAt\": \"%s\",\\n' \"$(json_escape \"$TIMESTAMP\")\"\n    printf '  \"agent\": \"claude-code\",\\n'\n    printf '  \"sessionId\": \"%s\",\\n' \"$(json_escape \"$SESSION_ID\")\"\n    printf '  \"transcriptPath\": \"%s\",\\n' \"$(json_escape \"$TRANSCRIPT_PATH\")\"\n    printf '  \"cwd\": \"%s\",\\n' \"$(json_escape \"$EFFECTIVE_CWD\")\"\n    printf '  \"gitBranch\": \"%s\",\\n' \"$(json_escape \"$GIT_BRANCH\")\"\n    printf '  \"gitRemote\": \"%s\",\\n' \"$(json_escape \"$GIT_REMOTE\")\"\n    printf '  \"agentVersion\": \"%s\",\\n' \"$(json_escape \"$AGENT_VERSION\")\"\n    printf '  \"pid\": %d\\n' \"$$\"\n    printf '}\\n'\n  } > \"$TMP_PATH\" 2>/dev/null || exit 0\n\n  mv \"$TMP_PATH\" \"$OUT_PATH\" 2>/dev/null || true\n\n  # Best-effort debug log (rotated to last 50 lines).\n  {\n    echo \"$(date -u +%Y-%m-%dT%H:%M:%SZ) wrote $OUT_PATH\"\n    if [ -f \"$DEBUG_LOG\" ]; then\n      tail -49 \"$DEBUG_LOG\" 2>/dev/null || true\n    fi\n  } > \"${DEBUG_LOG}.tmp\" 2>/dev/null && mv \"${DEBUG_LOG}.tmp\" \"$DEBUG_LOG\" 2>/dev/null || true\n} 2>/dev/null || true\n\n# Hard guarantee.\nexit 0\n";

package/dist/agents/session-start-hook.js

@@ -0,0 +1,159 @@
+/**
+ * SessionStart hook script for Claude Code (and any other agent that
+ * follows the same hook contract: stdin JSON with session_id and
+ * transcript_path).
+ *
+ * SAFETY CONTRACT - this hook MUST NEVER break the user's session.
+ *
+ * Failure modes a hook can cause in Claude Code:
+ *   - Non-zero exit -> Claude may surface an error or refuse to start
+ *   - Stdout contamination -> Claude may interpret it as a hook response
+ *   - Hanging -> Blocks the session indefinitely
+ *   - Stderr noise -> Pollutes the user's terminal
+ *
+ * Mitigations applied:
+ *   - No `set -e`. Every operation is fault-tolerant with || true.
+ *   - All stdout/stderr from internal operations are redirected to /dev/null.
+ *   - A hard wall-clock timeout via a backgrounded watchdog that SIGKILLs the
+ *     hook if it runs longer than 5 seconds.
+ *   - Wrapped in a "{...} </dev/null/stdin; echo nothing" pattern so failures
+ *     never propagate to Claude.
+ *   - Always exits 0, regardless of any internal failure.
+ *
+ * The hook does best-effort logging to a side-channel file
+ * (~/.runwork/sessions-hook-debug.log, last 50 entries) so we can debug
+ * issues without ever talking to Claude's stdio.
+ *
+ * Installed into the user's Claude Code plugin tree by sync. When Claude
+ * Code starts a new session, this script runs once and writes
+ * `~/.runwork/sessions/<sessionId>.json` with rich session metadata. The
+ * runwork CLI's runtime-detection module reads from that location.
+ *
+ * Hook installation locations:
+ *   - Claude Code (sync): ~/.claude/plugins/cache/runwork/<plugin>/<v>/hooks/
+ *                          + marketplace mirror
+ *   - Claude Desktop (Cowork): inside the runwork-plugin.zip the user uploads
+ */
+export const SESSION_START_HOOK_SCRIPT = `#!/usr/bin/env bash
+# Runwork SessionStart hook - SAFETY-FIRST design.
+#
+# Writes ~/.runwork/sessions/<sessionId>.json with rich session metadata.
+# Generated by the runwork CLI on sync; do not edit by hand.
+#
+# Hard guarantees:
+#   - Exits 0 no matter what.
+#   - Never writes to Claude's stdout (would corrupt the hook response).
+#   - Never hangs (5-second wall-clock kill via watchdog).
+#   - Never errors out into Claude's stderr.
+
+# Read full payload from stdin BEFORE we redirect anything; this is the one
+# thing we can't lose.
+PAYLOAD=""
+if [ ! -t 0 ]; then
+  PAYLOAD=$(cat 2>/dev/null || true)
+fi
+
+# Suppress every potential side-channel: redirect stdout/stderr to /dev/null
+# for the rest of execution. Claude reads the hook's stdout as a structured
+# response, so any accidental print would be interpreted as protocol data.
+exec 1>/dev/null 2>/dev/null
+
+# Watchdog: kill this hook after 5 seconds no matter what.
+( sleep 5 && kill -9 $$ 2>/dev/null ) &
+WATCHDOG_PID=$!
+# Ensure the watchdog is cleaned up if we exit normally.
+trap "kill -9 $WATCHDOG_PID 2>/dev/null; exit 0" EXIT INT TERM
+
+# Everything below runs in a "best-effort, never-fail" mode. We capture
+# extras via subshells with /dev/null redirection and || true so nothing
+# can escape.
+{
+  RUNWORK_DIR="\${HOME:-/tmp}/.runwork"
+  SESSIONS_DIR="$RUNWORK_DIR/sessions"
+  DEBUG_LOG="$RUNWORK_DIR/sessions-hook-debug.log"
+
+  mkdir -p "$SESSIONS_DIR" 2>/dev/null || exit 0
+
+  # Bail silently if no payload.
+  if [ -z "$PAYLOAD" ]; then
+    exit 0
+  fi
+
+  # Parse session_id and transcript_path. Prefer jq when available.
+  SESSION_ID=""
+  TRANSCRIPT_PATH=""
+  CWD=""
+
+  if command -v jq >/dev/null 2>&1; then
+    SESSION_ID=$(echo "$PAYLOAD" | jq -r '.session_id // .sessionId // empty' 2>/dev/null || true)
+    TRANSCRIPT_PATH=$(echo "$PAYLOAD" | jq -r '.transcript_path // .transcriptPath // empty' 2>/dev/null || true)
+    CWD=$(echo "$PAYLOAD" | jq -r '.cwd // empty' 2>/dev/null || true)
+  else
+    # Minimal grep+sed fallback - intentionally permissive about formatting.
+    SESSION_ID=$(echo "$PAYLOAD" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[^"]+"' 2>/dev/null | head -1 | sed -E 's/.*"([^"]+)"$/\\1/' || true)
+    TRANSCRIPT_PATH=$(echo "$PAYLOAD" | grep -oE '"transcript_path"[[:space:]]*:[[:space:]]*"[^"]+"' 2>/dev/null | head -1 | sed -E 's/.*"([^"]+)"$/\\1/' || true)
+    CWD=$(echo "$PAYLOAD" | grep -oE '"cwd"[[:space:]]*:[[:space:]]*"[^"]+"' 2>/dev/null | head -1 | sed -E 's/.*"([^"]+)"$/\\1/' || true)
+  fi
+
+  # Without a session ID we have nothing useful to write.
+  if [ -z "$SESSION_ID" ]; then
+    exit 0
+  fi
+
+  # Sanity check sessionId looks like a safe filename component
+  # (alphanumeric, hyphens, underscores only). Anything weird -> bail.
+  case "$SESSION_ID" in
+    *[!a-zA-Z0-9_-]*) exit 0 ;;
+  esac
+
+  EFFECTIVE_CWD="\${CWD:-\${PWD:-/}}"
+
+  GIT_BRANCH=""
+  GIT_REMOTE=""
+  if [ -n "$EFFECTIVE_CWD" ] && [ -d "$EFFECTIVE_CWD" ]; then
+    GIT_BRANCH=$(git -C "$EFFECTIVE_CWD" rev-parse --abbrev-ref HEAD 2>/dev/null || true)
+    GIT_REMOTE=$(git -C "$EFFECTIVE_CWD" config --get remote.origin.url 2>/dev/null | sed -E 's#.*[:/]([^/:]+/[^/]+)(\\.git)?$#\\1#' 2>/dev/null || true)
+  fi
+
+  AGENT_VERSION=$(claude --version 2>/dev/null | head -1 || true)
+
+  OUT_PATH="$SESSIONS_DIR/\${SESSION_ID}.json"
+  TMP_PATH="\${OUT_PATH}.tmp.$$"
+
+  # Build JSON safely; values that may contain quotes/backslashes are escaped
+  # via a tiny helper. We avoid heredoc + interpolation pitfalls.
+  json_escape() {
+    # Escape backslash and double-quote, strip newlines.
+    printf '%s' "$1" | sed -e 's/\\\\/\\\\\\\\/g' -e 's/"/\\\\"/g' | tr -d '\\n'
+  }
+
+  TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || true)
+
+  {
+    printf '{\\n'
+    printf '  "writtenAt": "%s",\\n' "$(json_escape "$TIMESTAMP")"
+    printf '  "agent": "claude-code",\\n'
+    printf '  "sessionId": "%s",\\n' "$(json_escape "$SESSION_ID")"
+    printf '  "transcriptPath": "%s",\\n' "$(json_escape "$TRANSCRIPT_PATH")"
+    printf '  "cwd": "%s",\\n' "$(json_escape "$EFFECTIVE_CWD")"
+    printf '  "gitBranch": "%s",\\n' "$(json_escape "$GIT_BRANCH")"
+    printf '  "gitRemote": "%s",\\n' "$(json_escape "$GIT_REMOTE")"
+    printf '  "agentVersion": "%s",\\n' "$(json_escape "$AGENT_VERSION")"
+    printf '  "pid": %d\\n' "$$"
+    printf '}\\n'
+  } > "$TMP_PATH" 2>/dev/null || exit 0
+
+  mv "$TMP_PATH" "$OUT_PATH" 2>/dev/null || true
+
+  # Best-effort debug log (rotated to last 50 lines).
+  {
+    echo "$(date -u +%Y-%m-%dT%H:%M:%SZ) wrote $OUT_PATH"
+    if [ -f "$DEBUG_LOG" ]; then
+      tail -49 "$DEBUG_LOG" 2>/dev/null || true
+    fi
+  } > "\${DEBUG_LOG}.tmp" 2>/dev/null && mv "\${DEBUG_LOG}.tmp" "$DEBUG_LOG" 2>/dev/null || true
+} 2>/dev/null || true
+
+# Hard guarantee.
+exit 0
+`;

package/dist/agents/types.d.ts

@@ -33,6 +33,18 @@ export interface AgentAdapter {
     mcpProvidesSkills?: boolean;
     /** Write team-managed instructions (separate marker block from auto-generated hint) */
     writeTeamInstructions?(instructions: string, scope: 'project' | 'user'): Promise<void>;
+    /**
+     * Install the runwork SessionStart hook (or any equivalent platform-managed
+     * hook) into the agent's hook directory. Called once per (adapter, scope) by
+     * the main sync loop, AFTER writeSkills has fully populated the plugin tree.
+     * Separate from writeSkills because writeSkills is also invoked per-skill by
+     * the diff executor during push/pull, and hook installation must not be
+     * repeated for every skill.
+     *
+     * Optional - only adapters with a hook system implement it (Claude Code,
+     * eventually Claude Desktop Cowork plugin tree).
+     */
+    writeBuiltInHooks?(scope: 'project' | 'user'): Promise<void>;
     /**
      * Write agent-specific config overrides from workspace admin (model, permissions).
      *

package/dist/api/client.d.ts

@@ -266,6 +266,53 @@ export declare class ApiClient {
         metadata?: Record<string, unknown>;
         timestamp: string;
     }>): Promise<void>;
+    createSharedConversation(workspaceId: string, body: {
+        recipients?: string[];
+        isPersonal?: boolean;
+        sourceAgent: string;
+        title: string;
+        note?: string;
+        bundles: Array<{
+            format: string;
+            content: string;
+            sizeBytes: number;
+            sha256: string;
+        }>;
+        metadata?: Record<string, unknown>;
+        ttlDays?: number;
+    }): Promise<{
+        share: {
+            id: string;
+            title: string;
+            expiresAt: string;
+        };
+        sharedCount: number;
+        invitedCount: number;
+        skipped: Array<{
+            identifier: string;
+            reason: string;
+        }>;
+    }>;
+    listSharedConversations(workspaceId: string, opts?: {
+        scope?: 'all' | 'received' | 'sent' | 'saved';
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        shares: Array<Record<string, unknown>>;
+        total: number;
+    }>;
+    getSharedConversation(workspaceId: string, shareId: string): Promise<{
+        share: Record<string, unknown>;
+    }>;
+    downloadSharedConversationBundle(workspaceId: string, shareId: string, format: string): Promise<{
+        format: string;
+        content: string;
+        sizeBytes: number;
+        sha256: string;
+    }>;
+    markSharedConversationResumed(workspaceId: string, shareId: string): Promise<{
+        success: boolean;
+    }>;
     callIntegrationProxy(integrationDbId: string, method: string, path: string, opts?: {
         body?: unknown;
         headers?: Record<string, string>;

package/dist/api/client.js

@@ -355,6 +355,38 @@ export class ApiClient {
     async reportTelemetry(workspaceId, events) {
         await this.request(`/api/workspaces/${workspaceId}/team/telemetry`, { method: 'POST', body: JSON.stringify({ events }) });
     }
+    // --- Shared Conversations ---
+    async createSharedConversation(workspaceId, body) {
+        const res = await this.request(`/api/workspaces/${workspaceId}/shared-conversations`, {
+            method: 'POST',
+            body: JSON.stringify(body),
+        });
+        return res.data;
+    }
+    async listSharedConversations(workspaceId, opts) {
+        const search = new URLSearchParams();
+        if (opts?.scope)
+            search.set('scope', opts.scope);
+        if (opts?.limit !== undefined)
+            search.set('limit', String(opts.limit));
+        if (opts?.offset !== undefined)
+            search.set('offset', String(opts.offset));
+        const query = search.toString() ? `?${search.toString()}` : '';
+        const res = await this.request(`/api/workspaces/${workspaceId}/shared-conversations${query}`);
+        return res.data;
+    }
+    async getSharedConversation(workspaceId, shareId) {
+        const res = await this.request(`/api/workspaces/${workspaceId}/shared-conversations/${shareId}`);
+        return res.data;
+    }
+    async downloadSharedConversationBundle(workspaceId, shareId, format) {
+        const res = await this.request(`/api/workspaces/${workspaceId}/shared-conversations/${shareId}/bundle/${encodeURIComponent(format)}`);
+        return res.data;
+    }
+    async markSharedConversationResumed(workspaceId, shareId) {
+        const res = await this.request(`/api/workspaces/${workspaceId}/shared-conversations/${shareId}/resumed`, { method: 'POST' });
+        return res.data;
+    }
     // --- Integrations: Proxy Call ---
     async callIntegrationProxy(integrationDbId, method, path, opts) {
         const targetPath = opts?.query ? `${path}?${opts.query}` : path;