Slice 3: amicode_workspace lifecycle management tool #1062

Acceptance Criteria

• amicode_workspace tool is registered in AMICODE_TOOLS with actions list, remove, and reset
• list action calls GET /experimental/worktree, returns worktree directories and branches in a readable format, and includes a count ("3 active worktrees")
• remove action accepts a directory parameter, calls DELETE /experimental/worktree with that directory, and returns confirmation or error
• reset action accepts a directory parameter, calls POST /experimental/worktree/reset with that directory, and returns confirmation or error
• All three actions translate API rejections (feature gate off, worktree not found, remove failed) into actionable error messages
• The tool degrades to a clear error when the engine client is absent (MCP transport), matching amicode_session's pattern
• EngineClientShape worktree methods (added in Slice 1) are sufficient for this tool — no additional interface extensions needed

Testing Decisions

Extend the mock engine from Slice 1's test infrastructure:

• New: workspace_lifecycle.test.ts — focused tests:
  • list → mock returns 3 worktrees → readable output with count
  • list → mock returns empty → "no active worktrees" message
  • remove with valid directory → mock remove called, confirmation returned
  • remove with non-existent directory → error translated to actionable message
  • reset with valid directory → mock reset called, confirmation returned
  • reset + API rejection → error message
  • All actions without engine client → refusal message

Key Decisions

1. Three actions, one tool. list, remove, and reset are one tool with an action parameter, not three separate tools. This keeps the tool count manageable and groups related operations.

2. No create action. Worktree creation is handled by amicode_session's workspace: "create" parameter (Slice 1). Creating a worktree without immediately binding a session to it is an edge case — if needed, the user can use the UI's "New workspace" button.

3. Directory as the identifier. Worktrees are identified by their filesystem directory, matching the engine API's RemoveInput and ResetInput schemas. The list output includes directories so the agent can pass them to remove/reset.

Constraints & Invariants

• The tool consumes the same engine worktree APIs as Slice 1 — no new engine endpoints
• The EngineClientShape.worktree interface from Slice 1 must not be modified — this slice only reads it
• The tool must work with the experimental feature gate in the same way as Slice 1 (API is authoritative, tool translates errors)

Prior Art

• packages/extension/src/amicode_tools_core.ts — the tool registry (add alongside amicode_session)
• packages/opencode/src/server/routes/instance/httpapi/groups/experimental.ts — the GET/DELETE/POST reset worktree endpoints
• packages/opencode/src/worktree/index.ts — Worktree.Service list/remove/reset interfaces
• Slice 1's EngineClientShape extension and mock engine pattern

Source

Part of #1059 · Blocked by Slice 1