claude-code-swarm 0.3.11 → 0.3.12

package/.claude-plugin/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "description": "Launch Claude Code with swarmkit capabilities, including team orchestration, MAP observability, and session tracking.",
   "owner": {
     "name": "alexngai"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-code-swarm",
   "description": "Spin up Claude Code agent teams from openteams YAML topologies with optional MAP (Multi-Agent Protocol) observability and coordination. Provides hooks for session lifecycle, agent spawn/complete tracking, and a /swarm skill to launch team configurations.",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "author": {
     "name": "alexngai"
   },
@@ -12,9 +12,7 @@
         "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/mcp-launcher.mjs",
         "opentasks"
       ],
-      "env": {
-        "OPENTASKS_WORKING_DIR": "${workspaceFolder}"
-      }
+      "env": {}
     },
     "agent-inbox": {
       "command": "node",
@@ -30,9 +28,7 @@
         "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/mcp-launcher.mjs",
         "minimem"
       ],
-      "env": {
-        "MINIMEM_WORKING_DIR": "${workspaceFolder}"
-      }
+      "env": {}
     }
   }
 }

package/hooks/hooks.json

@@ -7,6 +7,21 @@
           {
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs\""
+          },
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch session-start; fi"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch session-end; fi"
           }
         ]
       }
@@ -18,6 +33,21 @@
           {
             "type": "command",
             "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8')).map||{};process.exit(c.enabled||c.server||process.env.SWARM_MAP_SERVER||process.env.SWARM_MAP_ENABLED?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" inject; fi"
+          },
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch user-prompt-submit; fi"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch pre-task; fi"
           }
         ]
       }
@@ -32,12 +62,25 @@
           }
         ]
       },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch post-task; fi"
+          }
+        ]
+      },
       {
         "matcher": "TaskCreate",
         "hooks": [
           {
             "type": "command",
             "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8')).map||{};process.exit(c.enabled||c.server||process.env.SWARM_MAP_SERVER||process.env.SWARM_MAP_ENABLED?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" native-task-created; fi"
+          },
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch post-task-create; fi"
           }
         ]
       },
@@ -47,6 +90,46 @@
           {
             "type": "command",
             "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8')).map||{};process.exit(c.enabled||c.server||process.env.SWARM_MAP_SERVER||process.env.SWARM_MAP_ENABLED?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" native-task-updated; fi"
+          },
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch post-task-update; fi"
+          }
+        ]
+      },
+      {
+        "matcher": "TodoWrite",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch post-todo; fi"
+          }
+        ]
+      },
+      {
+        "matcher": "EnterPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch post-plan-enter; fi"
+          }
+        ]
+      },
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch post-plan-exit; fi"
+          }
+        ]
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch post-skill; fi"
           }
         ]
       }
@@ -62,6 +145,10 @@
           {
             "type": "command",
             "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));const m=c.map||{};process.exit((m.enabled||m.server||process.env.SWARM_MAP_SERVER||process.env.SWARM_MAP_ENABLED)&&c.sessionlog?.sync&&c.sessionlog.sync!=='off'?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-sync; fi"
+          },
+          {
+            "type": "command",
+            "command": "if [ -f .swarm/claude-swarm/config.json ] && node -e \"const c=JSON.parse(require('fs').readFileSync('.swarm/claude-swarm/config.json','utf-8'));process.exit(c.sessionlog?.enabled?0:1)\" 2>/dev/null; then node \"${CLAUDE_PLUGIN_ROOT}/scripts/map-hook.mjs\" sessionlog-dispatch stop; fi"
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-swarm",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "description": "Claude Code plugin for launching agent teams from openteams topologies with MAP observability",
   "type": "module",
   "exports": {

package/scripts/map-hook.mjs

@@ -19,6 +19,7 @@
  *   teammate-idle       — Update teammate state to idle
  *   task-completed      — Complete task in opentasks + emit bridge event
  *   opentasks-mcp-used  — Bridge opentasks MCP tool use → MAP task sync payload
+ *   sessionlog-dispatch — Dispatch a sessionlog lifecycle hook via programmatic API
  *
  * Usage: node map-hook.mjs <action>
  *        Hook event data is read from stdin (JSON).
@@ -48,7 +49,7 @@ import {
   handleNativeTaskCreatedEvent,
   handleNativeTaskUpdatedEvent,
 } from "../src/map-events.mjs";
-import { syncSessionlog } from "../src/sessionlog.mjs";
+import { syncSessionlog, dispatchSessionlogHook } from "../src/sessionlog.mjs";
 import { findSocketPath, pushSyncEvent } from "../src/opentasks-client.mjs";
 
 const action = process.argv[2];
@@ -184,6 +185,15 @@ async function handleNativeTaskUpdated(hookData, sessionId) {
   await handleNativeTaskUpdatedEvent(config, hookData, sessionId);
 }
 
+async function handleSessionlogDispatch(hookData) {
+  const sessionlogHookName = process.argv[3];
+  if (!sessionlogHookName) {
+    log.warn("sessionlog-dispatch: missing hook name argument");
+    return;
+  }
+  await dispatchSessionlogHook(sessionlogHookName, hookData);
+}
+
 // ── Main ──────────────────────────────────────────────────────────────────────
 
 async function main() {
@@ -204,6 +214,7 @@ async function main() {
       case "opentasks-mcp-used": await handleOpentasksMcpUsed(hookData, sessionId); break;
       case "native-task-created": await handleNativeTaskCreated(hookData, sessionId); break;
       case "native-task-updated": await handleNativeTaskUpdated(hookData, sessionId); break;
+      case "sessionlog-dispatch": await handleSessionlogDispatch(hookData); break;
       default:
         log.warn("unknown action", { action });
     }

package/src/__tests__/bootstrap.test.mjs

@@ -22,6 +22,8 @@ vi.mock("../map-events.mjs", () => ({
 
 vi.mock("../sessionlog.mjs", () => ({
   checkSessionlogStatus: vi.fn(() => "not installed"),
+  ensureSessionlogEnabled: vi.fn().mockResolvedValue(false),
+  hasStandaloneHooks: vi.fn().mockReturnValue(false),
   syncSessionlog: vi.fn().mockResolvedValue(undefined),
   annotateSwarmSession: vi.fn().mockResolvedValue(undefined),
 }));
@@ -86,7 +88,7 @@ const { bootstrap, backgroundInit } = await import("../bootstrap.mjs");
 const { readConfig } = await import("../config.mjs");
 const { killSidecar, startSidecar } = await import("../sidecar-client.mjs");
 const { sendCommand } = await import("../map-events.mjs");
-const { checkSessionlogStatus, syncSessionlog, annotateSwarmSession } = await import("../sessionlog.mjs");
+const { checkSessionlogStatus, ensureSessionlogEnabled, hasStandaloneHooks, syncSessionlog, annotateSwarmSession } = await import("../sessionlog.mjs");
 const { pluginDir, ensureOpentasksDir, ensureSessionDir, listSessionDirs } = await import("../paths.mjs");
 const { findSocketPath, isDaemonAlive, ensureDaemon } = await import("../opentasks-client.mjs");
 const { resolveSwarmkit, configureNodePath } = await import("../swarmkit-resolver.mjs");
@@ -161,16 +163,43 @@ describe("bootstrap", () => {
     });
 
     describe("sessionlog", () => {
-      it("returns 'checking' when sessionlog enabled (actual check is in background)", async () => {
+      it("defers to standalone when standalone hooks are present", async () => {
+        hasStandaloneHooks.mockReturnValue(true);
         readConfig.mockReturnValue(makeConfig({ sessionlogEnabled: true }));
         const result = await bootstrap();
-        expect(result.sessionlogStatus).toBe("checking");
+        expect(result.sessionlogStatus).toBe("active (standalone)");
+        expect(ensureSessionlogEnabled).not.toHaveBeenCalled();
       });
 
-      it("does not call checkSessionlogStatus synchronously", async () => {
+      it("enables sessionlog when no standalone hooks", async () => {
+        hasStandaloneHooks.mockReturnValue(false);
+        ensureSessionlogEnabled.mockResolvedValue(true);
         readConfig.mockReturnValue(makeConfig({ sessionlogEnabled: true }));
+        const result = await bootstrap();
+        expect(result.sessionlogStatus).toBe("active");
+        expect(ensureSessionlogEnabled).toHaveBeenCalled();
+      });
+
+      it("reports status when enable fails", async () => {
+        hasStandaloneHooks.mockReturnValue(false);
+        ensureSessionlogEnabled.mockResolvedValue(false);
+        readConfig.mockReturnValue(makeConfig({ sessionlogEnabled: true }));
+        const result = await bootstrap();
+        expect(result.sessionlogStatus).toBe("installed but not enabled");
+      });
+
+      it("returns 'checking' when hasStandaloneHooks throws", async () => {
+        hasStandaloneHooks.mockImplementation(() => { throw new Error("unexpected"); });
+        readConfig.mockReturnValue(makeConfig({ sessionlogEnabled: true }));
+        const result = await bootstrap();
+        expect(result.sessionlogStatus).toBe("checking");
+      });
+
+      it("does not check standalone when disabled", async () => {
+        readConfig.mockReturnValue(makeConfig({ sessionlogEnabled: false }));
         await bootstrap();
-        expect(checkSessionlogStatus).not.toHaveBeenCalled();
+        expect(hasStandaloneHooks).not.toHaveBeenCalled();
+        expect(ensureSessionlogEnabled).not.toHaveBeenCalled();
       });
     });
 

package/src/__tests__/helpers.mjs

@@ -32,6 +32,7 @@ export function makeConfig(overrides = {}) {
     sessionlog: {
       enabled: overrides.sessionlogEnabled ?? false,
       sync: overrides.sessionlogSync ?? "off",
+      mode: overrides.sessionlogMode ?? "auto",
     },
     opentasks: {
       enabled: overrides.opentasksEnabled ?? false,

package/src/__tests__/sessionlog-e2e.test.mjs

@@ -0,0 +1,270 @@
+/**
+ * E2E test: sessionlog lifecycle dispatch through cc-swarm plugin flow.
+ *
+ * Creates a real temp git repo with real config files, enables sessionlog,
+ * then dispatches lifecycle events via dispatchSessionlogHook() and verifies
+ * session state files on disk.
+ *
+ * Mocked:
+ *   - resolvePackage("sessionlog") — returns the real sessionlog module from
+ *     references/ (in production this resolves from global node_modules)
+ *   - paths.mjs GLOBAL_CONFIG_PATH — points to tmp dir to avoid reading
+ *     the user's real ~/.claude-swarm/config.json
+ *   - process.cwd() — points to tmp git repo
+ *
+ * Real:
+ *   - Git repo (git init + commit in tmp dir)
+ *   - sessionlog enable() — creates .sessionlog/, .git/sessionlog-sessions/, git hooks
+ *   - .swarm/claude-swarm/config.json — written to tmp dir, read by real readConfig()
+ *   - readConfig() — real config resolution (reads from tmp dir)
+ *   - hasStandaloneHooks() — real file read of .claude/settings.json
+ *   - dispatchSessionlogHook() — real dispatch through sessionlog lifecycle handler
+ *   - Session state files — real files at .git/sessionlog-sessions/<id>.json
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { execSync } from "child_process";
+
+// Resolve the real sessionlog module from the monorepo references dir
+const SESSIONLOG_PATH = path.resolve(
+  import.meta.dirname, "..", "..", "..", "sessionlog"
+);
+
+let _tmpDir;
+let _sessionlogMod;
+
+// Mock resolvePackage — the only mock needed for the core dispatch.
+// In production, sessionlog is resolved from global node_modules via swarmkit.
+// Here we return the real module from references/.
+vi.mock("../swarmkit-resolver.mjs", () => ({
+  resolvePackage: vi.fn(async (name) => {
+    if (name === "sessionlog") return _sessionlogMod;
+    return null;
+  }),
+}));
+
+// Mock GLOBAL_CONFIG_PATH to a tmp path so we don't read the user's real
+// ~/.claude-swarm/config.json. CONFIG_PATH stays relative (".swarm/claude-swarm/config.json")
+// and is resolved by readConfig() via path.resolve(process.cwd(), configPath).
+vi.mock("../paths.mjs", async (importOriginal) => {
+  const actual = await importOriginal();
+  const { mkdtempSync } = await import("fs");
+  const { join } = await import("path");
+  const { tmpdir } = await import("os");
+  const globalTmp = mkdtempSync(join(tmpdir(), "swarm-global-"));
+  return {
+    ...actual,
+    GLOBAL_CONFIG_PATH: join(globalTmp, "config.json"),
+  };
+});
+
+// Import the function under test AFTER mocks are set up
+const { dispatchSessionlogHook, hasStandaloneHooks } = await import("../sessionlog.mjs");
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function initGitRepo(dir) {
+  execSync("git init", { cwd: dir, stdio: "pipe" });
+  execSync('git config user.email "test@test.com"', { cwd: dir, stdio: "pipe" });
+  execSync('git config user.name "Test"', { cwd: dir, stdio: "pipe" });
+  fs.writeFileSync(path.join(dir, "README.md"), "# Test");
+  execSync("git add . && git commit -m initial", { cwd: dir, stdio: "pipe" });
+}
+
+function writeConfig(dir, config) {
+  const configDir = path.join(dir, ".swarm", "claude-swarm");
+  fs.mkdirSync(configDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(configDir, "config.json"),
+    JSON.stringify(config, null, 2)
+  );
+}
+
+function writeClaudeSettings(dir, settings) {
+  const claudeDir = path.join(dir, ".claude");
+  fs.mkdirSync(claudeDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(claudeDir, "settings.json"),
+    JSON.stringify(settings, null, 2)
+  );
+}
+
+function readSessionState(dir, sessionId) {
+  const stateFile = path.join(dir, ".git", "sessionlog-sessions", `${sessionId}.json`);
+  if (!fs.existsSync(stateFile)) return null;
+  return JSON.parse(fs.readFileSync(stateFile, "utf-8"));
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe("sessionlog e2e: plugin dispatch lifecycle", () => {
+  beforeEach(async () => {
+    _tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sessionlog-e2e-"));
+    initGitRepo(_tmpDir);
+
+    // Load the real sessionlog module
+    _sessionlogMod = await import(SESSIONLOG_PATH + "/src/index.ts");
+
+    // Enable sessionlog in the temp repo (dirs + git hooks, no agent hooks)
+    const result = await _sessionlogMod.enable({
+      cwd: _tmpDir,
+      agent: "claude-code",
+      skipAgentHooks: true,
+    });
+    if (!result.enabled) {
+      throw new Error(`sessionlog enable failed: ${result.errors.join(", ")}`);
+    }
+
+    // Point process.cwd() to the tmp dir — this makes:
+    // - readConfig() read .swarm/claude-swarm/config.json from tmp dir
+    // - hasStandaloneHooks() read .claude/settings.json from tmp dir
+    // - sessionlog stores resolve .git/sessionlog-sessions/ from tmp dir
+    vi.spyOn(process, "cwd").mockReturnValue(_tmpDir);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    try {
+      fs.rmSync(_tmpDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  });
+
+  it("hasStandaloneHooks returns false when skipAgentHooks was used", () => {
+    expect(hasStandaloneHooks()).toBe(false);
+  });
+
+  it("dispatches session-start with real config (mode: plugin)", async () => {
+    writeConfig(_tmpDir, {
+      sessionlog: { enabled: true, sync: "off", mode: "plugin" },
+    });
+
+    await dispatchSessionlogHook("session-start", {
+      session_id: "e2e-plugin-session",
+      transcript_path: path.join(_tmpDir, "transcript.jsonl"),
+    });
+
+    const state = readSessionState(_tmpDir, "e2e-plugin-session");
+    expect(state).not.toBeNull();
+    expect(state.sessionID).toBe("e2e-plugin-session");
+    expect(state.phase).toBe("idle");
+  });
+
+  it("full lifecycle: start → prompt → stop → end", async () => {
+    writeConfig(_tmpDir, {
+      sessionlog: { enabled: true, sync: "off", mode: "plugin" },
+    });
+
+    const sessionId = "e2e-full-lifecycle";
+    const transcriptPath = path.join(_tmpDir, "transcript.jsonl");
+    fs.writeFileSync(transcriptPath, "");
+
+    // SessionStart
+    await dispatchSessionlogHook("session-start", {
+      session_id: sessionId,
+      transcript_path: transcriptPath,
+    });
+    expect(readSessionState(_tmpDir, sessionId).phase).toBe("idle");
+
+    // UserPromptSubmit (TurnStart)
+    await dispatchSessionlogHook("user-prompt-submit", {
+      session_id: sessionId,
+      transcript_path: transcriptPath,
+      prompt: "implement feature X",
+    });
+    let state = readSessionState(_tmpDir, sessionId);
+    expect(state.phase).toBe("active");
+    expect(state.firstPrompt).toBe("implement feature X");
+
+    // Stop (TurnEnd)
+    await dispatchSessionlogHook("stop", {
+      session_id: sessionId,
+      transcript_path: transcriptPath,
+    });
+    expect(readSessionState(_tmpDir, sessionId).phase).toBe("idle");
+
+    // SessionEnd
+    await dispatchSessionlogHook("session-end", {
+      session_id: sessionId,
+      transcript_path: transcriptPath,
+    });
+    state = readSessionState(_tmpDir, sessionId);
+    expect(state.phase).toBe("ended");
+    expect(state.endedAt).toBeDefined();
+  });
+
+  it("standalone mode skips dispatch (real config)", async () => {
+    writeConfig(_tmpDir, {
+      sessionlog: { enabled: true, sync: "off", mode: "standalone" },
+    });
+
+    await dispatchSessionlogHook("session-start", {
+      session_id: "should-not-exist",
+      transcript_path: "/tmp/transcript.jsonl",
+    });
+
+    expect(readSessionState(_tmpDir, "should-not-exist")).toBeNull();
+  });
+
+  it("auto mode defers when standalone hooks exist in .claude/settings.json", async () => {
+    writeConfig(_tmpDir, {
+      sessionlog: { enabled: true, sync: "off", mode: "auto" },
+    });
+
+    // Write standalone sessionlog hooks to .claude/settings.json
+    writeClaudeSettings(_tmpDir, {
+      hooks: {
+        SessionStart: [
+          {
+            matcher: "",
+            hooks: [{ type: "command", command: "sessionlog hooks claude-code session-start" }],
+          },
+        ],
+      },
+    });
+
+    await dispatchSessionlogHook("session-start", {
+      session_id: "should-not-exist-auto",
+      transcript_path: "/tmp/transcript.jsonl",
+    });
+
+    expect(readSessionState(_tmpDir, "should-not-exist-auto")).toBeNull();
+  });
+
+  it("auto mode dispatches when no standalone hooks exist", async () => {
+    writeConfig(_tmpDir, {
+      sessionlog: { enabled: true, sync: "off", mode: "auto" },
+    });
+
+    // No .claude/settings.json with sessionlog hooks — auto should dispatch
+    await dispatchSessionlogHook("session-start", {
+      session_id: "e2e-auto-no-standalone",
+      transcript_path: path.join(_tmpDir, "transcript.jsonl"),
+    });
+
+    const state = readSessionState(_tmpDir, "e2e-auto-no-standalone");
+    expect(state).not.toBeNull();
+    expect(state.phase).toBe("idle");
+  });
+
+  it("mode defaults to auto when not specified in config", async () => {
+    // Config with no mode field — should default to "auto"
+    writeConfig(_tmpDir, {
+      sessionlog: { enabled: true, sync: "off" },
+    });
+
+    await dispatchSessionlogHook("session-start", {
+      session_id: "e2e-default-mode",
+      transcript_path: path.join(_tmpDir, "transcript.jsonl"),
+    });
+
+    // No standalone hooks → auto dispatches
+    const state = readSessionState(_tmpDir, "e2e-default-mode");
+    expect(state).not.toBeNull();
+    expect(state.phase).toBe("idle");
+  });
+});

package/src/__tests__/sessionlog.test.mjs

@@ -1,9 +1,36 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import path from "path";
 import fs from "fs";
-import { findActiveSession, buildTrajectoryCheckpoint } from "../sessionlog.mjs";
+import { execSync } from "child_process";
+import { findActiveSession, buildTrajectoryCheckpoint, ensureSessionlogEnabled, checkSessionlogStatus, dispatchSessionlogHook } from "../sessionlog.mjs";
 import { makeTmpDir, writeFile, makeConfig, cleanupTmpDir } from "./helpers.mjs";
 
+// Mock child_process for ensureSessionlogEnabled tests
+vi.mock("child_process", async (importOriginal) => {
+  const actual = await importOriginal();
+  return {
+    ...actual,
+    execSync: vi.fn(actual.execSync),
+  };
+});
+
+// Mock swarmkit-resolver for resolvePackage
+vi.mock("../swarmkit-resolver.mjs", () => ({
+  resolvePackage: vi.fn().mockResolvedValue(null),
+}));
+
+// Mock config — preserve resolveTeamName/resolveScope for buildTrajectoryCheckpoint tests,
+// override readConfig for dispatchSessionlogHook mode tests
+vi.mock("../config.mjs", async (importOriginal) => {
+  const actual = await importOriginal();
+  return {
+    ...actual,
+    readConfig: vi.fn(() => ({
+      sessionlog: { enabled: true, sync: "off", mode: "plugin" },
+    })),
+  };
+});
+
 describe("sessionlog", () => {
   let tmpDir;
   beforeEach(() => { tmpDir = makeTmpDir(); });
@@ -72,13 +99,18 @@ describe("sessionlog", () => {
       filesTouched: ["a.js", "b.js"],
       lastCheckpointID: "cp-42",
       turnCheckpointIDs: ["cp-40", "cp-41", "cp-42"],
-      tokenUsage: { input: 1000, output: 500 },
+      tokenUsage: { inputTokens: 1000, outputTokens: 500, cacheCreationTokens: 50, cacheReadTokens: 200, apiCallCount: 3 },
       extraField: "extra",
     };
 
-    it("sets agentId to teamName-sidecar", () => {
+    it("sets agent to teamName-sidecar (wire format)", () => {
       const cp = buildTrajectoryCheckpoint(baseState, "lifecycle", makeConfig());
-      expect(cp.agentId).toBe("test-team-sidecar");
+      expect(cp.agent).toBe("test-team-sidecar");
+    });
+
+    it("sets session_id from state.sessionID (wire format)", () => {
+      const cp = buildTrajectoryCheckpoint(baseState, "lifecycle", makeConfig());
+      expect(cp.session_id).toBe("sess-123");
     });
 
     it("builds checkpoint id from lastCheckpointID when available", () => {
@@ -92,10 +124,17 @@ describe("sessionlog", () => {
       expect(cp.id).toBe("sess-123-step10");
     });
 
-    it("builds human-readable label", () => {
+    it("builds human-readable label in metadata", () => {
+      const cp = buildTrajectoryCheckpoint(baseState, "lifecycle", makeConfig());
+      expect(cp.metadata.label).toContain("Turn turn-5");
+      expect(cp.metadata.label).toContain("step 10");
+    });
+
+    it("defaults files_touched and checkpoints_count at lifecycle level", () => {
       const cp = buildTrajectoryCheckpoint(baseState, "lifecycle", makeConfig());
-      expect(cp.label).toContain("Turn turn-5");
-      expect(cp.label).toContain("step 10");
+      expect(cp.files_touched).toEqual([]);
+      expect(cp.checkpoints_count).toBe(0);
+      expect(cp.token_usage).toBeUndefined();
     });
 
     it("includes base metadata at lifecycle level", () => {
@@ -106,15 +145,27 @@ describe("sessionlog", () => {
       expect(cp.metadata.stepCount).toBeUndefined();
     });
 
-    it("includes metrics at metrics level", () => {
+    it("promotes files_touched and token_usage to top level at metrics level", () => {
+      const cp = buildTrajectoryCheckpoint(baseState, "metrics", makeConfig());
+      expect(cp.files_touched).toEqual(["a.js", "b.js"]);
+      expect(cp.checkpoints_count).toBe(3);
+      expect(cp.token_usage).toEqual({
+        input_tokens: 1000,
+        output_tokens: 500,
+        cache_creation_tokens: 50,
+        cache_read_tokens: 200,
+        api_call_count: 3,
+      });
+    });
+
+    it("keeps stepCount and checkpoint IDs in metadata at metrics level", () => {
       const cp = buildTrajectoryCheckpoint(baseState, "metrics", makeConfig());
       expect(cp.metadata.stepCount).toBe(10);
-      expect(cp.metadata.filesTouched).toEqual(["a.js", "b.js"]);
-      expect(cp.metadata.tokenUsage).toEqual({ input: 1000, output: 500 });
       expect(cp.metadata.lastCheckpointID).toBe("cp-42");
+      expect(cp.metadata.turnCheckpointIDs).toEqual(["cp-40", "cp-41", "cp-42"]);
     });
 
-    it("includes all state fields at full level", () => {
+    it("includes all state fields in metadata at full level", () => {
       const cp = buildTrajectoryCheckpoint(baseState, "full", makeConfig());
       expect(cp.metadata.extraField).toBe("extra");
       expect(cp.metadata.stepCount).toBe(10);
@@ -131,9 +182,161 @@ describe("sessionlog", () => {
       expect(cp.metadata.endedAt).toBe("2024-01-01T01:00:00Z");
     });
 
-    it("sets sessionId from state.sessionID", () => {
-      const cp = buildTrajectoryCheckpoint(baseState, "lifecycle", makeConfig());
-      expect(cp.sessionId).toBe("sess-123");
+    it("handles legacy tokenUsage format (input/output instead of inputTokens/outputTokens)", () => {
+      const state = { ...baseState, tokenUsage: { input: 800, output: 400 } };
+      const cp = buildTrajectoryCheckpoint(state, "metrics", makeConfig());
+      expect(cp.token_usage.input_tokens).toBe(800);
+      expect(cp.token_usage.output_tokens).toBe(400);
+    });
+  });
+
+  describe("ensureSessionlogEnabled", () => {
+    beforeEach(() => {
+      vi.mocked(execSync).mockReset();
+    });
+
+    it("returns true immediately when sessionlog is already active", async () => {
+      // checkSessionlogStatus calls execSync twice: `which sessionlog` and `sessionlog status`
+      vi.mocked(execSync)
+        .mockImplementationOnce(() => "/usr/local/bin/sessionlog") // which
+        .mockImplementationOnce(() => "enabled: true\nstrategy: manual-commit"); // status
+      const result = await ensureSessionlogEnabled();
+      expect(result).toBe(true);
+    });
+
+    it("returns false when sessionlog is not installed", async () => {
+      vi.mocked(execSync).mockImplementationOnce(() => { throw new Error("not found"); }); // which
+      const result = await ensureSessionlogEnabled();
+      expect(result).toBe(false);
+    });
+
+    it("attempts CLI enable when installed but not enabled and resolvePackage returns null", async () => {
+      const { resolvePackage } = await import("../swarmkit-resolver.mjs");
+      vi.mocked(resolvePackage).mockResolvedValue(null);
+
+      // First two calls: checkSessionlogStatus (which + status)
+      // Third call: CLI fallback `sessionlog enable --agent claude-code`
+      vi.mocked(execSync)
+        .mockImplementationOnce(() => "/usr/local/bin/sessionlog") // which
+        .mockImplementationOnce(() => "enabled: false") // status → not enabled
+        .mockImplementationOnce(() => ""); // sessionlog enable succeeds
+      const result = await ensureSessionlogEnabled();
+      expect(result).toBe(true);
+    });
+
+    it("returns false when both programmatic and CLI enable fail", async () => {
+      const { resolvePackage } = await import("../swarmkit-resolver.mjs");
+      vi.mocked(resolvePackage).mockResolvedValue(null);
+
+      vi.mocked(execSync)
+        .mockImplementationOnce(() => "/usr/local/bin/sessionlog") // which
+        .mockImplementationOnce(() => "enabled: false") // status
+        .mockImplementationOnce(() => { throw new Error("enable failed"); }); // CLI fails
+      const result = await ensureSessionlogEnabled();
+      expect(result).toBe(false);
+    });
+
+    it("tries programmatic API before CLI fallback", async () => {
+      const { resolvePackage } = await import("../swarmkit-resolver.mjs");
+      const mockEnable = vi.fn().mockResolvedValue({ enabled: true });
+      vi.mocked(resolvePackage).mockResolvedValue({ enable: mockEnable });
+
+      vi.mocked(execSync)
+        .mockImplementationOnce(() => "/usr/local/bin/sessionlog") // which
+        .mockImplementationOnce(() => "enabled: false"); // status → not enabled
+      const result = await ensureSessionlogEnabled();
+      expect(result).toBe(true);
+      expect(mockEnable).toHaveBeenCalledWith({ agent: "claude-code", skipAgentHooks: true });
+    });
+  });
+
+  describe("dispatchSessionlogHook", () => {
+    function mockSessionlog(overrides = {}) {
+      return {
+        isEnabled: vi.fn().mockResolvedValue(true),
+        getAgent: vi.fn().mockReturnValue({ parseHookEvent: vi.fn().mockReturnValue({ type: "SessionStart" }) }),
+        hasHookSupport: vi.fn().mockReturnValue(true),
+        createLifecycleHandler: vi.fn().mockReturnValue({ dispatch: vi.fn() }),
+        createSessionStore: vi.fn().mockReturnValue({}),
+        createCheckpointStore: vi.fn().mockReturnValue({}),
+        ...overrides,
+      };
+    }
+
+    beforeEach(() => {
+      vi.mocked(execSync).mockReset();
+    });
+
+    it("skips dispatch when mode is 'standalone'", async () => {
+      const { readConfig } = await import("../config.mjs");
+      vi.mocked(readConfig).mockReturnValue({ sessionlog: { enabled: true, sync: "off", mode: "standalone" } });
+      const { resolvePackage } = await import("../swarmkit-resolver.mjs");
+      const mod = mockSessionlog();
+      vi.mocked(resolvePackage).mockResolvedValue(mod);
+      await dispatchSessionlogHook("session-start", { session_id: "s1" });
+      expect(mod.createLifecycleHandler().dispatch).not.toHaveBeenCalled();
+    });
+
+    it("dispatches when mode is 'plugin'", async () => {
+      const { readConfig } = await import("../config.mjs");
+      vi.mocked(readConfig).mockReturnValue({ sessionlog: { enabled: true, sync: "off", mode: "plugin" } });
+      const { resolvePackage } = await import("../swarmkit-resolver.mjs");
+      const mockDispatch = vi.fn();
+      const mockEvent = { type: "SessionStart", sessionID: "s1" };
+      const mockAgent = { parseHookEvent: vi.fn().mockReturnValue(mockEvent) };
+      vi.mocked(resolvePackage).mockResolvedValue(mockSessionlog({
+        getAgent: vi.fn().mockReturnValue(mockAgent),
+        createLifecycleHandler: vi.fn().mockReturnValue({ dispatch: mockDispatch }),
+      }));
+      await dispatchSessionlogHook("session-start", { session_id: "s1" });
+      expect(mockDispatch).toHaveBeenCalledWith(mockAgent, mockEvent);
+    });
+
+    it("bails silently when sessionlog package is not available", async () => {
+      const { readConfig } = await import("../config.mjs");
+      vi.mocked(readConfig).mockReturnValue({ sessionlog: { enabled: true, sync: "off", mode: "plugin" } });
+      const { resolvePackage } = await import("../swarmkit-resolver.mjs");
+      vi.mocked(resolvePackage).mockResolvedValue(null);
+      await dispatchSessionlogHook("session-start", { session_id: "s1" });
+    });
+
+    it("bails when isEnabled returns false", async () => {
+      const { readConfig } = await import("../config.mjs");
+      vi.mocked(readConfig).mockReturnValue({ sessionlog: { enabled: true, sync: "off", mode: "plugin" } });
+      const { resolvePackage } = await import("../swarmkit-resolver.mjs");
+      const mockDispatch = vi.fn();
+      vi.mocked(resolvePackage).mockResolvedValue(mockSessionlog({
+        isEnabled: vi.fn().mockResolvedValue(false),
+        createLifecycleHandler: vi.fn().mockReturnValue({ dispatch: mockDispatch }),
+      }));
+      await dispatchSessionlogHook("session-start", { session_id: "s1" });
+      expect(mockDispatch).not.toHaveBeenCalled();
+    });
+
+    it("bails when parseHookEvent returns null", async () => {
+      const { readConfig } = await import("../config.mjs");
+      vi.mocked(readConfig).mockReturnValue({ sessionlog: { enabled: true, sync: "off", mode: "plugin" } });
+      const { resolvePackage } = await import("../swarmkit-resolver.mjs");
+      const mockDispatch = vi.fn();
+      vi.mocked(resolvePackage).mockResolvedValue(mockSessionlog({
+        getAgent: vi.fn().mockReturnValue({ parseHookEvent: vi.fn().mockReturnValue(null) }),
+        createLifecycleHandler: vi.fn().mockReturnValue({ dispatch: mockDispatch }),
+      }));
+      await dispatchSessionlogHook("unknown-hook", {});
+      expect(mockDispatch).not.toHaveBeenCalled();
+    });
+
+    it("bails when getAgent returns null", async () => {
+      const { readConfig } = await import("../config.mjs");
+      vi.mocked(readConfig).mockReturnValue({ sessionlog: { enabled: true, sync: "off", mode: "plugin" } });
+      const { resolvePackage } = await import("../swarmkit-resolver.mjs");
+      const mockDispatch = vi.fn();
+      vi.mocked(resolvePackage).mockResolvedValue(mockSessionlog({
+        getAgent: vi.fn().mockReturnValue(null),
+        createLifecycleHandler: vi.fn().mockReturnValue({ dispatch: mockDispatch }),
+      }));
+      await dispatchSessionlogHook("session-start", { session_id: "s1" });
+      expect(mockDispatch).not.toHaveBeenCalled();
     });
   });
 });

package/src/bootstrap.mjs

@@ -20,7 +20,7 @@ import { findSocketPath, isDaemonAlive, ensureDaemon } from "./opentasks-client.
 import { loadTeam } from "./template.mjs";
 import { killSidecar, startSidecar, sendToInbox } from "./sidecar-client.mjs";
 import { sendCommand } from "./map-events.mjs";
-import { checkSessionlogStatus, syncSessionlog, annotateSwarmSession } from "./sessionlog.mjs";
+import { checkSessionlogStatus, ensureSessionlogEnabled, syncSessionlog, annotateSwarmSession, hasStandaloneHooks } from "./sessionlog.mjs";
 import { resolveSwarmkit, configureNodePath } from "./swarmkit-resolver.mjs";
 
 /**
@@ -330,7 +330,7 @@ export async function backgroundInit(config, scope, dir, sessionId) {
       );
     }
 
-    // Sessionlog sync + swarm annotation
+    // Sessionlog sync + swarm annotation (enable already happened in fast path)
     if (config.map.enabled && config.sessionlog.sync !== "off") {
       tasks.push(syncSessionlog(config, sessionId).catch(() => {}));
     }
@@ -394,10 +394,23 @@ export async function bootstrap(pluginDirOverride, sessionId) {
     }
   }
 
-  // 3. Sessionlog status — actual check is slow (execSync), defer to background
+  // 3. Sessionlog: ensure enabled, detect standalone vs plugin mode.
+  //    Mode is resolved per-hook in dispatchSessionlogHook() — bootstrap just
+  //    ensures sessionlog infrastructure exists and reports status.
   let sessionlogStatus = "not installed";
   if (config.sessionlog.enabled) {
-    sessionlogStatus = "checking";
+    try {
+      const mode = config.sessionlog.mode || "auto";
+      const standalone = mode === "standalone" || (mode === "auto" && hasStandaloneHooks());
+      if (standalone) {
+        sessionlogStatus = "active (standalone)";
+      } else {
+        const enabled = await ensureSessionlogEnabled();
+        sessionlogStatus = enabled ? "active" : "installed but not enabled";
+      }
+    } catch {
+      sessionlogStatus = "checking";
+    }
   }
 
   // 4. Quick MAP status — report "starting" for session sidecars (actual startup is background)

package/src/config.mjs

@@ -8,6 +8,7 @@
  */
 
 import fs from "fs";
+import path from "path";
 import { CONFIG_PATH, GLOBAL_CONFIG_PATH } from "./paths.mjs";
 
 export const DEFAULTS = {
@@ -53,8 +54,10 @@ function readJsonFile(filePath) {
  * Never throws — returns defaults on any error.
  */
 export function readConfig(configPath = CONFIG_PATH, globalConfigPath = GLOBAL_CONFIG_PATH) {
-  const global = readJsonFile(globalConfigPath);
-  const project = readJsonFile(configPath);
+  // Resolve relative paths against process.cwd() — fs.readFileSync resolves
+  // against the OS working directory which may differ (e.g. worktrees, subdirs).
+  const global = readJsonFile(path.resolve(globalConfigPath));
+  const project = readJsonFile(path.resolve(configPath));
 
   // Project overrides global for each field (not deep merge — per-field fallthrough)
   const server = envStr("SWARM_MAP_SERVER") ?? project.map?.server ?? global.map?.server ?? undefined;
@@ -84,6 +87,7 @@ export function readConfig(configPath = CONFIG_PATH, globalConfigPath = GLOBAL_C
     sessionlog: {
       enabled: envBool("SWARM_SESSIONLOG_ENABLED") ?? Boolean(project.sessionlog?.enabled ?? global.sessionlog?.enabled),
       sync: envStr("SWARM_SESSIONLOG_SYNC") ?? project.sessionlog?.sync ?? global.sessionlog?.sync ?? DEFAULTS.sessionlogSync,
+      mode: envStr("SWARM_SESSIONLOG_MODE") ?? project.sessionlog?.mode ?? global.sessionlog?.mode ?? "auto",
     },
     opentasks: {
       enabled: envBool("SWARM_OPENTASKS_ENABLED") ?? Boolean(project.opentasks?.enabled ?? global.opentasks?.enabled),

package/src/index.mjs

@@ -80,10 +80,13 @@ export {
 // Sessionlog
 export {
   checkSessionlogStatus,
+  ensureSessionlogEnabled,
+  hasStandaloneHooks,
   findActiveSession,
   buildTrajectoryCheckpoint,
   syncSessionlog,
   annotateSwarmSession,
+  dispatchSessionlogHook,
 } from "./sessionlog.mjs";
 
 // Template

package/src/sessionlog.mjs

@@ -10,6 +10,7 @@ import fs from "fs";
 import path from "path";
 import { execSync } from "child_process";
 import { SESSIONLOG_DIR, SESSIONLOG_STATE_PATH, sessionPaths } from "./paths.mjs";
+import { readConfig } from "./config.mjs";
 import { resolveTeamName, resolveScope } from "./config.mjs";
 import { sendToSidecar, ensureSidecar } from "./sidecar-client.mjs";
 import { fireAndForgetTrajectory } from "./map-connection.mjs";
@@ -40,6 +41,60 @@ export function checkSessionlogStatus() {
   }
 }
 
+/**
+ * Check if sessionlog's standalone hooks are installed in .claude/settings.json.
+ * Reads the file directly — no dependency on resolvePackage("sessionlog").
+ * Looks for any SessionStart hook command containing "sessionlog " as a sentinel
+ * (if session-start is there, all 12 hooks were installed together).
+ */
+export function hasStandaloneHooks() {
+  try {
+    const settingsPath = path.join(process.cwd(), ".claude", "settings.json");
+    const content = fs.readFileSync(settingsPath, "utf-8");
+    const settings = JSON.parse(content);
+    const hooks = settings.hooks?.SessionStart ?? [];
+    return hooks.some(m => m.hooks?.some(h => h.command?.includes("sessionlog ")));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Auto-enable sessionlog if it is installed but not yet enabled.
+ * Tries the programmatic API first (dynamic import), then falls back to CLI.
+ * Best-effort — returns true if enabled, false otherwise. Never throws.
+ */
+export async function ensureSessionlogEnabled() {
+  const status = checkSessionlogStatus();
+  if (status === "active") return true;
+  if (status === "not installed") return false;
+
+  // Status is "installed but not enabled" — try to enable it
+
+  // 1. Try programmatic API via dynamic import
+  //    skipAgentHooks: true — agent hooks are managed by cc-swarm's hooks.json
+  try {
+    const sessionlogMod = await resolvePackage("sessionlog");
+    if (sessionlogMod?.enable) {
+      const result = await sessionlogMod.enable({ agent: "claude-code", skipAgentHooks: true });
+      if (result.enabled) return true;
+    }
+  } catch {
+    // Fall through to CLI
+  }
+
+  // 2. Fallback to CLI
+  try {
+    execSync("sessionlog enable --agent claude-code --skip-agent-hooks", {
+      stdio: "ignore",
+      timeout: 15_000,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Find the active (non-ended) sessionlog session file.
  * Returns parsed SessionState or null.
@@ -79,31 +134,54 @@ export function findActiveSession(sessionlogDir = SESSIONLOG_DIR) {
 
 /**
  * Build a MAP TrajectoryCheckpoint from sessionlog state.
- * Metadata contents are filtered by sync level.
+ *
+ * Conforms to sessionlog's SessionSyncCheckpoint wire format (snake_case,
+ * top-level fields) so OpenHive's sync listener can extract fields correctly.
+ * Extra sessionlog-specific fields go in `metadata` for passthrough.
  */
 export function buildTrajectoryCheckpoint(state, syncLevel, config) {
   const teamName = resolveTeamName(config);
-  const agentId = `${teamName}-sidecar`;
 
   const id =
     state.lastCheckpointID ||
     `${state.sessionID}-step${state.stepCount || 0}`;
 
-  const label = `Turn ${state.turnID || "?"} (step ${state.stepCount || 0}, ${state.phase || "unknown"})`;
+  // Wire format fields (top-level, snake_case) — always present
+  const checkpoint = {
+    id,
+    session_id: state.sessionID,
+    agent: `${teamName}-sidecar`,
+    files_touched: [],
+    checkpoints_count: 0,
+  };
 
+  // Metadata — sessionlog-specific fields for passthrough
   const metadata = {
     phase: state.phase,
     turnId: state.turnID,
     startedAt: state.startedAt,
+    label: `Turn ${state.turnID || "?"} (step ${state.stepCount || 0}, ${state.phase || "unknown"})`,
   };
   if (state.endedAt) metadata.endedAt = state.endedAt;
 
   if (syncLevel === "metrics" || syncLevel === "full") {
+    // Promote to top-level wire format fields
+    checkpoint.files_touched = state.filesTouched || [];
+    checkpoint.checkpoints_count = (state.turnCheckpointIDs || []).length;
+    if (state.tokenUsage) {
+      checkpoint.token_usage = {
+        input_tokens: state.tokenUsage.inputTokens ?? state.tokenUsage.input ?? 0,
+        output_tokens: state.tokenUsage.outputTokens ?? state.tokenUsage.output ?? 0,
+        cache_creation_tokens: state.tokenUsage.cacheCreationTokens ?? 0,
+        cache_read_tokens: state.tokenUsage.cacheReadTokens ?? 0,
+        api_call_count: state.tokenUsage.apiCallCount ?? 0,
+      };
+    }
+
+    // Keep in metadata for sessionlog consumers
     metadata.stepCount = state.stepCount;
-    metadata.filesTouched = state.filesTouched;
     metadata.lastCheckpointID = state.lastCheckpointID;
     metadata.turnCheckpointIDs = state.turnCheckpointIDs;
-    if (state.tokenUsage) metadata.tokenUsage = state.tokenUsage;
   }
 
   if (syncLevel === "full") {
@@ -114,13 +192,7 @@ export function buildTrajectoryCheckpoint(state, syncLevel, config) {
     }
   }
 
-  return {
-    id,
-    agentId,
-    sessionId: state.sessionID,
-    label,
-    metadata,
-  };
+  return { ...checkpoint, metadata };
 }
 
 /**
@@ -203,3 +275,63 @@ export async function annotateSwarmSession(config, sessionId) {
     // Non-critical — session may not exist yet or annotate failed
   }
 }
+
+/**
+ * Dispatch a sessionlog hook event programmatically.
+ * Replaces the CLI pattern: `sessionlog hooks claude-code <hookName>`
+ * Uses resolvePackage("sessionlog") to call the lifecycle handler directly.
+ * Best-effort — never throws.
+ *
+ * @param {string} hookName - Sessionlog hook name (e.g. "session-start", "stop")
+ * @param {object} hookData - Raw hook event data from Claude Code stdin
+ */
+export async function dispatchSessionlogHook(hookName, hookData) {
+  // Decide whether plugin dispatch should handle this hook.
+  // config.sessionlog.mode: "plugin" (always dispatch), "standalone" (never dispatch), "auto" (check)
+  const config = readConfig();
+  const mode = config.sessionlog?.mode || "auto";
+  if (mode === "standalone") return;
+  if (mode === "auto" && hasStandaloneHooks()) return;
+
+  let sessionlogMod;
+  try {
+    sessionlogMod = await resolvePackage("sessionlog");
+  } catch {
+    return;
+  }
+  if (!sessionlogMod) return;
+
+  const {
+    isEnabled,
+    getAgent,
+    hasHookSupport,
+    createLifecycleHandler,
+    createSessionStore,
+    createCheckpointStore,
+  } = sessionlogMod;
+
+  // Pass cwd explicitly — sessionlog's defaults use git rev-parse which
+  // resolves against the OS working directory, not process.cwd().
+  const cwd = process.cwd();
+
+  // Bail if sessionlog is not enabled in this repo
+  try {
+    if (typeof isEnabled === "function" && !(await isEnabled(cwd))) return;
+  } catch {
+    return;
+  }
+
+  const agent = getAgent("claude-code");
+  if (!agent || (typeof hasHookSupport === "function" && !hasHookSupport(agent))) return;
+
+  const event = agent.parseHookEvent(hookName, JSON.stringify(hookData));
+  if (!event) return;
+
+  const handler = createLifecycleHandler({
+    sessionStore: createSessionStore(cwd),
+    checkpointStore: createCheckpointStore(cwd),
+    cwd,
+  });
+
+  await handler.dispatch(agent, event);
+}