@yannelli/paseo-linear-plugin 1.0.1 → 1.1.0-alpha.0

package/server/subagent-logs.ts

@@ -0,0 +1,146 @@
+import { open, readdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import type { SubagentLog } from "../shared/live";
+
+// Claude writes each subagent's transcript beside the session, also for subagents that run in
+// the background and send nothing to the parent timeline. This reads their tool calls and turns
+// them into timeline items the panel already understands. Nothing here writes or runs anything.
+
+const SESSION_ID = /^[A-Za-z0-9-]{8,80}$/;
+const MAX_RUNS = 8;
+const MAX_TAIL_BYTES = 512 * 1024;
+const MAX_ITEMS = 120;
+
+/** Folders that can hold Claude's `projects` folder: the env setting, the default, Paseo homes. */
+async function claudeHomes(): Promise<string[]> {
+  const homes = [process.env.CLAUDE_CONFIG_DIR, path.join(homedir(), ".claude")];
+  const paseoHome = process.env.PASEO_HOME || path.join(homedir(), ".paseo");
+  const accounts = await readdir(path.join(paseoHome, "zerosub", "homes")).catch(() => []);
+  for (const name of accounts) homes.push(path.join(paseoHome, "zerosub", "homes", name));
+  return [...new Set(homes.filter((home): home is string => Boolean(home)))];
+}
+
+const found = new Map<string, string>();
+
+async function isDirectory(target: string): Promise<boolean> {
+  return (await stat(target).catch(() => null))?.isDirectory() ?? false;
+}
+
+/** The session's `subagents` folder. Claude names the project folder after the cwd. */
+export async function subagentFolder(sessionId: string, cwd: string): Promise<string | null> {
+  if (!SESSION_ID.test(sessionId)) return null;
+  const known = found.get(sessionId);
+  if (known) return known;
+  const slug = cwd.replace(/[^A-Za-z0-9]/g, "-");
+  for (const home of await claudeHomes()) {
+    const projects = path.join(home, "projects");
+    const guess = path.join(projects, slug, sessionId, "subagents");
+    const names = (await isDirectory(guess)) ? [slug] : await readdir(projects).catch(() => []);
+    for (const name of names) {
+      const folder = path.join(projects, name, sessionId, "subagents");
+      if (await isDirectory(folder)) {
+        found.set(sessionId, folder);
+        return folder;
+      }
+    }
+  }
+  return null;
+}
+
+async function tail(file: string): Promise<string> {
+  const handle = await open(file, "r");
+  try {
+    const { size } = await handle.stat();
+    const start = Math.max(0, size - MAX_TAIL_BYTES);
+    const buffer = Buffer.alloc(size - start);
+    await handle.read(buffer, 0, buffer.length, start);
+    const text = buffer.toString("utf8");
+    // A cut first line is not valid JSON; drop it.
+    return start > 0 ? text.slice(text.indexOf("\n") + 1) : text;
+  } finally {
+    await handle.close();
+  }
+}
+
+type Block = Record<string, unknown>;
+type Item = SubagentLog["items"][number];
+
+const str = (value: unknown) => (typeof value === "string" ? value : "");
+const lines = (value: unknown) => (str(value) ? str(value).replace(/\n$/, "").split("\n").length : 0);
+
+/** A Claude tool call as a Paseo-style tool call item, with paths moved from the worktree. */
+export function toolItem(block: Block, move: (value: string) => string, cwd: string): Item {
+  const input = (block.input ?? {}) as Block;
+  const name = str(block.name);
+  const file = move(str(input.file_path) || str(input.notebook_path));
+  let detail: Record<string, unknown> = { type: "unknown" };
+  if (name === "Read" && file) detail = { type: "read", filePath: file };
+  else if ((name === "Edit" || name === "MultiEdit" || name === "NotebookEdit") && file) {
+    const edits = Array.isArray(input.edits) ? (input.edits as Block[]) : [input];
+    const added = edits.reduce((sum, edit) => sum + lines(edit.new_string ?? edit.new_source), 0);
+    const removed = edits.reduce((sum, edit) => sum + lines(edit.old_string), 0);
+    detail = { type: "edit", filePath: file, added, removed };
+  } else if (name === "Write" && file) detail = { type: "write", filePath: file, added: lines(input.content) };
+  else if (name === "Grep" || name === "Glob") detail = { type: "search", query: str(input.pattern) };
+  else if (name === "Bash") detail = { type: "shell", command: move(str(input.command)), cwd };
+  return { type: "tool_call", callId: str(block.id), name, status: "running", detail };
+}
+
+/** Tool calls in a transcript, newest last, with each finished call marked done or failed. */
+export function transcriptItems(text: string, move: (value: string) => string, cwd: string) {
+  const items = new Map<string, Item>();
+  let finished = false;
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    let entry: Block;
+    try {
+      entry = JSON.parse(line) as Block;
+    } catch {
+      continue;
+    }
+    const message = (entry.message ?? {}) as Block;
+    const content = Array.isArray(message.content) ? (message.content as Block[]) : [];
+    if (entry.type === "assistant") {
+      finished = message.stop_reason === "end_turn" && !content.some((block) => block.type === "tool_use");
+    }
+    for (const block of content) {
+      if (block.type === "tool_use" && str(block.id)) items.set(str(block.id), toolItem(block, move, cwd));
+      const done = block.type === "tool_result" ? items.get(str(block.tool_use_id)) : undefined;
+      if (done) done.status = block.is_error ? "failed" : "completed";
+    }
+  }
+  return { items: [...items.values()].slice(-MAX_ITEMS), finished };
+}
+
+/** The newest subagents of a Claude session, with their tool calls. */
+export async function subagentLogs(sessionId: string, cwd: string): Promise<SubagentLog[]> {
+  const folder = await subagentFolder(sessionId, cwd);
+  if (!folder) return [];
+  const names = (await readdir(folder).catch(() => [])).filter((name) => /^agent-[A-Za-z0-9]+\.jsonl$/.test(name));
+  const dated = await Promise.all(
+    names.map(async (name) => ({ name, at: (await stat(path.join(folder, name)).catch(() => null))?.mtimeMs ?? 0 })),
+  );
+  const newest = dated.sort((a, b) => b.at - a.at).slice(0, MAX_RUNS);
+  const runs: SubagentLog[] = [];
+  for (const { name, at } of newest) {
+    const id = name.slice("agent-".length, -".jsonl".length);
+    const meta = JSON.parse(
+      (await readFile(path.join(folder, `agent-${id}.meta.json`), "utf8").catch(() => "{}")) || "{}",
+    ) as Block;
+    const worktree = str(meta.worktreePath).replace(/\/+$/, "");
+    // A subagent in its own worktree sees the same repository, so its paths map onto the agent's.
+    const move = (value: string) => (worktree ? value.split(worktree).join(cwd) : value);
+    const { items, finished } = transcriptItems(await tail(path.join(folder, name)).catch(() => ""), move, cwd);
+    runs.push({
+      id,
+      type: str(meta.agentType) || "Subagent",
+      description: str(meta.description),
+      toolUseId: str(meta.toolUseId) || null,
+      updatedAt: Math.round(at),
+      finished,
+      items,
+    });
+  }
+  return runs;
+}

package/server/sync.ts

@@ -0,0 +1,133 @@
+import type { PluginServerContext } from "@getpaseo/plugin/server";
+import type { WorkflowState } from "../shared/linear";
+import { syncNowRpc } from "../shared/live";
+import { AGENT_LABELS, isInternalAgent } from "../shared/prompts";
+import { type LinearSettings, projectDefaults, projectEnabled } from "../shared/settings";
+import { planStatusMoves, progressByKey, type TodoLike } from "../shared/todo-sync";
+import type { Paseo } from "./agent-runs";
+import type { LinearAccess } from "./handlers";
+import { agentInfo } from "./live";
+
+const STATES_MAX_AGE_MS = 10 * 60_000;
+
+export interface SyncDependencies {
+  access: LinearAccess;
+  readSettings(): Promise<LinearSettings | null>;
+}
+
+export interface SyncResult {
+  moves: { identifier: string; from: WorkflowState; to: WorkflowState }[];
+  skipped: string | null;
+}
+
+function latestTodos(items: readonly { type: string; items?: unknown }[]): TodoLike[] | null {
+  for (let index = items.length - 1; index >= 0; index -= 1) {
+    const item = items[index];
+    if (item?.type === "todo" && Array.isArray(item.items)) return item.items as TodoLike[];
+  }
+  return null;
+}
+
+export function registerSync(server: PluginServerContext, dependencies: SyncDependencies) {
+  const { access, readSettings } = dependencies;
+  const teamStates = new Map<string, { at: number; states: Map<string, WorkflowState[]> }>();
+  const queues = new Map<string, Promise<unknown>>();
+
+  async function statesFor(projectId: string | null, teamId: string) {
+    const { linear, fingerprint } = await access.connect(projectId);
+    const cached = teamStates.get(fingerprint);
+    if (cached && Date.now() - cached.at < STATES_MAX_AGE_MS && cached.states.has(teamId)) {
+      return cached.states.get(teamId) ?? [];
+    }
+    const catalog = await linear.catalog();
+    const states = new Map(catalog.teams.map((team) => [team.id, team.states]));
+    teamStates.set(fingerprint, { at: Date.now(), states });
+    return states.get(teamId) ?? [];
+  }
+
+  // Reads Linear fresh, not the response cache, so a manual move since the last turn counts.
+  async function syncIssue(
+    identifier: string,
+    projectId: string | null,
+    todos: readonly TodoLike[],
+  ): Promise<SyncResult> {
+    const progress = progressByKey(todos);
+    if (progress.size === 0) return { moves: [], skipped: "No todo starts with an issue key." };
+    const { linear } = await access.connect(projectId);
+    const issue = await linear.getIssue(identifier);
+    const states = await statesFor(projectId, issue.team.id);
+    const moves = planStatusMoves({ parent: issue, progress, states });
+    const applied: SyncResult["moves"] = [];
+    for (const move of moves) {
+      await access.mutate(projectId, (service) =>
+        service.updateIssue(move.issueId, { stateId: move.to.id }),
+      );
+      applied.push({ identifier: move.identifier, from: move.from, to: move.to });
+    }
+    if (applied.length > 0) {
+      console.log(`Linear sync moved ${applied.map((m) => `${m.identifier} to ${m.to.name}`).join(", ")}`);
+    }
+    return { moves: applied, skipped: null };
+  }
+
+  // One sync per issue at a time, so two turns ending together cannot move an issue twice.
+  function queued(identifier: string, run: () => Promise<SyncResult>): Promise<SyncResult> {
+    const previous = queues.get(identifier) ?? Promise.resolve();
+    const next = previous.catch(() => undefined).then(run);
+    queues.set(identifier, next);
+    void next.finally(() => {
+      if (queues.get(identifier) === next) queues.delete(identifier);
+    });
+    return next;
+  }
+
+  async function syncAgent(
+    paseo: Paseo,
+    agentId: string,
+    todos: readonly TodoLike[] | null,
+    automatic = false,
+  ): Promise<SyncResult> {
+    const agent = await agentInfo(paseo, agentId);
+    const settings = await readSettings();
+    if (settings && !projectEnabled(settings.access, agent.projectId)) {
+      return { moves: [], skipped: "Linear is off for this project." };
+    }
+    if (automatic && !(settings && projectDefaults(settings, agent.projectId).syncTodos)) {
+      return { moves: [], skipped: "Todo sync is off for this project." };
+    }
+    const identifier = agent.labels[AGENT_LABELS.issue];
+    if (!identifier || isInternalAgent(agent.labels)) {
+      return { moves: [], skipped: "This agent is not linked to a Linear issue." };
+    }
+    if (agent.labels[AGENT_LABELS.action] !== "implement") {
+      return { moves: [], skipped: "Only implementing agents update Linear statuses." };
+    }
+    let items = todos;
+    if (!items) {
+      const page = await paseo.agents
+        .ref(agentId)
+        .timeline.refetch({ direction: "tail", limit: 400, projection: "projected" });
+      items = latestTodos(page.entries.map((entry) => entry.item));
+    }
+    if (!items) return { moves: [], skipped: "The agent has no todos yet." };
+    const projectId = agent.labels[AGENT_LABELS.project] ?? null;
+    const todoItems = items;
+    return queued(identifier, () => syncIssue(identifier, projectId, todoItems));
+  }
+
+  // A project can turn sync on or off for itself, so the check needs the agent's project.
+  server.on("agent.turn_ended", async (event, { paseo }) => {
+    const settings = await readSettings();
+    const anyOn = settings?.live.syncTodos || settings?.projects.some((entry) => entry.overrides.syncTodos);
+    if (!anyOn) return;
+    const todos = latestTodos(event.timeline);
+    if (!todos) return;
+    try {
+      await syncAgent(paseo, event.agent.id, todos, true);
+    } catch (error) {
+      console.error("Linear sync failed", error);
+    }
+  });
+
+  server.handle(syncNowRpc, async ({ agentId }, { paseo }) => syncAgent(paseo, agentId, null));
+}

package/shared/activity.ts

@@ -0,0 +1,268 @@
+import { displayCommand, shellActivity } from "./shell-activity";
+import { isSubagentCall, mergeSubagent, type SubagentRun, subagentOf } from "./subagents";
+import type { TodoLike } from "./todo-sync";
+
+// Structural view of Paseo timeline items, so shared code needs no protocol import.
+export interface TimelineItemLike {
+  type: string;
+  [key: string]: unknown;
+}
+
+export type TouchKind = "read" | "edit" | "write" | "search";
+export type EventKind = TouchKind | "list" | "shell" | "agent" | "tool";
+export type ToolStatus = "running" | "completed" | "failed" | "canceled";
+
+export interface FileTouch {
+  path: string;
+  reads: number;
+  edits: number;
+  added: number;
+  removed: number;
+  created: boolean;
+  /** Position of the last touch in the timeline. Higher is more recent. */
+  order: number;
+  last: TouchKind;
+}
+
+export interface ActivityEvent {
+  id: string;
+  kind: EventKind;
+  text: string;
+  /** The command as run, for shell events. */
+  detail: string | null;
+  path: string | null;
+  /** Every file the event read or changed; `path` is the first. */
+  paths: string[];
+  status: ToolStatus;
+  added: number;
+  removed: number;
+  exitCode: number | null;
+}
+
+export interface DirTouch {
+  /** Folder with a trailing slash; "" is the repository root. */
+  path: string;
+  /** Searched recursively, not only listed. */
+  deep: boolean;
+  order: number;
+}
+
+export interface Activity {
+  files: FileTouch[];
+  dirs: DirTouch[];
+  /** Subagents started inside the provider, in launch order. */
+  subagents: SubagentRun[];
+  /** Newest first. */
+  events: ActivityEvent[];
+  current: ActivityEvent | null;
+  todos: TodoLike[];
+}
+
+const MAX_EVENTS = 40;
+// Bookkeeping tools: the todos already show what they do.
+const HIDDEN_TOOLS = /^(Task(Create|Update|List|Get|Stop|Output)|TodoWrite|ToolSearch|advisor|task_notification)$/;
+
+/** A repo-relative path, or null when the path is outside the agent's folder. */
+export function relativePath(path: string, cwd: string): string | null {
+  let value = path.trim().replace(/\\/g, "/");
+  const root = cwd.trim().replace(/\\/g, "/").replace(/\/+$/, "");
+  if (root && value.startsWith(`${root}/`)) value = value.slice(root.length + 1);
+  else if (value.startsWith("/") || /^[A-Za-z]:\//.test(value)) return null;
+  value = value.replace(/^(\.\/)+/, "");
+  if (!value || value.split("/").includes("..")) return null;
+  return value;
+}
+
+function text(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+function lineCount(value: string | null): number {
+  if (!value) return 0;
+  return value.replace(/\n$/, "").split("\n").length;
+}
+
+function diffCounts(detail: Record<string, unknown>): { added: number; removed: number } {
+  // Subagent transcripts send counts, not the text.
+  if (typeof detail.added === "number") {
+    return { added: detail.added, removed: typeof detail.removed === "number" ? detail.removed : 0 };
+  }
+  const diff = text(detail.unifiedDiff);
+  if (diff) {
+    let added = 0;
+    let removed = 0;
+    for (const line of diff.split("\n")) {
+      if (line.startsWith("+") && !line.startsWith("+++")) added += 1;
+      else if (line.startsWith("-") && !line.startsWith("---")) removed += 1;
+    }
+    return { added, removed };
+  }
+  return { added: lineCount(text(detail.newString)), removed: lineCount(text(detail.oldString)) };
+}
+
+function toolStatus(value: unknown): ToolStatus {
+  return value === "running" || value === "failed" || value === "canceled" ? value : "completed";
+}
+
+function baseName(path: string): string {
+  return path.split("/").pop() ?? path;
+}
+
+// Tool calls stream as repeated items with one callId. The last copy wins, in first position.
+function latestToolCalls(items: readonly TimelineItemLike[]) {
+  const order: string[] = [];
+  const byId = new Map<string, TimelineItemLike>();
+  items.forEach((item, index) => {
+    if (item.type !== "tool_call") return;
+    const id = text(item.callId) ?? `index-${index}`;
+    if (!byId.has(id)) order.push(id);
+    byId.set(id, item);
+  });
+  return order.map((id) => ({ id, item: byId.get(id) as TimelineItemLike }));
+}
+
+export function deriveActivity(items: readonly TimelineItemLike[], cwd: string): Activity {
+  const files = new Map<string, FileTouch>();
+  const dirs = new Map<string, DirTouch>();
+  const events: ActivityEvent[] = [];
+  const subagents = new Map<string, SubagentRun>();
+  const subagentEvents = new Map<string, ActivityEvent>();
+  const resolve = (path: string) => relativePath(path, cwd);
+  let todos: TodoLike[] = [];
+  for (const item of items) {
+    if (item.type === "todo" && Array.isArray(item.items)) todos = item.items as TodoLike[];
+  }
+  const touch = (path: string, kind: TouchKind, order: number) => {
+    const entry = files.get(path) ?? {
+      path,
+      reads: 0,
+      edits: 0,
+      added: 0,
+      removed: 0,
+      created: false,
+      order,
+      last: kind,
+    };
+    entry.order = order;
+    entry.last = kind;
+    files.set(path, entry);
+    return entry;
+  };
+
+  latestToolCalls(items).forEach(({ id, item }, order) => {
+    if (HIDDEN_TOOLS.test(text(item.name) ?? "")) return;
+    const signal = subagentOf(item, resolve);
+    if (!signal && isSubagentCall(item)) return;
+    if (signal) {
+      // The launch call and the subagent item are one run, so they make one feed row.
+      const run = mergeSubagent(subagents, signal, order);
+      const known = subagentEvents.get(run.key);
+      const row: ActivityEvent = known ?? {
+        id,
+        kind: "agent",
+        text: run.description ? `${run.type}: ${run.description}` : run.type,
+        detail: null,
+        path: null,
+        paths: [],
+        status: run.status,
+        added: 0,
+        removed: 0,
+        exitCode: null,
+      };
+      row.status = run.status;
+      row.paths = run.targets;
+      row.path = run.targets[0] ?? null;
+      if (!known) {
+        subagentEvents.set(run.key, row);
+        events.push(row);
+      }
+      return;
+    }
+    const detail = (item.detail ?? {}) as Record<string, unknown>;
+    const status = toolStatus(item.status);
+    const event: ActivityEvent = {
+      id,
+      kind: "tool",
+      text: text(item.name) ?? "Tool call",
+      detail: null,
+      path: null,
+      paths: [],
+      status,
+      added: 0,
+      removed: 0,
+      exitCode: null,
+    };
+    const raw = text(detail.filePath);
+    const path = raw ? relativePath(raw, cwd) : null;
+    if (path) event.paths = [path];
+    if (detail.type === "read" && raw) {
+      event.kind = "read";
+      event.path = path;
+      event.text = `Read ${path ?? baseName(raw)}`;
+      if (path) touch(path, "read", order).reads += 1;
+    } else if ((detail.type === "edit" || detail.type === "write") && raw) {
+      const write = detail.type === "write";
+      const counts = write && typeof detail.added !== "number"
+        ? { added: lineCount(text(detail.content)), removed: 0 }
+        : diffCounts(detail);
+      event.kind = write ? "write" : "edit";
+      event.path = path;
+      event.added = counts.added;
+      event.removed = counts.removed;
+      event.text = `${write ? "Wrote" : "Edited"} ${path ?? baseName(raw)}`;
+      if (path && status !== "failed") {
+        const entry = touch(path, event.kind, order);
+        entry.edits += 1;
+        entry.added += counts.added;
+        entry.removed += counts.removed;
+        if (write && entry.reads === 0 && entry.edits === 1) entry.created = true;
+      }
+    } else if (detail.type === "search") {
+      event.kind = "search";
+      event.text = `Searched ${JSON.stringify(text(detail.query) ?? "")}`;
+      const hits = Array.isArray(detail.filePaths) ? detail.filePaths : [];
+      for (const hit of hits) {
+        const hitPath = typeof hit === "string" ? relativePath(hit, cwd) : null;
+        if (hitPath && !files.has(hitPath)) touch(hitPath, "search", order);
+      }
+    } else if (detail.type === "shell") {
+      const command = text(detail.command) ?? "";
+      const start = relativePath(text(detail.cwd) ?? "", cwd) ?? "";
+      const shell = shellActivity(command, cwd, start);
+      event.exitCode = typeof detail.exitCode === "number" ? detail.exitCode : null;
+      event.detail = displayCommand(command, cwd);
+      event.text = shell.summary;
+      event.paths = [...shell.writes.map((write) => write.path), ...shell.reads];
+      event.path = event.paths[0] ?? null;
+      event.kind = "shell";
+      if (shell.writes.length > 0) event.kind = "write";
+      else if (shell.reads.length > 0) event.kind = "read";
+      else if (shell.pattern !== null) event.kind = "search";
+      else if (shell.dirs.length > 0) event.kind = "list";
+      for (const read of shell.reads) touch(read, "read", order).reads += 1;
+      // A failed write may not have happened; reads count either way, as grep exits 1 on no match.
+      const succeeded = status === "completed" && (event.exitCode ?? 0) === 0;
+      for (const write of succeeded ? shell.writes : []) {
+        const entry = touch(write.path, write.mode, order);
+        entry.edits += 1;
+        if (write.mode === "write" && entry.reads === 0 && entry.edits === 1) entry.created = true;
+      }
+      for (const dir of shell.dirs) {
+        const known = dirs.get(dir.path);
+        dirs.set(dir.path, { path: dir.path, deep: dir.deep || (known?.deep ?? false), order });
+      }
+    }
+    events.push(event);
+  });
+
+  const recent = events.slice(-MAX_EVENTS).reverse();
+  const current = recent.find((event) => event.status === "running") ?? recent[0] ?? null;
+  return {
+    files: [...files.values()].sort((a, b) => b.order - a.order),
+    dirs: [...dirs.values()],
+    subagents: [...subagents.values()],
+    events: recent,
+    current,
+    todos,
+  };
+}

package/shared/agent-hooks.ts

@@ -0,0 +1,68 @@
+import { defineRpc } from "@getpaseo/plugin";
+import { z } from "zod";
+import { GuidanceSchema } from "./settings";
+
+// Claude Code hooks for an agent started from an issue. The daemon writes them as a Claude Code
+// plugin and the launch passes its folder with --plugin-dir, so they never replace the settings
+// Paseo itself passes with --settings. Each hook only prints text; none of them runs project code.
+
+export const IDENTIFIER = /^[A-Za-z][A-Za-z0-9]*-\d+$/;
+
+const HookIssueSchema = z.object({
+  identifier: z.string().regex(IDENTIFIER),
+  title: z.string(),
+  children: z.array(z.object({ identifier: z.string().regex(IDENTIFIER), title: z.string() })).max(100),
+});
+export type HookIssue = z.infer<typeof HookIssueSchema>;
+
+export const agentHooksRpc = defineRpc({
+  name: "linear.agent.hooks",
+  input: z.object({ issue: HookIssueSchema, guidance: GuidanceSchema }),
+  /** Null when no hook applies or the daemon host cannot run them. */
+  output: z.object({ pluginDir: z.string().nullable() }),
+});
+
+/** Single-quotes text for a POSIX shell. */
+export function shellQuote(text: string): string {
+  return `'${text.replace(/'/g, `'\\''`)}'`;
+}
+
+function printHook(event: string, context: string) {
+  const output = { hookSpecificOutput: { hookEventName: event, additionalContext: context } };
+  return { type: "command", command: `printf '%s' ${shellQuote(JSON.stringify(output))}` };
+}
+
+function issueLines(issue: HookIssue): string[] {
+  const lines = [`Linear issue ${issue.identifier}: ${issue.title}`];
+  for (const child of issue.children.slice(0, 30)) lines.push(`- ${child.identifier}: ${child.title}`);
+  return lines;
+}
+
+/** The plugin's hooks.json, or null when no guidance option needs a hook. */
+export function claudeHooks(issue: HookIssue, guidance: z.infer<typeof GuidanceSchema>) {
+  const hooks: Record<string, unknown[]> = {};
+  if (guidance.subagentKeys) {
+    const context = [
+      `You are a subagent for ${issue.identifier}.`,
+      ...issueLines(issue),
+      "Put the key of the issue you work on in the first line of your reply, such as",
+      `"${issue.children[0]?.identifier ?? issue.identifier}: checked the form".`,
+      "If your work moves to another issue, state the new key.",
+    ].join("\n");
+    hooks.SubagentStart = [{ hooks: [printHook("SubagentStart", context)] }];
+  }
+  if (guidance.updateLinear || guidance.subagentKeys || guidance.paseoSubagents) {
+    // After compaction the summary can drop the issue, so restate it.
+    const context = [
+      `You work on ${issue.identifier}. The Linear rules in your first prompt still apply.`,
+      ...issueLines(issue),
+    ].join("\n");
+    hooks.SessionStart = [{ matcher: "compact", hooks: [printHook("SessionStart", context)] }];
+  }
+  return Object.keys(hooks).length > 0 ? { hooks } : null;
+}
+
+/** Claude Code plugin names are lowercase words joined by hyphens. */
+export function hookPluginName(identifier: string): string {
+  return `paseo-linear-${identifier.toLowerCase()}`;
+}