qlogicagent 2.13.3 → 2.13.5

package/dist/skills/tools/web-research-tool.js

@@ -0,0 +1,254 @@
+// ============================================================
+// Web Research Tool — agentic 深挖:拆子问题 → 多轮 search+fetch → reflect 补搜 → 综述报告(V2/L5)。
+// Category: web
+// 复用 web_answer 的 deps 形态(search/fetchUrl/generate)+ 可选 saveMemory(§14 写记忆)。
+// 预算硬上限(§4.2 ResearchBudget):maxRounds / maxWallClockMs + signal 取消,防失控。
+// §15-4 已知限制:单工具内长流程,UI 全程静默直到结束(shouldDefer + 描述已注明)。
+// §15-7:写记忆经 consolidator 去重/过滤,入库结果如实报告、不假定成功。
+// ============================================================
+export const WEB_RESEARCH_TOOL_NAME = "web_research";
+export const WEB_RESEARCH_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        task: {
+            type: "string",
+            description: "The research task / question to investigate in depth. " +
+                "This runs a multi-step search-read-reflect-synthesize loop and may take 30s+.",
+        },
+        budget: {
+            type: "object",
+            properties: {
+                maxRounds: {
+                    type: "number",
+                    description: "Max search-read-reflect rounds (default 2).",
+                },
+                maxWallClockMs: {
+                    type: "number",
+                    description: "Max wall-clock time in ms (default 120000).",
+                },
+            },
+            description: "Hard budget caps to prevent runaway research.",
+        },
+    },
+    required: ["task"],
+};
+const DEFAULT_MAX_ROUNDS = 2;
+const DEFAULT_MAX_WALL_CLOCK_MS = 120_000;
+const MAX_SUBQUESTIONS = 5;
+const REFLECT_EXTRA_QUESTIONS = 2;
+const FETCH_PER_SUB = 2;
+const PER_PAGE_MAX_CHARS = 3000;
+export function createWebResearchTool(deps) {
+    return {
+        name: WEB_RESEARCH_TOOL_NAME,
+        label: "Web Research",
+        searchHint: "deep research investigate report sources multi-round 深度研究 调研 研究报告 资料调查",
+        description: "Deep web research: decomposes a task into sub-questions, searches and reads sources for each, " +
+            "reflects on gaps and searches again (budget-capped), then synthesizes a structured report with markdown citations. " +
+            "Use for complex, multi-faceted research that a single web_search/web_answer can't cover. May take 30s+ (silent until done).",
+        parameters: WEB_RESEARCH_TOOL_SCHEMA,
+        isReadOnly: true,
+        isEgress: true,
+        egressCarriesData: false,
+        shouldDefer: true,
+        execute: async (_toolCallId, params, signal) => {
+            const task = params.task?.trim();
+            if (!task || task.length < 4) {
+                return {
+                    content: [{ type: "text", text: "Error: task must be at least 4 characters." }],
+                    details: { type: "web_research", error: "invalid_task" },
+                };
+            }
+            const maxRounds = Math.max(1, params.budget?.maxRounds ?? DEFAULT_MAX_ROUNDS);
+            const maxWallClockMs = Math.max(10_000, params.budget?.maxWallClockMs ?? DEFAULT_MAX_WALL_CLOCK_MS);
+            const startedAt = Date.now();
+            const trace = [];
+            const budgetLeft = () => !signal.aborted && Date.now() - startedAt < maxWallClockMs;
+            // L5.1 plan:拆子问题(smallModel;无模型则退化为单问题 = task 本身)
+            const tPlan = Date.now();
+            let subQuestions;
+            try {
+                const planRaw = await deps.generate("smallModel", buildPlanPrompt(task), signal);
+                subQuestions = parseSubQuestions(planRaw, task);
+            }
+            catch {
+                subQuestions = [task];
+            }
+            subQuestions = subQuestions.slice(0, MAX_SUBQUESTIONS);
+            trace.push({ action: "plan", detail: `${subQuestions.length} sub-questions`, tookMs: Date.now() - tPlan });
+            // L5.2 各子问题 search + fetch(预算:墙钟 + signal)
+            const findings = [];
+            const investigate = async (questions) => {
+                for (const question of questions) {
+                    if (!budgetLeft())
+                        break;
+                    const tQ = Date.now();
+                    const searchOut = await deps.search(question, { maxResults: 4 });
+                    const top = searchOut.results.slice(0, FETCH_PER_SUB);
+                    const fetched = await Promise.allSettled(top.map((r) => deps.fetchUrl({ url: r.url, query: question, maxChars: PER_PAGE_MAX_CHARS, signal })));
+                    findings.push({
+                        question,
+                        sources: top.map((r, i) => {
+                            const f = fetched[i];
+                            return { title: r.title, url: r.url, body: f && f.status === "fulfilled" ? f.value.content : r.snippet };
+                        }),
+                    });
+                    trace.push({ action: "search", detail: `"${question.slice(0, 60)}" → ${top.length} sources`, tookMs: Date.now() - tQ });
+                }
+            };
+            await investigate(subQuestions);
+            // L5.3 reflect 补搜环(§5-L5:够了吗?缺什么?→ 补搜;轮数 + 墙钟双重封顶)
+            let rounds = 1;
+            while (rounds < maxRounds && budgetLeft() && findings.length > 0) {
+                const tR = Date.now();
+                let gaps = [];
+                try {
+                    const reflectRaw = await deps.generate("smallModel", buildReflectPrompt(task, findings), signal);
+                    gaps = parseReflectGaps(reflectRaw);
+                }
+                catch {
+                    gaps = [];
+                }
+                trace.push({
+                    action: "reflect",
+                    detail: gaps.length > 0 ? `gaps: ${gaps.map((g) => g.slice(0, 40)).join(" | ")}` : "sufficient — no follow-up",
+                    tookMs: Date.now() - tR,
+                });
+                if (gaps.length === 0)
+                    break; // 反思认为足够,提前结束
+                rounds++;
+                await investigate(gaps.slice(0, REFLECT_EXTRA_QUESTIONS));
+            }
+            const totalSources = findings.reduce((n, f) => n + f.sources.length, 0);
+            if (totalSources === 0) {
+                return {
+                    content: [{ type: "text", text: `No web sources found for research task: "${task}"` }],
+                    details: { type: "web_research", task, sourceCount: 0, trace },
+                };
+            }
+            // L5.4 synthesize 报告(textGeneration)
+            const tS = Date.now();
+            let report;
+            try {
+                report = await deps.generate("textGeneration", buildSynthPrompt(task, findings), signal);
+            }
+            catch (err) {
+                return {
+                    content: [{ type: "text", text: `web_research synthesis failed: ${err.message}` }],
+                    details: { type: "web_research", error: "generate_failed", trace },
+                };
+            }
+            trace.push({ action: "synthesize", detail: `${report?.length ?? 0} chars`, tookMs: Date.now() - tS });
+            if (!report) {
+                // fail-loud 降级:无文本模型 → 按子问题列出所有来源(不静默编造)
+                return {
+                    content: [{ type: "text", text: buildFallbackReport(task, findings) }],
+                    details: { type: "web_research", task, degraded: true, sourceCount: totalSources, subQuestionCount: findings.length, rounds, trace },
+                };
+            }
+            // L5.5 写记忆(§14;可选注入,经去重管线 §15-7,结果如实报告)
+            let memorySaved = "skipped";
+            if (deps.saveMemory && !signal.aborted) {
+                const tM = Date.now();
+                try {
+                    memorySaved = await deps.saveMemory(`[web_research] ${task}\n\n${report.slice(0, 2000)}`, { source: "web_research", category: "research" });
+                }
+                catch {
+                    memorySaved = false;
+                }
+                trace.push({ action: "memory", detail: `saved=${memorySaved}`, tookMs: Date.now() - tM });
+            }
+            return {
+                content: [{ type: "text", text: report }],
+                details: {
+                    type: "web_research",
+                    task,
+                    subQuestionCount: findings.length,
+                    sourceCount: totalSources,
+                    rounds,
+                    wallClockMs: Date.now() - startedAt,
+                    memorySaved,
+                    trace,
+                },
+            };
+        },
+    };
+}
+function buildPlanPrompt(task) {
+    return [
+        "Break the research task into 3-5 focused, non-overlapping sub-questions.",
+        "Output one sub-question per line, plain text, NO numbering or bullets.",
+        "",
+        `Task: ${task}`,
+    ].join("\n");
+}
+function parseSubQuestions(raw, task) {
+    if (!raw)
+        return [task];
+    const lines = raw
+        .split("\n")
+        .map((l) => l.replace(/^\s*(?:[-*\d.)\]]+)\s*/, "").trim())
+        .filter((l) => l.length >= 4);
+    return lines.length > 0 ? lines : [task];
+}
+function buildReflectPrompt(task, findings) {
+    const covered = findings
+        .map((f, i) => `${i + 1}. ${f.question} — sources: ${f.sources.map((s) => s.title).join("; ").slice(0, 160)}`)
+        .join("\n");
+    return [
+        "You are reviewing in-progress research. Decide if the gathered material sufficiently answers the task.",
+        `If sufficient, output exactly: ENOUGH`,
+        `If NOT sufficient, output 1-${REFLECT_EXTRA_QUESTIONS} missing sub-questions (one per line, plain text, no bullets). Only ask what is genuinely missing.`,
+        "",
+        `Task: ${task}`,
+        "",
+        "Covered so far:",
+        covered,
+    ].join("\n");
+}
+function parseReflectGaps(raw) {
+    if (!raw)
+        return [];
+    const text = raw.trim();
+    if (/^ENOUGH\b/i.test(text))
+        return [];
+    return text
+        .split("\n")
+        .map((l) => l.replace(/^\s*(?:[-*\d.)\]]+)\s*/, "").trim())
+        .filter((l) => l.length >= 4 && !/^ENOUGH\b/i.test(l));
+}
+function buildSynthPrompt(task, findings) {
+    const blocks = findings
+        .map((f, i) => {
+        const srcs = f.sources
+            .map((s, j) => `  (${i + 1}.${j + 1}) ${s.title}\n  URL: ${s.url}\n  ${s.body.slice(0, PER_PAGE_MAX_CHARS)}`)
+            .join("\n\n");
+        return `## Sub-question ${i + 1}: ${f.question}\n${srcs}`;
+    })
+        .join("\n\n---\n\n");
+    return [
+        "You are a research analyst. Write a structured report answering the task below,",
+        "using ONLY the findings provided. Cite sources inline as markdown links [title](url).",
+        "Organize by theme, note disagreements between sources, and end with a short summary.",
+        "Do not invent facts; if findings are insufficient, say so explicitly.",
+        "",
+        `Research task: ${task}`,
+        "",
+        "Findings:",
+        blocks,
+    ].join("\n");
+}
+function buildFallbackReport(task, findings) {
+    const parts = [
+        `(no text model configured — degraded to a structured source list)`,
+        "",
+        `# Research sources for: ${task}`,
+    ];
+    for (let i = 0; i < findings.length; i++) {
+        const f = findings[i];
+        parts.push(`\n## ${i + 1}. ${f.question}`);
+        for (const s of f.sources)
+            parts.push(`- [${s.title}](${s.url})`);
+    }
+    return parts.join("\n");
+}

package/dist/skills/tools/web-search-tool.d.ts

@@ -0,0 +1,46 @@
+import type { PortableTool } from "../portable-tool.js";
+import type { WebSearchBackend, WebSearchOutput, WebSearchResult } from "../../runtime/ports/web-search-contracts.js";
+export declare const WEB_SEARCH_TOOL_NAME: "web_search";
+export interface WebSearchToolParams {
+    query: string;
+    allowedDomains?: string[];
+    blockedDomains?: string[];
+    freshness?: "day" | "week" | "month" | "year" | "any";
+}
+export declare const WEB_SEARCH_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly query: {
+            readonly type: "string";
+            readonly description: "Search query string. Be specific and concise for best results.";
+        };
+        readonly allowedDomains: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: string;
+        };
+        readonly blockedDomains: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+            readonly description: "Exclude results from these domains. Cannot be used together with allowedDomains.";
+        };
+        readonly freshness: {
+            readonly type: "string";
+            readonly enum: readonly ["day", "week", "month", "year", "any"];
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["query"];
+};
+export type { WebSearchOutput, WebSearchResult };
+/**
+ * Host-provided web search backend.
+ * The host may use any search engine (SearXNG, Brave, Tavily, etc.).
+ */
+export interface WebSearchToolDeps extends WebSearchBackend {
+}
+export declare function createWebSearchTool(deps: WebSearchToolDeps): PortableTool<WebSearchToolParams>;

package/dist/skills/tools/web-search-tool.js

@@ -0,0 +1,95 @@
+// ============================================================
+// Web Search Tool — search the web for information.
+// Reference: claude-code-haha/src/tools/WebSearchTool/WebSearchTool.ts
+//            hermes-agent-2026.4.30/tools/web_tools.py
+// Category: web
+// ============================================================
+export const WEB_SEARCH_TOOL_NAME = "web_search";
+export const WEB_SEARCH_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        query: {
+            type: "string",
+            description: "Search query string. Be specific and concise for best results.",
+        },
+        allowedDomains: {
+            type: "array",
+            items: { type: "string" },
+            description: "Only include results from these domains (e.g. ['docs.python.org', 'stackoverflow.com']). " +
+                "Cannot be used together with blockedDomains.",
+        },
+        blockedDomains: {
+            type: "array",
+            items: { type: "string" },
+            description: "Exclude results from these domains. Cannot be used together with allowedDomains.",
+        },
+        freshness: {
+            type: "string",
+            enum: ["day", "week", "month", "year", "any"],
+            description: "Restrict results to a recent time window (e.g. 'week' for news, 'year' for evolving tech). " +
+                "Omit or 'any' for no time filter.",
+        },
+    },
+    required: ["query"],
+};
+const MAX_RESULTS = 10;
+export function createWebSearchTool(deps) {
+    return {
+        name: WEB_SEARCH_TOOL_NAME,
+        label: "Web Search",
+        description: "Search the web for current information. Returns top results with title, URL, and snippet. " +
+            "Use this when you need up-to-date information that may not be in your training data. " +
+            "You MUST include source URLs as markdown links when citing search results.",
+        parameters: WEB_SEARCH_TOOL_SCHEMA,
+        isReadOnly: true,
+        isEgress: true,
+        execute: async (_toolCallId, params) => {
+            // Validate mutual exclusivity
+            if (params.allowedDomains?.length && params.blockedDomains?.length) {
+                return {
+                    content: [{ type: "text", text: "Error: allowedDomains and blockedDomains cannot both be specified." }],
+                    details: { type: "web_search", error: "mutual_exclusion" },
+                };
+            }
+            // Validate query
+            if (!params.query || params.query.trim().length < 2) {
+                return {
+                    content: [{ type: "text", text: "Error: query must be at least 2 characters." }],
+                    details: { type: "web_search", error: "invalid_query" },
+                };
+            }
+            const output = await deps.search(params.query.trim(), {
+                allowedDomains: params.allowedDomains,
+                blockedDomains: params.blockedDomains,
+                maxResults: MAX_RESULTS,
+                freshness: params.freshness,
+            });
+            if (output.results.length === 0) {
+                return {
+                    content: [{ type: "text", text: `No results found for: "${params.query}"` }],
+                    details: { type: "web_search", query: params.query, resultCount: 0 },
+                };
+            }
+            const lines = [
+                `Web search results for: "${output.query}"`,
+                "",
+                "REMINDER: You MUST include source URLs as markdown links when referencing these results.",
+                "",
+            ];
+            for (let i = 0; i < output.results.length; i++) {
+                const r = output.results[i];
+                lines.push(`${i + 1}. [${r.title}](${r.url})`);
+                lines.push(`   ${r.snippet}`);
+                lines.push("");
+            }
+            return {
+                content: [{ type: "text", text: lines.join("\n") }],
+                details: {
+                    type: "web_search",
+                    query: output.query,
+                    resultCount: output.results.length,
+                },
+            };
+        },
+    };
+}

package/dist/skills/tools/workflow-tool.d.ts

@@ -0,0 +1,45 @@
+import type { PortableTool } from "../portable-tool.js";
+export type WorkflowAction = "list" | "get" | "describe" | "create" | "patch" | "setActive" | "run" | "delete";
+export interface WorkflowToolParams {
+    action: WorkflowAction;
+    workflowId?: string;
+    name?: string;
+    def?: Record<string, unknown>;
+    patch?: unknown[];
+    baseRev?: number;
+    scope?: string[];
+    active?: boolean;
+}
+export interface WorkflowToolRecord {
+    id: string;
+    name?: string;
+    rev?: number;
+    active?: boolean;
+}
+export interface WorkflowRunOutcome {
+    status?: string;
+}
+export interface WorkflowToolService {
+    list(): Promise<WorkflowToolRecord[]>;
+    get(id: string): Promise<unknown>;
+    describe(id: string): Promise<string>;
+    create(input: {
+        id: string;
+        name: string;
+        def: Record<string, unknown>;
+        active: boolean;
+    }): Promise<WorkflowToolRecord>;
+    patch(id: string, envelope: {
+        patch: unknown[];
+        baseRev?: number;
+        scope?: string[];
+    }): Promise<unknown>;
+    setActive(id: string, active: boolean): Promise<WorkflowToolRecord>;
+    run(id: string): Promise<WorkflowRunOutcome>;
+    delete(id: string): Promise<void>;
+}
+export interface WorkflowToolDeps {
+    /** Resolve the host-owned workflow service port. Keeps skills independent from orchestration internals. */
+    getService(): WorkflowToolService;
+}
+export declare function createWorkflowTool(deps: WorkflowToolDeps): PortableTool<WorkflowToolParams>;

package/dist/skills/tools/workflow-tool.js

@@ -0,0 +1,113 @@
+// ============================================================
+// Workflow Tool — agent-facing authoring/run surface over the unified WorkflowController.
+//
+// Single-track replacement of the legacy JSON step-DAG tool (plan D20). Authoring actions
+// (list/get/describe/create/patch/setActive/delete) go through the controller + file-backed
+// store; `run` delegates to the live, run-capable controller published by the ACP workflow
+// handler (workflow-service singleton). When the engine is not initialized in this context,
+// `run` fail-louds with guidance (no silent no-op; §1.5). One store, two entry points (D17).
+//
+// Category: automation
+// ============================================================
+import { randomUUID } from "node:crypto";
+const WORKFLOW_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        action: {
+            type: "string",
+            enum: ["list", "get", "describe", "create", "patch", "setActive", "run", "delete"],
+            description: "list/get/describe/create/patch/setActive/run/delete.",
+        },
+        workflowId: { type: "string", description: "Workflow id (required for all but list/create)." },
+        name: { type: "string", description: "Human-readable name (create)." },
+        def: { type: "object", description: "WorkflowDef { nodes, edges, trigger? } (create)." },
+        patch: { type: "array", description: "WorkflowPatch op array (patch)." },
+        baseRev: { type: "number", description: "Optimistic-concurrency base revision (patch)." },
+        scope: { type: "array", items: { type: "string" }, description: "Node ids to confine the patch to (scoped/框选批注 edit)." },
+        active: { type: "boolean", description: "Activation flag (create/setActive)." },
+    },
+    required: ["action"],
+};
+function text(t, details) {
+    return { content: [{ type: "text", text: t }], details: { type: "workflow", ...details } };
+}
+export function createWorkflowTool(deps) {
+    return {
+        name: "workflow",
+        label: "Workflow",
+        description: "Author and manage automation workflows on the unified engine. Workflows persist in " +
+            ".qlogicagent/workflows and are run by triggers (cron/IM/webhook) or the app. " +
+            "Actions: list, get, describe, create, patch (incl. scoped edits), setActive, run, delete.",
+        parameters: WORKFLOW_TOOL_SCHEMA,
+        shouldDefer: true,
+        isConcurrencySafe: false,
+        isReadOnly: false,
+        searchHint: "workflow automation create edit run schedule trigger pipeline 工作流 自动化 流程 触发器",
+        execute: async (_toolCallId, params) => {
+            const service = deps.getService();
+            switch (params.action) {
+                case "list": {
+                    const records = await service.list();
+                    if (records.length === 0)
+                        return text("No workflows yet. Use action=create.", { count: 0 });
+                    const lines = records.map(r => `  - ${r.id}: ${r.name} (rev ${r.rev}${r.active ? ", active" : ""})`);
+                    return text(["Workflows:", ...lines].join("\n"), { count: records.length });
+                }
+                case "get": {
+                    if (!params.workflowId)
+                        return text("Error: workflowId is required for get.");
+                    const rec = await service.get(params.workflowId);
+                    return text(JSON.stringify(rec, null, 2), { workflowId: rec.id, rev: rec.rev });
+                }
+                case "describe": {
+                    if (!params.workflowId)
+                        return text("Error: workflowId is required for describe.");
+                    return text(await service.describe(params.workflowId), { workflowId: params.workflowId });
+                }
+                case "create": {
+                    if (!params.def)
+                        return text("Error: def is required for create.");
+                    const id = params.workflowId ?? `wf_${randomUUID().slice(0, 8)}`;
+                    const rec = await service.create({ id, name: params.name ?? id, def: params.def, active: params.active === true });
+                    return text(`Created workflow "${rec.id}" (rev ${rec.rev}).`, { workflowId: rec.id, rev: rec.rev });
+                }
+                case "patch": {
+                    if (!params.workflowId || !params.patch)
+                        return text("Error: workflowId and patch are required for patch.");
+                    const outcome = await service.patch(params.workflowId, { patch: params.patch, baseRev: params.baseRev, scope: params.scope });
+                    return text(JSON.stringify(outcome), { workflowId: params.workflowId });
+                }
+                case "setActive": {
+                    if (!params.workflowId || typeof params.active !== "boolean")
+                        return text("Error: workflowId and boolean active are required for setActive.");
+                    const rec = await service.setActive(params.workflowId, params.active);
+                    return text(`Workflow "${rec.id}" active=${rec.active}.`, { workflowId: rec.id });
+                }
+                case "run": {
+                    if (!params.workflowId)
+                        return text("Error: workflowId is required for run.");
+                    // The workflow engine only runs when initialized by the app/trigger
+                    // context. In a plain CLI turn there is no live engine — return
+                    // structured guidance instead of throwing an opaque error.
+                    try {
+                        const outcome = await service.run(params.workflowId);
+                        return text(`Run "${params.workflowId}": ${outcome.status}.`, { workflowId: params.workflowId, status: outcome.status });
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        return text(`Cannot run workflow "${params.workflowId}" here: ${msg}\n` +
+                            `Activate it with action="setActive" so a trigger runs it, or run it from the app.`, { workflowId: params.workflowId, status: "unavailable" });
+                    }
+                }
+                case "delete": {
+                    if (!params.workflowId)
+                        return text("Error: workflowId is required for delete.");
+                    await service.delete(params.workflowId);
+                    return text(`Deleted workflow "${params.workflowId}".`, { workflowId: params.workflowId });
+                }
+                default:
+                    return text(`Error: unknown action "${params.action}".`);
+            }
+        },
+    };
+}

package/dist/skills/tools/worktree-tool.d.ts

@@ -0,0 +1,69 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const WORKTREE_TOOL_NAME: "worktree";
+export type WorktreeAction = "enter" | "exit" | "list";
+export interface WorktreeToolParams {
+    /** Action: enter (create worktree), exit (leave worktree), list (show all) */
+    action: WorktreeAction;
+    /** Branch/worktree name (for enter). kebab-case, max 64 chars. */
+    name?: string;
+    /** For exit: 'keep' retains the worktree, 'remove' deletes it */
+    exitAction?: "keep" | "remove";
+    /** Required true to discard uncommitted changes on exit with remove */
+    discardChanges?: boolean;
+}
+export declare const WORKTREE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["enter", "exit", "list"];
+            readonly description: string;
+        };
+        readonly name: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly exitAction: {
+            readonly type: "string";
+            readonly enum: readonly ["keep", "remove"];
+            readonly description: "For exit: 'keep' retains the worktree for later use; 'remove' deletes it.";
+        };
+        readonly discardChanges: {
+            readonly type: "boolean";
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["action"];
+};
+export interface WorktreeInfo {
+    name: string;
+    path: string;
+    branch: string;
+    isCurrent: boolean;
+    hasChanges: boolean;
+    unpushedCommits: number;
+}
+export interface WorktreeResult {
+    success: boolean;
+    worktree?: WorktreeInfo;
+    worktrees?: WorktreeInfo[];
+    previousCwd?: string;
+    error?: string;
+}
+/**
+ * Host-provided git worktree backend.
+ * Manages worktree creation, switching, and cleanup.
+ */
+export interface WorktreeToolDeps {
+    /** Create a new worktree and switch session cwd */
+    enterWorktree(name?: string): Promise<WorktreeResult>;
+    /** Exit worktree (keep or remove) */
+    exitWorktree(action: "keep" | "remove", discardChanges?: boolean): Promise<WorktreeResult>;
+    /** List all worktrees */
+    listWorktrees(): Promise<WorktreeResult>;
+    /** Check if currently in a worktree */
+    isInWorktree(): boolean;
+    /** Get current worktree info */
+    currentWorktree?(): WorktreeInfo | null;
+}
+export declare function createWorktreeTool(deps: WorktreeToolDeps): PortableTool<WorktreeToolParams>;