openclacky 0.9.7 → 0.9.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d394950ed8cf36ccbd3b7652e96c92c4aa393149000e025724536ca47b8eb3a8
-  data.tar.gz: b4fd60b391e11c6677d4816ee4747faa486edb3b8d41bba42b16a875bc1e5b6d
+  metadata.gz: bc91293707f008c4b110c563d2c03e295cc6c337d456c050ccfa79b761fb8993
+  data.tar.gz: 7cc5b5a1a98c59e8cb0a5779e6ce8a06ee64d41e814c0ba1e4ace2800b8f8670
 SHA512:
-  metadata.gz: 57631797dd271d127aae893c6f62977234af8a9712b301e6b8dadb82c803fd878b0d9ac7e84bda9a9331e8a4eacb78c8cb2387ac27da85ed7990fe01d2a05c11
-  data.tar.gz: 4b4cdfec917d2eb82d80b6b79902f178ac693ccaef82e5bda7075a22bac34e01bf28dbeadc0c7b259d1333df978d66c150419b71df744fa53a74a2db887b148c
+  metadata.gz: e2448da89cc3c21bee66d370f9641246d631ba477d8662cf72093439c52f0c91e9eac1d9584aa03f84aa1406257f723cf68b05f8c0d84a33c8eed67fde1e6e23
+  data.tar.gz: 0e88e8994f4d6a3ceae39e925831c9462c539726e1181c4624734117efc1444821df646609da19610655a6c395f45a007ba9f1851ac2aae04d37966fbdf32c83

data/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.8] - 2026-03-23
+
+### Added
+- **Real browser automation via CDP**: the browser tool now drives a real Chromium browser using the Chrome DevTools Protocol — structured action schemas, snapshots, screenshots, and full page interaction are all supported
+- **Browser DevTools MCP integration**: the browser connects to Chrome's DevTools via MCP, enabling deeper inspection and control beyond standard WebDriver capabilities
+- **Browser manager in Web UI**: a new browser management panel lets you start, stop, restart, and monitor the connected browser session directly from the Web UI
+- **WeChat (Weixin) channel support**: the agent can now receive and reply to messages via WeChat, including sending and receiving images
+- **Feishu Docs integration**: the agent can now read and process Feishu (Lark) documents directly as context
+- **PDF preview in Web UI**: PDFs attached to a conversation now render inline in the chat interface
+- **Session source tracking**: sessions now track where they originated (Web UI, Feishu, WeCom, WeChat, CLI) and display the source in the sessions list
+- **Sessions list in Web UI**: a dedicated sessions UI shows all your recent conversations with source badges and load-more pagination
+- **Setup session type**: a special onboarding session type is available to guide new users through initial configuration
+- **Personal website skill**: a built-in skill that generates and publishes a personal profile page (linktree-style) from your user profile
+- **Sub-directory `.clackyrules` loading**: project rules files in subdirectories are now discovered and merged automatically
+- **Self-improving response parser**: the parser now repairs itself when it encounters malformed tool-call sequences, improving reliability with all models
+- **UJK format support**: the agent can now handle UJK-encoded content in file and channel inputs
+- **Browser toggle in Web UI**: a toggle in the settings sidebar lets you enable or disable browser control without restarting
+- **Logo and QR code on homepage**: the Web UI homepage now displays the product logo and a shareable QR code
+- **Clear thinking in channel**: channel messages now strip internal `<thinking>` blocks before sending the reply to the user
+
+### Fixed
+- **`invoke_skill` tool-call sequence**: skill invocations via tool call now correctly follow the expected request/response order, preventing out-of-sequence tool results
+- **URI parsing for edge cases**: fixed a crash when parsing certain malformed or unusual URIs
+- **Doc reader parsing**: fixed an issue where some document formats were not correctly parsed by the doc reader tool
+- **Zip skill location discovery**: fixed skill loading from zip files installed in non-standard locations
+- **Install script compatibility**: the install script now explicitly uses bash to avoid failures on systems where `/bin/sh` is not bash
+
+### More
+- Rename `working` → `thinking` in agent status display
+- Channel and Web UI now sync session state in real time
+- Cost usage display improvements
+
 ## [0.9.7] - 2026-03-20
 
 ### Added

data/docs/browser-cdp-native-design.md

@@ -0,0 +1,195 @@
+# Browser Tool: Native CDP Integration Design
+
+## 背景与目标
+
+现有的 browser tool 依赖 `agent-browser`（Rust 二进制，通过 npm 分发），每次使用都启动一个独立的 Chrome 实例，存在以下问题：
+
+- 用户登录态、Cookie 无法复用
+- 需要额外安装 npm / agent-browser
+- 每次任务弹出新 Chrome 窗口，体验差
+- 依赖链长：npm → agent-browser binary → Chrome for Testing
+
+**核心目标**：Clacky 直接复用用户已打开的 Chrome，继承所有登录态和 Cookie，零额外依赖。
+
+---
+
+## Chrome 146 的关键变化
+
+### 时间线
+
+| Chrome 版本 | 行为 |
+|------------|------|
+| ≤ 135 | `--remote-debugging-port` 可连接 default profile（不推荐但能用）|
+| 136 ~ 145 | Default profile 被封锁，必须用 `--user-data-dir` 开隔离 profile（空的，无登录态）|
+| **146+** | 新增 **autoConnect toggle**，一次开关，直接连真实浏览器，Consent-based ✅ |
+
+### 用户操作（一次性）
+
+1. 打开 `chrome://inspect/#remote-debugging`
+2. 勾选 **"Allow remote debugging for this browser instance"**
+3. Chrome 在 `127.0.0.1:9222` 启动 CDP server
+
+之后每次 Clacky 连接时，Chrome 会弹一次 **"Allow remote debugging?"** 权限确认框，用户点 Allow 即可。
+
+---
+
+## 技术方案：纯 Ruby CDP Client
+
+### 核心发现
+
+Chrome 146 的 autoConnect 模式**不暴露标准 `/json` HTTP endpoint**（返回 404），而是通过一个文件告知连接信息：
+
+```
+~/Library/Application Support/Google/Chrome/DevToolsActivePort
+```
+
+文件内容格式：
+```
+9222
+/devtools/browser/98823857-17b3-48ec-8f24-5805e3012a05
+```
+
+第一行是端口，第二行是 WebSocket path，直接拼成：
+
+```
+ws://127.0.0.1:9222/devtools/browser/98823857-17b3-48ec-8f24-5805e3012a05
+```
+
+### 连接流程
+
+```
+1. 读 DevToolsActivePort 文件
+        ↓
+2. WebSocket 连接 Browser endpoint
+        ↓
+3. Target.getTargets → 列出所有真实 tab
+        ↓
+4. Target.attachToTarget(targetId, flatten: true) → 获得 sessionId
+        ↓
+5. 通过 sessionId 发送 CDP 命令操作指定 tab
+```
+
+### 依赖
+
+**零新依赖**，只用已有的：
+- `websocket-driver`（已在 gemspec）
+- `socket`（Ruby 标准库）
+- `net/http`（Ruby 标准库）
+- `json`（Ruby 标准库）
+
+### 已验证能力
+
+实测（2026-03-20）通过脚本验证：
+
+- ✅ 读取 DevToolsActivePort，发现 9222 端口
+- ✅ WebSocket 连接 Browser endpoint
+- ✅ `Target.getTargets` 列出用户所有真实 tab（含标题、URL）
+- ✅ `Target.attachToTarget` attach 到指定 tab
+- ✅ `Runtime.evaluate` 执行 JS（获取 URL、title 等）
+- ✅ `Page.captureScreenshot` 截图
+- ✅ `Target.createTarget` 开新 tab 并导航
+- ✅ 复用用户登录态（访问 yafeilee.com/admin 直接进后台，无需重新登录）
+
+---
+
+## 实施方案
+
+### 第一层：Discovery（发现层）
+
+```ruby
+# 检测 Chrome 是否开启了 remote debugging
+def discover_chrome_cdp
+  port_file = File.expand_path(
+    "~/Library/Application Support/Google/Chrome/DevToolsActivePort"
+  )
+  return nil unless File.exist?(port_file)
+
+  lines = File.read(port_file).strip.split("\n")
+  port = lines[0].to_i
+  path = lines[1]
+
+  # 验证端口确实在监听
+  TCPSocket.new("127.0.0.1", port).close
+  { port: port, path: path, ws_url: "ws://127.0.0.1:#{port}#{path}" }
+rescue Errno::ECONNREFUSED
+  nil
+end
+```
+
+**没有发现时的引导**：
+
+> "请在 Chrome 地址栏打开 `chrome://inspect/#remote-debugging`，
+> 勾选 'Allow remote debugging for this browser instance'，只需一次。"
+
+### 第二层：CDP Client（通信层）
+
+新建 `lib/clacky/tools/cdp_client.rb`，实现：
+
+- WebSocket 连接管理
+- 命令发送（带 id）/ 响应匹配
+- Session 管理（Browser-level vs Tab-level）
+- 事件监听（Page.loadEventFired 等）
+
+### 第三层：Browser Tool 改造
+
+`lib/clacky/tools/browser.rb` 改造策略：
+
+```
+优先级 1: 检测 DevToolsActivePort → 用户真实 Chrome（Native CDP）
+优先级 2: Fallback → 现有 agent-browser（向后兼容）
+```
+
+### macOS 路径（其他平台待补充）
+
+| 平台 | DevToolsActivePort 路径 |
+|------|------------------------|
+| macOS | `~/Library/Application Support/Google/Chrome/DevToolsActivePort` |
+| Linux | `~/.config/google-chrome/DevToolsActivePort` |
+| Windows | `%LOCALAPPDATA%\Google\Chrome\User Data\DevToolsActivePort` |
+
+---
+
+## 关键问题与结论
+
+### Q: `/json` endpoint 返回 404，怎么办？
+
+Chrome 146 autoConnect 模式不走 HTTP `/json`，改用 `DevToolsActivePort` 文件 + 直接 WebSocket 连接。
+
+### Q: ferrum gem 是否适用？
+
+**不适用**。`Ferrum::Browser.new(url: "http://localhost:9222")` 虽然能连接到已有 Chrome，但会创建新的 incognito browser context，不复用用户的 tab 和登录态。需要绕过 ferrum，直接操作原始 CDP。
+
+### Q: 每次连接都要点 Allow？
+
+是的，Chrome 146 每次新的 WebSocket 连接都会弹确认框。这是 Chrome 的安全 consent 机制，无法绕过，但体验上是可以接受的（用户清楚地知道浏览器被控制了）。
+
+### Q: agent-browser 是否彻底废弃？
+
+建议渐进迁移：先并行运行，Native CDP 作为优先路径，agent-browser 作为 fallback，稳定后再移除。
+
+---
+
+## 参考资料
+
+- [Chrome 146 autoConnect 介绍 - DEV Community](https://dev.to/minatoplanb/chrome-146-finally-lets-ai-control-your-real-browser-google-oauth-included-28b7)
+- [One Toggle That Changed Browser Automation - LinkedIn](https://www.linkedin.com/posts/surajadsul_one-toggle-that-changed-the-browser-automation-activity-7439161929664864257-0v8z)
+- [Chrome DevTools MCP 连接模式详解](https://www.heyuan110.com/posts/ai/2026-03-17-chrome-devtools-mcp-guide/)
+- [agent-browser #412: Support --auto-connect](https://github.com/vercel-labs/agent-browser/issues/412)
+- [Chrome DevTools Protocol 官方文档](https://chromedevtools.github.io/devtools-protocol/)
+- [DevToolsActivePort WebSocket path 说明](https://deepwiki.com/ChromeDevTools/chrome-devtools-mcp/2.3-connection-modes)
+- [ferrum issue #320: Connect to existing Chrome](https://github.com/rubycdp/ferrum/issues/320)
+- [Chrome remote-debugging security changes](https://developer.chrome.com/blog/remote-debugging-port)
+
+---
+
+## 测试脚本
+
+原型验证脚本位于：`tmp/cdp_test.rb`
+
+运行前提：
+1. Chrome 已开启 remote debugging（`chrome://inspect/#remote-debugging`）
+2. 点击 Allow 弹框
+
+```bash
+bundle exec ruby tmp/cdp_test.rb
+```

data/docs/session-management-redesign.md

@@ -0,0 +1,202 @@
+# Session Management Redesign
+
+> Status: Design finalized, pending implementation
+> Date: 2026-03-22
+
+---
+
+## Background
+
+Current session management has several problems:
+
+| Problem | Detail |
+|---------|--------|
+| **Delete bug (P0)** | `DELETE /api/sessions/:id` only removes from in-memory registry, disk JSON file is never deleted |
+| **Retention too small** | `cleanup_by_count(keep: 10)` — floods quickly with cron + channel sessions |
+| **Only 5 sessions restored on startup** | Misses most cron/channel history |
+| **No agent type selection in WebUI** | Always creates `general` profile, no UI to choose |
+| **No session source tracking** | No `source` field — can't distinguish manual vs cron vs channel |
+| **No agent profile tracking** | No `agent_profile` field in session JSON |
+
+---
+
+## UI Design
+
+### Sidebar Layout
+
+```
+┌─────────────────────────────────┐
+│  Sessions          [+ ▾]        │
+├─────────────────────────────────┤
+│  Manual  Scheduled  Channel     │  ← tab 切换
+├─────────────────────────────────┤
+│                                  │
+│  ● Session 3        2t  $0.02   │
+│  ○ Session 2        5t  $0.08   │
+│  ○ Session 1        1t  $0.01   │
+│                                  │
+├─────────────────────────────────┤
+│  👨‍💻 Coding                       │  ← 固定区域，不参与 tab
+├─────────────────────────────────┤
+│  ● 重构 auth 模块   3t  $0.05   │
+│  ○ 接口联调         1t  $0.02   │
+└─────────────────────────────────┘
+```
+
+**Upper area — General Agent sessions:**
+- Three tabs: `Manual` / `Scheduled` / `Channel`
+- Default tab: `Manual`
+- Each tab shows sessions filtered by `source` field AND `agent_profile = general`
+- Scheduled and Channel tabs show sessions where `agent_profile = general` AND `source = cron/channel`
+
+**Lower area — Coding Agent (and future agents):**
+- Fixed section, always visible, does not participate in tab switching
+- Shows all sessions where `agent_profile = coding`, regardless of source
+- Future custom agents each get their own section below Coding
+
+---
+
+### New Session Button: `[+ ▾]`
+
+```
+┌─────────────────────────────────┐
+│  Sessions          [+ ▾]        │
+└─────────────────────────────────┘
+```
+
+- **Click `+`** → immediately create a new General session (zero friction, most common action)
+- **Click `▾`** → dropdown appears:
+
+```
+                    ┌──────────────────┐
+                    │ ✦ General        │
+                    │ 👨‍💻 Coding         │
+                    │ ──────────────── │
+                    │ + Create Agent   │  ← future
+                    └──────────────────┘
+```
+
+- Selecting an agent from the dropdown creates a new session with that `agent_profile`
+- `Create Agent` is a placeholder for future custom agent creation UI
+
+---
+
+## Data Layer Changes
+
+### Session JSON — new fields
+
+```json
+{
+  "session_id": "...",
+  "source": "manual",
+  "agent_profile": "general",
+  ...
+}
+```
+
+**`source` values:** `manual` | `cron` | `channel`
+**`agent_profile` values:** `general` | `coding` | `<custom-name>`
+
+### `build_session` signature update
+
+```ruby
+build_session(
+  name:,
+  working_dir:,
+  source: :manual,          # :manual | :cron | :channel
+  profile: "general",       # agent profile name
+  permission_mode: :confirm_all
+)
+```
+
+Both `source` and `agent_profile` must be serialized into the session JSON and restored on `from_session`.
+
+---
+
+## New API Endpoints
+
+### `GET /api/agents`
+
+Returns all available agent profiles (built-in + user custom).
+
+Scan order:
+1. `~/.clacky/agents/<name>/profile.yml` (user override / custom)
+2. `<gem>/lib/clacky/default_agents/<name>/profile.yml` (built-in)
+
+Response:
+```json
+{
+  "agents": [
+    { "name": "general", "description": "A versatile digital employee living on your computer", "builtin": true },
+    { "name": "coding",  "description": "AI coding assistant and technical co-founder", "builtin": true },
+    { "name": "my-pm",   "description": "Product manager assistant", "builtin": false }
+  ]
+}
+```
+
+### `POST /api/sessions` — updated body
+
+```json
+{
+  "name": "Session 4",
+  "agent_profile": "coding"
+}
+```
+
+`source` is always `manual` for API-created sessions. `agent_profile` defaults to `"general"` if omitted.
+
+### `DELETE /api/sessions/:id` — fix
+
+Must delete the disk JSON file in addition to removing from registry:
+
+```ruby
+def api_delete_session(session_id, res)
+  if @registry.delete(session_id)
+    @session_manager.delete(session_id)   # ← ADD THIS
+    broadcast(session_id, { type: "session_deleted", session_id: session_id })
+    unsubscribe_all(session_id)
+    json_response(res, 200, { ok: true })
+  else
+    json_response(res, 404, { error: "Session not found" })
+  end
+end
+```
+
+`SessionManager` needs a `delete(session_id)` method that finds and removes the file by session_id prefix.
+
+---
+
+## Persistence Strategy Changes
+
+| Setting | Current | New |
+|---------|---------|-----|
+| Count limit | `keep: 10` | `keep: 200` |
+| Time-based cleanup | None | Delete sessions not accessed in **90 days** |
+| Cleanup timing | On every save | On server startup + every 24h |
+| Sessions restored on startup | 5 (current dir only) | 20 (current dir) |
+
+---
+
+## Implementation Order
+
+1. **Fix DELETE bug** — `api_delete_session` + `SessionManager#delete` by session_id
+2. **Data fields** — add `source` + `agent_profile` to `build_session`, `to_session_data`, `restore_session`
+3. **Channel/Cron tagging** — pass `source: :channel` / `source: :cron` when `ChannelManager` and cron create sessions
+4. **Persistence upgrade** — `keep: 200`, 90-day cleanup, restore 20 on startup
+5. **`GET /api/agents`** — scan both dirs, merge, return list
+6. **Frontend — sidebar redesign** — Manual/Scheduled/Channel tabs + Coding fixed section
+7. **Frontend — `[+ ▾]` button** — split button with agent dropdown
+
+---
+
+## File Locations
+
+| File | Change |
+|------|--------|
+| `lib/clacky/session_manager.rb` | Add `delete(session_id)`, change keep to 200, add 90-day cleanup |
+| `lib/clacky/agent/session_serializer.rb` | Serialize/restore `source` + `agent_profile` |
+| `lib/clacky/server/http_server.rb` | Fix `api_delete_session`, add `GET /api/agents`, update `build_session`, restore 20 sessions |
+| `lib/clacky/server/session_registry.rb` | Expose `agent_profile` + `source` in `session_summary` |
+| `lib/clacky/server/channel/channel_manager.rb` | Pass `source: :channel` to `build_session` |
+| `lib/clacky/web/sessions.js` | Tab switching, Coding section, `[+ ▾]` button |
+| CSS / HTML template | New sidebar layout, tab styles, split button |

data/docs/system-skill-authoring-guide.md

@@ -0,0 +1,47 @@
+# System Skill Authoring Guide
+
+Guidelines for writing built-in (system-level) skills under `lib/clacky/default_skills/`.
+
+---
+
+## 1. Communicating with the Clacky server
+
+Always use environment variables — never hardcode the port.
+
+```bash
+curl -s http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/xxx
+```
+
+`http_server.rb` injects `CLACKY_SERVER_HOST` and `CLACKY_SERVER_PORT` at startup.
+
+---
+
+## 2. Read state via API, not config files
+
+Skills must not read local config files directly.
+
+- ❌ `cat ~/.clacky/browser.yml`
+- ✅ `curl http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/browser/status`
+
+Exception: lightweight `enable` / `disable` operations may read/write yml directly (see `channel-setup`).
+
+---
+
+## 3. Running supporting scripts
+
+If a skill includes supporting scripts, instruct the AI to run them directly using the full path — **do not describe how to discover the path**. The LLM context already contains the full paths of all files in the skill directory (injected via supporting files at invoke time).
+
+Write it simply as:
+
+```
+Run the setup script:
+ruby SKILL_DIR/scripts/feishu_setup.rb
+```
+
+or for Python:
+
+```
+python3 SKILL_DIR/scripts/setup.py
+```
+
+No `Gem.find_files`, no `find` fallback, no path-discovery logic needed.

data/lib/clacky/agent/cost_tracker.rb

@@ -174,7 +174,8 @@ module Clacky
           total_tokens: total_tokens,
           cache_write: cache_write,
           cache_read: cache_read,
-          cost: cost
+          cost: cost,
+          cost_source: @cost_source
         }
       end
     end

data/lib/clacky/agent/session_serializer.rb

@@ -17,6 +17,8 @@ module Clacky
         @working_dir = session_data[:working_dir]
         @created_at = session_data[:created_at]
         @total_tasks = session_data.dig(:stats, :total_tasks) || 0
+        # Restore source; fall back to :manual for sessions saved before this field existed
+        @source = (session_data[:source] || "manual").to_sym
 
         # Restore cache statistics if available
         @cache_stats = session_data.dig(:stats, :cache_stats) || {
@@ -83,6 +85,8 @@ module Clacky
           created_at: @created_at,
           updated_at: Time.now.iso8601,
           working_dir: @working_dir,
+          source: @source.to_s,                      # "manual" | "cron" | "channel" | "setup"
+          agent_profile: @agent_profile&.name || "", # "general" | "coding" | custom
           todos: @todos,  # Include todos in session data
           time_machine: {  # Include Time Machine state
             task_parents: @task_parents || {},
@@ -171,9 +175,16 @@ module Clacky
 
         page.each do |round|
           msg = round[:user_msg]
-          raw_text = extract_text_from_content(msg[:content])
-          # Files are stored as system_injected messages (skipped below), not embedded in user text.
-          ui.show_user_message(raw_text, created_at: msg[:created_at])
+          raw_text    = extract_text_from_content(msg[:content])
+          # Images: recovered from inline image_url blocks in content (carry data_url for <img> rendering)
+          image_files = extract_image_files_from_content(msg[:content])
+          # Disk files (PDF, doc, etc.): stored in display_files on the user message at send time
+          disk_files  = Array(msg[:display_files]).map { |f|
+            { name: f[:name] || f["name"], type: f[:type] || f["type"] || "file",
+              preview_path: f[:preview_path] || f["preview_path"] }
+          }
+          all_files = image_files + disk_files
+          ui.show_user_message(raw_text, created_at: msg[:created_at], files: all_files)
 
           round[:events].each do |ev|
             # Skip system-injected messages (e.g. synthetic skill content, memory prompts)
@@ -309,6 +320,28 @@ module Clacky
           content.to_s
         end
       end
+
+      # Extract images from a multipart content array and return them as file entries.
+      # Returns an array of { name:, mime_type:, data_url: } hashes — the same structure
+      # that the frontend sends via `files` in a message, and that show_user_message(files:) expects.
+      # Only includes inline data_url images (not remote URLs).
+      def extract_image_files_from_content(content)
+        return [] unless content.is_a?(Array)
+
+        content.each_with_index.filter_map do |block, idx|
+          next unless block.is_a?(Hash)
+          # OpenAI-style: { type: "image_url", image_url: { url: "data:image/png;base64,..." } }
+          next unless block[:type] == "image_url"
+
+          url = block.dig(:image_url, :url)
+          next unless url && url.start_with?("data:")
+
+          # Derive mime_type from the data URL prefix (e.g. "data:image/jpeg;base64,...")
+          mime_type = url[/\Adata:([^;]+);/, 1] || "image/jpeg"
+          ext       = mime_type.split("/").last
+          { name: "image_#{idx + 1}.#{ext}", mime_type: mime_type, data_url: url }
+        end
+      end
     end
   end
 end

data/lib/clacky/agent/skill_manager.rb

@@ -371,7 +371,25 @@ module Clacky
         # If the user typed the skill command with no arguments (e.g. "/jade-appraisal"),
         # use a generic trigger phrase so the user message is never empty.
         task_input = arguments.to_s.strip.empty? ? "Please proceed." : arguments
-        result = subagent.run(task_input)
+
+        begin
+          result = subagent.run(task_input)
+        rescue Clacky::AgentInterrupted
+          # Subagent was interrupted by user (Ctrl+C).
+          # Write an interrupted summary into history so the parent agent's history
+          # has a clean tool result — prevents a dangling tool_call with no tool_result
+          # which would confuse the LLM on the next user message.
+          interrupted_summary = "[Subagent '#{skill.identifier}' was interrupted by the user before completing.]"
+          @history.mutate_last_matching(->(m) { m[:subagent_instructions] }) do |m|
+            m[:content] = interrupted_summary
+            m.delete(:subagent_instructions)
+            m[:subagent_result] = true
+            m[:skill_name] = skill.identifier
+            m[:interrupted] = true
+          end
+
+          raise  # Re-raise so parent agent also exits cleanly
+        end
 
         # Generate summary
         summary = generate_subagent_summary(subagent)

data/lib/clacky/agent/system_prompt_builder.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../utils/workspace_rules"
+
 module Clacky
   class Agent
     # System prompt construction
@@ -49,21 +51,36 @@ module Clacky
       end
 
       private def load_project_rules
-        rules_files = [
-          { path: ".clackyrules", name: ".clackyrules" },
-          { path: ".cursorrules", name: ".cursorrules" },
-          { path: "CLAUDE.md",    name: "CLAUDE.md" }
-        ]
-
-        rules_files.each do |file_info|
-          full_path = File.join(@working_dir, file_info[:path])
-          next unless File.exist?(full_path)
-
-          content = File.read(full_path).strip
-          return { content: content, source: file_info[:name] } unless content.empty?
+        main = Utils::WorkspaceRules.find_main(@working_dir)
+        sub_projects = Utils::WorkspaceRules.find_sub_projects(@working_dir)
+
+        return nil if main.nil? && sub_projects.empty?
+
+        combined_content = []
+        combined_content << main[:content] if main
+
+        unless sub_projects.empty?
+          n = Utils::WorkspaceRules::SUB_PROJECT_SUMMARY_LINES
+          summaries = sub_projects.map do |sp|
+            <<~SECTION.strip
+              ### Sub-project: #{sp[:sub_name]}/
+              Summary (first #{n} lines of #{sp[:relative_path]}):
+              #{sp[:summary]}
+              > IMPORTANT: Before working on any files under #{sp[:sub_name]}/, read the full rules file at `#{sp[:relative_path]}` using file_reader.
+            SECTION
+          end
+
+          combined_content << <<~BLOCK.strip
+            ## SUB-PROJECT AGENTS
+            This workspace contains sub-projects, each with their own rules.
+            When working in a sub-project, you MUST read its full .clackyrules first.
+
+            #{summaries.join("\n\n")}
+          BLOCK
         end
 
-        nil
+        source = main ? main[:name] : "sub-projects"
+        { content: combined_content.join("\n\n"), source: source }
       end
 
       private def format_section(title, content, footer: nil)