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

package/client/connect.tsx

@@ -1,10 +1,11 @@
 import { useRpc } from "@getpaseo/plugin/client";
-import { Icon, TextInput, useToast } from "@getpaseo/plugin/client/react-native";
+import { TextInput, useToast } from "@getpaseo/plugin/client/react-native";
 import { ExternalLink } from "@getpaseo/plugin/client/ui";
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { useCallback, useMemo, useState } from "react";
 import { Text, View } from "react-native";
 import { authSaveRpc } from "../shared/linear";
+import { PluginIcon } from "./plugin-icon";
 import { Button, errorMessage, type Theme } from "./ui";
 
 export const LINEAR_KEY_SETTINGS_URL = "https://linear.app/settings/account/security";
@@ -121,7 +122,7 @@ export function ConnectCard({ theme, compact }: { theme: Theme; compact: boolean
     <View style={styles.root}>
       <View style={styles.card}>
         <View style={styles.header}>
-          <Icon name="SquareKanban" size={22} color={colors.foreground} />
+          <PluginIcon size={22} color={colors.foreground} theme={theme} />
           <Text style={styles.title}>Connect Linear</Text>
         </View>
         <Text style={styles.body}>

package/client/launch-assignments.tsx

@@ -0,0 +1,182 @@
+import { Icon } from "@getpaseo/plugin/client/react-native";
+import { useCallback, useMemo, useState } from "react";
+import { Text, View } from "react-native";
+import type { IssueDetail } from "../shared/linear";
+import { type AgentPicks, optionLabel, resolveAgent } from "./agent-options";
+import type { LaunchChoices } from "./launch-choices";
+import { Chip } from "./launch-fields";
+import { agentLabel, type SubIssueAgent } from "./launch-plan";
+import { ModelBrowser } from "./model-browser";
+import { PickerModal } from "./pickers";
+import { ProviderIcon } from "./provider-icon";
+import { IconButton, type Theme } from "./ui";
+
+// The user picks an agent for some sub-issues. The agent that starts gets them in its prompt
+// and hands each one off with start_agent, which runs it on the chosen agent.
+
+type Picks = Record<string, AgentPicks>;
+
+/** The agents chosen for sub-issues, in the order of the sub-issues. */
+export function useSubIssueAgents(issue: IssueDetail, choices: LaunchChoices) {
+  const [picks, setPicks] = useState<Picks>({});
+  const { agents, remembered } = choices;
+  const leadAgent = choices.agent?.agent.id ?? null;
+  const leadMode = choices.agent?.mode?.id ?? null;
+  const assignments = useMemo((): SubIssueAgent[] => {
+    const result: SubIssueAgent[] = [];
+    for (const child of issue.children) {
+      const pick = picks[child.identifier];
+      if (!pick) continue;
+      // An agent of the same provider as the lead runs in the lead's mode.
+      const mode = pick.mode ?? (pick.agent === leadAgent ? leadMode : null);
+      const agent = resolveAgent(agents, { ...pick, mode }, "", remembered);
+      if (agent) result.push({ identifier: child.identifier, agent });
+    }
+    return result;
+  }, [issue.children, picks, agents, remembered, leadAgent, leadMode]);
+  const choose = useCallback((identifier: string, pick: AgentPicks | null) => {
+    setPicks((current) => {
+      const { [identifier]: _previous, ...others } = current;
+      return pick ? { ...others, [identifier]: pick } : others;
+    });
+  }, []);
+  return { assignments, picks, choose };
+}
+
+type Open = { identifier: string; kind: "model" | "effort" } | null;
+
+export function SubIssueAgents(props: {
+  theme: Theme;
+  issue: IssueDetail;
+  choices: LaunchChoices;
+  state: ReturnType<typeof useSubIssueAgents>;
+  /** Why the section cannot be used, or null. */
+  blocked: string | null;
+}) {
+  const { theme, issue, choices, state, blocked } = props;
+  const { colors } = theme;
+  const [open, setOpen] = useState<Open>(null);
+  const styles = useMemo(
+    () => ({
+      hint: { color: colors.foregroundMuted, fontSize: 12 },
+      row: {
+        flexDirection: "row" as const,
+        flexWrap: "wrap" as const,
+        alignItems: "center" as const,
+        columnGap: 8,
+        rowGap: 2,
+        paddingVertical: 4,
+      },
+      issue: { flexDirection: "row" as const, alignItems: "center" as const, gap: 8, flexGrow: 1, flexBasis: 220, minWidth: 0 },
+      key: { color: colors.foregroundMuted, fontSize: 12, fontWeight: "500" as const },
+      title: { flex: 1, color: colors.foreground, fontSize: 14 },
+      controls: { flexDirection: "row" as const, alignItems: "center" as const, gap: 2 },
+    }),
+    [colors],
+  );
+  const byKey = useMemo(
+    () => new Map(state.assignments.map((entry) => [entry.identifier, entry.agent])),
+    [state.assignments],
+  );
+  const close = useCallback(() => setOpen(null), []);
+  const { choose } = state;
+  const selectModel = useCallback(
+    (agentId: string, modelId: string) => {
+      if (open) choose(open.identifier, { agent: agentId, model: modelId, effort: null, mode: null });
+      setOpen(null);
+    },
+    [open, choose],
+  );
+  const selectEffort = useCallback(
+    (effort: string) => {
+      const pick = open ? state.picks[open.identifier] : undefined;
+      if (open && pick) choose(open.identifier, { ...pick, effort });
+      setOpen(null);
+    },
+    [open, state.picks, choose],
+  );
+  if (blocked) return <Text style={styles.hint}>{blocked}</Text>;
+  const muted = colors.foregroundMuted;
+  const current = open ? byKey.get(open.identifier) : undefined;
+  return (
+    <View>
+      <Text style={styles.hint}>
+        Choose an agent for a sub-issue, and the agent you start hands that sub-issue to it. It does the other sub-issues itself, or hands them off when Hand off work to Paseo agents is on.
+      </Text>
+      {issue.children.map((child) => {
+        const agent = byKey.get(child.identifier);
+        const label = agent ? `${agent.agent.label} · ${agent.model.label}` : "Not assigned";
+        return (
+          <View key={child.identifier} style={styles.row}>
+            <View style={styles.issue}>
+              <Text style={styles.key}>{child.identifier}</Text>
+              <Text style={styles.title} numberOfLines={1}>
+                {child.title}
+              </Text>
+            </View>
+            <View style={styles.controls}>
+              <Chip
+                theme={theme}
+                icon={
+                  agent ? (
+                    <ProviderIcon provider={agent.agent.id} iconSvg={agent.agent.iconSvg} size={16} color={muted} />
+                  ) : (
+                    <Icon name="Bot" size={16} color={muted} />
+                  )
+                }
+                value={label}
+                accessibilityLabel={`Agent for ${child.identifier}: ${label}`}
+                disabled={choices.agents.length === 0}
+                onPress={() => setOpen({ identifier: child.identifier, kind: "model" })}
+              />
+              {agent?.effort ? (
+                <Chip
+                  theme={theme}
+                  icon={<Icon name="Brain" size={16} color={muted} />}
+                  value={optionLabel(agent.effort)}
+                  accessibilityLabel={`Thinking for ${child.identifier}: ${optionLabel(agent.effort)}`}
+                  onPress={() => setOpen({ identifier: child.identifier, kind: "effort" })}
+                />
+              ) : null}
+              {agent ? (
+                <IconButton
+                  theme={theme}
+                  icon="X"
+                  label={`Remove the agent for ${child.identifier}`}
+                  onPress={() => choose(child.identifier, null)}
+                />
+              ) : null}
+            </View>
+          </View>
+        );
+      })}
+      {open?.kind === "model" ? (
+        <ModelBrowser
+          theme={theme}
+          agents={choices.agents}
+          agentId={current?.agent.id ?? null}
+          modelId={current?.model.id ?? null}
+          onClose={close}
+          onSelect={selectModel}
+        />
+      ) : null}
+      {open?.kind === "effort" && current ? (
+        <PickerModal
+          theme={theme}
+          title={`Thinking for ${open.identifier}`}
+          icon="Brain"
+          open
+          options={current.model.efforts.map((entry) => ({ value: entry.id, label: optionLabel(entry) }))}
+          value={current.effort?.id ?? null}
+          onClose={close}
+          onSelect={selectEffort}
+        />
+      ) : null}
+    </View>
+  );
+}
+
+/** Names for the prompt: each sub-issue key with its agent. */
+export function promptAssignments(assignments: readonly SubIssueAgent[]) {
+  return assignments.map((entry) => ({ identifier: entry.identifier, label: agentLabel(entry.agent) }));
+}

package/client/launch-choices.ts

@@ -2,8 +2,9 @@ import { usePaseo } from "@getpaseo/plugin/client";
 import { useQuery } from "@tanstack/react-query";
 import { useCallback, useMemo, useState } from "react";
 import type { IssueDetail } from "../shared/linear";
-import type { AgentAction, LinearSettings } from "../shared/settings";
+import { type AgentAction, type LinearSettings, projectDefaults, projectEnabled } from "../shared/settings";
 import { type AgentPicks, resolveAgent } from "./agent-options";
+import { loadAgentPreferences } from "./agent-preferences";
 import {
   defaultProjectId,
   type Placement,
@@ -40,7 +41,15 @@ export function useLaunchChoices(input: {
   target: TargetWorkspace | null;
 }) {
   const { issue, settings, action } = input;
-  const projects = useProjects();
+  const allProjects = useProjects();
+  // Projects where Linear is off are not offered as launch targets.
+  const projects = useMemo(
+    () => ({
+      ...allProjects,
+      data: allProjects.data?.filter((entry) => projectEnabled(settings.access, entry.projectId)),
+    }),
+    [allProjects, settings.access],
+  );
   const providers = useProviders();
   const { target } = input;
   const prNumber = action === "review" ? pullRequestNumber(issue) : null;
@@ -52,10 +61,15 @@ export function useLaunchChoices(input: {
   const [projectChoice, setProjectChoice] = useState<string | null>(null);
   const [placementChoice, setPlacementChoice] = useState<Placement | null>(null);
   const [picks, setPicks] = useState<AgentPicks>(NO_PICKS);
-  const projectId =
+  const [remembered] = useState(loadAgentPreferences);
+  const preferredId =
     projectChoice ??
     defaultProjectId({ target, teamId: issue.team.id, settings, projects: projects.data });
-  const project = projects.data?.find((entry) => entry.projectId === projectId) ?? null;
+  const project =
+    projects.data?.find((entry) => entry.projectId === preferredId) ??
+    (projectChoice ? null : (projects.data?.[0] ?? null));
+  const projectId = project?.projectId ?? preferredId;
+  const defaults = projectDefaults(settings, projectId);
   const placements = useMemo(
     () =>
       placementOptions({
@@ -72,10 +86,10 @@ export function useLaunchChoices(input: {
     placements,
     placementChoice,
     action,
-    settings.launch.isolation,
+    defaults.launch.isolation,
   );
   const agents = providers.data ?? [];
-  const agent = resolveAgent(agents, picks, settings.launch.provider);
+  const agent = resolveAgent(agents, picks, defaults.launch.provider, remembered);
   const chooseProject = useCallback((value: string) => {
     setProjectChoice(value);
     setPlacementChoice(null);
@@ -112,6 +126,9 @@ export function useLaunchChoices(input: {
     prNumber,
     project,
     projectConfig: settings.projects.find((entry) => entry.projectId === projectId) ?? null,
+    /** Launch and tool settings with the project's own values applied. */
+    defaults,
+    remembered,
     placements,
     placement,
     chooseProject,

package/client/launch-guidance.tsx

@@ -0,0 +1,103 @@
+import { useSettings } from "@getpaseo/plugin/client";
+import { useCallback, useMemo, useState } from "react";
+import { Switch, Text, View } from "react-native";
+import {
+  GUIDANCE_KEYS,
+  type Guidance,
+  GuidanceSchema,
+  linearSettings,
+  type ProjectConfig,
+  type ToolSettings,
+  withProjectGuidance,
+} from "../shared/settings";
+import type { PaseoProjectOption } from "./queries";
+import type { Theme } from "./ui";
+
+// Launch options that add instructions to the prompt. Each project keeps its own choices, so
+// the next launch in the project starts with them.
+
+const DEFAULT_GUIDANCE = GuidanceSchema.parse({});
+
+const COPY: Record<(typeof GUIDANCE_KEYS)[number], { label: string; hint: string }> = {
+  updateLinear: {
+    label: "Keep Linear updated",
+    hint: "The agent edits the issue description and checks off task list items as it works, with the plugin's Linear tools. It posts no comments. Todos start with issue keys, so status sync can move each sub-issue.",
+  },
+  subagentKeys: {
+    label: "Subagents state their issue key",
+    hint: "Subagents open with the key of the issue they work on and state the new key when it changes. Claude agents also get a hook that tells each subagent.",
+  },
+  paseoSubagents: {
+    label: "Hand off work to Paseo agents",
+    hint: "The agent starts one Paseo agent for each sub-issue with the plugin's tools, on its own provider and model. Each one checks off its own items, and Linear Live shows its work.",
+  },
+};
+
+/** The project's guidance, changed locally at once and saved to the project in the background. */
+export function useProjectGuidance(project: PaseoProjectOption | null, config: ProjectConfig | null) {
+  const settings = useSettings(linearSettings);
+  const [edits, setEdits] = useState<Record<string, Guidance>>({});
+  const guidance = (project ? edits[project.projectId] : undefined) ?? config?.guidance ?? DEFAULT_GUIDANCE;
+  const change = useCallback(
+    (key: (typeof GUIDANCE_KEYS)[number], value: boolean) => {
+      if (!project) return;
+      const next = { ...guidance, [key]: value };
+      setEdits((current) => ({ ...current, [project.projectId]: next }));
+      if (settings.status === "ready") void settings.save(withProjectGuidance(settings.values, project, next), settings.revision);
+    },
+    [project, guidance, settings],
+  );
+  return { guidance, change };
+}
+
+/** The hint of an option whose Linear tools are off or limited, or null for the usual hint. */
+function toolsHint(key: (typeof GUIDANCE_KEYS)[number], tools: ToolSettings): string | null {
+  if (key === "paseoSubagents" && !tools.enabled) {
+    return "This needs the plugin's Linear tools, which are off for this project. Turn them on in Linear settings, under Agents.";
+  }
+  if (key === "updateLinear" && !(tools.enabled && tools.allowEdits)) {
+    return "Todos start with issue keys, so status sync can move each sub-issue. The agent cannot edit the issue, because the Linear tools or description edits are off for this project.";
+  }
+  return null;
+}
+
+export function GuidanceToggles(props: {
+  theme: Theme;
+  guidance: Guidance;
+  tools: ToolSettings;
+  onChange(key: (typeof GUIDANCE_KEYS)[number], value: boolean): void;
+}) {
+  const { colors } = props.theme;
+  const styles = useMemo(
+    () => ({
+      row: { flexDirection: "row" as const, alignItems: "center" as const, gap: 10, paddingVertical: 4 },
+      body: { flex: 1, gap: 2 },
+      label: { color: colors.foreground, fontSize: 14 },
+      hint: { color: colors.foregroundMuted, fontSize: 12 },
+      track: { true: colors.accent, false: colors.surface2 },
+    }),
+    [colors],
+  );
+  return (
+    <View>
+      {GUIDANCE_KEYS.map((key) => {
+        const blocked = key === "paseoSubagents" && !props.tools.enabled;
+        return (
+          <View key={key} style={styles.row}>
+            <View style={styles.body}>
+              <Text style={styles.label}>{COPY[key].label}</Text>
+              <Text style={styles.hint}>{toolsHint(key, props.tools) ?? COPY[key].hint}</Text>
+            </View>
+            <Switch
+              accessibilityLabel={COPY[key].label}
+              value={props.guidance[key] && !blocked}
+              disabled={blocked}
+              onValueChange={(value) => props.onChange(key, value)}
+              trackColor={styles.track}
+            />
+          </View>
+        );
+      })}
+    </View>
+  );
+}

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,13 @@ import {
   updateIssueRpc,
   type WorkflowState,
 } from "../shared/linear";
+import { agentHooksRpc } from "../shared/agent-hooks";
+import { type Assignment, 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 AgentSelection, agentConfig } from "./agent-options";
+import type { AgentAction, Guidance, Isolation, LinearSettings, ToolSettings } from "../shared/settings";
+import { type AgentSelection, agentConfig, optionLabel } from "./agent-options";
+import { rememberLaunch } from "./agent-preferences";
 import type { PaseoProjectOption } from "./queries";
 import { errorMessage } from "./ui";
 
@@ -91,10 +96,13 @@ export function placementOptions(input: {
   return options;
 }
 
-// Reviews look at existing work: the pull request, then the implementing agent's workspace.
+// Reviews look at existing work: the pull request, the implementing agent's workspace, then
+// the issue branch. Checking out a branch nobody pushed yet starts a new worktree instead.
 function preferredPlacement(action: AgentAction, isolation: Isolation): Placement[] {
-  if (action === "review") return ["pull-request", "agent-workspace", "workspace"];
-  return isolation === "worktree" ? ["worktree", "workspace"] : ["workspace"];
+  const review = action === "review";
+  const existing: Placement[] = review ? ["pull-request", "agent-workspace"] : [];
+  const fresh: Placement[] = isolation === "worktree" ? [review ? "branch" : "worktree"] : [];
+  return [...existing, ...fresh, "workspace"];
 }
 
 export function resolvePlacement(
@@ -137,23 +145,80 @@ export interface LaunchRequest {
   started: WorkflowState | null;
   /** The Paseo project whose Linear key loaded the issue. */
   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;
+  /** The tool settings of the project. */
+  tools: ToolSettings;
+  /** Agents the user chose for sub-issues. */
+  assignments: readonly SubIssueAgent[];
 }
 
-type Paseo = ReturnType<typeof usePaseo>;
+/** The agent the user chose for one sub-issue on the launch page. */
+export interface SubIssueAgent {
+  identifier: string;
+  agent: AgentSelection;
+}
+
+/** The agent's name in prompts and replies, such as "Codex · GPT-5.5 · High". */
+export function agentLabel(selection: AgentSelection): string {
+  const parts = [selection.agent.label, selection.model.label];
+  if (selection.effort) parts.push(optionLabel(selection.effort));
+  return parts.join(" · ");
+}
+
+/** The assignments as the MCP server keeps them, by issue key. */
+export function assignmentRecord(assignments: readonly SubIssueAgent[]): Record<string, Assignment> {
+  return Object.fromEntries(
+    assignments.map((entry) => [entry.identifier, { config: agentConfig(entry.agent), label: agentLabel(entry.agent) }]),
+  );
+}
+
+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 launch needs the MCP tools for Linear edits or agents on sub-issues, when they are on. */
+export const needsLinearTools = (guidance: Guidance, tools: ToolSettings, assignments: number) =>
+  tools.enabled && (guidance.updateLinear || guidance.paseoSubagents || assignments > 0);
+
+/** 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>;
+
+// Linear suggests a branch name for every issue, even when nobody has pushed that branch.
+// The plugin API passes only the daemon's message, so match its "Unknown branch" text.
+function isUnknownBranch(error: unknown): boolean {
+  return errorMessage(error).includes("Unknown branch");
+}
+
+function createIssueWorktree(paseo: Paseo, request: LaunchRequest, title: string) {
+  const { issue, project } = request;
+  return paseo.workspaces.create({
+    title,
+    source: {
+      kind: "worktree",
+      cwd: project.rootPath,
+      projectId: project.projectId,
+      action: "branch-off",
+      branchName: issue.branchName,
+    },
+  });
+}
 
-async function openWorkspace(paseo: Paseo, request: LaunchRequest) {
+export async function openWorkspace(paseo: Paseo, request: LaunchRequest) {
   const { issue, project } = request;
   if (request.placement === "worktree") {
-    return paseo.workspaces.create({
-      title: `${issue.identifier} ${issue.title}`,
-      source: {
-        kind: "worktree",
-        cwd: project.rootPath,
-        projectId: project.projectId,
-        action: "branch-off",
-        branchName: issue.branchName,
-      },
-    });
+    return createIssueWorktree(paseo, request, `${issue.identifier} ${issue.title}`);
   }
   if (request.placement === "pull-request" && request.prNumber !== null) {
     return paseo.workspaces.create({
@@ -168,16 +233,22 @@ async function openWorkspace(paseo: Paseo, request: LaunchRequest) {
     });
   }
   if (request.placement === "branch") {
-    return paseo.workspaces.create({
-      title: `Review ${issue.identifier}`,
-      source: {
-        kind: "worktree",
-        cwd: project.rootPath,
-        projectId: project.projectId,
-        action: "checkout",
-        refName: issue.branchName,
-      },
-    });
+    const title = `Review ${issue.identifier}`;
+    try {
+      return await paseo.workspaces.create({
+        title,
+        source: {
+          kind: "worktree",
+          cwd: project.rootPath,
+          projectId: project.projectId,
+          action: "checkout",
+          refName: issue.branchName,
+        },
+      });
+    } catch (error) {
+      if (!isUnknownBranch(error)) throw error;
+      return createIssueWorktree(paseo, request, title);
+    }
   }
   if (request.placement === "agent-workspace" && request.agentWorkspace) {
     return paseo.workspaces.ref(request.agentWorkspace.id);
@@ -192,17 +263,80 @@ export function useLaunchAgent() {
   const paseo = usePaseo();
   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;
       const workspace = await openWorkspace(paseo, request);
-      const agent = await workspace.agents.create({
-        config: agentConfig(request.agent),
+      const state = request.patch.stateId && request.started ? request.started : issue.state;
+      const card = {
+        identifier: issue.identifier,
+        title: issue.title,
+        url: issue.url,
+        stateName: state.name,
+        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, request.tools, request.assignments.length)
+        ? await prepareTools({
+            root: issue.identifier,
+            home: issue.identifier,
+            keyScope: request.keyScope,
+            workspaceId: workspace.id,
+            projectId: request.project.projectId,
+            config,
+            ...(request.assignments.length > 0 ? { assignments: assignmentRecord(request.assignments) } : {}),
+          }).catch(() => null)
+        : null;
+      const 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 },
-      });
+        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.
+      let agentId: string | null;
+      if (request.explore && action === "implement") {
+        const launched = await launchAfterExplore({
+          workspaceId: workspace.id,
+          identifier: issue.identifier,
+          keyScope: request.keyScope,
+          agent,
+          card,
+        });
+        agentId = launched.agentId;
+      } else {
+        agentId = (await workspace.agents.create(agent)).id;
+        void attachCard({ agentId, card }).catch(() => undefined);
+      }
       lastProjectByTeam.set(issue.team.id, request.project.projectId);
+      rememberLaunch({
+        agent: request.agent.agent.id,
+        model: request.agent.model.id,
+        effort: request.agent.effort?.id ?? null,
+        mode: request.agent.mode?.id ?? null,
+      });
       let warning: string | null = null;
       if (Object.keys(request.patch).length > 0) {
         try {
@@ -211,17 +345,7 @@ export function useLaunchAgent() {
           warning = errorMessage(error);
         }
       }
-      const state = request.patch.stateId && request.started ? request.started : issue.state;
-      const card = {
-        identifier: issue.identifier,
-        title: issue.title,
-        url: issue.url,
-        stateName: state.name,
-        stateColor: state.color,
-        action,
-      };
-      void attachCard({ agentId: agent.id, card }).catch(() => undefined);
-      return { agentId: agent.id, warning };
+      return { agentId, workspaceId: workspace.id, warning };
     },
   });
 }