v1.3.0

What's in this release

Changed

• Tool trail detail (D46 / Cursor·Grok-aligned): Verb-group headers use tool families (Fetched N pages, Searched N queries); web_fetch / web_search titles show host/query; step rows show the target URL/query; expand attaches a truncated result preview. View in Terminal works for any tool step (not only shell).
• Allow network default On (D15): New installs expose web_search by default; turn off in Settings → General to hide it. Catalog also hides remember_preference when Memory is off.
• Tool-skip harness (D44 / Grok-aligned): Live-fact turns (weather/news/URL) that get a prose answer with zero tool_calls trigger one reminder + tool_choice=required retry so advertised tools are actually used.
• Usage / Steps (D9 · D22): Composer + → Usage removed; Overview Session Token Analytics keeps the section but shows — placeholders until provider-true usage (DECISIONS Q-USAGE-1).
• Subtask budgets (D10): Nested explore/implement loops use 16 / 12 tool-step caps (was flat 8); explore system prompt steers away from repeated list_dir.
• Background jobs (D11): Composer bar shows running jobs only; finished jobs seal into the Chat timeline (Supervisor monitor + View output card).
• Kill feedback (D11): Kill is optimistic (chip flips immediately); user Kill no longer shows the red failure toast; process reap is off-thread.
• Permission modes (D27 / D54): Composer pill is Agent / Plan / Full / Ask (Cursor-style order & labels; ∞ / checklist / warning / chat). Default Agent (auto_edit). Ask is conversation-only; legacy Explore maps to Ask. First-run onboarding Permissions step matches (selectable modes; no longer “Ask only / coming soon”).

Fixed

• Plan approve → execute: After the user says 确认/批准/按计划/按照你说的, Chat injects an execute reminder and tool-skip nudge so the model must todo_write then apply_patch/search_replace — no more re-asking for confirmation or claiming done with prose only.
• Shell writes → Changes (no git required): run_terminal_cmd mutations (cat >, mv, rm, …) are detected via workspace mtime snapshot and fill files_changed / Changes / D47 chips even when the workspace is not a git repo. Tool copy steers models to prefer apply_patch/search_replace for source edits.
• Chat ASGI / max-iterations leak: Long tool loops that close the WebSocket no longer surface Unexpected ASGI message 'websocket.send'… as the agent reply; live emits swallow closed-socket errors. Hitting the 24-step budget now attempts one tool-free synthesis answer. web_fetch rejects search-engine result pages (Bing/Google/…) so open questions use web_search instead of burning the budget.
• Network thrash cap: Open-web Q&A soft-caps at 3 web_search/web_fetch calls (stop-and-answer nudge) and hard-caps at 5; prompt/tool copy steers 1 search → ≤2 fetches → answer like mainstream agents.
• Live tool UX: One loading cue only — spinner + Working… / Thinking… on the agent label. Live process is a Grok-style flat step stream (no dense “Fetched N pages” box); each step stays visible in chat with a Working… footer.
• Pinned Todos width: Sticky Todos rail matches the chat content box (full column between sidebars) with an opaque curtain so right-aligned bubbles cannot peek beside; card is w-full of that rail. Pin stays for the whole turn (even 3/3) so todos are not nested narrow inside Working.
• Auto-open generated HTML in system browser: When the agent finishes writing an .html / .htm file (prefer index.html), Clutch opens the rendered page in the OS default browser (not the in-app source preview). Inline HTML edit cards show Open in browser instead of dumping source.
• Process trail UX: Unified live/sealed step rows (status + title + focus line); todo_write hidden from the trail (Todo card is SSOT); expand only shows a capped result body — no heavy Target card. Expanding a step no longer force-scrolls the chat (dock-only re-pin).
• Network soft-cap nudge: After the web budget, reminds the model to continue write tools for file/HTML deliverables instead of ending with prose alone.
• SERP web_fetch → web_search: Calling web_fetch on google.com/search / Bing SERPs auto-runs web_search with the query instead of failing 3× and tripping the loop fuse. Policy rejects no longer count toward the fuse.
• Models list hid OpenCode Zen: Catalog models without a saved key stay listed (use + Add model for keys); footer picker still only shows usable models. clutch_managed is true for Keychain-backed providers so Edit remains available.
• OpenCode Zen key save blocked by TLS: Transient SSL/urlopen failures no longer block saving an OpenCode Zen API key — only explicit key rejection does.
• HTML deliverable hang: After the agent writes a .html page (browser auto-opens), inject a one-shot wrap-up nudge so Flash models mark todos done and finish the turn instead of idling on Working….
• HTML auto-open on history: Opening a past session no longer re-opens .html in the browser — auto-open only when a live turn newly writes the file.
• Deliverable intent (need → kind): Chat decomposes the user ask (search / summarize / visualize / present / implement) and infers deliverable kind — users need not name “HTML/图片”. Browser auto-open only for inferred pages; image/video/code/answer asks get a correction nudge if the model fakes an HTML page; feature-plan HTML stack only when a page was inferred.
• Real images + clean artifacts (D54): Chat gets generate_image (configured image model → .clutch/generated/images/). Infographic/信息图/可视化 count as image intent; writing .html as a fake visual is refused. New chat .md/.html/image dumps at the repo root are relocated to .clutch/artifacts/ (like other agents’ output folders).
• Auto media from Settings: After a Chat turn that needs image/video, Clutch auto-calls the user’s configured Agnes (or other) image/video model — no footer model switch required. If no key is configured, the chat reply states clearly that the last step failed and how to fix it. Also adds generate_video tool.
• LLM SSL urlopen leak: Agnes/OpenAI-compat chat via urllib no longer surfaces raw <urlopen error [SSL: UNEXPECTED_EOF…]> in Chat — retries once and shows a short TLS/retry hint instead.
• web_fetch SERP false positive: baijiahao.baidu.com/s?id=… (百家号文章) is no longer blocked as a Baidu search page.
• apply_patch End Patch heal: Truncated patches missing *** End Patch are auto-closed when the body is otherwise valid; after 2 apply_patch failures a write-recovery nudge steers toward search_replace before the loop fuse trips.
• Plan-approve resume UX: After Approve, Chat keeps showing Working… while status === running (no longer looks frozen until a new user message appears).
• Sidebar recent-first: Projects and sessions sort by last chat activity (updated_at); reopening an old chat floats it (and its project) to the top so you don’t scroll to the bottom.
• E2E MVP closed-loop: With CLUTCH_E2E_SANDBOX + CLUTCH_E2E_FAKE_LLM=1, workflow source=flow short-circuits route_engine (no real Claude CLI) so sandbox MVP closed-loop reaches awaiting_human → approve → passed; plain_chat still uses hybrid/FAKE_HYBRID.
• D10 explore PM: Agnes Flash explore subtasks no longer die at 8 iterations before summarizing.
• D8 PM acceptance polish: todo_write no longer explodes JSON-string todos into per-character items; compaction patches replace the message list (digest visible); manual /compact appends a User /compact bubble then an amber digest at the feed end; Stop flips to Stopping/Continue immediately; status questions (还剩哪些 todo) instruct the model not to resume edits; slash notices use a high-contrast dark toast.

Added

• Git worktree isolation (D32): Optional Enable worktree in Chat — Agent cwd points to .clutch/worktrees/<id>; Merge or Discard UI; main workspace stays clean until merge.
• Scheduled / loop tasks (Cap-D25 / extension D25 scheduler): Persisted interval tasks (default off, confirm to enable); list/delete API + Chat panel; asyncio tick fires notifications or optional Agent turn.
• Code diagnostics MVP (D24): Builtin diagnostics tool runs tsc / ruff / py_compile when present; issues inject into next turn + Chat issues strip.
• Headless / CI Agent (D36): POST /api/agent/run and python -m src.headless_cli -p "..." share the Chat Agent core (chat_runner / mcp_react).
• External Grok CLI (D14): Optional grok-cli engine routes grok -p when on PATH; clear unavailable when missing; trails in Terminal/steps.
• Foreground → background (D34): Move to background bar transfers live run_terminal_cmd into bg_jobs.
• Cross-session memory (D16): Settings Memory toggle, remember_preference tool, memory prompt layer, Clear memory.
• Tool hooks (D17): User/project hooks.json PreToolUse/PostToolUse deny rules; Chat tool steps show Hook denial reason.
• Capability packs (D35): Import zip/dir bundles (skills + hooks + MCP) from Settings → Skills; uninstall support.
• Chat slash commands (capability D18): Composer / picker adds /plan (plan mode), /compact (force context fold + digest), /todos (focus Todo card), /help, alongside Skills; POST /api/runs/{id}/compact for forced compaction.
• Session fork + file rewind (capability D23): Message Fork session here copies transcript from that turn into a new session; composer Rewind restores the Agent’s last file edits and leaves a Supervisor audit line.
• Goal tracking (capability D29): Builtin goal_write streams a live Goal bar (title + progress) until marked done.
• Session overview board (capability D30): Composer exposes a compact session board (goal / todos / plan / permissions / MCP) for at-a-glance status.
• Clutch Agent builtin tools (capability D1): Default clutch-tools for Clutch Agent with an authorized workspace — read_file, list_dir, grep, search_replace, run_terminal_cmd, plus existing apply_patch. No Hub bind required for builtins.
• Agent Manager MCP Hub binding (capability D37): Clutch Agent edit Module 4 restores Hub server checkboxes; save persists mcpServerIds (no longer wiped). Detail pane lists bound servers.
• Chat live tool activity (capability D46): Clutch Agent / MCP ReAct tool trail uses a Grok/Cursor-style verb_group fold (Fetched 4 pages, Searched 1 query); expand for target + result preview. Steps stream via pending_tool_steps, then seal onto the assistant message as toolSteps (survive refresh). Log parsing remains fallback only.
• Layered runtime prompt (capability D53): System prompt assembled as layers (system / env / protocol / workspace rules / skills catalog / plan-mode reminder). Skills default to name+blurb (full SKILL.md on demand). Agent Manager shows a Runtime prompt layers panel (refreshable); GET /api/agents/{id}/prompt-assembly returns the same summary. Agent Manager markdownDoc is the editable protocol segment only.
• Chat files-changed chips (capability D47): Paths from this turn’s files_changed seal onto the assistant message as filesChanged; Chat renders clickable chips (optional image thumbs) that open the existing workspace file preview (DECISIONS D42). Changes panel file_changed events unchanged.
• Plan-before-edit + in-chat plan card (capability D2 + D49): Builtin propose_plan pauses the ReAct loop; Chat shows a Plan card with Approve / Revise / Cancel. Writes resume only after Approve; Revise asks the agent to call propose_plan again. Trivial turns may skip the tool.
• Chat todos (capability D3 + D49): Builtin todo_write updates agent_todos live and seals todoList on the assistant message; Chat renders a Todo card (pending / in_progress / completed). While any item is incomplete during a run, the Todo card sticks to the top of the chat scroll area; when all items are checked it unpins and scrolls with the sealed bubble. Sticky and sealed Todo cards support chevron collapse/expand via shared chatAgentCard chrome (default expanded; collapsed header keeps title + done/total). todo_write is not a human-approval gate (UI state only). Plan steps strip model-supplied 1. prefixes so cards do not show 1. 1. …; tool-trail header no longer appends a redundant total count next to “Awaiting approval”. Live Working UI uses pending_tool_steps only (does not replay the previous turn’s terminal_logs wave on a trivial follow-up). Supervisor approval bubbles dedupe by approvalKey; plan cards no longer seal a frozen tool trail; ReAct max_steps raised to 24 so plan+todo+edits do not falsely hit the iteration wall. Approval Args render as expandable/scrollable JSON (not a 120-char ellipsis); chat list scroll padding clears the fixed Allow/Reject dock.
• Structured question card (capability D4 + D49): Builtin ask_user_question pauses ReAct for a real fork (e.g. Redis vs Memcached). Chat shows a Question card with option buttons; picking an option (or typing a custom answer in the dock) resumes with the selection. Cancel ends the turn. Uses its own pause path (not the generic MCP risk Allow gate).
• Self-check verification report (capability D5 + D50): Builtin submit_verification seals a Verification report card in Chat (steps + passed/failed). Failed reports include next actions; claiming passed while session todos are incomplete is forced to failed. View changes opens sealed changed files (D47 / D42 preview).
• Diff review in Chat (capability D6 + D50): Each successful edit streams a Cursor-style per-file Diff card into the Chat timeline immediately (filename + +/- hunks). Optional submit_diff_summary still publishes a multi-file review card. Coexists with the Changes rail.
• Project rules + Skills (capability D7, Grok-aligned): Workspace rules load along git root → authorized workspace (AGENTS.md / CLAUDE.md + .grok/.claude/.cursor/rules; deeper wins). Skills use an open catalog (enabled global ∪ project ∪ custom Search Paths, plus optional Agent binds; same-name project > custom > global). Full SKILL.md via read_skill. User-home AGENTS rules deferred. Activating a workspace rotates project skill mounts only — manual Search Paths stay.
• Long-chat task state (capability D8, PM ✅): Context compaction keeps Todo/Plan in the digest + task_state layer; /compact shows User /compact then amber「上下文压缩摘要」at the end of Chat so「还剩哪些 todo」survives fold.
• Run control in Chat (capability D9): Stop leaves a resume hint + Continue control; consecutive tool failures trip a loop fuse (env CLUTCH_LOOP_FUSE_FAILURES); Chat composer shows live Steps n/m · ~tok (run_stats).
• Subtask delegation (capability D10 + D48): Builtin delegate_subtask (explore | implement) runs a capped nested ReAct loop; parent Chat shows nested Subtasks cards (live + sealed) with status/summary and expandable steps.
• Background commands (capability D11): run_terminal_cmd supports background=true plus list_background_jobs / kill_background_job; Chat shows a Background jobs bar (view output / kill) while the foreground turn stays free.
• Git + web fetch (capability D12): Builtin git_status / git_diff / git_commit (commit is risky/approval) and web_fetch for URL text summarization; steps appear in the D46 tool trail.
• Permission rules (capability D13): Persist allow/ask/deny command patterns; dangerous shell (rm -rf, sudo, …) force-ask even in Full; Chat permission menu Clear remembered approvals.
• Chat ↔ Terminal sync (capability D51): Tool steps (including web_fetch / web_search) and subtask cards expose View in Terminal — opens the right-rail Terminal tab and highlights the matching [CHAT] Step log line (stays in Chat mode; does not jump to interactive Terminal / “Connecting…”).
• Capability ↔ Chat UI gate (capability D52): PRODUCT_INTRO ships a Capability → Chat UI table (D1/D10/D37 spot-check rows required); scripts/check-capability-ui-table.sh is wired into check-doc-drift.sh (INV-D52).
• MCP Hub trusted status (capability D38): Remove misleading Hub “under development” banner; per-server Test connection (POST /api/mcp/servers/test) returns tool count on success or a readable error on failure.
• MCP transport honesty (capability D39): Hub registration is stdio-only (SSE option disabled; API rejects new SSE registers); optional Env KEY=value lines on register; legacy SSE rows stay visible as unavailable.
• Chat MCP binding badge (capability D40): Clutch Agent Chat shows N MCP · ~M tools (popover with server names) or a Bind MCP CTA when Hub bindings are empty.
• MCP Hub real tool names + one-click FS (capability D42∥D44): Agent Manager catalog/detail show real Hub tool names (not fake permission chips); Module 4 Enable workspace file tools binds local-fs in one click.
• MCP resources pin-for-Chat (capability D43): Hub can Browse resources on stdio servers; Pin for Chat stores a text snapshot injected into Clutch Agent prompt layers (mcp_resources).
• Ignore rules + strict sandbox (capability D21): Builtin list_dir / grep / read_file respect workspace .gitignore and .clutchignore; ignored paths are omitted from listings/search and rejected on direct read. Settings → General → Strict sandbox rejects shell commands and paths that escape the authorized workspace with readable errors.
• Usage dashboard (capability D22): Click the D9 Steps n/m · ~tok strip to open a history panel (current run + recent sessions); sidecar persists session_tokens / tool_steps on session records when runs end or are touched.
• Chat mode presets (capability D27): Composer permission menu switches Explore / Plan / Edit automatically (explore / plan / auto_edit); Explore hard-blocks write/exec MCP tools while allowing read/search.
• MCP tool discovery (capability D28): When bound Hub tools exceed ~24, ReAct exposes search_mcp_tools plus a few always-on aliases instead of dumping every schema; search enables matches for subsequent calls (D46 trail shows the search step).
• Web search builtin (capability D15): Settings Allow network toggles builtin web_search (DuckDuckGo HTML via httpx). Off hides the tool and rejects calls with a readable error.
• Rich file read (capability D33): Builtin read_file routes images through local OCR/analysis (chat_content path) and PDFs through pdftotext when on PATH; otherwise a clear install hint.
• Plan step comments (capability D31): Pending plan cards expose per-step comment fields; Revise sends structured JSON feedback so the agent revises propose_plan before execution.
• Agent busy message queue (capability D20): While Clutch Agent / MCP plain chat is running, new sends enqueue above the composer with Queue #n position badges and per-item cancel; messages drain in FIFO order when the turn returns to idle.
• Thinking stream (capability D19): Models that return reasoning_content stream into the D46 Agent live activity fold as Thinking / 思考 (same strip as tool steps). Long run_terminal_cmd output attaches as expandable step detail snippets.
• Background job monitor (capability D26): When a D11 background job finishes, fails, or is killed, Chat gets a [Monitor] Supervisor line; failures also raise a short composer toast.
• Compact tool approval bar: awaiting_human uses a slim Allow / Reject strip above the composer (optional note + Retry), replacing the large Human-In-The-Loop card.
• Sidebar session spinner: MCP approve/complete now updates session history status; active Coding rows follow live clutchStatus so finished chats stop spinning.

Changed

• Chat composer (minimal): Visible chrome is only + · mode · send (Cursor/Copilot-style). Sessions, Rewind, MCP, Worktree, schedule, and usage live in the + menu; idle stacked bars removed; active worktree still shows a slim status chip.
• Removed redundant Explore / Plan / Implement pills above the Chat composer; the same modes remain in the permission menu.
• Clutch Agent system prompt documents clutch-tools usage.

Feature/patch release — Coding image paste & click-to-preview, Design handoff/Spec flow polish, workspace history stability.

Added

• Coding image paste (Chat + Terminal OrchestratorBar): Clipboard/attach images from Clutch composers (not xterm). Chat always sends multimodal first; on vision soft-refuse / API reject, retries with local OCR/palette analysis. Local CLI agents (Mimo / Claude Code, …) get workspace file refs (@path / [file:]) instead of base64 on argv. Terminal uploads to .clutch/attachments/ with * gitignore + size-triggered GC; send button Loading during upload.
• Click-to-preview artifacts: Chat paths / [file:] / @path / fenced code blocks open the App preview overlay (large content uses plain <pre>; images open as media). Terminal xterm + dispatch history linkify paths/filenames with workspace resolve (exact → unique basename fuzzy); missing/ambiguous shows toast. Terminal Overview shows attachment image thumbnails on dispatch records (click to enlarge).
• Pillow + pytesseract: Declared orchestrator dependencies for local image analysis / OCR fallback (system tesseract binary still required for OCR text).

Changed

• Design Spec→UI continuous by default (D40): Prompt generates Spec then screens in one run — no confirm CTA. Opt-in pause with CLUTCH_DESIGN_SPEC_CONFIRM=1 (awaiting_spec_confirm + Confirm Spec & Generate UI).
• Design handoff SSOT (D39/D41): Preview Demo → Coding stepped flow. Generate is a deterministic HTML→React export (no LLM redraw): real per-screen .tsx, prototype Tailwind CDN theme, contract Links in source. Preview scaled-to-fit + open full size → Approve → Send to Coding (wire APIs next).
• Design Spec soft-confirm + flow discipline (D40): Soft-confirm is opt-in (CLUTCH_DESIGN_SPEC_CONFIRM=1); brief enhance before Spec; declared iterate modes (Edit / Add / Variant / Revise Spec); async iterate + confirm-spec; HTML prompts allow semantic buttons/data-clutch-id for IUE.

Fixed

• Chat Thinking bubble height: Typing indicator no longer mirrors the last user bubble (image messages made a huge empty box). Uses normal agent-bubble width + min-h-9 (single-line reply height), not a w-fit pill.
• Design “New Design” not at top of sidebar: Clicking New Design reused an old empty draft (kept its started_at / history position). Always create a fresh session at the top and delete prior empty New Design drafts.
• Design iterate stuck “Generating…” overlay: Async Edit/Pick iterate left drawing true and round pin on after poll reached ready, so the artboard kept the spinner and could show stale HTML. Clear overlay + unpin to latest round when the session finishes.
• Workspace list / session history desync (D43): Project ids are now path-stable (sha256 of resolved path); legacy random ids migrate on load and remap history.json. workspaces.json uses atomic replace. Default store refuses ephemeral /tmp-style authorize (tests must set CLUTCH_STORAGE_DIR / CLUTCH_E2E_SANDBOX). Desktop E2E passes CLUTCH_STORAGE_DIR into tauri:e2e so sandboxes cannot wipe clutch_dev.
• Coding/Design image try-first: Attached images are always sent to the LLM as multimodal first. Only when the model soft-refuses vision or the API rejects image input do we retry with local OCR/palette analysis (Coding uses a chat-specific fragment without Design hex mandates).
• Agnes 2.0 Flash chat vision: Agnes chat models are treated as vision-capable; clipboard pastes are attempted multimodally (no preemptive data: downgrade).
• Chat vision history: _history_for_llm no longer flattens multimodal user turns to [image omitted] when vision is enabled for the turn.
• Sidebar session history for all workspaces: Hydrate/load history for every project in the sidebar, not only the active one.

---

Install

macOS (Apple Silicon only):

curl -fsSL https://raw.githubusercontent.com/fancy1108/Clutch/main/scripts/install.sh | bash

Or Homebrew:

brew tap fancy1108/clutch
brew install --cask clutch

Windows:

irm https://raw.githubusercontent.com/fancy1108/Clutch/main/scripts/install.ps1 | iex

Or download *-setup.exe / *.msi from Assets on this page.

Full guide: docs/INSTALL.md · docs/PACKAGE_MANAGERS.md

Upgrade

Situation	Action
macOS v1.0.0 / v1.0.1	Install v1.0.2+ DMG manually once — older builds lack the in-app updater
macOS v1.0.2+	Follow the in-app update banner, or reinstall from Assets
Homebrew	brew upgrade --cask clutch
Windows	Download and run the new installer (no in-app updater yet)

Details: docs/UPDATES.md · docs/INSTALL.md §3

macOS: first launch (unsigned app)

Clutch is unsigned (no Apple notarization yet — see D31). Gatekeeper warnings are expected, not malware or a corrupt download.

You may see: “cannot verify developer”, “Clutch is damaged”, or double-click does nothing.

Fix (pick one):

1. Finder: Applications → right-click Clutch.app → Open → Open again.
2. Terminal (one-time): xattr -cr /Applications/Clutch.app && open -a Clutch

More: docs/INSTALL.md §2–§4 · docs/DATA_AND_PRIVACY.md

Windows

Windows 10/11 x64 MSI and NSIS (.exe) may appear under Assets (since v1.0.2).

Item	Note
CI	Built by GitHub Actions; pytest and packaging checks pass
Smoke test	Maintainers have not completed full manual smoke on physical Win10/11 (#23)
Code signing	None — SmartScreen may warn; verify SHA-256 and Release source first

Report issues: GitHub Issues (include installer filename and Windows version).

Verify download

Checksum (recommended):

shasum -a 256 -c SHA256SUMS.txt

(Run in the folder where you downloaded the DMG and SHA256SUMS.txt.)

After launch (~5 s):

curl -s http://127.0.0.1:8123/health

Expected: {"status":"ok"}