openclacky 0.7.5 → 0.7.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f623e852b5705d9339509514773528e2937fe90fe1fb8feca214a44633aa4d8d
-  data.tar.gz: bfff8a16fc705012a2d30a4ea8ac9a90ac6506ddbd45d9f30debe6019d04c52c
+  metadata.gz: 001070cf8c2d2587620da0669c4cc014bff55930033beafd038ae86ae7374276
+  data.tar.gz: 6c08cf048ab754c8e3be4841496b19b14cf081bdc62cadb313070226cb4e8679
 SHA512:
-  metadata.gz: 06cf4fe9c03e899ad4f9ccf6a325c10c1c952179240e37d5f18bd9c40b3d0088a4928c2536c578ea4735a606e55d3b5d58ffe9c19d21830f5589e002c99b887a
-  data.tar.gz: aa8bf7a73ca171fc1a234bfd3fac2ed51db67c18610fa525179d656186853d00023b0835d8bc7590c772f57563957299968f540239c1d736057d43dcd9f4488c
+  metadata.gz: 1bd44e7efcb16f9d9a15bb49c8d253183697107dcbb25f9ad8edc624d1a357d67c7f54f974cc06ae2140f66c0dec4bd2c2d8b50fae93ad3a8cf2453a0ee5f808
+  data.tar.gz: 4328e4ff99db8731e5ed0a1c298c281261da097d214b600e8d6d1b544073055cc35145d76f53853ea30f6f4827f831cd3444129559ff66e10b4d5a23b30e71e0

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.6] - 2026-03-02
+
+### Added
+- Non-interactive `--message`/`-m` CLI mode for scripting and automation (run a single prompt and exit)
+- Real-time refresh and thread-safety improvements to fullscreen UI mode
+
+### Improved
+- Extract string matching logic into `Utils::StringMatcher` for cleaner, reusable edit diffing
+- Glob tool now uses force mode in system prompt for more reliable file discovery
+- VCS directories (`.git`, `.svn`, etc.) defined as `ALWAYS_IGNORED_DIRS` constant
+
+### Fixed
+- Subagent fork now injects assistant acknowledgment to fix conversation structure issues
+- Tool-denial message clarified; added `action_performed` flag for better control flow
+
+### More
+- Add memory architecture documentation
+- Minor whitespace cleanup in `agent_config.rb`
+
 ## [0.7.5] - 2026-02-28
 
 ### Fixed

data/docs/memory-architecture.md

@@ -0,0 +1,343 @@
+# Agent 记忆架构：主动写入 vs 记忆压缩
+
+> **目标读者**：想在自己的 Agent 项目中复用 OpenClaw 记忆架构的开发者。
+>
+> **适用场景**：基于 LLM 的长期运行 Agent，需要跨 session 保留知识、同时管理上下文窗口溢出。
+
+---
+
+## 一、两套机制概览
+
+OpenClaw 的"记忆"由两个**完全独立、互相补充**的机制构成：
+
+| 机制 | 核心目标 | 存储位置 | 跨 Session |
+|---|---|---|---|
+| **主动写入 MEMORY.md** | 知识持久化 | 磁盘 `.md` 文件 | ✅ 永久保留 |
+| **Compaction（记忆压缩）** | 上下文窗口管理 | 内存消息历史（in-memory） | ❌ session 结束即消失 |
+
+---
+
+## 二、主动写入 MEMORY.md
+
+### 2.1 提示词来源
+
+**写入指令**不在代码里硬编码，而是来自 workspace 的 `AGENTS.md` 文件。  
+Session 启动时，系统通过以下链路将 `AGENTS.md` 注入系统提示词：
+
+```
+resolveBootstrapContextForRun()
+  └─ buildBootstrapContextFiles()
+       └─ contextFiles[]
+            └─ 注入到系统提示词的 "# Project Context" 段落
+```
+
+**只有读取指令**被硬编码在 `system-prompt.ts` 的 `buildMemorySection()` 里：
+
+```
+## Memory Recall
+Before answering anything about prior work, decisions, dates, people, preferences,
+or todos: run memory_search on MEMORY.md + memory/*.md; then use memory_get to pull
+only the needed lines.
+```
+
+> 结论：**读的提示词 → 代码硬编码**，**写的提示词 → AGENTS.md（用户可自定义）**。
+
+---
+
+### 2.2 AGENTS.md 写入指令原文
+
+以下是 `docs/reference/templates/AGENTS.md` 的核心记忆相关段落：
+
+#### 每次 Session 开始时（强制读取）
+
+```markdown
+## Every Session
+
+Before doing anything else:
+1. Read `SOUL.md` — this is who you are
+2. Read `USER.md` — this is who you're helping
+3. Read `memory/YYYY-MM-DD.md` (today + yesterday) for recent context
+4. **If in MAIN SESSION**: Also read `MEMORY.md`
+
+Don't ask permission. Just do it.
+```
+
+#### MEMORY.md 长期记忆规则
+
+```markdown
+### 🧠 MEMORY.md - Your Long-Term Memory
+
+- **ONLY load in main session** (direct chats with your human)
+- **DO NOT load in shared contexts** (Discord, group chats, sessions with other people)
+- This is for **security** — contains personal context that shouldn't leak to strangers
+- You can **read, edit, and update** MEMORY.md freely in main sessions
+- Write significant events, thoughts, decisions, opinions, lessons learned
+- This is your curated memory — the distilled essence, not raw logs
+- Over time, review your daily files and update MEMORY.md with what's worth keeping
+```
+
+#### 写入原则：禁止"心理便条"
+
+```markdown
+### 📝 Write It Down - No "Mental Notes"!
+
+- **Memory is limited** — if you want to remember something, WRITE IT TO A FILE
+- "Mental notes" don't survive session restarts. Files do.
+- When someone says "remember this" → update `memory/YYYY-MM-DD.md` or relevant file
+- When you learn a lesson → update AGENTS.md, TOOLS.md, or the relevant skill
+```
+
+#### Heartbeat 期间的维护任务
+
+```markdown
+### 🔄 Memory Maintenance (During Heartbeats)
+
+1. Read through recent `memory/YYYY-MM-DD.md` files
+2. Update `MEMORY.md` with distilled learnings
+3. Remove outdated info from MEMORY.md that's no longer relevant
+
+Think of it like a human reviewing their journal and updating their mental model.
+Daily files are raw notes; MEMORY.md is curated wisdom.
+```
+
+---
+
+### 2.3 记忆文件结构
+
+```
+workspace/
+├── AGENTS.md          # Agent 行为指令（含写入规则），session 启动时注入系统提示词
+├── SOUL.md            # Agent 的性格/价值观
+├── USER.md            # 用户背景信息
+├── MEMORY.md          # 长期记忆（精华，仅主 session 加载）
+└── memory/
+    ├── 2026-06-15.md  # 今日日志（原始记录）
+    ├── 2026-06-14.md  # 昨日日志
+    └── ...
+```
+
+**两层记忆设计**：
+- `memory/YYYY-MM-DD.md`：**原始日志**，当天发生了什么，快速写入，不筛选
+- `MEMORY.md`：**精华提炼**，LLM 主动筛选后写入，类似人类的长期记忆
+
+---
+
+## 三、Compaction（记忆压缩）
+
+### 3.1 触发时机
+
+当 context window 接近上限（token 溢出）时，系统自动触发：
+
+```
+attempt.ts（run loop）
+  └─ 检测 token 超限（overflow）
+       └─ compactInLane()
+            └─ session.compact(customInstructions)
+                 └─ generateSummary()
+                      └─ 旧消息被摘要文本替换（in-memory）
+```
+
+### 3.2 核心实现
+
+**`src/agents/compaction.ts`** 中的 `summarizeChunks()`：
+
+```typescript
+// 将消息历史分块，逐块生成摘要
+async function summarizeChunks(params: {
+  messages: AgentMessage[];
+  model: ...;
+  previousSummary?: string;
+}): Promise<string> {
+  // SECURITY: 工具调用结果的详情不进入摘要 LLM，防止数据泄露
+  const safeMessages = stripToolResultDetails(params.messages);
+  const chunks = chunkMessagesByMaxTokens(safeMessages, params.maxChunkTokens);
+
+  let summary = params.previousSummary;
+  for (const chunk of chunks) {
+    summary = await generateSummary(chunk, ...);
+  }
+  return summary ?? "No prior history.";
+}
+```
+
+**`src/agents/pi-embedded-runner/compact.ts`** 中的触发逻辑：
+
+```typescript
+const result = await compactWithSafetyTimeout(() =>
+  session.compact(params.customInstructions),
+);
+// compaction 完成后，session.messages 中的旧消息已被摘要替换
+// 注意：不写磁盘，session 结束即消失
+```
+
+### 3.3 安全设计
+
+- `stripToolResultDetails()`：确保工具调用的详细返回值不进入摘要 LLM（防止敏感数据泄露给压缩模型）
+- Compaction 生成的摘要只替换内存里的消息，**不写任何磁盘文件**
+
+---
+
+## 四、两套机制完整对比
+
+| 维度 | **主动写入 MEMORY.md** | **Compaction（记忆压缩）** |
+|---|---|---|
+| **操作对象** | 磁盘文件（`.md`） | 内存中的消息历史 |
+| **触发者** | LLM 自主决定（或用户指令） | 系统自动（token 超限） |
+| **触发时机** | 任何时候 LLM 认为有意义 | context window 接近上限 |
+| **存储位置** | 持久化磁盘 | in-memory，替换旧消息 |
+| **跨 session** | ✅ 永久保留 | ❌ session 结束即消失 |
+| **内容性质** | 精华/curated（LLM 主动筛选） | 原始对话的自动压缩摘要 |
+| **可检索性** | ✅ 支持向量检索（`memory_search`） | ❌ 不可单独检索 |
+| **LLM 参与** | LLM 主动调用 write/edit 工具 | 由系统调用独立摘要 LLM |
+| **数据安全** | 用户控制写入内容 | `stripToolResultDetails()` 自动过滤 |
+| **可自定义** | ✅ 通过 AGENTS.md 自定义规则 | ✅ 可传入 `customInstructions` |
+
+---
+
+## 五、架构图
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                      当前 Session 上下文                          │
+│                                                                  │
+│  [系统提示词]                                                     │
+│    ├─ AGENTS.md（写入规则）   ← resolveBootstrapContextForRun()   │
+│    ├─ buildMemorySection()（读取规则，硬编码）                     │
+│    └─ MEMORY.md 内容（主 session 才注入）                         │
+│                                                                  │
+│  [消息历史] [消息1][消息2]...[消息N]  ← in-memory                  │
+│   ─────────────────────────────────── context window limit       │
+│                                                                  │
+│  ⚡ 快满了 → Compaction 触发：                                    │
+│    旧消息 ──→ summarizeChunks() ──→ [摘要文本]                    │
+│    [摘要] 替换旧消息（仍在 in-memory）                             │
+│    ↑ 只压缩窗口，不写磁盘，session 结束消失                        │
+└──────────────────────────────────────────────────────────────────┘
+                              ↕ 互相独立，互相补充
+┌──────────────────────────────────────────────────────────────────┐
+│                      磁盘持久化记忆系统                            │
+│                                                                  │
+│  LLM 主动 write/edit 工具 ─────────────────────────────────────  │
+│    ↓ 用户说"记住这个"                                             │
+│    ↓ LLM 觉得值得保留                                            │
+│    ↓ Heartbeat 定期维护                                          │
+│                                                                  │
+│  MEMORY.md           ← 精华长期记忆（仅主 session 读取）           │
+│  memory/2026-06-15.md ← 今日原始日志                             │
+│  memory/2026-06-14.md ← 昨日日志                                 │
+│                                                                  │
+│  chokidar watch ──→ SQLite 向量索引更新                          │
+│  memory_search ──→ 下次 session 可检索                           │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 六、关键文件清单
+
+| 文件 | 作用 |
+|---|---|
+| `docs/reference/templates/AGENTS.md` | **写入指令来源**，workspace 启动模板，包含 MEMORY.md 写入规则 |
+| `src/agents/system-prompt.ts` | `buildMemorySection()`，只含**读取**指令（`## Memory Recall`） |
+| `src/agents/pi-embedded-helpers/bootstrap.ts` | `buildBootstrapContextFiles()`，将 AGENTS.md 等文件注入系统提示词 |
+| `src/agents/bootstrap-files.ts` | `resolveBootstrapContextForRun()`，加载 workspace bootstrap 文件 |
+| `src/agents/pi-embedded-runner/compact.ts` | Compaction 入口，`session.compact()` 触发，管理上下文溢出 |
+| `src/agents/compaction.ts` | `summarizeChunks()` / `summarizeWithFallback()`，LLM 摘要逻辑 |
+| `src/agents/session-transcript-repair.ts` | `stripToolResultDetails()`，Compaction 安全过滤 |
+
+---
+
+## 七、在新项目中复用这套架构
+
+### 7.1 最小实现方案
+
+只需要三样东西：
+
+```
+1. AGENTS.md（写入规则）    → 告诉 LLM 什么时候、怎么写文件
+2. 文件读写工具             → write / read / edit（标准文件操作工具）
+3. 系统提示词中的读取指令   → 告诉 LLM 在回答前先查记忆
+```
+
+### 7.2 推荐的 AGENTS.md 写入规则模板
+
+```markdown
+## Memory Rules
+
+### Long-Term Memory (memory.md)
+- Load at session start; read, edit, update freely
+- Write: significant decisions, user preferences, lessons learned, open questions
+- Curated — distill from daily notes, remove outdated info
+
+### Daily Notes (notes/YYYY-MM-DD.md)
+- Raw logs of what happened today; create if missing
+- Write freely; no curation needed
+
+### Key Principle
+**Memory is limited — if you want to remember something, WRITE IT TO A FILE.**
+Mental notes don't survive restarts. Files do.
+
+When user says "remember this" → update notes/YYYY-MM-DD.md and/or memory.md.
+When you learn a lesson → update memory.md.
+```
+
+### 7.3 系统提示词中的读取指令
+
+```markdown
+## Memory Recall
+
+Before answering anything about prior work, decisions, dates, people,
+preferences, or todos:
+1. Read memory.md for long-term context
+2. Read notes/YYYY-MM-DD.md (today + yesterday) for recent context
+3. Then answer using this retrieved context
+```
+
+### 7.4 Compaction 实现要点
+
+如果你的 Agent 框架不内置 compaction，参考以下要点自己实现：
+
+```typescript
+// 伪代码：简单 compaction 实现
+async function compactIfNeeded(messages: Message[], model: Model) {
+  const tokens = estimateTokens(messages);
+  if (tokens < contextWindow * 0.8) return messages; // 还有余量
+
+  // 安全过滤：不把工具调用结果喂给摘要 LLM
+  const safeMessages = stripSensitiveToolResults(messages);
+
+  // 保留最近 N 条消息，其余压缩为摘要
+  const toSummarize = safeMessages.slice(0, -10);
+  const recent = messages.slice(-10);
+
+  const summary = await generateSummary(toSummarize, model);
+  return [{ role: "system", content: `[Previous context summary]\n${summary}` }, ...recent];
+}
+```
+
+**关键安全注意**：工具调用返回的详细数据（尤其是外部 API 响应）**不应进入**摘要 LLM，避免敏感信息泄露到你可能无法控制的模型。
+
+### 7.5 两层记忆的设计哲学
+
+| 层级 | 文件 | 写入频率 | 内容要求 | 对应人类记忆 |
+|---|---|---|---|---|
+| 日志层 | `notes/YYYY-MM-DD.md` | 高频、随时 | 原始记录，不筛选 | 日记 |
+| 精华层 | `memory.md` | 低频、定期整理 | 蒸馏后的关键信息 | 长期记忆 |
+
+**为什么要两层**：高频写入保证不遗漏，低频整理保证质量。LLM 在 heartbeat（定期任务）中把日志蒸馏进长期记忆，删除过时内容，就像人类每周回顾日记、更新心智模型。
+
+---
+
+## 八、常见问题
+
+**Q：为什么写入规则放 AGENTS.md 而不是硬编码在系统提示词里？**  
+A：灵活性。不同 workspace 可以有不同的记忆规则（有的 Agent 记更多，有的记更少），用户可以直接编辑 AGENTS.md 调整行为，不需要改代码。
+
+**Q：Compaction 会不会把写入 MEMORY.md 的内容也压缩掉？**  
+A：不会。写入 MEMORY.md 是磁盘操作，Compaction 只压缩内存里的消息历史。MEMORY.md 的内容在下次 session 启动时会重新从磁盘加载进系统提示词，不受 Compaction 影响。
+
+**Q：如果 MEMORY.md 本身太大怎么办？**  
+A：定期在 heartbeat 任务中让 LLM 清理过时内容。OpenClaw 在 AGENTS.md 里明确要求"Remove outdated info from MEMORY.md that's no longer relevant"，这个维护任务由 LLM 自主完成。
+
+**Q：多用户场景下 MEMORY.md 会泄露给别人吗？**  
+A：OpenClaw 的设计是：MEMORY.md 只在 main session（直接对话）加载，在 Discord / 群聊等共享上下文中不加载，防止个人信息泄露给陌生人。复用时需要在系统提示词里加类似的条件判断。

data/lib/clacky/agent/skill_manager.rb

@@ -100,17 +100,21 @@ module Clacky
         # Log subagent fork
         @ui&.show_info("Subagent start: #{skill.identifier}")
 
-        # Build task content from skill
-        task_content = skill.process_content(arguments)
+        # Build skill role/constraint instructions only — do NOT substitute $ARGUMENTS here.
+        # The actual task is delivered as a clean user message via subagent.run(arguments),
+        # which arrives *after* the assistant acknowledgement injected by fork_subagent.
+        # This gives the subagent a clear 3-part structure:
+        #   [user] role/constraints  →  [assistant] acknowledgement  →  [user] actual task
+        skill_instructions = skill.process_content("")
 
         # Fork subagent with skill configuration
         subagent = fork_subagent(
           model: skill.subagent_model,
           forbidden_tools: skill.forbidden_tools_list,
-          system_prompt_suffix: task_content
+          system_prompt_suffix: skill_instructions
         )
 
-        # Run subagent
+        # Run subagent with the actual task as the sole user turn
         result = subagent.run(arguments)
 
         # Generate summary

data/lib/clacky/agent/system_prompt_builder.rb

@@ -24,7 +24,7 @@ module Clacky
            - After creating the TODO list, START EXECUTING each task immediately
            - Don't stop after planning - continue to work on the tasks!
         2. Always read existing code before making changes (use file_reader/glob/grep or invoke code-explorer skill)
-        3. **Use glob tool to search for files** - it respects .gitignore, filters binary files, and sorts by modification time
+        3. **ALWAYS use `glob` tool to find files in the current directory — NEVER use shell `find` command for file discovery.**
         4. Ask clarifying questions if requirements are unclear
         5. Break down complex tasks into manageable steps
         6. **USE TOOLS to create/modify files** - don't just return code

data/lib/clacky/agent/tool_executor.rb

@@ -197,14 +197,16 @@ module Clacky
           }
         else
           # User manually denied or provided feedback
+          # Clearly state the action was NOT performed so the LLM knows the change did not happen
           message = if user_feedback && !user_feedback.empty?
-                      "Tool use denied by user. User feedback: #{user_feedback}"
+                      "Tool use denied by user. This action was NOT performed. User feedback: #{user_feedback}"
                     else
-                      "Tool use denied by user"
+                      "Tool use denied by user. This action was NOT performed."
                     end
 
           tool_content = {
             error: message,
+            action_performed: false,
             user_feedback: user_feedback
           }
         end
@@ -382,8 +384,12 @@ module Clacky
 
         file_content = File.read(path)
 
-        # Check if old_string exists in file
-        unless file_content.include?(old_string)
+        # Use the same find_match logic as Edit tool to handle fuzzy matching
+        # (trim, unescape, smart line matching) — prevents diff from being blank
+        # when simple include? fails but Edit#execute's fuzzy match would succeed
+        match_result = Utils::StringMatcher.find_match(file_content, old_string)
+
+        unless match_result
           # Log debug info for troubleshooting
           @debug_logs << {
             timestamp: Time.now.iso8601,
@@ -402,11 +408,14 @@ module Clacky
           }
         end
 
+        # Use the actual matched string (may differ via trim/unescape) for replacement
+        actual_old_string = match_result[:matched_string]
+
         # Use the same replace logic as the actual tool execution
         new_content = if replace_all
-                        file_content.gsub(old_string, new_string)
+                        file_content.gsub(actual_old_string, new_string)
                       else
-                        file_content.sub(old_string, new_string)
+                        file_content.sub(actual_old_string, new_string)
                       end
         @ui&.show_diff(file_content, new_content, max_lines: 50)
         nil  # No error

data/lib/clacky/agent.rb

@@ -506,7 +506,16 @@ module Clacky
             if result.is_a?(Hash) && result[:message]
               @ui&.show_assistant_message(result[:message])
             end
-            awaiting_feedback = true
+
+            if @config.permission_mode == :auto_approve
+              # Auto-approve mode means no human is watching — inject a reply so the LLM
+              # knows it should make a reasonable decision and keep going
+              result = result.merge(
+                auto_reply: "No user is available. Please make a reasonable decision based on the context and continue."
+              )
+            else
+              awaiting_feedback = true
+            end
           else
             # Use tool's format_result method to get display-friendly string
             formatted_result = tool.respond_to?(:format_result) ? tool.format_result(result) : result.to_s
@@ -691,6 +700,15 @@ module Clacky
           system_injected: true,
           subagent_instructions: true
         }
+
+        # Insert an assistant acknowledgement so the conversation structure is complete:
+        #   [user] role/constraints  →  [assistant] ack  →  [user] actual task (from run())
+        # Without this, two consecutive user messages confuse the model about what to act on.
+        messages << {
+          role: "assistant",
+          content: "Understood. I am now operating as a subagent with the constraints above. Please provide the task.",
+          system_injected: true
+        }
       end
 
       # Register hook to forbid certain tools at runtime (doesn't affect tool registry for cache)

data/lib/clacky/agent_config.rb

@@ -150,7 +150,7 @@ module Clacky
 
     PERMISSION_MODES = [:auto_approve, :confirm_safes, :plan_only].freeze
 
-    attr_accessor :permission_mode, :max_tokens, :verbose, 
+    attr_accessor :permission_mode, :max_tokens, :verbose,
                   :enable_compression, :enable_prompt_caching,
                   :models, :current_model_index
 
@@ -161,7 +161,7 @@ module Clacky
       @enable_compression = options[:enable_compression].nil? ? true : options[:enable_compression]
       # Enable prompt caching by default for cost savings
       @enable_prompt_caching = options[:enable_prompt_caching].nil? ? true : options[:enable_prompt_caching]
-      
+
       # Models configuration
       @models = options[:models] || []
       @current_model_index = options[:current_model_index] || 0

data/lib/clacky/cli.rb

@@ -5,6 +5,7 @@ require "tty-prompt"
 require "fileutils"
 require_relative "ui2"
 require_relative "json_ui_controller"
+require_relative "plain_ui_controller"
 
 module Clacky
   class CLI < Thor
@@ -50,6 +51,8 @@ module Clacky
     option :list, type: :boolean, aliases: "-l", desc: "List recent sessions"
     option :attach, type: :string, aliases: "-a", desc: "Attach to session by number or keyword"
     option :json, type: :boolean, default: false, desc: "Output NDJSON to stdout (for scripting/piping)"
+    option :message, type: :string, aliases: "-m", desc: "Run non-interactively with this message and exit"
+    option :image, type: :array, aliases: "-i", desc: "Image file path(s) to attach (use with -m; can be specified multiple times)"
     option :help, type: :boolean, aliases: "-h", desc: "Show this help message"
     def agent
       # Handle help option
@@ -101,7 +104,9 @@ module Clacky
       should_chdir = File.realpath(working_dir) != File.realpath(original_dir)
       Dir.chdir(working_dir) if should_chdir
       begin
-        if options[:json]
+        if options[:message]
+          run_non_interactive(agent, options[:message], Array(options[:image]), agent_config, session_manager)
+        elsif options[:json]
           run_agent_with_json(agent, working_dir, agent_config, session_manager, client)
         else
           run_agent_with_ui2(agent, working_dir, agent_config, session_manager, client, is_session_load: is_session_load)
@@ -353,6 +358,33 @@ module Clacky
         end
       end
 
+      # Run agent non-interactively with a single message, then exit.
+      # Forces auto_approve mode so no human confirmation is needed.
+      # Output goes directly to stdout; exits with code 0 on success, 1 on error.
+      def run_non_interactive(agent, message, images, agent_config, session_manager)
+        # Force auto-approve — no one is around to confirm anything
+        agent_config.permission_mode = :auto_approve
+
+        # Validate image paths up-front so we fail fast with a clear message
+        images.each do |path|
+          raise ArgumentError, "Image file not found: #{path}" unless File.exist?(path)
+        end
+
+        # Wire up plain-text stdout UI so all agent output is visible
+        plain_ui = Clacky::PlainUIController.new
+        agent.instance_variable_set(:@ui, plain_ui)
+
+        agent.run(message, images: images)
+        session_manager&.save(agent.to_session_data(status: :success))
+        exit(0)
+      rescue Clacky::AgentInterrupted
+        $stderr.puts "\nInterrupted."
+        exit(1)
+      rescue => e
+        $stderr.puts "Error: #{e.message}"
+        exit(1)
+      end
+
       # Run agent with JSON (NDJSON) output mode — persistent process.
       # Reads JSON messages from stdin, writes NDJSON events to stdout.
       # Stays alive until "/exit", {"type":"exit"}, or stdin EOF.