@yannelli/paseo-linear-plugin 1.1.0-beta.0 → 1.1.0-beta.2

package/client/launch-plan.ts

@@ -1,3 +1,4 @@
+import type { RpcOutput } from "@getpaseo/plugin";
 import { usePaseo, useRpc } from "@getpaseo/plugin/client";
 import { useMutation } from "@tanstack/react-query";
 import {
@@ -7,9 +8,11 @@ import {
   updateIssueRpc,
   type WorkflowState,
 } from "../shared/linear";
+import { agentHooksRpc } from "../shared/agent-hooks";
+import { agentToolsRpc, TOOLS_SERVER } from "../shared/agent-tools";
 import { launchAfterExploreRpc } from "../shared/live";
 import { AGENT_LABELS, agentTitle } from "../shared/prompts";
-import type { AgentAction, Isolation, LinearSettings } from "../shared/settings";
+import type { AgentAction, Guidance, Isolation, LinearSettings } from "../shared/settings";
 import { type AgentSelection, agentConfig } from "./agent-options";
 import { rememberLaunch } from "./agent-preferences";
 import type { PaseoProjectOption } from "./queries";
@@ -144,6 +147,25 @@ export interface LaunchRequest {
   keyScope: string | null;
   /** Maps the files with the read-only explore agent first, then starts the agent. */
   explore: boolean;
+  /** Guidance options; for Claude some also add hooks. */
+  guidance: Guidance;
+}
+
+type AgentTools = RpcOutput<typeof agentToolsRpc>;
+
+/** The config with the plugin's MCP server, whose token only reaches this issue tree. */
+export function withLinearTools<C extends object>(config: C, tools: Pick<AgentTools, "server" | "toolPolicy"> | null) {
+  if (!tools) return config;
+  return { ...config, mcpServers: { [TOOLS_SERVER]: tools.server }, toolPolicy: tools.toolPolicy };
+}
+
+/** The issue's guidance needs the MCP tools: Linear edits, or agents started on sub-issues. */
+export const needsLinearTools = (guidance: Guidance) => guidance.updateLinear || guidance.paseoSubagents;
+
+/** The config with the issue's Claude Code hooks, loaded as a plugin with --plugin-dir. */
+export function withHookPlugin<C extends object>(config: C, pluginDir: string | null) {
+  if (!pluginDir) return config;
+  return { ...config, providerOptions: { extraArgs: { "plugin-dir": pluginDir } } };
 }
 
 export type Paseo = ReturnType<typeof usePaseo>;
@@ -217,6 +239,8 @@ export function useLaunchAgent() {
   const updateIssue = useRpc(updateIssueRpc);
   const attachCard = useRpc(attachIssueCardRpc);
   const launchAfterExplore = useRpc(launchAfterExploreRpc);
+  const prepareHooks = useRpc(agentHooksRpc);
+  const prepareTools = useRpc(agentToolsRpc);
   return useMutation({
     mutationFn: async (request: LaunchRequest) => {
       const { issue, action } = request;
@@ -230,14 +254,38 @@ export function useLaunchAgent() {
         stateColor: state.color,
         action,
       };
+      // Hooks are a Claude Code feature; a failure to write them never blocks the launch.
+      const hooks =
+        request.agent.agent.id === "claude"
+          ? await prepareHooks({
+              issue: {
+                identifier: issue.identifier,
+                title: issue.title,
+                children: issue.children.map(({ identifier, title }) => ({ identifier, title })),
+              },
+              guidance: request.guidance,
+            }).catch(() => null)
+          : null;
+      const config = agentConfig(request.agent);
+      // Without the tools the agent still starts; its prompt then names tools it does not have.
+      const tools = needsLinearTools(request.guidance)
+        ? await prepareTools({
+            root: issue.identifier,
+            home: issue.identifier,
+            keyScope: request.keyScope,
+            workspaceId: workspace.id,
+            config,
+          }).catch(() => null)
+        : null;
       const agent = {
-        config: agentConfig(request.agent),
+        config: withLinearTools(withHookPlugin(config, hooks?.pluginDir ?? null), tools),
         title: agentTitle(action, issue),
         prompt: request.prompt,
         labels: {
           [AGENT_LABELS.issue]: issue.identifier,
           [AGENT_LABELS.action]: action,
           ...(request.keyScope ? { [AGENT_LABELS.project]: request.keyScope } : {}),
+          ...(tools ? { [AGENT_LABELS.tools]: tools.grantId } : {}),
         },
       };
       // The daemon starts the agent once the map is ready, so agentId is null until then.

package/client/launch.tsx

@@ -15,6 +15,7 @@ import { modeIcon, optionLabel } from "./agent-options";
 import { useKeyScope } from "./key-scope";
 import { type LaunchChoices, useLaunchChoices } from "./launch-choices";
 import { Chip, Field, Toggle } from "./launch-fields";
+import { GuidanceToggles, useProjectGuidance } from "./launch-guidance";
 import { linearPatch, type TargetWorkspace, useLaunchAgent } from "./launch-plan";
 import { ModelBrowser } from "./model-browser";
 import { PickerModal } from "./pickers";
@@ -157,6 +158,7 @@ function LaunchComposer(props: LaunchPageProps & { issue: IssueDetail; settings:
   // Null until the user types. Until then the prompt follows the template and options.
   const [customPrompt, setCustomPrompt] = useState<string | null>(null);
   const { projectConfig } = choices;
+  const { guidance, change: changeGuidance } = useProjectGuidance(choices.project, projectConfig);
   const generated = useMemo(
     () =>
       composePrompt({
@@ -166,8 +168,9 @@ function LaunchComposer(props: LaunchPageProps & { issue: IssueDetail; settings:
         project: projectConfig,
         includeComments,
         extraInstructions: "",
+        guidance,
       }),
-    [action, issue, settings, projectConfig, includeComments],
+    [action, issue, settings, projectConfig, includeComments, guidance],
   );
   const prompt = customPrompt ?? generated;
   const styles = useMemo(() => {
@@ -271,6 +274,7 @@ function LaunchComposer(props: LaunchPageProps & { issue: IssueDetail; settings:
         patch,
         started,
         keyScope,
+        guidance,
         explore: settings.live.enabled && settings.live.mapping === "explore",
       },
       {
@@ -301,6 +305,7 @@ function LaunchComposer(props: LaunchPageProps & { issue: IssueDetail; settings:
     issue,
     prompt,
     keyScope,
+    guidance,
     queries,
     toast,
     onStarted,
@@ -443,6 +448,10 @@ function LaunchComposer(props: LaunchPageProps & { issue: IssueDetail; settings:
             />
           ) : null}
         </View>
+        <View style={styles.group}>
+          <SectionLabel theme={theme}>Agent guidance</SectionLabel>
+          <GuidanceToggles theme={theme} guidance={guidance} onChange={changeGuidance} />
+        </View>
         {launch.error ? (
           <Text accessibilityRole="alert" style={styles.error}>
             {errorMessage(launch.error)}

package/client/live-agents.tsx

@@ -1,7 +1,7 @@
 import type { PluginAgentSnapshot } from "@getpaseo/plugin";
 import { usePaseo } from "@getpaseo/plugin/client";
 import { Icon } from "@getpaseo/plugin/client/react-native";
-import { useQuery } from "@tanstack/react-query";
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
 import { useCallback, useMemo } from "react";
 import { Pressable, StyleSheet, Text, View } from "react-native";
 import {
@@ -12,9 +12,10 @@ import {
   deriveActivity,
   type FileTouch,
 } from "../shared/activity";
+import type { SubagentLog } from "../shared/live";
 import type { SubagentRun } from "../shared/subagents";
 import { MONO } from "./live-issues";
-import { useAgentTimelines } from "./live-timeline";
+import { useAgentTimelines, useSubagentLogs } from "./live-timeline";
 import { ProviderIcon } from "./provider-icon";
 import { type Theme, usePressableStyle } from "./ui";
 
@@ -22,9 +23,12 @@ import { type Theme, usePressableStyle } from "./ui";
 // have their own timelines, and provider subagents, which only report what they were asked.
 
 const CHILD_LABEL = "paseo.parent-agent-id";
-const MAX_CHILDREN = 4;
-const CHILD_COLORS = ["#e879f9", "#38bdf8", "#facc15", "#fb7185"];
+const MAX_CHILDREN = 8;
+const CHILD_COLORS = ["#e879f9", "#38bdf8", "#facc15", "#fb7185", "#4ade80", "#f97316", "#818cf8", "#2dd4bf"];
 const POLL_MS = 10_000;
+const SUBAGENT_COLORS = ["#a78bfa", "#34d399", "#f97316", "#22d3ee", "#f472b6", "#a3e635", "#fbbf24", "#60a5fa"];
+// A transcript that has not grown for this long belongs to a subagent that stopped.
+const SUBAGENT_IDLE_MS = 3 * 60_000;
 
 export type AgentStatus = PluginAgentSnapshot["status"];
 
@@ -35,13 +39,49 @@ export interface ChildAgent {
   status: AgentStatus;
   cwd: string;
   color: string;
+  workspaceId?: string | null;
+  /** The issue it works on, from its Linear label or a key at the start of its title. */
+  issueKey?: string | null;
+}
+
+const LEADING_KEY = /^\s*([A-Za-z][A-Za-z0-9]*-\d+)\b/;
+
+/** The issue a child agent works on, such as ENG-42 for "ENG-42: Add the form". */
+export function childIssueKey(labels: Readonly<Record<string, string>> | undefined, title: string | null) {
+  const key = labels?.["linear.issue"] ?? LEADING_KEY.exec(title ?? "")?.[1] ?? null;
+  return key ? key.toUpperCase() : null;
 }
 
 export interface ChildView {
   agent: ChildAgent;
   activity: Activity | null;
-  /** Works in the parent's folder, so its files can go on the same map. */
-  sameFolder: boolean;
+  /** Works in the parent's folder or a worktree of the same project, so its paths fit the map. */
+  sameRepo: boolean;
+  /** A provider subagent read from its transcript, which Paseo cannot open as an agent. */
+  subagent?: boolean;
+}
+
+const runKey = (log: SubagentLog) => `${log.type}\u0000${log.description}`;
+const runTitle = (type: string, description: string) => (description ? `${type}: ${description}` : type);
+
+/** Subagents with a transcript, as views like child agents in the parent's folder. */
+export function subagentViews(logs: readonly SubagentLog[], cwd: string, checkedAt: number): ChildView[] {
+  return logs.map((log, index) => {
+    const running = !log.finished && checkedAt - log.updatedAt < SUBAGENT_IDLE_MS;
+    return {
+      agent: {
+        id: `sub:${log.id}`,
+        title: runTitle(log.type, log.description),
+        provider: "claude",
+        status: running ? "running" : "idle",
+        cwd,
+        color: SUBAGENT_COLORS[index % SUBAGENT_COLORS.length] ?? "#a78bfa",
+      },
+      activity: deriveActivity(log.items, cwd),
+      sameRepo: true,
+      subagent: true,
+    };
+  });
 }
 
 export interface AgentMarker {
@@ -79,10 +119,52 @@ export function useChildAgents(agentId: string, polling: boolean): ChildAgent[]
       status: agent.status as AgentStatus,
       cwd: agent.cwd,
       color: CHILD_COLORS[index % CHILD_COLORS.length] ?? "#38bdf8",
+      workspaceId: agent.workspaceId ?? null,
+      issueKey: childIssueKey(agent.labels, agent.title ?? null),
     }));
   }, [query.data]);
 }
 
+const projectOf = new Map<string, string | null>();
+
+/** The Paseo project of each workspace. A workspace never changes project, so each is read once. */
+export function useWorkspaceProjects(workspaceIds: readonly (string | null | undefined)[]) {
+  const paseo = usePaseo();
+  const ids = useMemo(
+    () => [...new Set(workspaceIds.filter((id): id is string => Boolean(id)))].sort(),
+    [workspaceIds],
+  );
+  const query = useQuery({
+    queryKey: ["linear", "live", "workspace-projects", ids],
+    queryFn: async () => {
+      await Promise.all(
+        ids
+          .filter((id) => !projectOf.has(id))
+          .map(async (id) => {
+            const handle = paseo.workspaces.ref(id);
+            const info = await handle.refresh().catch(() => null);
+            projectOf.set(id, info?.projectId ?? handle.projectId ?? null);
+          }),
+      );
+      return new Map(ids.map((id) => [id, projectOf.get(id) ?? null]));
+    },
+    enabled: ids.length > 0,
+    staleTime: Number.POSITIVE_INFINITY,
+    placeholderData: keepPreviousData,
+  });
+  return query.data;
+}
+
+/** Both workspaces belong to one Paseo project, so a worktree's paths match the parent's. */
+export function sameProject(
+  projects: ReadonlyMap<string, string | null> | undefined,
+  a: string | null | undefined,
+  b: string | null | undefined,
+): boolean {
+  const first = a ? projects?.get(a) : null;
+  return Boolean(first) && first === (b ? projects?.get(b) : null);
+}
+
 export function sameFolder(a: string, b: string): boolean {
   return a.replace(/\/+$/, "") === b.replace(/\/+$/, "");
 }
@@ -112,7 +194,7 @@ export function agentMarkers(input: {
   }
   for (const child of input.children) {
     const current = child.activity?.current;
-    if (child.agent.status !== "running" || !child.sameFolder || !current) continue;
+    if (child.agent.status !== "running" || !child.sameRepo || !current) continue;
     add(markers, current.paths, {
       key: child.agent.id,
       kind: "child",
@@ -250,7 +332,7 @@ export function AgentsList(props: {
         detail={props.current?.text ?? null}
         live={parentRunning}
       />
-      {props.childAgents.map(({ agent, activity, sameFolder: shared }) => (
+      {props.childAgents.map(({ agent, activity, sameRepo: shared, subagent: subagentView }) => (
         <AgentRow
           key={agent.id}
           theme={theme}
@@ -258,10 +340,10 @@ export function AgentsList(props: {
           icon="provider"
           provider={agent.provider}
           title={agent.title}
-          status={STATUS_COPY[agent.status] ?? agent.status}
+          status={subagentView && agent.status !== "running" ? "Done" : (STATUS_COPY[agent.status] ?? agent.status)}
           detail={shared ? (activity?.current?.text ?? null) : `In ${agent.cwd.split("/").pop() ?? agent.cwd}`}
           live={agent.status === "running"}
-          onPress={onOpenAgent ? open(agent.id) : undefined}
+          onPress={onOpenAgent && !subagentView ? open(agent.id) : undefined}
         />
       ))}
       {props.subagents.map((run) => (
@@ -285,7 +367,7 @@ export function AgentsList(props: {
 function mergeTouches(own: readonly FileTouch[], children: readonly ChildView[]): FileTouch[] {
   const merged = new Map(own.map((file) => [file.path, { ...file }]));
   for (const child of children) {
-    if (!child.sameFolder) continue;
+    if (!child.sameRepo) continue;
     for (const file of child.activity?.files ?? []) {
       const known = merged.get(file.path);
       if (!known) {
@@ -307,26 +389,43 @@ export function useLiveAgents(input: {
   theme: Theme;
   agentId: string;
   cwd: string;
+  workspaceId: string | null;
   status: AgentStatus;
   provider: string;
   activity: Activity;
 }) {
   const { theme, agentId, cwd, status, provider, activity } = input;
   const children = useChildAgents(agentId, status === "running");
+  const projects = useWorkspaceProjects(
+    useMemo(() => [input.workspaceId, ...children.map((child) => child.workspaceId)], [input.workspaceId, children]),
+  );
   const ids = useMemo(() => children.map((child) => child.id), [children]);
   const timelines = useAgentTimelines(ids);
+  const logs = useSubagentLogs(
+    agentId,
+    provider.split("/")[0] === "claude" && activity.subagents.length > 0,
+    status === "running",
+  );
+  const subViews = useMemo(() => subagentViews(logs.runs, cwd, logs.checkedAt), [logs, cwd]);
   const views = useMemo(
-    () =>
-      children.map((agent): ChildView => {
+    () => [
+      ...children.map((agent): ChildView => {
         const timeline = timelines.get(agent.id);
         return {
           agent,
           activity: timeline ? deriveActivity(timeline.items, agent.cwd) : null,
-          sameFolder: sameFolder(agent.cwd, cwd),
+          sameRepo: sameFolder(agent.cwd, cwd) || sameProject(projects, input.workspaceId, agent.workspaceId),
         };
       }),
-    [children, timelines, cwd],
+      ...subViews,
+    ],
+    [children, timelines, cwd, subViews, projects, input.workspaceId],
   );
+  // Subagents with a transcript show as agents; the rest only report what they were asked.
+  const subagents = useMemo(() => {
+    const covered = new Set(logs.runs.map(runKey));
+    return activity.subagents.filter((run) => !covered.has(run.key));
+  }, [activity.subagents, logs.runs]);
   const markers = useMemo(
     () =>
       agentMarkers({
@@ -335,19 +434,27 @@ export function useLiveAgents(input: {
         working: status === "running",
         current: activity.current,
         children: views,
-        subagents: activity.subagents,
+        subagents,
       }),
-    [theme, provider, status, activity.current, activity.subagents, views],
+    [theme, provider, status, activity.current, subagents, views],
   );
   const files = useMemo(() => mergeTouches(activity.files, views), [activity.files, views]);
   const dirs = useMemo(
     (): DirTouch[] => [
       ...activity.dirs,
-      ...views.flatMap((view) => (view.sameFolder ? (view.activity?.dirs ?? []) : [])),
+      ...views.flatMap((view) => (view.sameRepo ? (view.activity?.dirs ?? []) : [])),
     ],
     [activity.dirs, views],
   );
-  return { children: views, markers, files, dirs };
+  // A subagent's row in the feed shows what it does now.
+  const events = useMemo(() => {
+    const doing = new Map(subViews.map((view) => [view.agent.title, view.activity?.current?.text ?? null]));
+    return activity.events.map((event) => {
+      const now = event.kind === "agent" ? doing.get(event.text) : undefined;
+      return now ? { ...event, detail: now } : event;
+    });
+  }, [activity.events, subViews]);
+  return { children: views, subagents, markers, files, dirs, events };
 }
 
 /** An agent that moves over the graph to what it works on. */
@@ -358,6 +465,8 @@ export interface CursorAgent {
   color: string;
   provider: string | null;
   focus: AgentFocus | null;
+  /** Where it hovers when its focus is not on the graph: the issue it works on. */
+  home: AgentFocus | null;
   running: boolean;
   /** What it does now, such as "Read page.tsx". */
   caption: string | null;
@@ -371,6 +480,8 @@ export function cursorAgents(input: {
   working: boolean;
   activity: Activity;
   children: readonly ChildView[];
+  /** Subagents with no cursor of their own, which circle the agent instead. */
+  subagents: readonly SubagentRun[];
 }): CursorAgent[] {
   const { activity } = input;
   const name = input.provider ? input.provider.charAt(0).toUpperCase() + input.provider.slice(1) : "Agent";
@@ -382,24 +493,28 @@ export function cursorAgents(input: {
       color: input.theme.colors.accent,
       provider: input.provider,
       focus: activity.focus,
+      home: null,
       running: input.working,
       caption: input.working ? (activity.current?.text ?? null) : null,
-      satellites: input.working ? activity.subagents.filter((run) => run.status === "running").length : 0,
+      satellites: input.working ? input.subagents.filter((run) => run.status === "running").length : 0,
     },
   ];
   for (const child of input.children) {
     // Paths are relative to each agent's folder, so only agents in this folder fit the graph.
-    if (!child.sameFolder || !child.activity) continue;
+    if (!child.sameRepo) continue;
     const running = child.agent.status === "running";
+    // Finished subagents can be many, so only working ones get a cursor.
+    if (child.subagent && !running) continue;
     agents.push({
       id: child.agent.id,
       kind: "child",
       label: child.agent.title,
       color: child.agent.color,
       provider: null,
-      focus: child.activity.focus,
+      focus: child.activity?.focus ?? null,
+      home: child.agent.issueKey ? { kind: "issue", key: child.agent.issueKey } : null,
       running,
-      caption: running ? (child.activity.current?.text ?? null) : null,
+      caption: running ? (child.activity?.current?.text ?? null) : null,
       satellites: 0,
     });
   }

package/client/live-cursor.tsx

@@ -38,6 +38,8 @@ export interface CursorProps {
   hover(id: string): Point | null;
   /** Canvas width, to keep the caption inside it. */
   width: number;
+  /** One over the graph zoom, so the cursor keeps its size on screen. */
+  inverse: Animated.AnimatedInterpolation<number>;
   reduce: boolean;
 }
 
@@ -259,7 +261,7 @@ export const AgentCursor = memo(function AgentCursor(props: CursorProps) {
   return (
     <Animated.View
       pointerEvents="none"
-      style={[styles.anchor, { transform: [{ translateX: motion.x }, { translateY: motion.y }] }]}
+      style={[styles.anchor, { transform: [{ translateX: motion.x }, { translateY: motion.y }, { scale: props.inverse }] }]}
     >
       <Animated.View style={styles.float}>
         {agent.running ? <Animated.View style={styles.halo} /> : null}