@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/agent/tools/paseo-tools.js

@@ -0,0 +1,2616 @@
+import { z } from "zod";
+import { ensureValidJson } from "../../json-utils.js";
+import { AgentFeatureSchema, AgentPermissionRequestPayloadSchema, AgentListItemPayloadSchema, AgentPermissionResponseSchema, AgentSnapshotPayloadSchema, WorkspaceStateBucketSchema, } from "../../messages.js";
+import { emptyAgentFilterCriteria, filterSelectionFrom, isAgentDay, } from "@hyperdrive.bot/fleet-protocol/agent-filter";
+import { collectAgentListFacets, filterAgentList, withActiveChildCounts, } from "../agent-list-filter.js";
+import { buildStoredAgentPayload, toAgentListItemPayload, toAgentPayload, } from "../agent-projections.js";
+import { curateAgentActivity } from "../activity-curator.js";
+import { selectItemsByProjectedLimit } from "../timeline-projection.js";
+import { ensureAgentLoaded } from "../agent-loading.js";
+import { isStoredAgentProviderAvailable } from "../../persistence-hooks.js";
+import { killTerminalsForWorkspace, } from "../../workspace-archive-service.js";
+import { WaitForAgentTracker } from "../wait-for-agent-tracker.js";
+import { createAgentCommand } from "../create-agent/create.js";
+import { expandUserPath, isSameOrDescendantPath, resolvePathFromBase } from "../../path-utils.js";
+import { isReadOnlyPaseoTool } from "./read-only-surface.js";
+import { AgentRoutineSchema } from "@hyperdrive.bot/fleet-protocol/schedule/routine";
+import { normalizeScheduleCadenceArg, normalizeScheduleTimeZoneArg, resolveScheduleCreateCadence, } from "../../schedule/create-cadence.js";
+import { ScheduleRunSchema, ScheduleSummarySchema, StoredScheduleSchema, } from "@hyperdrive.bot/fleet-protocol/schedule/types";
+import { AgentModelSchema, AgentProviderEnum, AgentStatusEnum, ProviderModeSchema, ProviderSummarySchema, parseDurationString, resolveRequiredProviderModel, sanitizePermissionRequest, serializeSnapshotWithMetadata, toScheduleSummary, waitForAgentWithTimeout, } from "../mcp-shared.js";
+import { sendPromptToAgent, setupFinishNotification } from "../agent-prompt.js";
+import { respondToAgentPermission } from "../permission-response.js";
+import { archiveAgentCommand, cancelAgentRunCommand, closeAgentCommand, setAgentModeCommand, updateAgentCommand, } from "../lifecycle-command.js";
+import { WorktreeRequestError } from "../../worktree-errors.js";
+import { archiveCommand, createPaseoWorktreeCommand, listPaseoWorktreesCommand, } from "../../worktree/commands.js";
+import { registerBrowserTools } from "../../browser-tools/tools.js";
+/**
+ * Resolves the archived dimension from the tri-state field, falling back to the
+ * legacy boolean. `hide` stays the default: a list that silently includes
+ * months of archived sessions is the wrong answer to an unqualified
+ * "list agents".
+ */
+function resolveArchivedMode(archived, includeArchived) {
+    if (archived)
+        return archived;
+    if (includeArchived === true)
+        return "all";
+    return "hide";
+}
+/**
+ * Turns the two wire shapes into the single tagged selection the predicate
+ * takes.
+ *
+ * A window and an exact range are the SAME dimension, so supplying both is a
+ * contradiction rather than an intersection; the explicit range wins because it
+ * is the more specific request. A half-specified range (`from` without `to`) or
+ * an impossible day (2026-02-31) is ignored rather than silently emptying the
+ * list, because an empty result is indistinguishable from "nothing matched".
+ */
+function resolveTimeSelection(window, from, to) {
+    if (isAgentDay(from) && isAgentDay(to))
+        return { kind: "range", range: { from, to } };
+    if (window)
+        return { kind: "window", window };
+    return null;
+}
+function parseTimestamp(value) {
+    if (!value) {
+        return 0;
+    }
+    const parsed = Date.parse(value);
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+function resolveAgentListActivityTime(agent) {
+    return Math.max(parseTimestamp(agent.updatedAt), parseTimestamp(agent.lastUserMessageAt), parseTimestamp(agent.attentionTimestamp), parseTimestamp(agent.archivedAt), parseTimestamp(agent.createdAt));
+}
+function toProviderSummary(entry) {
+    return {
+        id: entry.provider,
+        label: entry.label ?? entry.provider,
+        description: entry.description ?? "",
+        enabled: entry.enabled,
+        modes: entry.modes ?? [],
+        status: entry.status === "ready" ? "available" : entry.status,
+        ...(entry.error ? { error: entry.error } : {}),
+    };
+}
+function compareAgentListItems(a, b) {
+    const attentionDelta = Number(b.requiresAttention ?? false) - Number(a.requiresAttention ?? false);
+    if (attentionDelta !== 0) {
+        return attentionDelta;
+    }
+    const statusOrder = {
+        running: 0,
+        initializing: 1,
+        idle: 2,
+        error: 3,
+        closed: 4,
+    };
+    const statusDelta = (statusOrder[a.status] ?? 999) - (statusOrder[b.status] ?? 999);
+    if (statusDelta !== 0) {
+        return statusDelta;
+    }
+    return resolveAgentListActivityTime(b) - resolveAgentListActivityTime(a);
+}
+// The two create_agent response paths both report a routine the same way.
+// Shared so neither drifts, and so neither pays a branch against the handler's
+// complexity budget.
+function describeAttachedRoutine(routine) {
+    return routine ? { scheduleId: routine.scheduleId, nextRunAt: routine.nextRunAt } : {};
+}
+function resolveScheduleProviderAndModel(params) {
+    const providerInput = params.provider?.trim() || params.defaultProvider;
+    const slashIndex = providerInput.indexOf("/");
+    if (slashIndex === -1) {
+        return { provider: providerInput };
+    }
+    const provider = providerInput.slice(0, slashIndex).trim();
+    const model = providerInput.slice(slashIndex + 1).trim();
+    if (!provider || !model) {
+        throw new Error("provider must be <provider> or <provider>/<model>");
+    }
+    return {
+        provider: provider,
+        model,
+    };
+}
+function resolveScheduleUpdateProviderAndModel(params) {
+    const providerInput = params.provider?.trim();
+    const modelInput = typeof params.model === "string" ? params.model.trim() : params.model;
+    if (params.model !== undefined && modelInput === "") {
+        throw new Error("model cannot be empty");
+    }
+    if (!providerInput) {
+        return params.model !== undefined ? { model: modelInput } : {};
+    }
+    const slashIndex = providerInput.indexOf("/");
+    if (slashIndex === -1) {
+        return {
+            provider: providerInput,
+            ...(params.model !== undefined ? { model: modelInput } : {}),
+        };
+    }
+    const provider = providerInput.slice(0, slashIndex).trim();
+    const modelFromProvider = providerInput.slice(slashIndex + 1).trim();
+    if (!provider || !modelFromProvider) {
+        throw new Error("provider must be <provider> or <provider>/<model>");
+    }
+    if (params.model === null) {
+        throw new Error("provider specifies a model but model is null");
+    }
+    if (typeof modelInput === "string" && modelInput !== modelFromProvider) {
+        throw new Error("Conflicting model values provided");
+    }
+    return {
+        provider,
+        model: modelInput ?? modelFromProvider,
+    };
+}
+function resolveScheduleUpdateCadence(input) {
+    const every = normalizeScheduleCadenceArg(input.every);
+    const cron = normalizeScheduleCadenceArg(input.cron);
+    const timeZone = normalizeScheduleTimeZoneArg(input.timezone);
+    if (every !== undefined && cron !== undefined) {
+        throw new Error("Specify at most one of every or cron");
+    }
+    if (timeZone !== undefined && cron === undefined) {
+        throw new Error("timezone can only be used with cron");
+    }
+    if (every !== undefined) {
+        return { type: "every", everyMs: parseDurationString(every) };
+    }
+    if (cron !== undefined) {
+        return {
+            type: "cron",
+            expression: cron,
+            ...(timeZone !== undefined ? { timezone: timeZone } : {}),
+        };
+    }
+    return undefined;
+}
+function resolveScheduleUpdateExpiresAt(input) {
+    if (input.expiresIn !== undefined && input.clearExpires) {
+        throw new Error("Specify at most one of expiresIn or clearExpires");
+    }
+    if (input.expiresIn !== undefined) {
+        return new Date(Date.now() + parseDurationString(input.expiresIn)).toISOString();
+    }
+    if (input.clearExpires) {
+        return null;
+    }
+    return undefined;
+}
+function buildScheduleUpdateInput(input) {
+    const cadence = resolveScheduleUpdateCadence(input);
+    const expiresAt = resolveScheduleUpdateExpiresAt(input);
+    const providerModelPatch = resolveScheduleUpdateProviderAndModel({
+        provider: input.provider,
+        model: input.model,
+    });
+    const newAgentConfig = {
+        ...(providerModelPatch.provider !== undefined ? { provider: providerModelPatch.provider } : {}),
+        ...(providerModelPatch.model !== undefined ? { model: providerModelPatch.model } : {}),
+        ...(input.mode !== undefined ? { modeId: input.mode } : {}),
+        ...(input.cwd !== undefined ? { cwd: input.cwd } : {}),
+    };
+    return {
+        id: input.id,
+        ...(input.name !== undefined ? { name: input.name } : {}),
+        ...(input.prompt !== undefined ? { prompt: input.prompt } : {}),
+        ...(cadence !== undefined ? { cadence } : {}),
+        ...(input.maxRuns !== undefined ? { maxRuns: input.maxRuns } : {}),
+        ...(expiresAt !== undefined ? { expiresAt } : {}),
+        ...(Object.keys(newAgentConfig).length > 0 ? { newAgentConfig } : {}),
+    };
+}
+function resolveChildAgentCwd(params) {
+    const lockedCwd = params.lockedCwd?.trim();
+    if (lockedCwd) {
+        return expandUserPath(lockedCwd);
+    }
+    const requestedCwd = params.requestedCwd?.trim();
+    if (!requestedCwd || !params.allowCustomCwd) {
+        return params.parentCwd;
+    }
+    return resolvePathFromBase(params.parentCwd, requestedCwd);
+}
+const TerminalSummarySchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    cwd: z.string(),
+});
+const WorktreeSummarySchema = z.object({
+    path: z.string(),
+    createdAt: z.string(),
+    branchName: z.string().optional(),
+    head: z.string().optional(),
+});
+function resolveTerminalKeyToken(key, literal) {
+    if (literal) {
+        return key;
+    }
+    switch (key) {
+        case "Enter":
+            return "\r";
+        case "Tab":
+            return "\t";
+        case "Escape":
+            return "\u001b";
+        case "Space":
+            return " ";
+        case "BSpace":
+            return "\u007f";
+        case "C-c":
+            return "\u0003";
+        case "C-d":
+            return "\u0004";
+        case "C-z":
+            return "\u001a";
+        case "C-l":
+            return "\u000c";
+        case "C-a":
+            return "\u0001";
+        case "C-e":
+            return "\u0005";
+        default:
+            return key;
+    }
+}
+export function createPaseoToolCatalog(options) {
+    const { agentManager, agentStorage, terminalManager, scheduleService, providerSnapshotManager, callerAgentId, resolveSpeakHandler, resolveCallerContext, logger, } = options;
+    const childLogger = logger.child({ module: "agent", component: "paseo-tool-catalog" });
+    const waitTracker = new WaitForAgentTracker(logger);
+    const callerContext = callerAgentId ? (resolveCallerContext?.(callerAgentId) ?? null) : null;
+    const parseToolInput = async (tool, input) => {
+        const inputSchema = tool.inputSchema;
+        if (!inputSchema) {
+            return input;
+        }
+        const schema = typeof inputSchema === "object" &&
+            inputSchema !== null &&
+            typeof inputSchema.safeParseAsync === "function"
+            ? inputSchema
+            : z.object(inputSchema).passthrough();
+        return schema.parseAsync(input);
+    };
+    const tools = new Map();
+    const registerTool = (name, config, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Tool handlers are schema-validated at registration boundaries.
+    handler) => {
+        // Read-only gate (JARVIS-V1-SPEC §6). Allowlist, so a mutating tool added
+        // later fails closed instead of silently joining a read-only surface.
+        if (options.readOnly && !isReadOnlyPaseoTool(name)) {
+            return;
+        }
+        tools.set(name, {
+            name,
+            title: config.title,
+            description: config.description ?? name,
+            inputSchema: config.inputSchema,
+            outputSchema: config.outputSchema,
+            handler: handler,
+        });
+    };
+    const toCatalog = () => ({
+        tools,
+        getTool(name) {
+            return tools.get(name);
+        },
+        async executeTool(name, input, context = {}) {
+            const tool = tools.get(name);
+            if (!tool) {
+                throw new Error(`Paseo tool not found: ${name}`);
+            }
+            return tool.handler(await parseToolInput(tool, input), context);
+        },
+    });
+    const buildScheduleExpiry = (expiresIn) => {
+        return expiresIn === undefined
+            ? undefined
+            : new Date(Date.now() + parseDurationString(expiresIn)).toISOString();
+    };
+    const resolveCallerAgent = () => {
+        if (!callerAgentId) {
+            return null;
+        }
+        const parentAgent = agentManager.getAgent(callerAgentId);
+        if (!parentAgent) {
+            throw new Error(`Parent agent ${callerAgentId} not found`);
+        }
+        return parentAgent;
+    };
+    const resolveScopedCwd = (requestedCwd, opts) => {
+        const callerAgent = resolveCallerAgent();
+        if (callerAgent) {
+            return resolveChildAgentCwd({
+                parentCwd: callerAgent.cwd,
+                requestedCwd,
+                lockedCwd: callerContext?.lockedCwd,
+                allowCustomCwd: callerContext?.allowCustomCwd ?? true,
+            });
+        }
+        const trimmedCwd = requestedCwd?.trim();
+        if (!trimmedCwd) {
+            if (opts?.required) {
+                throw new Error("cwd is required");
+            }
+            throw new Error("cwd is required outside an agent-scoped session");
+        }
+        return expandUserPath(trimmedCwd);
+    };
+    async function resolveTerminalWorkspaceId(resolvedCwd) {
+        // An agent-spawned terminal belongs to the caller agent's workspace. Only if
+        // the caller has no workspace do we mint one for the cwd.
+        const callerAgent = callerAgentId ? agentManager.getAgent(callerAgentId) : null;
+        if (callerAgent?.workspaceId) {
+            return callerAgent.workspaceId;
+        }
+        if (!options.ensureWorkspaceForCreate) {
+            throw new Error(callerAgentId
+                ? `Caller agent ${callerAgentId} has no workspace and workspace minting is not configured`
+                : "workspaceId is required outside an agent-scoped session");
+        }
+        return options.ensureWorkspaceForCreate(resolvedCwd);
+    }
+    function resolveWorkspaceIdForRename(requestedWorkspaceId) {
+        const explicitWorkspaceId = requestedWorkspaceId?.trim();
+        if (explicitWorkspaceId) {
+            return explicitWorkspaceId;
+        }
+        if (callerAgentId) {
+            const callerAgent = resolveCallerAgent();
+            if (!callerAgent?.workspaceId) {
+                throw new Error(`Caller agent ${callerAgentId} has no current workspace`);
+            }
+            return callerAgent.workspaceId;
+        }
+        throw new Error("workspaceId is required outside an agent-scoped session");
+    }
+    const buildCallerAgentScheduleConfigExtras = (callerAgent) => {
+        return {
+            ...(callerAgent.config.thinkingOptionId
+                ? { thinkingOptionId: callerAgent.config.thinkingOptionId }
+                : {}),
+            ...(callerAgent.config.approvalPolicy
+                ? { approvalPolicy: callerAgent.config.approvalPolicy }
+                : {}),
+            ...(callerAgent.config.sandboxMode ? { sandboxMode: callerAgent.config.sandboxMode } : {}),
+            ...(typeof callerAgent.config.networkAccess === "boolean"
+                ? { networkAccess: callerAgent.config.networkAccess }
+                : {}),
+            ...(typeof callerAgent.config.webSearch === "boolean"
+                ? { webSearch: callerAgent.config.webSearch }
+                : {}),
+            ...(callerAgent.config.title ? { title: callerAgent.config.title } : {}),
+            ...(callerAgent.config.extra ? { extra: callerAgent.config.extra } : {}),
+            ...(callerAgent.config.featureValues
+                ? { featureValues: callerAgent.config.featureValues }
+                : {}),
+            ...(callerAgent.config.systemPrompt ? { systemPrompt: callerAgent.config.systemPrompt } : {}),
+            ...(callerAgent.config.mcpServers ? { mcpServers: callerAgent.config.mcpServers } : {}),
+        };
+    };
+    const buildCallerAgentScheduleConfig = (callerAgent, params) => {
+        const hasProviderOverride = params?.provider !== undefined;
+        const resolvedProviderModel = hasProviderOverride
+            ? resolveScheduleProviderAndModel({
+                provider: params?.provider,
+                defaultProvider: callerAgent.provider,
+            })
+            : null;
+        const resolvedProvider = resolvedProviderModel?.provider ?? callerAgent.provider;
+        let resolvedModel;
+        if (resolvedProviderModel?.model) {
+            resolvedModel = resolvedProviderModel.model;
+        }
+        else if (!hasProviderOverride && callerAgent.config.model) {
+            resolvedModel = callerAgent.config.model;
+        }
+        return {
+            provider: resolvedProvider,
+            cwd: params?.cwd?.trim() ? expandUserPath(params.cwd) : callerAgent.cwd,
+            ...(callerAgent.currentModeId && callerAgent.provider === resolvedProvider
+                ? {
+                    modeId: callerAgent.currentModeId,
+                }
+                : {}),
+            ...(resolvedModel ? { model: resolvedModel } : {}),
+            ...buildCallerAgentScheduleConfigExtras(callerAgent),
+        };
+    };
+    const resolveNewAgentScheduleTarget = (params) => {
+        if (!params?.provider?.trim()) {
+            throw new Error("provider is required when target is new-agent");
+        }
+        const callerAgent = resolveCallerAgent();
+        if (callerAgent) {
+            return {
+                type: "new-agent",
+                config: buildCallerAgentScheduleConfig(callerAgent, params),
+            };
+        }
+        const resolvedProviderModel = resolveScheduleProviderAndModel({
+            provider: params?.provider,
+            defaultProvider: params.provider,
+        });
+        return {
+            type: "new-agent",
+            config: {
+                provider: resolvedProviderModel.provider,
+                cwd: params?.cwd?.trim() ? expandUserPath(params.cwd) : process.cwd(),
+                ...(resolvedProviderModel.model ? { model: resolvedProviderModel.model } : {}),
+            },
+        };
+    };
+    // A schedule bound to an agent that is gone can never fire: the startup sweep
+    // completes it on sight. Fail loudly at create time instead of handing back a
+    // schedule that reads active and is already dead.
+    const assertScheduleTargetAgentExists = async (agentId) => {
+        if (agentManager.getAgent(agentId)) {
+            return;
+        }
+        const record = await agentStorage.get(agentId);
+        if (!record || record.internal) {
+            throw new Error(`Agent ${agentId} not found`);
+        }
+        if (record.archivedAt) {
+            throw new Error(`Agent ${agentId} is archived and cannot be a schedule target`);
+        }
+    };
+    const resolveScheduleCreateTarget = async (params) => {
+        const target = params.target?.trim();
+        // Default stays new-agent so callers written against the narrower schema
+        // keep the behaviour they had before target existed.
+        if (!target || target === "new-agent") {
+            return resolveNewAgentScheduleTarget({
+                ...(params.provider !== undefined ? { provider: params.provider } : {}),
+                ...(params.cwd !== undefined ? { cwd: params.cwd } : {}),
+            });
+        }
+        if (params.provider !== undefined || params.cwd !== undefined) {
+            throw new Error("provider and cwd can only be used with target new-agent");
+        }
+        if (target === "self") {
+            if (!callerAgentId) {
+                throw new Error('target "self" requires an agent-scoped session');
+            }
+            resolveCallerAgent();
+            return { type: "agent", agentId: callerAgentId };
+        }
+        await assertScheduleTargetAgentExists(target);
+        return { type: "agent", agentId: target };
+    };
+    // Recurring creates go through createOrReplace so an agent re-registering the
+    // same standing schedule refreshes it instead of minting a twin. A one-off must
+    // NOT: createOrReplace carries the existing schedule's `runs` forward, and
+    // shouldCompleteSchedule counts them against the incoming maxRuns before tick
+    // looks at nextRunAt, so replacing a schedule that has already run with
+    // maxRuns 1 completes it on the next tick without ever firing. There is also
+    // nothing to make idempotent about a one-off: two calls mean two reminders.
+    // Covered by schedule/service.test.ts "replacing a schedule that has run with
+    // maxRuns 1 buries it without firing".
+    const persistNewSchedule = async (input, oneOff) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        return oneOff ? scheduleService.create(input) : scheduleService.createOrReplace(input);
+    };
+    const ProviderModelInputSchema = AgentProviderEnum.trim()
+        .refine((value) => value.includes("/"), {
+        message: "provider must be provider/model, for example codex/gpt-5.4",
+    })
+        .refine((value) => {
+        try {
+            resolveRequiredProviderModel(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, { message: "provider must be provider/model, for example codex/gpt-5.4" });
+    const ProviderOrProviderModelInputSchema = AgentProviderEnum.trim()
+        .min(1, "provider is required")
+        .refine((value) => {
+        if (!value.includes("/")) {
+            return true;
+        }
+        try {
+            resolveRequiredProviderModel(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }, { message: "provider must be provider or provider/model, for example codex/gpt-5.4" });
+    const CreateAgentSettingsInputSchema = z
+        .object({
+        modeId: z.string().optional().describe("Session mode to configure before the first run."),
+        thinkingOptionId: z.string().optional().describe("Thinking option ID."),
+        features: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Provider-specific feature values, for example { fast_mode: true } for Codex."),
+        // OPTIONAL at the API level on purpose. A system prompt is one half of what
+        // makes a session a durable AGENT (the other is an active schedule targeting
+        // it), and that requirement is enforced by the classifier, not here: making
+        // it required would break every existing ad-hoc create for a rule that is
+        // about listing, not about creation.
+        systemPrompt: z
+            .string()
+            .optional()
+            .describe("Persistent system prompt for the agent, stored on its config. Required for the agent to appear on the Agents page (together with a schedule targeting it); optional here."),
+        // Durable identity, beside systemPrompt: what the agent is for, and the
+        // job it is hired for. Deliberately NOT the per-session `digest.goal`,
+        // which the agent self-reports and mergeDigest overwrites. Neither is part
+        // of the durable-agent classifier: that stays systemPrompt + routine,
+        // because a goal does not make something an agent.
+        goal: z
+            .string()
+            .optional()
+            .describe("The agent's standing objective, one line: why this agent exists. Durable config, stored on the agent. Not the same as the per-session digest goal, which is self-reported per run and overwritten on every patch."),
+        jobToBeDone: z
+            .string()
+            .optional()
+            .describe("The job this agent is hired for, in JTBD framing. Kept separate from goal: goal is the outcome, this is the hiring rationale."),
+    })
+        .strict();
+    const UpdateAgentSettingsInputSchema = z
+        .object({
+        modeId: z.string().optional().describe("Session mode ID."),
+        model: z.string().nullable().optional().describe("Model ID. Pass null to clear."),
+        thinkingOptionId: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Thinking option ID. Pass null to clear."),
+        features: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Provider-specific feature values, for example { fast_mode: true } for Codex."),
+        // The repair path for a locked-out agent. Without it, an agent created
+        // with an allowlist that matches nothing could not run a single tool and
+        // could not be edited out of that state, so archive-and-recreate was the
+        // only cure. `null` and `[]` both clear it, because paseo spells "every
+        // tool" as NO allowlist; a bare "*" normalises to the same thing.
+        allowedTools: z
+            .array(z.string())
+            .nullable()
+            .optional()
+            .describe('Per-run tool allowlist in Claude Code permission-rule syntax ("Bash", "Bash(git:*)", "Read", "mcp__server__tool"). A tool outside the list cannot run. Pass null or [] to clear it, which allows EVERY tool; a bare "*" entry means the same. claude provider only.'),
+        // Settable after creation too: an agent's job is often only articulated
+        // once it has run a few times, and having to archive and recreate it to
+        // write that down would defeat the point of a durable field.
+        goal: z
+            .string()
+            .optional()
+            .describe("The agent's standing objective, one line: why this agent exists. Durable config, stored on the agent. Not the same as the per-session digest goal, which is self-reported per run and overwritten on every patch."),
+        jobToBeDone: z
+            .string()
+            .optional()
+            .describe("The job this agent is hired for, in JTBD framing. Kept separate from goal: goal is the outcome, this is the hiring rationale."),
+    })
+        .strict();
+    const InspectProviderSettingsInputSchema = z
+        .object({
+        modeId: z.string().optional().describe("Draft session mode ID."),
+        model: z.string().optional().describe("Draft model ID."),
+        thinkingOptionId: z.string().optional().describe("Draft thinking option ID."),
+        features: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Draft provider feature values."),
+    })
+        .strict();
+    const AgentRelationshipInputSchema = z.discriminatedUnion("kind", [
+        z
+            .object({ kind: z.literal("subagent") })
+            .strict()
+            .describe("Create a child agent under this agent's subagent track."),
+        z
+            .object({ kind: z.literal("detached") })
+            .strict()
+            .describe("Create a root agent that does not appear in this agent's subagent track."),
+    ]);
+    const AgentCreateWorktreeTargetInputSchema = z.discriminatedUnion("kind", [
+        z
+            .object({
+            kind: z.literal("branch-off"),
+            worktreeSlug: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Optional worktree slug/path label. Omit to let Paseo generate one."),
+            branchName: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Optional git branch name. Defaults to the worktree slug."),
+            baseBranch: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Optional base branch. Defaults to the repository default branch."),
+        })
+            .strict()
+            .describe("Create a new branch in a new Paseo worktree."),
+        z
+            .object({
+            kind: z.literal("checkout-branch"),
+            branch: z.string().min(1).describe("Existing branch to check out."),
+        })
+            .strict()
+            .describe("Check out an existing branch in a new Paseo worktree."),
+        z
+            .object({
+            kind: z.literal("checkout-pr"),
+            githubPrNumber: z.number().int().positive().describe("GitHub pull request number."),
+        })
+            .strict()
+            .describe("Check out a GitHub pull request in a new Paseo worktree."),
+    ]);
+    const AgentWorkspaceInputSchema = z.discriminatedUnion("kind", [
+        z
+            .object({
+            kind: z.literal("current"),
+            cwd: z.string().optional().describe("Optional runtime cwd. Defaults to the caller's cwd."),
+        })
+            .strict()
+            .describe("Use the caller's current workspace."),
+        z
+            .object({
+            kind: z.literal("existing"),
+            workspaceId: z.string().min(1).describe("Existing workspace id to attach the agent to."),
+            cwd: z
+                .string()
+                .optional()
+                .describe("Optional runtime cwd. Defaults to the existing workspace cwd."),
+        })
+            .strict()
+            .describe("Attach the agent to an existing workspace."),
+        z
+            .object({
+            kind: z.literal("create"),
+            source: z.discriminatedUnion("kind", [
+                z
+                    .object({
+                    kind: z.literal("directory"),
+                    path: z
+                        .string()
+                        .optional()
+                        .describe("Optional directory path. Defaults to the caller's cwd."),
+                })
+                    .strict(),
+                z
+                    .object({
+                    kind: z.literal("worktree"),
+                    cwd: z
+                        .string()
+                        .optional()
+                        .describe("Optional source repository. Defaults to the caller's cwd."),
+                    target: AgentCreateWorktreeTargetInputSchema,
+                })
+                    .strict(),
+            ]),
+        })
+            .strict()
+            .describe("Create a new workspace for the agent."),
+    ]);
+    // A routine plus settings.systemPrompt is what makes an agent DURABLE rather
+    // than a one-off session. Supplying it here instead of calling create_schedule
+    // afterwards is not just fewer calls: between the two calls the agent has a
+    // persona and no schedule, which is precisely the shape of a plain session, so
+    // it is misclassified for as long as the gap lasts.
+    const CreateAgentRoutineInputSchema = AgentRoutineSchema.strict().describe("Standing routine for the agent, created in the same call. Requires settings.systemPrompt. Exactly one of at, every or cron.");
+    const commonCreateAgentInputSchema = {
+        relationship: AgentRelationshipInputSchema.describe("Whether the created agent is a subagent under you or a detached root agent."),
+        workspace: AgentWorkspaceInputSchema.describe("Workspace ownership/location for the created agent."),
+        title: z
+            .string()
+            .trim()
+            .min(1, "Title is required")
+            .max(60, "Title must be 60 characters or fewer")
+            .describe("Short descriptive title (<= 60 chars) summarizing the agent's focus."),
+        provider: ProviderModelInputSchema.describe("Required provider/model pair, for example codex/gpt-5.4."),
+        labels: z.record(z.string(), z.string()).optional().describe("Labels to set on the agent"),
+        settings: CreateAgentSettingsInputSchema.optional().describe("Initial runtime settings for the new agent."),
+        initialPrompt: z
+            .string()
+            .trim()
+            .min(1, "initialPrompt is required")
+            .describe("Required first task to run immediately after creation."),
+        routine: CreateAgentRoutineInputSchema.optional(),
+    };
+    const agentToAgentInputSchema = {
+        ...commonCreateAgentInputSchema,
+        notifyOnFinish: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Get notified when the created agent finishes, errors, or needs permission. Set false only for truly fire-and-forget agents."),
+    };
+    const canonicalTopLevelInputSchema = {
+        ...commonCreateAgentInputSchema,
+        background: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Run agent in background. If false (default), waits for completion or permission request. If true, returns immediately."),
+        notifyOnFinish: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Agent-scoped only: get notified when the created agent finishes, errors, or needs permission."),
+    };
+    const legacyTopLevelCreateAgentInputSchema = {
+        relationship: commonCreateAgentInputSchema.relationship.optional(),
+        workspace: commonCreateAgentInputSchema.workspace.optional(),
+        cwd: z
+            .string()
+            .optional()
+            .describe("Legacy top-level working directory. Prefer workspace.source.path."),
+        mode: z.string().optional().describe("Legacy session mode ID. Prefer settings.modeId."),
+        thinking: z
+            .string()
+            .optional()
+            .describe("Legacy thinking option ID. Prefer settings.thinkingOptionId."),
+        features: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Legacy feature values. Prefer settings.features."),
+        worktreeName: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Legacy worktree slug. Prefer workspace.source.target.worktreeSlug."),
+        branchName: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Legacy branch name. Prefer workspace.source.target.branchName."),
+        baseBranch: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Legacy base branch. Prefer workspace.source.target.baseBranch."),
+        refName: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Legacy branch/ref to check out. Prefer workspace.source.target.branch."),
+        githubPrNumber: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Legacy GitHub PR number. Prefer workspace.source.target.githubPrNumber."),
+    };
+    const topLevelInputSchema = {
+        ...canonicalTopLevelInputSchema,
+        ...legacyTopLevelCreateAgentInputSchema,
+    };
+    const createAgentInputSchema = callerAgentId ? agentToAgentInputSchema : topLevelInputSchema;
+    const agentToAgentCreateAgentArgsSchema = z.object(agentToAgentInputSchema).strict();
+    const canonicalTopLevelCreateAgentArgsSchema = z.object(canonicalTopLevelInputSchema).strict();
+    const topLevelCreateAgentArgsSchema = z.object(topLevelInputSchema).strict();
+    const commonSendAgentPromptInputSchema = {
+        agentId: z.string(),
+        prompt: z.string(),
+        sessionMode: z.string().optional().describe("Optional mode to set before running the prompt."),
+    };
+    const agentToAgentSendAgentPromptInputSchema = {
+        ...commonSendAgentPromptInputSchema,
+        background: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Run agent in background. Agent-scoped default is true so you can continue until the finish notification arrives. Set false only when you need a blocking response."),
+        notifyOnFinish: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Get notified when the prompted agent finishes, errors, or needs permission. Set false only for truly fire-and-forget prompts."),
+    };
+    const topLevelSendAgentPromptInputSchema = {
+        ...commonSendAgentPromptInputSchema,
+        background: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Run agent in background. If false (default), waits for completion or permission request. If true, returns immediately."),
+        notifyOnFinish: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Agent-scoped only: get notified when the prompted agent finishes, errors, or needs permission."),
+    };
+    const sendAgentPromptInputSchema = callerAgentId
+        ? agentToAgentSendAgentPromptInputSchema
+        : topLevelSendAgentPromptInputSchema;
+    const inspectProviderInputSchema = {
+        provider: ProviderOrProviderModelInputSchema.describe("Provider ID, optionally with a model ID (for example codex or codex/gpt-5.4)."),
+        cwd: z
+            .string()
+            .optional()
+            .describe("Working directory used to resolve provider feature availability."),
+        settings: InspectProviderSettingsInputSchema.optional().describe("Draft provider settings used to compute available features."),
+    };
+    if (options.voiceOnly || options.enableVoiceTools || callerContext?.enableVoiceTools) {
+        registerTool("speak", {
+            title: "Speak",
+            description: "Speak text to the user via daemon-managed voice output. Blocks until playback completes.",
+            inputSchema: {
+                text: z
+                    .string()
+                    .trim()
+                    .min(1, "text is required")
+                    .max(4000, "text must be 4000 characters or fewer"),
+            },
+            outputSchema: {
+                ok: z.boolean(),
+            },
+        }, async (args, context) => {
+            if (!callerAgentId) {
+                throw new Error("speak is only available to agent-scoped tool sessions");
+            }
+            const handler = resolveSpeakHandler?.(callerAgentId) ?? null;
+            if (!handler) {
+                throw new Error(`No speak handler registered for your session '${callerAgentId}'`);
+            }
+            await handler({
+                text: args.text,
+                callerAgentId,
+                signal: context?.signal,
+            });
+            return {
+                content: [],
+                structuredContent: ensureValidJson({ ok: true }),
+            };
+        });
+    }
+    // The judge's one mutating capability. Registered through `tools.set` rather
+    // than `registerTool` on purpose: `registerTool` applies the read-only
+    // allowlist, and this tool must be available to a read-only agent precisely
+    // BECAUSE its own gate is stricter than the allowlist. Keeping it out of
+    // READ_ONLY_PASEO_TOOLS also keeps that list honestly "reads only".
+    if (options.judgeRelayGate) {
+        const gate = options.judgeRelayGate;
+        tools.set("relay_to_agent", {
+            name: "relay_to_agent",
+            title: "Relay the user's decision to an agent",
+            description: "Pass the user's instruction to an agent you were briefed about. Only usable when the user has just told you something in this conversation; it is refused while you are processing an event. You do not act yourself, the target agent acts with its own context and permissions.",
+            inputSchema: {
+                agentId: z.string().describe("The agent to relay to. Must be one you were briefed about."),
+                message: z
+                    .string()
+                    .trim()
+                    .min(1)
+                    .max(4000)
+                    .describe("The user's instruction, in your words. Do not invent instructions."),
+            },
+            outputSchema: { ok: z.boolean(), agentId: z.string() },
+            handler: (async (args) => {
+                const decision = gate.evaluate(args.agentId);
+                if (!decision.allowed) {
+                    throw new Error(decision.detail ?? "Relay refused");
+                }
+                const target = await ensureAgentLoaded(args.agentId, {
+                    agentManager,
+                    agentStorage,
+                    logger: options.logger,
+                });
+                if (agentManager.hasInFlightRun(target.id)) {
+                    throw new Error(`Agent ${args.agentId} is mid-run; try again once it settles.`);
+                }
+                await agentManager.runAgent(target.id, args.message);
+                return {
+                    content: [],
+                    structuredContent: ensureValidJson({ ok: true, agentId: args.agentId }),
+                };
+            }),
+        });
+    }
+    if (options.voiceOnly) {
+        return toCatalog();
+    }
+    if (options.browserToolsEnabled && options.browserToolsBroker) {
+        registerBrowserTools({
+            registerTool,
+            broker: options.browserToolsBroker,
+            callerAgentId,
+            resolveCallerAgent,
+        });
+    }
+    registerTool("create_agent", {
+        title: "Create agent",
+        description: "Create an agent. Requires relationship, workspace, provider/model (for example codex/gpt-5.4), and an initial prompt. Do not guess; call list_providers and list_models first if uncertain.",
+        inputSchema: createAgentInputSchema,
+        outputSchema: {
+            agentId: z.string(),
+            type: AgentProviderEnum,
+            status: AgentStatusEnum,
+            cwd: z.string(),
+            workspaceId: z.string().optional(),
+            currentModeId: z.string().nullable(),
+            availableModes: z.array(ProviderModeSchema),
+            lastMessage: z.string().nullable().optional(),
+            permission: AgentPermissionRequestPayloadSchema.nullable().optional(),
+            guidance: z.string().optional(),
+            // Present only when the call carried a routine, i.e. when this agent
+            // came out of create_agent already durable rather than as a session.
+            scheduleId: z.string().optional(),
+            nextRunAt: z.string().nullable().optional(),
+        },
+    }, async (args) => {
+        const resolvedArgs = await resolveCreateAgentToolArgs(args);
+        const { parsedArgs, worktree } = resolvedArgs;
+        let requestedBackground;
+        let notifyOnFinish;
+        let detached;
+        if (resolvedArgs.kind === "agent-scoped") {
+            requestedBackground = true;
+            notifyOnFinish = parsedArgs.notifyOnFinish;
+            detached = resolvedArgs.relationship.kind === "detached";
+        }
+        else {
+            requestedBackground = resolvedArgs.parsedArgs.background;
+            notifyOnFinish = resolvedArgs.parsedArgs.notifyOnFinish ?? false;
+            detached = resolvedArgs.parsedArgs.relationship.kind === "detached";
+        }
+        const { snapshot, background: createdInBackground, initialPromptStarted, routine: attachedRoutine, } = await createAgentCommand({
+            agentManager,
+            agentStorage,
+            logger: childLogger,
+            paseoHome: options.paseoHome,
+            worktreesRoot: options.worktreesRoot,
+            terminalManager,
+            providerSnapshotManager,
+            createPaseoWorktree: options.createPaseoWorktree,
+            // Passed unconditionally: undefined already means "no schedule
+            // service", and a conditional spread only costs lint complexity. The
+            // ?? normalizes the null this option can carry into that undefined.
+            scheduleService: scheduleService ?? undefined,
+            ...(options.ensureWorkspaceForCreate
+                ? { ensureWorkspaceForCreate: options.ensureWorkspaceForCreate }
+                : {}),
+        }, {
+            kind: "mcp",
+            provider: parsedArgs.provider,
+            title: parsedArgs.title,
+            initialPrompt: parsedArgs.initialPrompt,
+            cwd: resolvedArgs.cwd,
+            workspaceId: resolvedArgs.workspaceId,
+            ...toCreateAgentSettingsInput(parsedArgs.settings),
+            labels: parsedArgs.labels,
+            // A routine here is what makes the created agent DURABLE instead of a
+            // session: createAgentCommand attaches the schedule before the first
+            // prompt runs, and rolls the agent back if it cannot.
+            routine: parsedArgs.routine,
+            background: requestedBackground,
+            notifyOnFinish,
+            detached,
+            callerAgentId,
+            callerContext,
+            worktree,
+        });
+        try {
+            if (!createdInBackground && initialPromptStarted) {
+                const result = await waitForAgentWithTimeout(agentManager, snapshot.id, {
+                    waitForActive: true,
+                });
+                const liveSnapshot = agentManager.getAgent(snapshot.id) ?? snapshot;
+                const responseData = {
+                    agentId: snapshot.id,
+                    type: snapshot.provider,
+                    status: result.status,
+                    cwd: liveSnapshot.cwd,
+                    ...(liveSnapshot.workspaceId ? { workspaceId: liveSnapshot.workspaceId } : {}),
+                    currentModeId: liveSnapshot.currentModeId,
+                    availableModes: liveSnapshot.availableModes,
+                    lastMessage: result.lastMessage,
+                    permission: sanitizePermissionRequest(result.permission),
+                    ...describeAttachedRoutine(attachedRoutine),
+                };
+                const validJson = ensureValidJson(responseData);
+                const response = {
+                    content: [],
+                    structuredContent: validJson,
+                };
+                return response;
+            }
+        }
+        catch (error) {
+            childLogger.error({ err: error, agentId: snapshot.id }, "Failed to run initial prompt");
+            throw error;
+        }
+        // Return immediately for async creation.
+        const currentSnapshot = agentManager.getAgent(snapshot.id) ?? snapshot;
+        const guidance = callerAgentId && notifyOnFinish && initialPromptStarted
+            ? "You will get notified when the created agent finishes, errors, or needs permission. Do not call wait_for_agent or poll for status; continue with other work until the notification arrives."
+            : undefined;
+        const response = {
+            content: [],
+            structuredContent: ensureValidJson({
+                agentId: currentSnapshot.id,
+                type: snapshot.provider,
+                status: currentSnapshot.lifecycle,
+                cwd: currentSnapshot.cwd,
+                ...(currentSnapshot.workspaceId ? { workspaceId: currentSnapshot.workspaceId } : {}),
+                currentModeId: currentSnapshot.currentModeId,
+                availableModes: currentSnapshot.availableModes,
+                lastMessage: null,
+                permission: null,
+                ...describeAttachedRoutine(attachedRoutine),
+                ...(guidance ? { guidance } : {}),
+            }),
+        };
+        return response;
+    });
+    async function resolveCreateAgentToolArgs(args) {
+        if (callerAgentId) {
+            const parsed = agentToAgentCreateAgentArgsSchema.parse(args);
+            const { cwd, workspaceId, worktree } = await resolveCreateAgentWorkspace(parsed.workspace, {
+                prompt: parsed.initialPrompt,
+            });
+            return {
+                kind: "agent-scoped",
+                parsedArgs: parsed,
+                relationship: parsed.relationship,
+                cwd,
+                workspaceId,
+                worktree,
+            };
+        }
+        const parsedArgs = normalizeTopLevelCreateAgentArgs(topLevelCreateAgentArgsSchema.parse(args));
+        if (parsedArgs.relationship.kind === "subagent") {
+            throw new Error("relationship subagent requires an agent-scoped tool session");
+        }
+        const { cwd, workspaceId, worktree } = await resolveCreateAgentWorkspace(parsedArgs.workspace, {
+            prompt: parsedArgs.initialPrompt,
+        });
+        return {
+            kind: "top-level",
+            parsedArgs,
+            cwd,
+            workspaceId,
+            worktree,
+        };
+    }
+    /**
+     * Flatten the `settings` bag onto the named fields `createAgentCommand`
+     * takes.
+     *
+     * Extracted rather than spread inline because every `settings?.x` optional
+     * chain counts toward the create handler's cyclomatic complexity, and adding
+     * `goal` and `jobToBeDone` put it at 22 against a ceiling of 20. Each new
+     * setting belongs here, not in the handler.
+     */
+    function toCreateAgentSettingsInput(settings) {
+        return {
+            thinking: settings?.thinkingOptionId,
+            features: settings?.features,
+            mode: settings?.modeId,
+            systemPrompt: settings?.systemPrompt,
+            goal: settings?.goal,
+            jobToBeDone: settings?.jobToBeDone,
+        };
+    }
+    function normalizeTopLevelCreateAgentArgs(args) {
+        const { cwd, mode, thinking, features, worktreeName, branchName, baseBranch, refName, githubPrNumber, ...canonicalCandidate } = args;
+        const settings = {
+            ...canonicalCandidate.settings,
+            ...(mode ? { modeId: mode } : {}),
+            ...(thinking ? { thinkingOptionId: thinking } : {}),
+            ...(features ? { features } : {}),
+        };
+        if (canonicalCandidate.relationship && canonicalCandidate.workspace) {
+            return canonicalTopLevelCreateAgentArgsSchema.parse({
+                ...canonicalCandidate,
+                ...(Object.keys(settings).length > 0 ? { settings } : {}),
+            });
+        }
+        if (canonicalCandidate.relationship || canonicalCandidate.workspace) {
+            throw new Error("relationship and workspace must be provided together");
+        }
+        if (!cwd?.trim()) {
+            throw new Error("cwd is required for legacy top-level create_agent calls");
+        }
+        const legacyWorktreeTarget = resolveLegacyCreateAgentWorktreeTarget({
+            worktreeName,
+            branchName,
+            baseBranch,
+            refName,
+            githubPrNumber,
+        });
+        const workspace = legacyWorktreeTarget
+            ? {
+                kind: "create",
+                source: {
+                    kind: "worktree",
+                    cwd,
+                    target: legacyWorktreeTarget,
+                },
+            }
+            : {
+                kind: "create",
+                source: {
+                    kind: "directory",
+                    path: cwd,
+                },
+            };
+        return canonicalTopLevelCreateAgentArgsSchema.parse({
+            ...canonicalCandidate,
+            relationship: { kind: "detached" },
+            workspace,
+            ...(Object.keys(settings).length > 0 ? { settings } : {}),
+        });
+    }
+    function resolveLegacyCreateAgentWorktreeTarget(input) {
+        if (input.githubPrNumber !== undefined) {
+            return {
+                kind: "checkout-pr",
+                githubPrNumber: input.githubPrNumber,
+            };
+        }
+        if (input.refName) {
+            return {
+                kind: "checkout-branch",
+                branch: input.refName,
+            };
+        }
+        if (input.worktreeName || input.branchName || input.baseBranch) {
+            return {
+                kind: "branch-off",
+                worktreeSlug: input.worktreeName,
+                branchName: input.branchName,
+                baseBranch: input.baseBranch,
+            };
+        }
+        return null;
+    }
+    async function resolveCreateAgentWorkspace(workspace, firstAgentContext) {
+        if (workspace.kind === "current") {
+            if (!callerAgentId) {
+                throw new Error("workspace current requires an agent-scoped tool session");
+            }
+            const callerAgent = resolveCallerAgent();
+            if (!callerAgent?.workspaceId) {
+                throw new Error(`Caller agent ${callerAgentId} has no current workspace`);
+            }
+            return {
+                cwd: workspace.cwd,
+                workspaceId: callerAgent.workspaceId,
+                worktree: undefined,
+            };
+        }
+        if (workspace.kind === "existing") {
+            if (!options.listActiveWorkspaces) {
+                throw new Error("Workspace lookup is not configured");
+            }
+            const existingWorkspace = (await options.listActiveWorkspaces()).find((candidate) => candidate.workspaceId === workspace.workspaceId);
+            if (!existingWorkspace) {
+                throw new Error(`Workspace ${workspace.workspaceId} not found`);
+            }
+            const cwd = workspace.cwd
+                ? resolveScopedCwd(workspace.cwd, { required: true })
+                : existingWorkspace.cwd;
+            const lockedCwd = callerContext?.lockedCwd?.trim();
+            if (lockedCwd && !isSameOrDescendantPath(expandUserPath(lockedCwd), cwd)) {
+                throw new Error(`Workspace ${workspace.workspaceId} is outside the allowed cwd`);
+            }
+            return {
+                cwd,
+                workspaceId: workspace.workspaceId,
+                worktree: undefined,
+            };
+        }
+        if (workspace.source.kind === "directory") {
+            const cwd = resolveScopedCwd(workspace.source.path, { required: true });
+            if (!options.ensureWorkspaceForCreate) {
+                throw new Error("Workspace creation is not configured");
+            }
+            return {
+                cwd,
+                workspaceId: await options.ensureWorkspaceForCreate(cwd, firstAgentContext),
+                worktree: undefined,
+            };
+        }
+        const cwd = resolveScopedCwd(workspace.source.cwd, { required: true });
+        return {
+            cwd,
+            workspaceId: undefined,
+            worktree: resolveCreateAgentWorktree(workspace.source.target),
+        };
+    }
+    function resolveCreateAgentWorktree(target) {
+        switch (target.kind) {
+            case "branch-off":
+                return {
+                    action: "branch-off",
+                    worktreeName: target.worktreeSlug,
+                    branchName: target.branchName,
+                    baseBranch: target.baseBranch,
+                };
+            case "checkout-branch":
+                return {
+                    action: "checkout",
+                    refName: target.branch,
+                };
+            case "checkout-pr":
+                return {
+                    action: "checkout",
+                    githubPrNumber: target.githubPrNumber,
+                };
+            default:
+                throw new Error("unreachable");
+        }
+    }
+    registerTool("wait_for_agent", {
+        title: "Wait for agent",
+        description: "Block until the agent requests permission or the current run completes. Returns the pending permission (if any) and recent activity summary.",
+        inputSchema: {
+            agentId: z.string().describe("Agent identifier returned by the create_agent tool"),
+        },
+        outputSchema: {
+            agentId: z.string(),
+            status: AgentStatusEnum,
+            permission: AgentPermissionRequestPayloadSchema.nullable(),
+            lastMessage: z.string().nullable(),
+        },
+    }, async ({ agentId }, { signal }) => {
+        const abortController = new AbortController();
+        const cleanupFns = [];
+        const cleanup = () => {
+            while (cleanupFns.length) {
+                const fn = cleanupFns.pop();
+                try {
+                    fn?.();
+                }
+                catch {
+                    // ignore cleanup errors
+                }
+            }
+        };
+        const forwardExternalAbort = () => {
+            if (!abortController.signal.aborted) {
+                const reason = signal?.reason ?? new Error("wait_for_agent aborted");
+                abortController.abort(reason);
+            }
+        };
+        if (signal) {
+            if (signal.aborted) {
+                forwardExternalAbort();
+            }
+            else {
+                signal.addEventListener("abort", forwardExternalAbort, { once: true });
+                cleanupFns.push(() => signal.removeEventListener("abort", forwardExternalAbort));
+            }
+        }
+        const unregister = waitTracker.register(agentId, (reason) => {
+            if (!abortController.signal.aborted) {
+                abortController.abort(new Error(reason ?? "wait_for_agent cancelled"));
+            }
+        });
+        cleanupFns.push(unregister);
+        try {
+            const result = await waitForAgentWithTimeout(agentManager, agentId, {
+                signal: abortController.signal,
+            });
+            const validJson = ensureValidJson({
+                agentId,
+                status: result.status,
+                permission: sanitizePermissionRequest(result.permission),
+                lastMessage: result.lastMessage,
+            });
+            const response = {
+                content: [],
+                structuredContent: validJson,
+            };
+            return response;
+        }
+        finally {
+            cleanup();
+        }
+    });
+    registerTool("send_agent_prompt", {
+        title: "Send agent prompt",
+        description: "Send a task to a running agent. Agent-scoped callers run in background by default; top-level callers wait by default.",
+        inputSchema: sendAgentPromptInputSchema,
+        outputSchema: {
+            success: z.boolean(),
+            status: AgentStatusEnum,
+            lastMessage: z.string().nullable().optional(),
+            permission: AgentPermissionRequestPayloadSchema.nullable().optional(),
+            guidance: z.string().optional(),
+        },
+    }, async ({ agentId, prompt, sessionMode, background = Boolean(callerAgentId), notifyOnFinish = Boolean(callerAgentId), }) => {
+        if (agentManager.hasInFlightRun(agentId)) {
+            waitTracker.cancel(agentId, "Agent run interrupted by new prompt");
+        }
+        const shouldNotifyOnFinish = Boolean(callerAgentId && notifyOnFinish && background);
+        await sendPromptToAgent({
+            agentManager,
+            agentStorage,
+            agentId,
+            prompt,
+            sessionMode,
+            logger: childLogger,
+        });
+        if (shouldNotifyOnFinish && callerAgentId) {
+            setupFinishNotification({
+                agentManager,
+                agentStorage,
+                childAgentId: agentId,
+                callerAgentId,
+                logger: childLogger,
+            });
+        }
+        // If not running in background, wait for completion
+        if (!background) {
+            const result = await waitForAgentWithTimeout(agentManager, agentId, {
+                waitForActive: true,
+            });
+            const responseData = {
+                success: true,
+                status: result.status,
+                lastMessage: result.lastMessage,
+                permission: sanitizePermissionRequest(result.permission),
+            };
+            const validJson = ensureValidJson(responseData);
+            const response = {
+                content: [],
+                structuredContent: validJson,
+            };
+            return response;
+        }
+        // Return immediately if background=true
+        // Re-fetch snapshot since the state may have changed
+        const currentSnapshot = agentManager.getAgent(agentId);
+        const responseData = {
+            success: true,
+            status: currentSnapshot?.lifecycle ?? "idle",
+            lastMessage: null,
+            permission: null,
+            ...(shouldNotifyOnFinish
+                ? {
+                    guidance: "You will get notified when the prompted agent finishes, errors, or needs permission. Do not call wait_for_agent or poll for status; continue with other work until the notification arrives.",
+                }
+                : {}),
+        };
+        const validJson = ensureValidJson(responseData);
+        const response = {
+            content: [],
+            structuredContent: validJson,
+        };
+        return response;
+    });
+    registerTool("get_agent_status", {
+        title: "Get agent status",
+        description: "Return the latest snapshot for an agent, including lifecycle state, capabilities, and pending permissions.",
+        inputSchema: {
+            agentId: z.string(),
+        },
+        outputSchema: {
+            status: AgentStatusEnum,
+            snapshot: AgentSnapshotPayloadSchema,
+        },
+    }, async ({ agentId }) => {
+        const snapshot = agentManager.getAgent(agentId);
+        if (snapshot) {
+            const structuredSnapshot = await serializeSnapshotWithMetadata(agentStorage, snapshot, childLogger);
+            return {
+                content: [],
+                structuredContent: ensureValidJson({
+                    status: snapshot.lifecycle,
+                    snapshot: structuredSnapshot,
+                }),
+            };
+        }
+        const record = await agentStorage.get(agentId);
+        if (!record || record.internal) {
+            throw new Error(`Agent ${agentId} not found`);
+        }
+        const structuredSnapshot = buildStoredAgentPayload(record, new Set(providerSnapshotManager.listRegisteredProviderIds()));
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                status: structuredSnapshot.status,
+                snapshot: structuredSnapshot,
+            }),
+        };
+    });
+    registerTool("list_agents", {
+        title: "List agents",
+        description: "List agents with the same filters the paseo UI offers. `state` is the DERIVED bucket " +
+            "the app groups by (running / pending / needs_input / attention / failed / done); " +
+            "`statuses` is the raw lifecycle and they are different questions. Open dimensions " +
+            "(tag, kanban, provider) also take a `not*` half because their complement cannot be " +
+            "enumerated; closed ones (state, origin) do not need one. The response carries `facets` " +
+            "listing every tag / kanban bucket / provider present, so you can name a value without " +
+            "guessing, plus `total` and `hasMore` for paging with `offset`.",
+        inputSchema: {
+            cwd: z
+                .string()
+                .optional()
+                .describe("Restrict to this directory and its descendants. Defaults to the caller's cwd."),
+            archived: z
+                .enum(["all", "only", "hide"])
+                .optional()
+                .describe("How to treat archived agents. Defaults to `hide`. `only` shows archived exclusively, " +
+                "which the legacy `includeArchived` boolean cannot express."),
+            includeArchived: z
+                .boolean()
+                .optional()
+                .describe('LEGACY. `true` means `archived: "all"`. Prefer `archived`.'),
+            statuses: z
+                .array(AgentStatusEnum)
+                .optional()
+                .describe("Raw LIFECYCLE status (initializing / idle / running / error / closed). Not the same " +
+                "as `state`: an `idle` agent may be pending, attention, needs_input or done."),
+            state: z
+                .array(WorkspaceStateBucketSchema)
+                .optional()
+                .describe("Derived state buckets to keep. Closed six-value set, so `except X` is expressible " +
+                "by listing the other five and no exclude half is offered."),
+            origin: z
+                .array(z.enum(["root", "delegated"]))
+                .optional()
+                .describe("`root` = human-started, `delegated` = spawned by another agent."),
+            tags: z.array(z.string()).optional().describe("Keep agents carrying ANY of these tags."),
+            notTags: z.array(z.string()).optional().describe("Drop agents carrying ANY of these tags."),
+            kanban: z
+                .array(z.string())
+                .optional()
+                .describe("Keep agents in any of these kanban buckets."),
+            notKanban: z.array(z.string()).optional().describe("Drop agents in any of these buckets."),
+            providers: z
+                .array(z.string())
+                .optional()
+                .describe("Keep agents on any of these providers."),
+            notProviders: z
+                .array(z.string())
+                .optional()
+                .describe("Drop agents on any of these providers."),
+            timeField: z
+                .enum(["created", "active", "archived"])
+                .optional()
+                .describe("Which timestamp the date filter measures. A MODE, not a second dimension: " +
+                "`created` uses createdAt, `active` (default) uses last activity, `archived` " +
+                "uses archivedAt so `window`/`from`/`to` answer 'what was archived in this " +
+                "period'. Picking `archived` implies archived agents are in scope and lifts " +
+                "the `sinceHours` recency cut for them, since the archive date is doing the " +
+                "bounding; agents that were never archived have no archive date and so match " +
+                "no window."),
+            window: z
+                .enum(["today", "3d", "7d", "30d", "stale"])
+                .optional()
+                .describe("Rolling window over `timeField`. Single-valued because the windows nest; `stale` is " +
+                "the strict complement of `30d`. Mutually exclusive with `from`/`to`."),
+            from: z
+                .string()
+                .optional()
+                .describe("Exact range start, local calendar day `YYYY-MM-DD`. Requires `to`."),
+            to: z
+                .string()
+                .optional()
+                .describe("Exact range end, inclusive, local calendar day `YYYY-MM-DD`. Requires `from`."),
+            text: z.string().optional().describe("Case-insensitive substring over title and cwd."),
+            sinceHours: z
+                .number()
+                .int()
+                .positive()
+                .max(24 * 30)
+                .optional()
+                .describe("LEGACY recency cutoff. It only ever applied to ARCHIVED agents and still does; it " +
+                "never filtered live ones. Use `window` / `from`+`to` for a real date filter."),
+            limit: z.number().int().positive().max(200).optional().default(50),
+            offset: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("Rows to skip, for reaching past `limit`. Ordering is by activity, so a concurrently " +
+                "updated agent can shift between pages; `total` tells you when you are done."),
+        },
+        outputSchema: {
+            agents: z.array(AgentListItemPayloadSchema),
+            total: z.number().int().nonnegative(),
+            hasMore: z.boolean(),
+            facets: z.object({
+                tags: z.array(z.string()),
+                kanban: z.array(z.string()),
+                providers: z.array(z.string()),
+            }),
+        },
+    }, async ({ cwd, archived, includeArchived, statuses, state, origin, tags, notTags, kanban, notKanban, providers, notProviders, timeField, window: timeWindow, from, to, text, sinceHours = 48, limit = 50, offset = 0, }) => {
+        const archivedMode = resolveArchivedMode(archived, includeArchived);
+        const timeSelection = resolveTimeSelection(timeWindow, from, to);
+        const resolvedTimeField = timeField ?? "active";
+        const callerCwd = callerAgentId ? resolveCallerAgent()?.cwd : undefined;
+        const requestedCwd = cwd?.trim() ? expandUserPath(cwd) : callerCwd;
+        const statusFilter = statuses && statuses.length > 0 ? new Set(statuses) : null;
+        const sinceMs = Date.now() - sinceHours * 60 * 60 * 1000;
+        // Asking to measure BY the archive date puts archived agents in scope by
+        // definition, so the default `hide` must not silently empty the result.
+        // The reader still controls which rows via `archived`; this only stops the
+        // default from contradicting the field they explicitly chose.
+        const wantsArchived = archivedMode !== "hide" || resolvedTimeField === "archived";
+        const liveSnapshots = agentManager.listAgents();
+        const liveAgents = await Promise.all(liveSnapshots.map((snapshot) => serializeSnapshotWithMetadata(agentStorage, snapshot, childLogger)));
+        const liveIds = new Set(liveSnapshots.map((snapshot) => snapshot.id));
+        const storedRecords = await agentStorage.list();
+        const registeredProviderIds = new Set(providerSnapshotManager.listRegisteredProviderIds());
+        const storedAgents = storedRecords
+            .filter((record) => !record.internal && !liveIds.has(record.id))
+            .filter((record) => wantsArchived || !record.archivedAt)
+            .filter((record) => wantsArchived || isStoredAgentProviderAvailable(record, registeredProviderIds))
+            .map((record) => buildStoredAgentPayload(record, registeredProviderIds));
+        // The child-count rollup has to see the WHOLE corpus before any narrowing,
+        // or a parent whose only live child sits outside the cwd/status filter
+        // loses its `pending` bucket and reads as done.
+        const corpus = withActiveChildCounts([...liveAgents, ...storedAgents].map(toAgentListItemPayload))
+            .filter((agent) => !requestedCwd || isSameOrDescendantPath(requestedCwd, agent.cwd))
+            .filter((agent) => !statusFilter || statusFilter.has(agent.status))
+            // `sinceHours` is a recency cut on ACTIVITY, and it prunes archived
+            // agents. Under `timeField: "archived"` that silently truncates the very
+            // span being asked for: an agent archived 10 days ago has no activity
+            // inside a 48h window, so "what did I archive last month" would return
+            // nothing while looking like an honest empty. The archive date is the
+            // bound in that mode, so this cut steps aside for archived rows.
+            .filter((agent) => !agent.archivedAt ||
+            resolvedTimeField === "archived" ||
+            resolveAgentListActivityTime(agent) >= sinceMs);
+        const criteria = {
+            ...emptyAgentFilterCriteria(),
+            stateSelection: filterSelectionFrom(state, undefined),
+            originSelection: filterSelectionFrom(origin, undefined),
+            tagSelection: filterSelectionFrom(tags, notTags),
+            kanbanSelection: filterSelectionFrom(kanban, notKanban),
+            providerSelection: filterSelectionFrom(providers, notProviders),
+            archivedMode,
+            timeSelection,
+            textQuery: (text ?? "").trim().toLowerCase(),
+        };
+        // One clock read for the whole request, so the facets and the page can
+        // never disagree about which side of a window boundary a row falls on.
+        const now = new Date();
+        const matched = filterAgentList(corpus, criteria, resolvedTimeField, now).sort(compareAgentListItems);
+        const agents = matched.slice(offset, offset + limit);
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                agents,
+                total: matched.length,
+                hasMore: offset + agents.length < matched.length,
+                facets: collectAgentListFacets(corpus),
+            }),
+        };
+    });
+    registerTool("cancel_agent", {
+        title: "Cancel agent run",
+        description: "Abort the agent's current run but keep the agent alive for future tasks.",
+        inputSchema: {
+            agentId: z.string(),
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ agentId }) => {
+        const { cancelled } = await cancelAgentRunCommand({ agentManager, logger: childLogger }, agentId);
+        if (cancelled) {
+            waitTracker.cancel(agentId, "Agent run cancelled");
+        }
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: cancelled }),
+        };
+    });
+    registerTool("archive_agent", {
+        title: "Archive agent",
+        description: "Archive an agent (soft-delete). The agent is interrupted if running and removed from the active list.",
+        inputSchema: {
+            agentId: z.string(),
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ agentId }) => {
+        await archiveAgentCommand({
+            agentManager,
+            agentStorage,
+            logger: childLogger,
+        }, agentId);
+        waitTracker.cancel(agentId, "Agent archived");
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true }),
+        };
+    });
+    registerTool("kill_agent", {
+        title: "Kill agent",
+        description: "Terminate an agent session permanently.",
+        inputSchema: {
+            agentId: z.string(),
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ agentId }) => {
+        await closeAgentCommand({ agentManager }, agentId);
+        waitTracker.cancel(agentId, "Agent terminated");
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true }),
+        };
+    });
+    registerTool("update_agent", {
+        title: "Update agent",
+        description: "Update an agent name, labels, and/or runtime settings.",
+        inputSchema: {
+            agentId: z.string(),
+            name: z.string().optional(),
+            labels: z.record(z.string(), z.string()).optional().describe("Labels to set on the agent"),
+            settings: UpdateAgentSettingsInputSchema.optional().describe("Runtime settings to apply to the agent."),
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ agentId, name, labels, settings }) => {
+        if (settings?.modeId !== undefined) {
+            await agentManager.setAgentMode(agentId, settings.modeId);
+        }
+        if (settings?.model !== undefined) {
+            await agentManager.setAgentModel(agentId, settings.model);
+        }
+        if (settings?.thinkingOptionId !== undefined) {
+            await agentManager.setAgentThinkingOption(agentId, settings.thinkingOptionId);
+        }
+        if (settings?.features) {
+            for (const [featureId, value] of Object.entries(settings.features)) {
+                await agentManager.setAgentFeature(agentId, featureId, value);
+            }
+        }
+        if (settings?.allowedTools !== undefined) {
+            await agentManager.setAgentAllowedTools(agentId, settings.allowedTools);
+        }
+        // One call for both, and only when at least one was sent: passing
+        // undefined through would be indistinguishable from "clear it", and an
+        // update that only renames the agent must not blank its job.
+        if (settings?.goal !== undefined || settings?.jobToBeDone !== undefined) {
+            await agentManager.setAgentDurableDescriptions(agentId, {
+                ...(settings.goal !== undefined ? { goal: settings.goal } : {}),
+                ...(settings.jobToBeDone !== undefined ? { jobToBeDone: settings.jobToBeDone } : {}),
+            });
+        }
+        await updateAgentCommand({ agentManager }, { agentId, name, labels });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true }),
+        };
+    });
+    registerTool("rename_workspace", {
+        title: "Rename workspace",
+        description: "Rename a workspace by setting its user-visible title. Omit workspaceId to rename your current workspace.",
+        inputSchema: {
+            workspaceId: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe("Workspace id to rename. Omit to rename your current workspace."),
+            title: z
+                .string()
+                .trim()
+                .min(1, "title is required")
+                .describe("New user-visible workspace title."),
+        },
+        outputSchema: {
+            success: z.boolean(),
+            workspaceId: z.string(),
+            title: z.string(),
+        },
+    }, async ({ workspaceId: requestedWorkspaceId, title }) => {
+        if (!options.workspaceRegistry) {
+            throw new Error("Workspace registry is required to rename workspaces");
+        }
+        if (!options.emitWorkspaceUpdatesForWorkspaceIds) {
+            throw new Error("Workspace update emitter is required to rename workspaces");
+        }
+        const workspaceId = resolveWorkspaceIdForRename(requestedWorkspaceId);
+        const existing = await options.workspaceRegistry.get(workspaceId);
+        if (!existing) {
+            throw new Error(`Workspace ${workspaceId} not found`);
+        }
+        if (existing.archivedAt) {
+            throw new Error(`Workspace ${workspaceId} is archived`);
+        }
+        await options.workspaceRegistry.upsert({
+            ...existing,
+            title,
+            updatedAt: new Date().toISOString(),
+        });
+        await options.emitWorkspaceUpdatesForWorkspaceIds([workspaceId]);
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                success: true,
+                workspaceId,
+                title,
+            }),
+        };
+    });
+    registerTool("list_terminals", {
+        title: "List terminals",
+        description: "List terminals for a working directory or across all working directories.",
+        inputSchema: {
+            cwd: z
+                .string()
+                .optional()
+                .describe("Optional working directory. Defaults to your current working directory."),
+            all: z.boolean().optional().describe("List terminals across all working directories."),
+        },
+        outputSchema: {
+            terminals: z.array(TerminalSummarySchema),
+        },
+    }, async ({ cwd, all }) => {
+        if (!terminalManager) {
+            throw new Error("Terminal manager is not configured");
+        }
+        const terminals = all
+            ? (await Promise.all(terminalManager.listDirectories().map(async (directory) => (await terminalManager.getTerminals(directory)).map((terminal) => ({
+                id: terminal.id,
+                name: terminal.name,
+                cwd: terminal.cwd,
+            }))))).flat()
+            : (await terminalManager.getTerminals(resolveScopedCwd(cwd, { required: true }))).map((terminal) => ({
+                id: terminal.id,
+                name: terminal.name,
+                cwd: terminal.cwd,
+            }));
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ terminals }),
+        };
+    });
+    registerTool("create_terminal", {
+        title: "Create terminal",
+        description: "Create a terminal session for a working directory.",
+        inputSchema: {
+            cwd: z
+                .string()
+                .optional()
+                .describe("Optional working directory. Defaults to your current working directory."),
+            name: z.string().optional().describe("Optional terminal name."),
+        },
+        outputSchema: TerminalSummarySchema.shape,
+    }, async ({ cwd, name }) => {
+        if (!terminalManager) {
+            throw new Error("Terminal manager is not configured");
+        }
+        const resolvedCwd = resolveScopedCwd(cwd, { required: true });
+        const workspaceId = await resolveTerminalWorkspaceId(resolvedCwd);
+        const terminal = await terminalManager.createTerminal({
+            cwd: resolvedCwd,
+            workspaceId,
+            ...(name?.trim() ? { name: name.trim() } : {}),
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                id: terminal.id,
+                name: terminal.name,
+                cwd: terminal.cwd,
+            }),
+        };
+    });
+    registerTool("kill_terminal", {
+        title: "Kill terminal",
+        description: "Kill an existing terminal session.",
+        inputSchema: {
+            terminalId: z.string(),
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ terminalId }) => {
+        if (!terminalManager) {
+            throw new Error("Terminal manager is not configured");
+        }
+        const terminal = terminalManager.getTerminal(terminalId);
+        if (!terminal) {
+            throw new Error(`Terminal ${terminalId} not found`);
+        }
+        terminal.kill();
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true }),
+        };
+    });
+    registerTool("capture_terminal", {
+        title: "Capture terminal",
+        description: "Capture plain-text terminal output lines from a terminal session.",
+        inputSchema: {
+            terminalId: z.string(),
+            start: z.number().optional(),
+            end: z.number().optional(),
+            scrollback: z.boolean().optional(),
+            stripAnsi: z.boolean().optional().default(true),
+        },
+        outputSchema: {
+            terminalId: z.string(),
+            lines: z.array(z.string()),
+            totalLines: z.number().int().nonnegative(),
+        },
+    }, async ({ terminalId, start, end, scrollback, stripAnsi = true }) => {
+        if (!terminalManager) {
+            throw new Error("Terminal manager is not configured");
+        }
+        if (!terminalManager.getTerminal(terminalId)) {
+            throw new Error(`Terminal ${terminalId} not found`);
+        }
+        const capture = await terminalManager.captureTerminal(terminalId, {
+            start: scrollback ? 0 : start,
+            end,
+            stripAnsi,
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                terminalId,
+                lines: capture.lines,
+                totalLines: capture.totalLines,
+            }),
+        };
+    });
+    registerTool("send_terminal_keys", {
+        title: "Send terminal keys",
+        description: "Send literal text or special key tokens to a terminal session.",
+        inputSchema: {
+            terminalId: z.string(),
+            keys: z.string(),
+            literal: z.boolean().optional(),
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ terminalId, keys, literal = false }) => {
+        if (!terminalManager) {
+            throw new Error("Terminal manager is not configured");
+        }
+        const terminal = terminalManager.getTerminal(terminalId);
+        if (!terminal) {
+            throw new Error(`Terminal ${terminalId} not found`);
+        }
+        terminal.send({
+            type: "input",
+            data: resolveTerminalKeyToken(keys, literal),
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true }),
+        };
+    });
+    registerTool("create_schedule", {
+        title: "Create schedule",
+        description: "Schedule a prompt for later: once at a specific time (at), on a repeating interval (every), or on a cron cadence (cron). The prompt can start a fresh agent, come back to you (target self), or go to another agent by id. Prefer this over an in-session loop whenever the work must survive this session ending, since schedules are owned by the daemon.",
+        inputSchema: {
+            prompt: z.string().trim().min(1, "prompt is required"),
+            at: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe('One-off delivery time. An ISO 8601 instant ("2026-08-21T21:30:00-03:00") or a duration from now ("90m", "2h30m"). Runs exactly once. Mutually exclusive with every and cron.'),
+            every: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe('Repeating interval, for example "5m", "1h", "2h30m", "1d". Mutually exclusive with at and cron.'),
+            cron: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe('Repeating cron expression, for example "0 9 * * 1-5". Mutually exclusive with at and every.'),
+            timezone: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe("IANA time zone for the cron cadence. Requires cron. For example: America/New_York."),
+            name: z
+                .string()
+                .optional()
+                .describe("Reusing a name with the same target refreshes that schedule in place instead of creating a second one."),
+            target: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe('Who receives the prompt: "new-agent" (default) starts a fresh agent each run, "self" delivers to you, or an agent id delivers to that agent.'),
+            provider: AgentProviderEnum.optional().describe("Provider, or provider/model (for example: codex or codex/gpt-5.4). Only valid with target new-agent."),
+            cwd: z.string().optional().describe("Working directory. Only valid with target new-agent."),
+            maxRuns: z.number().int().positive().optional(),
+            expiresIn: z.string().optional(),
+            runNow: z
+                .boolean()
+                .optional()
+                .describe("Also fire once immediately on create. Defaults to true for every, false for cron. Not allowed with at."),
+        },
+        outputSchema: ScheduleSummarySchema.shape,
+    }, async ({ prompt, at, every, cron, timezone, name, target, provider, cwd, maxRuns, expiresIn, runNow, }) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        const { cadence, oneOff } = resolveScheduleCreateCadence({ at, every, cron, timezone }, new Date());
+        if (oneOff && maxRuns !== undefined && maxRuns !== 1) {
+            throw new Error("maxRuns cannot be combined with at: an at schedule runs exactly once");
+        }
+        if (oneOff && runNow === true) {
+            throw new Error("runNow cannot be combined with at: an at schedule runs only at its time");
+        }
+        const resolvedTarget = await resolveScheduleCreateTarget({ target, provider, cwd });
+        const expiresAt = buildScheduleExpiry(expiresIn);
+        const scheduleInput = {
+            prompt: prompt.trim(),
+            cadence,
+            target: resolvedTarget,
+            ...(name?.trim() ? { name: name.trim() } : {}),
+            ...(oneOff
+                ? { maxRuns: 1, runOnCreate: false }
+                : {
+                    ...(maxRuns === undefined ? {} : { maxRuns }),
+                    ...(runNow === undefined ? {} : { runOnCreate: runNow }),
+                }),
+            ...(expiresAt === undefined ? {} : { expiresAt }),
+        };
+        const schedule = await persistNewSchedule(scheduleInput, oneOff);
+        return {
+            content: [],
+            structuredContent: ensureValidJson(toScheduleSummary(schedule)),
+        };
+    });
+    registerTool("create_heartbeat", {
+        title: "Create heartbeat",
+        description: "Schedule a prompt back to yourself: once at a specific time (at), on a repeating interval (every), or on a cron cadence (cron). Equivalent to create_schedule with target self.",
+        inputSchema: {
+            prompt: z.string().trim().min(1, "prompt is required"),
+            at: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe('One-off delivery time. An ISO 8601 instant ("2026-08-21T21:30:00-03:00") or a duration from now ("90m"). Runs exactly once. Mutually exclusive with every and cron.'),
+            every: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe('Repeating interval, for example "5m", "1h", "2h30m". Mutually exclusive with at and cron.'),
+            cron: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe('Repeating cron expression, for example "0 9 * * 1-5". Mutually exclusive with at and every.'),
+            timezone: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe("IANA time zone for the cron cadence. Requires cron. For example: America/New_York."),
+            name: z.string().optional(),
+            maxRuns: z.number().int().positive().optional(),
+            expiresIn: z.string().optional(),
+            runNow: z
+                .boolean()
+                .optional()
+                .describe("Also fire once immediately on create. Defaults to true for every, false for cron. Not allowed with at."),
+        },
+        outputSchema: ScheduleSummarySchema.shape,
+    }, async ({ prompt, at, every, cron, timezone, name, maxRuns, expiresIn, runNow }) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        if (!callerAgentId) {
+            throw new Error("create_heartbeat requires an agent-scoped session");
+        }
+        resolveCallerAgent();
+        const { cadence, oneOff } = resolveScheduleCreateCadence({ at, every, cron, timezone }, new Date());
+        if (oneOff && maxRuns !== undefined && maxRuns !== 1) {
+            throw new Error("maxRuns cannot be combined with at: an at schedule runs exactly once");
+        }
+        if (oneOff && runNow === true) {
+            throw new Error("runNow cannot be combined with at: an at schedule runs only at its time");
+        }
+        const expiresAt = buildScheduleExpiry(expiresIn);
+        const scheduleInput = {
+            prompt: prompt.trim(),
+            cadence,
+            target: { type: "agent", agentId: callerAgentId },
+            ...(name?.trim() ? { name: name.trim() } : {}),
+            ...(oneOff
+                ? { maxRuns: 1, runOnCreate: false }
+                : {
+                    ...(maxRuns === undefined ? {} : { maxRuns }),
+                    ...(runNow === undefined ? {} : { runOnCreate: runNow }),
+                }),
+            ...(expiresAt === undefined ? {} : { expiresAt }),
+        };
+        const schedule = await persistNewSchedule(scheduleInput, oneOff);
+        return {
+            content: [],
+            structuredContent: ensureValidJson(toScheduleSummary(schedule)),
+        };
+    });
+    registerTool("run_schedule_once", {
+        title: "Run schedule once",
+        description: "Fire a schedule immediately, out of band. The cadence and the next scheduled run are left untouched, but the run is recorded and counts toward maxRuns.",
+        inputSchema: {
+            id: z.string(),
+        },
+        outputSchema: StoredScheduleSchema.shape,
+    }, async ({ id }) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        const schedule = await scheduleService.runOnce(id);
+        return {
+            content: [],
+            structuredContent: ensureValidJson(schedule),
+        };
+    });
+    registerTool("list_schedules", {
+        title: "List schedules",
+        description: "List all schedules managed by the daemon.",
+        inputSchema: {},
+        outputSchema: {
+            schedules: z.array(ScheduleSummarySchema),
+        },
+    }, async () => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        const schedules = (await scheduleService.list()).map((schedule) => toScheduleSummary(schedule));
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ schedules }),
+        };
+    });
+    registerTool("inspect_schedule", {
+        title: "Inspect schedule",
+        description: "Inspect a schedule and its run history.",
+        inputSchema: {
+            id: z.string(),
+        },
+        outputSchema: StoredScheduleSchema.shape,
+    }, async ({ id }) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        const schedule = await scheduleService.inspect(id);
+        return {
+            content: [],
+            structuredContent: ensureValidJson(schedule),
+        };
+    });
+    registerTool("pause_schedule", {
+        title: "Pause schedule",
+        description: "Pause an active schedule.",
+        inputSchema: {
+            id: z.string(),
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ id }) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        await scheduleService.pause(id);
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true }),
+        };
+    });
+    registerTool("resume_schedule", {
+        title: "Resume schedule",
+        description: "Resume a paused schedule.",
+        inputSchema: {
+            id: z.string(),
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ id }) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        await scheduleService.resume(id);
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true }),
+        };
+    });
+    registerTool("delete_schedule", {
+        title: "Delete schedule",
+        description: "Delete a schedule permanently.",
+        inputSchema: {
+            id: z.string(),
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ id }) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        await scheduleService.delete(id);
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true }),
+        };
+    });
+    registerTool("update_schedule", {
+        title: "Update schedule",
+        description: "Update an existing schedule. Only provided fields are changed; omitted fields remain unchanged.",
+        inputSchema: {
+            id: z.string(),
+            every: z.string().optional().describe("New interval duration string (e.g. 5m, 1h)."),
+            cron: z.string().optional().describe("New cron expression."),
+            timezone: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe("IANA time zone for cron cadence; requires cron. For example: America/New_York."),
+            name: z.string().nullable().optional().describe("New name (null to clear)."),
+            prompt: z.string().trim().min(1).optional().describe("New prompt text."),
+            maxRuns: z
+                .number()
+                .int()
+                .positive()
+                .nullable()
+                .optional()
+                .describe("New max runs limit (null to clear)."),
+            provider: z
+                .string()
+                .trim()
+                .min(1)
+                .optional()
+                .describe("New provider for new-agent target."),
+            model: z
+                .string()
+                .trim()
+                .min(1)
+                .nullable()
+                .optional()
+                .describe("New model for new-agent target (null to clear)."),
+            mode: z
+                .string()
+                .trim()
+                .min(1)
+                .nullable()
+                .optional()
+                .describe("New mode for new-agent target (null to clear)."),
+            cwd: z.string().trim().min(1).optional().describe("New cwd for new-agent target."),
+            expiresIn: z
+                .string()
+                .optional()
+                .describe("New relative expiry duration (for example: 1h, 2d)."),
+            clearExpires: z.boolean().optional().describe("Clear any schedule expiry."),
+        },
+        outputSchema: StoredScheduleSchema.shape,
+    }, async (input) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        const schedule = await scheduleService.update(buildScheduleUpdateInput(input));
+        return {
+            content: [],
+            structuredContent: ensureValidJson(schedule),
+        };
+    });
+    registerTool("schedule_logs", {
+        title: "Schedule logs",
+        description: "Get the run history (logs) for a schedule.",
+        inputSchema: {
+            id: z.string(),
+        },
+        outputSchema: {
+            runs: z.array(ScheduleRunSchema),
+        },
+    }, async ({ id }) => {
+        if (!scheduleService) {
+            throw new Error("Schedule service is not configured");
+        }
+        const runs = await scheduleService.logs(id);
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ runs }),
+        };
+    });
+    registerTool("list_providers", {
+        title: "List providers",
+        description: "List configured agent providers, availability, and their modes.",
+        inputSchema: {},
+        outputSchema: {
+            providers: z.array(ProviderSummarySchema),
+        },
+    }, async () => {
+        const providers = (await providerSnapshotManager.listProviders({ wait: true })).map(toProviderSummary);
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ providers }),
+        };
+    });
+    registerTool("list_models", {
+        title: "List models",
+        description: "List models for an agent provider.",
+        inputSchema: {
+            provider: AgentProviderEnum,
+        },
+        outputSchema: {
+            provider: z.string(),
+            models: z.array(AgentModelSchema),
+        },
+    }, async ({ provider }) => {
+        const models = await providerSnapshotManager.listModels({
+            provider,
+            wait: true,
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                provider,
+                models,
+            }),
+        };
+    });
+    registerTool("inspect_provider", {
+        title: "Inspect provider",
+        description: "Inspect compact provider capabilities for orchestration, including modes and draft feature settings. Use list_models for the full model list.",
+        inputSchema: inspectProviderInputSchema,
+        outputSchema: {
+            provider: AgentProviderEnum,
+            label: z.string().nullable().optional(),
+            description: z.string().nullable().optional(),
+            enabled: z.boolean(),
+            status: z.string(),
+            modes: z.array(ProviderModeSchema).nullish(),
+            selectedModel: z.string().nullable(),
+            features: z.array(AgentFeatureSchema),
+        },
+    }, async ({ provider, cwd, settings }) => {
+        const resolvedProviderModel = resolveScheduleProviderAndModel({
+            provider,
+            defaultProvider: provider,
+        });
+        const providerId = resolvedProviderModel.provider;
+        const resolvedCwd = resolveScopedCwd(cwd, { required: true });
+        const entry = await providerSnapshotManager.getProvider({
+            cwd: resolvedCwd,
+            provider: providerId,
+            wait: true,
+        });
+        const summary = toProviderSummary(entry);
+        if (!entry.enabled) {
+            throw new Error(`Provider '${providerId}' is disabled`);
+        }
+        if (entry.status !== "ready") {
+            throw new Error(entry.error ?? `Provider '${providerId}' is unavailable`);
+        }
+        const selectedModel = settings?.model ?? resolvedProviderModel.model;
+        const features = await agentManager.listDraftFeatures({
+            provider: providerId,
+            cwd: resolvedCwd,
+            ...(settings?.modeId ? { modeId: settings.modeId } : {}),
+            ...(selectedModel ? { model: selectedModel } : {}),
+            ...(settings?.thinkingOptionId ? { thinkingOptionId: settings.thinkingOptionId } : {}),
+            ...(settings?.features ? { featureValues: settings.features } : {}),
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                provider: providerId,
+                label: summary.label,
+                description: summary.description,
+                enabled: summary.enabled,
+                status: summary.status,
+                modes: summary.modes,
+                selectedModel: selectedModel ?? null,
+                features,
+            }),
+        };
+    });
+    registerTool("list_worktrees", {
+        title: "List worktrees",
+        description: "List Paseo-managed git worktrees for a repository.",
+        inputSchema: {
+            cwd: z
+                .string()
+                .optional()
+                .describe("Optional repository cwd. Defaults to your current working directory."),
+        },
+        outputSchema: {
+            worktrees: z.array(WorktreeSummarySchema),
+        },
+    }, async ({ cwd }) => {
+        const resolvedCwd = resolveScopedCwd(cwd, { required: true });
+        if (!options.workspaceGitService) {
+            throw new Error("WorkspaceGitService is required to list worktrees");
+        }
+        const worktrees = await listPaseoWorktreesCommand({ workspaceGitService: options.workspaceGitService }, {
+            cwd: resolvedCwd,
+            reason: "mcp:list-worktrees",
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ worktrees }),
+        };
+    });
+    registerTool("create_worktree", {
+        title: "Create worktree",
+        description: "Create a Paseo-managed git worktree. Branch off a new branch, check out an existing branch, or check out a GitHub PR.",
+        inputSchema: {
+            cwd: z.string().optional().describe("Repository directory. Defaults to the agent's cwd."),
+            target: AgentCreateWorktreeTargetInputSchema.describe("What the worktree should contain."),
+        },
+        outputSchema: {
+            branchName: z.string(),
+            worktreePath: z.string(),
+            workspaceId: z.string(),
+        },
+    }, async ({ cwd, target }) => {
+        const repoRoot = resolveScopedCwd(cwd, { required: true });
+        const commandResult = await createPaseoWorktreeCommand({
+            paseoHome: options.paseoHome,
+            worktreesRoot: options.worktreesRoot,
+            createPaseoWorktreeWorkflow: options.createPaseoWorktree,
+        }, createMcpWorktreeCommandInput(repoRoot, target));
+        if (!commandResult.ok) {
+            throw new WorktreeRequestError(commandResult.error);
+        }
+        const { worktree, workspace } = commandResult.createdWorktree;
+        await options.workspaceGitService?.listWorktrees?.(repoRoot, {
+            force: true,
+            reason: "mcp:create-worktree",
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                branchName: worktree.branchName,
+                worktreePath: worktree.worktreePath,
+                workspaceId: workspace.workspaceId,
+            }),
+        };
+    });
+    registerTool("archive_worktree", {
+        title: "Archive worktree",
+        description: "Delete a Paseo-managed git worktree.",
+        inputSchema: {
+            cwd: z
+                .string()
+                .optional()
+                .describe("Optional repository cwd. Defaults to your current working directory."),
+            worktreePath: z.string().optional(),
+            worktreeSlug: z.string().optional(),
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ cwd, worktreePath, worktreeSlug }) => {
+        const resolvedCwd = resolveScopedCwd(cwd, { required: true });
+        if (!worktreePath && !worktreeSlug) {
+            throw new Error("worktreePath or worktreeSlug is required");
+        }
+        if (!options.workspaceGitService) {
+            throw new Error("WorkspaceGitService is required to archive worktrees");
+        }
+        const repoRoot = await options.workspaceGitService.resolveRepoRoot(resolvedCwd);
+        const result = await archiveCommand(archiveWorktreeDependencies(options, {
+            agentManager,
+            agentStorage,
+            terminalManager: terminalManager ?? null,
+            logger: childLogger,
+        }), {
+            requestId: "mcp:archive_worktree",
+            repoRoot,
+            worktreePath,
+            worktreeSlug,
+            // This tool archives every workspace on the directory, then removes the
+            // directory. Disk removal is derived from scope + last-reference.
+            scope: "worktree",
+        });
+        if (!result.ok) {
+            throw new Error(result.message);
+        }
+        await options.workspaceGitService.listWorktrees(repoRoot, {
+            force: true,
+            reason: "mcp:archive-worktree",
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true }),
+        };
+    });
+    registerTool("get_agent_activity", {
+        title: "Get agent activity",
+        description: "Return recent agent timeline entries as a curated summary.",
+        inputSchema: {
+            agentId: z.string(),
+            limit: z
+                .number()
+                .optional()
+                .describe("Optional limit for number of activities to include (most recent first)."),
+        },
+        outputSchema: {
+            agentId: z.string(),
+            updateCount: z.number(),
+            currentModeId: z.string().nullable(),
+            content: z.string(),
+        },
+    }, async ({ agentId, limit }) => {
+        await ensureAgentLoaded(agentId, {
+            agentManager,
+            agentStorage,
+            logger: childLogger,
+        });
+        const timeline = agentManager.getTimeline(agentId);
+        const snapshot = agentManager.getAgent(agentId);
+        const selection = selectItemsByProjectedLimit({
+            items: timeline,
+            direction: "tail",
+            limit: limit ?? 0,
+        });
+        const curatedContent = curateAgentActivity(selection.items);
+        const { totalProjected, shownProjected } = selection;
+        const noun = totalProjected === 1 ? "activity" : "activities";
+        const countHeader = limit && shownProjected < totalProjected
+            ? `Showing ${shownProjected} of ${totalProjected} ${noun} (limited to ${limit})`
+            : `Showing all ${totalProjected} ${noun}`;
+        const contentWithCount = `${countHeader}\n\n${curatedContent}`;
+        return {
+            content: [],
+            structuredContent: ensureValidJson({
+                agentId,
+                updateCount: timeline.length,
+                currentModeId: snapshot?.currentModeId ?? null,
+                content: contentWithCount,
+            }),
+        };
+    });
+    registerTool("set_agent_mode", {
+        title: "Set agent session mode",
+        description: "Switch the agent's session mode (plan, bypassPermissions, read-only, auto, etc.).",
+        inputSchema: {
+            agentId: z.string(),
+            modeId: z.string(),
+        },
+        outputSchema: {
+            success: z.boolean(),
+            newMode: z.string(),
+        },
+    }, async ({ agentId, modeId }) => {
+        const result = await setAgentModeCommand({ agentManager }, { agentId, modeId });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true, newMode: result.modeId }),
+        };
+    });
+    registerTool("list_pending_permissions", {
+        title: "List pending permissions",
+        description: "Return all pending permission requests across all agents with the normalized payloads.",
+        inputSchema: {},
+        outputSchema: {
+            permissions: z.array(z.object({
+                agentId: z.string(),
+                status: AgentStatusEnum,
+                request: AgentPermissionRequestPayloadSchema,
+            })),
+        },
+    }, async () => {
+        const permissions = agentManager.listAgents().flatMap((agent) => {
+            const payload = toAgentPayload(agent);
+            return payload.pendingPermissions.map((request) => ({
+                agentId: agent.id,
+                status: payload.status,
+                request: sanitizePermissionRequest(request),
+            }));
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ permissions }),
+        };
+    });
+    registerTool("respond_to_permission", {
+        title: "Respond to permission",
+        description: "Approve or deny a pending permission request with an AgentManager-compatible response payload.",
+        inputSchema: {
+            agentId: z.string(),
+            requestId: z.string(),
+            response: AgentPermissionResponseSchema,
+        },
+        outputSchema: {
+            success: z.boolean(),
+        },
+    }, async ({ agentId, requestId, response }) => {
+        await respondToAgentPermission({
+            agentManager,
+            agentId,
+            requestId,
+            response,
+            logger: childLogger,
+        });
+        return {
+            content: [],
+            structuredContent: ensureValidJson({ success: true }),
+        };
+    });
+    return toCatalog();
+}
+function archiveWorktreeDependencies(options, context) {
+    if (!options.github) {
+        throw new Error("GitHub service is required to archive worktrees");
+    }
+    if (!options.workspaceGitService) {
+        throw new Error("WorkspaceGitService is required to archive worktrees");
+    }
+    if (!options.archiveWorkspaceRecord) {
+        throw new Error("Workspace registry archiver is required to archive worktrees");
+    }
+    if (!options.findWorkspaceIdForCwd) {
+        throw new Error("Workspace resolver is required to archive worktrees");
+    }
+    if (!options.listActiveWorkspaces) {
+        throw new Error("Active workspace lister is required to archive worktrees");
+    }
+    if (!options.emitWorkspaceUpdatesForWorkspaceIds) {
+        throw new Error("Workspace update emitter is required to archive worktrees");
+    }
+    if (!options.markWorkspaceArchiving) {
+        throw new Error("Workspace archiving marker is required to archive worktrees");
+    }
+    if (!options.clearWorkspaceArchiving) {
+        throw new Error("Workspace archiving clearer is required to archive worktrees");
+    }
+    return {
+        paseoHome: options.paseoHome,
+        paseoWorktreesBaseRoot: options.worktreesRoot,
+        github: options.github,
+        workspaceGitService: options.workspaceGitService,
+        agentManager: context.agentManager,
+        agentStorage: context.agentStorage,
+        findWorkspaceIdForCwd: options.findWorkspaceIdForCwd,
+        listActiveWorkspaces: options.listActiveWorkspaces,
+        archiveWorkspaceRecord: options.archiveWorkspaceRecord,
+        emitWorkspaceUpdatesForWorkspaceIds: options.emitWorkspaceUpdatesForWorkspaceIds,
+        markWorkspaceArchiving: options.markWorkspaceArchiving,
+        clearWorkspaceArchiving: options.clearWorkspaceArchiving,
+        killTerminalsForWorkspace: (workspaceId) => killTerminalsForWorkspace({
+            terminalManager: context.terminalManager,
+            sessionLogger: context.logger,
+        }, workspaceId),
+        sessionLogger: context.logger,
+    };
+}
+function createMcpWorktreeCommandInput(repoRoot, target) {
+    const base = { cwd: repoRoot };
+    switch (target.kind) {
+        case "branch-off":
+            return {
+                ...base,
+                worktreeSlug: target.worktreeSlug,
+                branchName: target.branchName,
+                action: "branch-off",
+                ...(target.baseBranch ? { refName: target.baseBranch } : {}),
+            };
+        case "checkout-branch":
+            return { ...base, action: "checkout", refName: target.branch };
+        case "checkout-pr":
+            return { ...base, action: "checkout", githubPrNumber: target.githubPrNumber };
+        default:
+            throw new Error("unreachable");
+    }
+}
+//# sourceMappingURL=paseo-tools.js.map