illusion-code 0.1.0__py3-none-any.whl

illusion/tools/enter_worktree_tool.py

@@ -0,0 +1,188 @@
+"""
+进入工作树工具
+=============
+
+本模块提供创建和进入 git 工作树的功能，用于隔离开发环境。
+
+主要组件：
+    - EnterWorktreeTool: 创建并进入 git 工作树的工具
+
+使用示例：
+    >>> from illusion.tools import EnterWorktreeTool
+    >>> tool = EnterWorktreeTool()
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+from illusion.config.settings import load_settings
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+
+class EnterWorktreeToolInput(BaseModel):
+    """进入工作树参数。
+
+    属性：
+        name: 工作树名称（可选，不提供则生成随机名称）
+    """
+
+    name: str | None = Field(
+        default=None,
+        description="A name for the worktree. If not provided, a random name is generated.",
+    )
+
+
+class EnterWorktreeTool(BaseTool):
+    """创建 git 工作树。
+
+    仅在用户明确要求使用工作树时使用。此工具创建隔离的 git 工作树并切换当前会话到其中。
+    """
+
+    name = "enter_worktree"
+    description = """Use this tool ONLY when the user explicitly asks to work in a worktree. This tool creates an isolated git worktree and switches the current session into it.
+
+## When to Use
+
+- The user explicitly says "worktree" (e.g., "start a worktree", "work in a worktree", "create a worktree", "use a worktree")
+
+## When NOT to Use
+
+- The user asks to create a branch, switch branches, or work on a different branch -- use git commands instead
+- The user asks to fix a bug or work on a feature -- use normal git workflow unless they specifically mention worktrees
+- Never use this tool unless the user explicitly mentions "worktree"
+
+## Requirements
+
+- Must be in a git repository, OR have WorktreeCreate/WorktreeRemove hooks configured in settings.json
+- Must not already be in a worktree
+
+## Behavior
+
+- In a git repository: creates a new git worktree inside `.illusion/worktrees/` with a new branch based on HEAD
+- Outside a git repository: delegates to WorktreeCreate/WorktreeRemove hooks for VCS-agnostic isolation
+- Switches the session's working directory to the new worktree
+- Use ExitWorktree to leave the worktree mid-session (keep or remove). On session exit, if still in the worktree, the user will be prompted to keep or remove it
+
+## Parameters
+
+- `name` (optional): A name for the worktree. If not provided, a random name is generated."""
+    input_model = EnterWorktreeToolInput
+
+    async def execute(
+        self,
+        arguments: EnterWorktreeToolInput,
+        context: ToolExecutionContext,
+    ) -> ToolResult:
+        name = arguments.name or f"wt-{uuid4().hex[:8]}"
+
+        # 检查是否已在 worktree 中
+        if _is_in_worktree(context.cwd):
+            return ToolResult(
+                output="Already in a worktree session. Use exit_worktree to leave first.",
+                is_error=True,
+            )
+
+        branch_name = name
+
+        # 尝试 git 仓库路径
+        top_level = _git_output(context.cwd, "rev-parse", "--show-toplevel")
+        if top_level is not None:
+            # ---- Git 仓库模式 ----
+            repo_root = Path(top_level)
+            worktree_path = _resolve_worktree_path(repo_root, branch_name)
+            worktree_path.parent.mkdir(parents=True, exist_ok=True)
+            cmd = ["git", "worktree", "add", "-b", branch_name, str(worktree_path), "HEAD"]
+            result = subprocess.run(
+                cmd,
+                cwd=repo_root,
+                capture_output=True,
+                text=True,
+                check=False,
+                stdin=subprocess.DEVNULL,
+                **({"creationflags": subprocess.CREATE_NO_WINDOW} if sys.platform == "win32" else {}),
+            )
+            output = (result.stdout or result.stderr).strip() or f"Created worktree {worktree_path}"
+            if result.returncode != 0:
+                return ToolResult(output=output, is_error=True)
+            return ToolResult(
+                output=f"{output}\nPath: {worktree_path}",
+                metadata={"new_cwd": str(worktree_path)},
+            )
+        else:
+            # ---- 非 Git 仓库：检查 WorktreeCreate/WorktreeRemove hooks ----
+            settings = load_settings()
+            hooks = settings.hooks or {}
+            has_create = "WorktreeCreate" in hooks or "worktree_create" in hooks
+            has_remove = "WorktreeRemove" in hooks or "worktree_remove" in hooks
+            if has_create and has_remove:
+                worktree_path = _resolve_worktree_path(context.cwd.resolve(), branch_name)
+                worktree_path.mkdir(parents=True, exist_ok=True)
+                return ToolResult(
+                    output=f"Created isolated worktree at {worktree_path}",
+                    metadata={"new_cwd": str(worktree_path)},
+                )
+            return ToolResult(
+                output=(
+                    "enter_worktree requires a git repository "
+                    "or WorktreeCreate/WorktreeRemove hooks configured in settings.json"
+                ),
+                is_error=True,
+            )
+
+
+def _git_output(cwd: Path, *args: str) -> str | None:
+    """执行 git 命令并返回输出。
+
+    参数：
+        cwd: 工作目录
+        *args: git 命令参数
+
+    返回：
+        命令输出字符串，失败返回 None
+    """
+    result = subprocess.run(
+        ["git", *args],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        check=False,
+        stdin=subprocess.DEVNULL,
+        **({"creationflags": subprocess.CREATE_NO_WINDOW} if sys.platform == "win32" else {}),
+    )
+    if result.returncode != 0:
+        return None
+    return (result.stdout or "").strip()
+
+
+def _resolve_worktree_path(repo_root: Path, name: str) -> Path:
+    """解析工作树路径。
+
+    参数：
+        repo_root: 仓库根目录
+        name: 工作树名称
+
+    返回：
+        解析后的工作树路径
+    """
+    slug = re.sub(r"[^A-Za-z0-9._-]+", "-", name).strip("-") or "worktree"
+    return (repo_root / ".illusion" / "worktrees" / slug).resolve()
+
+
+def _is_in_worktree(cwd: Path) -> bool:
+    """检查当前工作目录是否已在 worktree 中。
+
+    参数：
+        cwd: 当前工作目录
+
+    返回：
+        是否已在 worktree 中
+    """
+    cwd_str = str(cwd.resolve())
+    return "/.illusion/worktrees/" in cwd_str.replace("\\", "/")

illusion/tools/exit_plan_mode_tool.py

@@ -0,0 +1,69 @@
+"""
+退出计划模式工具
+================
+
+本模块提供退出计划权限模式的功能，允许代理在完成计划编写后请求用户审批。
+
+主要组件：
+    - ExitPlanModeTool: 退出计划模式的工具
+
+使用示例：
+    >>> from illusion.tools import ExitPlanModeTool
+    >>> tool = ExitPlanModeTool()
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+from illusion.config.settings import load_settings, save_settings
+from illusion.permissions import PermissionMode
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+
+class ExitPlanModeToolInput(BaseModel):
+    """无操作输入模型（工具不需要任何参数）。"""
+
+
+class ExitPlanModeTool(BaseTool):
+    """将设置权限模式切换回默认值。
+
+    当代理在计划模式下完成计划编写并准备好请求用户审批时，使用此工具。
+    该工具会读取代理之前写入的计划文件内容，供用户在审批时查看。
+    """
+
+    name = "exit_plan_mode"
+    description = """Use this tool when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval.
+
+## How This Tool Works
+- You should have already written your plan to the plan file specified in the plan mode system message
+- This tool does NOT take the plan content as a parameter - it will read the plan from the file you wrote
+- This tool simply signals that you're done planning and ready for the user to review and approve
+- The user will see the contents of your plan file when they review it
+
+## When to Use This Tool
+IMPORTANT: Only use this tool when the task requires planning the implementation steps of a task that requires writing code. For research tasks where you're gathering information, searching files, reading files or in general trying to understand the codebase - do NOT use this tool.
+
+## Before Using This Tool
+Ensure your plan is complete and unambiguous:
+- If you have unresolved questions about requirements or approach, use AskUserQuestion first (in earlier phases)
+- Once your plan is finalized, use THIS tool to request approval
+
+**Important:** Do NOT use AskUserQuestion to ask "Is this plan okay?" or "Should I proceed?" - that's exactly what THIS tool does. ExitPlanMode inherently requests user approval of your plan.
+
+## Examples
+
+1. Initial task: "Search for and understand the implementation of input handling in the codebase" - Do not use the exit plan mode tool because you are not planning the implementation steps of a task.
+2. Initial task: "Help me implement a yank-like editor shortcut" - Use the exit plan mode tool after you have finished planning the implementation steps of the task.
+3. Initial task: "Add a new feature to handle user authentication" - If unsure about auth method (OAuth, JWT, etc.), use AskUserQuestion first, then use exit plan mode tool after clarifying the approach."""
+    input_model = ExitPlanModeToolInput
+
+    async def execute(self, arguments: ExitPlanModeToolInput, context: ToolExecutionContext) -> ToolResult:
+        del arguments, context
+        # 加载设置
+        settings = load_settings()
+        # 将权限模式设置为默认
+        settings.permission.mode = PermissionMode.DEFAULT
+        # 保存设置
+        save_settings(settings)
+        return ToolResult(output="Permission mode set to default")

illusion/tools/exit_worktree_tool.py

@@ -0,0 +1,225 @@
+"""
+退出工作树工具
+=============
+
+本模块提供移除 git 工作树的功能，用于结束工作树会话。
+
+主要组件：
+    - ExitWorktreeTool: 退出并可选删除工作树的工具
+
+使用示例：
+    >>> from illusion.tools import ExitWorktreeTool
+    >>> tool = ExitWorktreeTool()
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from illusion.tools.base import BaseTool, ToolExecutionContext, ToolResult
+
+
+class ExitWorktreeToolInput(BaseModel):
+    """工作树移除参数。
+
+    属性：
+        action: 操作类型，keep 或 remove
+        discard_changes: 是否放弃未提交的更改
+    """
+
+    action: Literal["keep", "remove"] = Field(
+        description='"keep" leaves the worktree directory and branch intact on disk; "remove" deletes both.',
+    )
+    discard_changes: bool = Field(
+        default=False,
+        description='Only meaningful with action "remove". If true, force-remove even with uncommitted changes.',
+    )
+
+
+class ExitWorktreeTool(BaseTool):
+    """移除 git 工作树。
+
+    退出由 EnterWorktree 创建的工作树会话，并将会话返回到原始工作目录。
+    """
+
+    name = "exit_worktree"
+    description = """Exit a worktree session created by EnterWorktree and return the session to the original working directory.
+
+## Scope
+
+This tool ONLY operates on worktrees created by EnterWorktree in this session. It will NOT touch:
+- Worktrees you created manually with `git worktree add`
+- Worktrees from a previous session (even if created by EnterWorktree then)
+- The directory you're in if EnterWorktree was never called
+
+If called outside an EnterWorktree session, the tool is a **no-op**: it reports that no worktree session is active and takes no action. Filesystem state is unchanged.
+
+## When to Use
+
+- The user explicitly asks to "exit the worktree", "leave the worktree", "go back", or otherwise end the worktree session
+- Do NOT call this proactively — only when the user asks
+
+## Parameters
+
+- `action` (required): `"keep"` or `"remove"`
+  - `"keep"` — leave the worktree directory and branch intact on disk. Use this if the user wants to come back to the work later, or if there are changes to preserve.
+  - `"remove"` — delete the worktree directory and its branch. Use this for a clean exit when the work is done or abandoned.
+- `discard_changes` (optional, default false): only meaningful with `action: "remove"`. If the worktree has uncommitted files or commits not on the original branch, the tool will REFUSE to remove it unless this is set to `true`. If the tool returns an error listing changes, confirm with the user before re-invoking with `discard_changes: true`.
+
+## Behavior
+
+- Restores the session's working directory to where it was before EnterWorktree
+- Clears CWD-dependent caches (system prompt sections, memory files, plans directory) so the session state reflects the original directory
+- If a tmux session was attached to the worktree: killed on `remove`, left running on `keep` (its name is returned so the user can reattach)
+- Once exited, EnterWorktree can be called again to create a fresh worktree"""
+    input_model = ExitWorktreeToolInput
+
+    async def execute(
+        self,
+        arguments: ExitWorktreeToolInput,
+        context: ToolExecutionContext,
+    ) -> ToolResult:
+        run_kwargs: dict = {}
+        if sys.platform == "win32":
+            run_kwargs["creationflags"] = subprocess.CREATE_NO_WINDOW
+
+        # 获取主仓库的公共 .git 目录（worktree 内也能正确指向主仓库）
+        common_dir = _git_output(context.cwd, "rev-parse", "--git-common-dir")
+        if common_dir is None:
+            return ToolResult(output="Not in a git repository", is_error=True)
+
+        # 解析主仓库根目录
+        git_dir = Path(common_dir)
+        if not git_dir.is_absolute():
+            git_dir = (context.cwd / git_dir).resolve()
+        else:
+            git_dir = git_dir.resolve()
+        main_repo_root = git_dir.parent
+
+        # 检查当前 CWD 是否在 .illusion/worktrees/ 下
+        worktree_base = (main_repo_root / ".illusion" / "worktrees").resolve()
+        current_cwd = context.cwd.resolve()
+
+        if not _is_subpath(current_cwd, worktree_base) and current_cwd != worktree_base:
+            # 不在 worktree 中 — no-op（非错误）
+            return ToolResult(output="No active worktree session found")
+
+        worktree_path = current_cwd
+
+        # keep 操作 — 保留工作树，仅恢复 CWD
+        if arguments.action == "keep":
+            return ToolResult(
+                output=f"Worktree kept at {worktree_path}",
+                metadata={"new_cwd": str(main_repo_root)},
+            )
+
+        # remove 操作
+        # 获取分支名（在删除 worktree 之前）
+        branch = _git_output(worktree_path, "rev-parse", "--abbrev-ref", "HEAD")
+
+        # 检查未提交的更改，除非 discard_changes 为 true
+        if not arguments.discard_changes:
+            status_check = subprocess.run(
+                ["git", "status", "--porcelain"],
+                cwd=worktree_path,
+                capture_output=True,
+                text=True,
+                check=False,
+                stdin=subprocess.DEVNULL,
+                **run_kwargs,
+            )
+            if status_check.stdout.strip():
+                return ToolResult(
+                    output=(
+                        f"Worktree has uncommitted changes. "
+                        f"Set discard_changes=true to force remove.\n"
+                        f"Changes:\n{status_check.stdout.strip()[:500]}"
+                    ),
+                    is_error=True,
+                )
+
+        # 移除工作树
+        cmd = ["git", "worktree", "remove"]
+        if arguments.discard_changes:
+            cmd.append("--force")
+        cmd.append(str(worktree_path))
+
+        result = subprocess.run(
+            cmd,
+            cwd=main_repo_root,
+            capture_output=True,
+            text=True,
+            check=False,
+            stdin=subprocess.DEVNULL,
+            **run_kwargs,
+        )
+        if result.returncode != 0:
+            output = (result.stdout or result.stderr).strip() or f"Failed to remove worktree {worktree_path}"
+            return ToolResult(output=output, is_error=True)
+
+        # 删除对应的分支
+        if branch and branch != "HEAD":
+            subprocess.run(
+                ["git", "branch", "-D", branch],
+                cwd=main_repo_root,
+                capture_output=True,
+                text=True,
+                check=False,
+                stdin=subprocess.DEVNULL,
+                **run_kwargs,
+            )
+
+        output = (result.stdout or "").strip() or f"Removed worktree {worktree_path}"
+        return ToolResult(
+            output=output,
+            metadata={"new_cwd": str(main_repo_root)},
+        )
+
+
+def _git_output(cwd: Path, *args: str) -> str | None:
+    """执行 git 命令并返回输出。
+
+    参数：
+        cwd: 工作目录
+        *args: git 命令参数
+
+    返回：
+        命令输出字符串，失败返回 None
+    """
+    run_kwargs: dict = {}
+    if sys.platform == "win32":
+        run_kwargs["creationflags"] = subprocess.CREATE_NO_WINDOW
+    result = subprocess.run(
+        ["git", *args],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        check=False,
+        stdin=subprocess.DEVNULL,
+        **run_kwargs,
+    )
+    if result.returncode != 0:
+        return None
+    return (result.stdout or "").strip()
+
+
+def _is_subpath(path: Path, parent: Path) -> bool:
+    """检查 path 是否为 parent 的子路径。
+
+    参数：
+        path: 要检查的路径
+        parent: 父路径
+
+    返回：
+        是否为子路径
+    """
+    try:
+        path.relative_to(parent)
+        return True
+    except ValueError:
+        return False