jeo-code 0.7.12 → 0.7.14

package/CHANGELOG.md

@@ -6,6 +6,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 The README mirrors the latest 5 entries — regenerate with `bun run changelog:sync`.
 
+
+## [0.7.14] - 2026-06-25
+_Quieter, cleaner output: a new `-q`/`--quiet` flag strips launch banners and courtesy logs, `/resume` no longer dumps walls of raw escaped JSON into scrollback, and a turn that edits files now reliably surfaces those paths to orchestrators._
+
+### Added
+- **`-q`/`--quiet` suppresses startup chrome.** `jeo launch -q` (and one-shot `-p`) skips the welcome box, the "what's new" release notes, the `(plain output)` / resume-hint footers, and the background "session memory distilling" line — so piped, CI, and minimal-terminal runs get just the agent's output instead of the full interactive banner set. The flag is wired through the runner (`-q`/`--quiet` help + launch-only flag set) and `parseFlags`.
+
+### Fixed
+- **`/resume` no longer renders a wall of raw escaped JSON.** The transcript formatter extracts an embedded tool call from anywhere in an assistant message (mirroring the engine's own `extractJsonObject`) instead of only when the content begins with `{`, and distinguishes a genuine prose-prefixed call (followed by its `Tool [x] result`) from an illustrative JSON snippet quoted inside prose. Pre-call narration is kept (dimmed) and a leading `"reasoning"` field is surfaced clipped; the raw multi-line edit/write payloads never reach scrollback.
+- **A turn that actually edits files now surfaces those paths, fixing the orchestrator "Agent finished but made zero valid code changes (finalArtifacts is empty)" failure.** `runAgentLoop` records every file a turn SUCCESSFULLY writes/edits and returns it as `AgentLoopResult.mutatedFiles` (repo-relative, sorted, de-duped; omitted when nothing mutated). The `task` subagent (`src/agent/task-tool.ts`) and the `team` executor (`src/commands/team.ts`) now derive their change set from this concrete list instead of an out-of-band tool counter, append a "Changed files (N): …" note to the subagent report, and base the parent UNVERIFIED/verify-independently audit on it — so a caller (or an external orchestrator like jeo-claw) collects the run's real code artifacts rather than inferring an empty change set after real edits. `.specify/` is also un-ignored in `.gitignore` so spec/plan artifacts written there are visible to a git-based artifact collector.
+
 ## [0.7.9] - 2026-06-24
 _Local model providers actually run, and OAuth/login hygiene: Ollama requests now carry an explicit `num_ctx` so jeo's large system prompt no longer overflows Ollama's small default window (the "ollama 모델이 안 돌아간다" blocker), LM Studio reasoning models that emit the whole reply on the reasoning channel are recovered instead of dying empty, GGUF chat templates that can't render the `tools` array are retried with native tools stripped, the OAuth success tab auto-closes with a clear hint, the effective-credential picker prefers a verified OAuth login over a stray API key, and abandoned idle `jeo` tmux REPL sessions are reaped on launch._
 

package/README.ja.md

@@ -149,6 +149,18 @@ jeo ultragoal
 `jeo` は `.jeo/memory/` 配下に **ローカルファースト・蒸留されたプロジェクトメモリ** を保持します(リモートバックエンドなし、ネイティブ依存ゼロ)。過去のセッションは [OKF](docs/okf_mem/) コンセプトバンドルへ蒸留され、次のセッションは関連性の高い予算内のスライスだけをシステムプロンプトへ再注入します — 指示ではなく DATA として堅牢化されます。`JEO_NO_MEMORY=1` ですべて無効化。
 
 **移行(`jeo memory-migrate`、ワンショット・冪等).** レガシーの単一ドキュメント `MEMORY.md` をロスレスでバンドルへ変換します: `## 見出し → タイプ`、各箇条書き → タイプ別コンセプト、インデント行 → 本文; `index.md`/`log.md` を再構築し、元ファイルを `MEMORY.md.bak` にリネームします。バンドルにコンセプトができた後の再実行は no-op です。**ロールバック:** `JEO_MEMORY_LEGACY=1` はバンドルを無視し、同じ注入堅牢化を通して `MEMORY.md`/`.bak` を読みます(`JEO_NO_MEMORY=1` がすべてに優先)。
+## 既存のエージェントやボットとの連携 (Works beside your existing agent or bot)
+
+| ツールまたはボット | 推奨される jeo コマンド | 境界 |
+| ----------- | ----------------------- | -------- |
+| Codex CLI | `jeo --tmux` または `jeo` | 兄弟 tmux セッションまたはインラインで実行されます。 |
+| Claude Code | `jeo --tmux` または `jeo` | jeo は Claude Code の拡張機能にはなりません。 |
+| OpenCode | `jeo` または `jeo --tmux` | 外部ランナーのワークフローのみ。 |
+| Claw Code | `jeo --tmux` | jeo は Claw Code にインストールされたり、置き換えたりしません。 |
+| 外部コントローラー / ボット | `jeo` (またはカスタム統合) | 外部コントローラーは、標準のターミナル/CLI インターフェースを介して jeo を駆動します。 |
+
+`-q`/`--quiet` (または `JEO_QUIET=1`) を追加すると、起動バナー・ウェルカムアニメーション・リリースノート・再開ヒントが抑制され、jeo を別のエージェントと並べて実行したりボットから駆動したりできます。`-p`/`--print` は quiet を含みます。
+
 
 ## ローカルモデル
 
@@ -193,11 +205,11 @@ CI は `.github/workflows/npm-publish.yml` で公開します — GitHub リリ
 ## 変更履歴 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.14]** (2026-06-25) — Quieter, cleaner output: a new `-q`/`--quiet` flag strips launch banners and courtesy logs, `/resume` no longer dumps walls of raw escaped JSON into scrollback, and a turn that edits files now reliably surfaces those paths to orchestrators.
 - **[0.7.9]** (2026-06-24) — Local model providers actually run, and OAuth/login hygiene: Ollama requests now carry an explicit `num_ctx` so jeo's large system prompt no longer overflows Ollama's small default window (the "ollama 모델이 안 돌아간다" blocker), LM Studio reasoning models that emit the whole reply on the reasoning channel are recovered instead of dying empty, GGUF chat templates that can't render the `tools` array are retried with native tools stripped, the OAuth success tab auto-closes with a clear hint, the effective-credential picker prefers a verified OAuth login over a stray API key, and abandoned idle `jeo` tmux REPL sessions are reaped on launch.
 - **[0.7.8]** (2026-06-24) — Long-session performance & resource hygiene: the detached memory-distill worker now always terminates itself (closing the `jeo memory-distill` orphan pileup that pinned each session's transcript in RSS), the live reasoning/output block re-wraps only its trailing window (O(tail) per frame instead of O(len²) over a long stream), the team loop stops reprinting the todo guide every iteration, and the readline caret stays aligned after an image attach.
 - **[0.7.7]** (2026-06-23) — Long-running-process hygiene & input robustness: backgrounded grandchildren (`next dev &`, daemons) are now reaped at the turn boundary via per-command process groups — closing the climbing `next-server` RSS leak — while the prompt gains recursive fuzzy `@path` search, ANSI-safe and idle-merged bracketed paste, a configurable OSC 52 clipboard cap, per-role ralplan model routing, and leaked-reasoning-tag stripping on salvaged answers.
 - **[0.7.6]** (2026-06-23) — Release & docs plumbing: the running version's release notes now travel inside the `--compile` single binary (so `/whats-new` works offline and from a global install), the in-TUI markdown table renderer stops splitting on escaped `\|` pipes, and the release pipeline gains a cross-compiled standalone-binary matrix — macOS/Linux **plus a first-class Windows x64 `.exe`** — built on one Linux runner and auto-attached to each GitHub release.
-- **[0.7.5]** (2026-06-23) — Startup & loop latency: redundant re-reads that fired on every subagent spawn and every loop step are now memoized behind cheap `stat`-signature caches, so cold paths stay correct (edits/deletes still picked up immediately) while warm paths skip the disk and the re-parse. Targets the per-turn and per-spawn overhead that dominates perceived slowness in team/ralph/autopilot fan-outs.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.ko.md

@@ -149,6 +149,18 @@ jeo ultragoal
 `jeo`는 `.jeo/memory/` 아래에 **로컬 우선·증류된 프로젝트 메모리**를 둡니다(원격 백엔드 없음, 네이티브 의존성 0). 지난 세션은 [OKF](docs/okf_mem/) 개념 번들로 증류되고, 다음 세션은 관련성 높은 예산 한도 내 일부만 시스템 프롬프트로 다시 주입합니다 — 지시가 아닌 DATA로 강화 처리됩니다. `JEO_NO_MEMORY=1`로 전체 비활성화.
 
 **마이그레이션 (`jeo memory-migrate`, 1회성 · 멱등).** 레거시 단일 문서 `MEMORY.md`를 무손실로 번들로 변환합니다: `## 헤딩 → 타입`, 각 불릿 → 타입별 개념, 들여쓴 줄 → 본문; `index.md`/`log.md`를 재생성하고 원본은 `MEMORY.md.bak`으로 이름을 바꿉니다. 번들에 개념이 생긴 뒤 재실행은 no-op입니다. **롤백:** `JEO_MEMORY_LEGACY=1`은 번들을 무시하고 동일한 주입 강화 처리로 `MEMORY.md`/`.bak`를 읽습니다(`JEO_NO_MEMORY=1`이 모든 것에 우선).
+## 기존 에이전트 또는 봇과 함께 작동 (Works beside your existing agent or bot)
+
+| 도구 또는 봇 | 권장 jeo 명령 | 경계 |
+| ----------- | ----------------------- | -------- |
+| Codex CLI | `jeo --tmux` 또는 `jeo` | 형제 tmux 세션 또는 인라인으로 실행됩니다. |
+| Claude Code | `jeo --tmux` 또는 `jeo` | jeo는 Claude Code 확장 프로그램이 되지 않습니다. |
+| OpenCode | `jeo` 또는 `jeo --tmux` | 현재는 외부 러너 워크플로만 지원합니다. |
+| Claw Code | `jeo --tmux` | jeo는 Claw Code에 설치되거나 대체되지 않습니다. |
+| 외부 컨트롤러 / 봇 | `jeo` (또는 사용자 정의 통합) | 외부 컨트롤러는 표준 터미널/CLI 인터페이스를 통해 jeo를 구동합니다. |
+
+`-q`/`--quiet` (또는 `JEO_QUIET=1`)를 추가하면 시작 배너, 환영 애니메이션, 릴리스 노트, 재개 힌트가 억제되어 jeo를 다른 에이전트와 나란히 실행하거나 봇으로 구동할 수 있습니다. `-p`/`--print`는 quiet를 함의합니다.
+
 
 ## 로컬 모델
 
@@ -193,11 +205,11 @@ CI는 `.github/workflows/npm-publish.yml`로 배포합니다 — GitHub 릴리
 ## 변경 이력 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.14]** (2026-06-25) — Quieter, cleaner output: a new `-q`/`--quiet` flag strips launch banners and courtesy logs, `/resume` no longer dumps walls of raw escaped JSON into scrollback, and a turn that edits files now reliably surfaces those paths to orchestrators.
 - **[0.7.9]** (2026-06-24) — Local model providers actually run, and OAuth/login hygiene: Ollama requests now carry an explicit `num_ctx` so jeo's large system prompt no longer overflows Ollama's small default window (the "ollama 모델이 안 돌아간다" blocker), LM Studio reasoning models that emit the whole reply on the reasoning channel are recovered instead of dying empty, GGUF chat templates that can't render the `tools` array are retried with native tools stripped, the OAuth success tab auto-closes with a clear hint, the effective-credential picker prefers a verified OAuth login over a stray API key, and abandoned idle `jeo` tmux REPL sessions are reaped on launch.
 - **[0.7.8]** (2026-06-24) — Long-session performance & resource hygiene: the detached memory-distill worker now always terminates itself (closing the `jeo memory-distill` orphan pileup that pinned each session's transcript in RSS), the live reasoning/output block re-wraps only its trailing window (O(tail) per frame instead of O(len²) over a long stream), the team loop stops reprinting the todo guide every iteration, and the readline caret stays aligned after an image attach.
 - **[0.7.7]** (2026-06-23) — Long-running-process hygiene & input robustness: backgrounded grandchildren (`next dev &`, daemons) are now reaped at the turn boundary via per-command process groups — closing the climbing `next-server` RSS leak — while the prompt gains recursive fuzzy `@path` search, ANSI-safe and idle-merged bracketed paste, a configurable OSC 52 clipboard cap, per-role ralplan model routing, and leaked-reasoning-tag stripping on salvaged answers.
 - **[0.7.6]** (2026-06-23) — Release & docs plumbing: the running version's release notes now travel inside the `--compile` single binary (so `/whats-new` works offline and from a global install), the in-TUI markdown table renderer stops splitting on escaped `\|` pipes, and the release pipeline gains a cross-compiled standalone-binary matrix — macOS/Linux **plus a first-class Windows x64 `.exe`** — built on one Linux runner and auto-attached to each GitHub release.
-- **[0.7.5]** (2026-06-23) — Startup & loop latency: redundant re-reads that fired on every subagent spawn and every loop step are now memoized behind cheap `stat`-signature caches, so cold paths stay correct (edits/deletes still picked up immediately) while warm paths skip the disk and the re-parse. Targets the per-turn and per-spawn overhead that dominates perceived slowness in team/ralph/autopilot fan-outs.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.md

@@ -150,6 +150,18 @@ Non-zero hook output is appended to the tool result the model reads (deduped per
 `jeo` keeps a **local-first, distilled project memory** under `.jeo/memory/` (no remote backend, zero native deps). Past sessions are distilled into an [OKF](docs/okf_mem/) concept bundle, and the next session injects only the relevant, budget-bounded slice back into the system prompt — hardened as DATA, never as instructions. Disable everything with `JEO_NO_MEMORY=1`.
 
 **Migration (`jeo memory-migrate`, one-shot · idempotent).** A legacy single-doc `MEMORY.md` is converted losslessly into the bundle: `## heading → type`, each bullet → a typed concept, indented lines → body; `index.md`/`log.md` are rebuilt and the original is renamed to `MEMORY.md.bak`. Re-running is a no-op once the bundle has concepts. **Rollback:** `JEO_MEMORY_LEGACY=1` ignores the bundle and reads `MEMORY.md`/`.bak` through the same injection-hardening (`JEO_NO_MEMORY=1` still wins over everything).
+## Works beside your existing agent or bot
+
+| Tool or bot | Recommended jeo command | Boundary |
+| ----------- | ----------------------- | -------- |
+| Codex CLI | `jeo --tmux` or `jeo` | Runs in a sibling tmux session or inline. |
+| Claude Code | `jeo --tmux` or `jeo` | jeo does not become a Claude Code extension. |
+| OpenCode | `jeo` or `jeo --tmux` | External-runner workflow only. |
+| Claw Code | `jeo --tmux` | jeo does not install into or replace Claw Code. |
+| External controller / bot | `jeo` (or custom integrations) | External controllers drive jeo through standard terminal/CLI interfaces. |
+
+Add `-q`/`--quiet` (or `JEO_QUIET=1`) to suppress startup banners, welcome animation, release notes, and resume hints so jeo can run cleanly beside another agent or be driven by a bot. `-p`/`--print` implies quiet.
+
 
 ## Local models
 
@@ -195,11 +207,11 @@ Huge thanks to [gajae-code](https://github.com/Yeachan-Heo/gajae-code) for the i
 ## Changelog
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.14]** (2026-06-25) — Quieter, cleaner output: a new `-q`/`--quiet` flag strips launch banners and courtesy logs, `/resume` no longer dumps walls of raw escaped JSON into scrollback, and a turn that edits files now reliably surfaces those paths to orchestrators.
 - **[0.7.9]** (2026-06-24) — Local model providers actually run, and OAuth/login hygiene: Ollama requests now carry an explicit `num_ctx` so jeo's large system prompt no longer overflows Ollama's small default window (the "ollama 모델이 안 돌아간다" blocker), LM Studio reasoning models that emit the whole reply on the reasoning channel are recovered instead of dying empty, GGUF chat templates that can't render the `tools` array are retried with native tools stripped, the OAuth success tab auto-closes with a clear hint, the effective-credential picker prefers a verified OAuth login over a stray API key, and abandoned idle `jeo` tmux REPL sessions are reaped on launch.
 - **[0.7.8]** (2026-06-24) — Long-session performance & resource hygiene: the detached memory-distill worker now always terminates itself (closing the `jeo memory-distill` orphan pileup that pinned each session's transcript in RSS), the live reasoning/output block re-wraps only its trailing window (O(tail) per frame instead of O(len²) over a long stream), the team loop stops reprinting the todo guide every iteration, and the readline caret stays aligned after an image attach.
 - **[0.7.7]** (2026-06-23) — Long-running-process hygiene & input robustness: backgrounded grandchildren (`next dev &`, daemons) are now reaped at the turn boundary via per-command process groups — closing the climbing `next-server` RSS leak — while the prompt gains recursive fuzzy `@path` search, ANSI-safe and idle-merged bracketed paste, a configurable OSC 52 clipboard cap, per-role ralplan model routing, and leaked-reasoning-tag stripping on salvaged answers.
 - **[0.7.6]** (2026-06-23) — Release & docs plumbing: the running version's release notes now travel inside the `--compile` single binary (so `/whats-new` works offline and from a global install), the in-TUI markdown table renderer stops splitting on escaped `\|` pipes, and the release pipeline gains a cross-compiled standalone-binary matrix — macOS/Linux **plus a first-class Windows x64 `.exe`** — built on one Linux runner and auto-attached to each GitHub release.
-- **[0.7.5]** (2026-06-23) — Startup & loop latency: redundant re-reads that fired on every subagent spawn and every loop step are now memoized behind cheap `stat`-signature caches, so cold paths stay correct (edits/deletes still picked up immediately) while warm paths skip the disk and the re-parse. Targets the per-turn and per-spawn overhead that dominates perceived slowness in team/ralph/autopilot fan-outs.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/README.zh.md

@@ -149,6 +149,18 @@ jeo ultragoal
 `jeo` 在 `.jeo/memory/` 下保存 **本地优先、蒸馏后的项目内存**(无远程后端,零原生依赖)。过往会话被蒸馏为 [OKF](docs/okf_mem/) 概念包,下一次会话仅把相关的、受预算约束的切片重新注入系统提示 —— 作为 DATA 而非指令加固。用 `JEO_NO_MEMORY=1` 完全禁用。
 
 **迁移(`jeo memory-migrate`,一次性 · 幂等).** 把旧版单文档 `MEMORY.md` 无损转换为概念包: `## 标题 → 类型`,每个项目符号 → 一个类型化概念,缩进行 → 正文; 重建 `index.md`/`log.md`,并把原文件重命名为 `MEMORY.md.bak`。一旦概念包中已有概念,再次运行即为 no-op。**回滚:** `JEO_MEMORY_LEGACY=1` 忽略概念包,通过相同的注入加固读取 `MEMORY.md`/`.bak`(`JEO_NO_MEMORY=1` 仍优先于一切)。
+## 与您现有的代理或机器人协同工作 (Works beside your existing agent or bot)
+
+| 工具或机器人 | 推荐的 jeo 命令 | 边界 |
+| ----------- | ----------------------- | -------- |
+| Codex CLI | `jeo --tmux` 或 `jeo` | 在同级 tmux 会话中运行或内联运行。 |
+| Claude Code | `jeo --tmux` 或 `jeo` | jeo 不会成为 Claude Code 的扩展。 |
+| OpenCode | `jeo` 或 `jeo --tmux` | 仅限外部运行器工作流。 |
+| Claw Code | `jeo --tmux` | jeo 不会安装到或替换 Claw Code。 |
+| 外部控制器 / 机器人 | `jeo` (或自定义集成) | 外部控制器通过标准终端/CLI 接口驱动 jeo。 |
+
+添加 `-q`/`--quiet`（或 `JEO_QUIET=1`）可抑制启动横幅、欢迎动画、发布说明和恢复提示，使 jeo 能够与其他代理并行运行或由机器人驱动。`-p`/`--print` 隐含 quiet。
+
 
 ## 本地模型
 
@@ -193,11 +205,11 @@ CI 通过 `.github/workflows/npm-publish.yml` 发布 — GitHub 发布 release
 ## 更新日志 (Changelog)
 
 <!-- CHANGELOG:START (auto-generated from CHANGELOG.md — run `bun run changelog:sync`) -->
+- **[0.7.14]** (2026-06-25) — Quieter, cleaner output: a new `-q`/`--quiet` flag strips launch banners and courtesy logs, `/resume` no longer dumps walls of raw escaped JSON into scrollback, and a turn that edits files now reliably surfaces those paths to orchestrators.
 - **[0.7.9]** (2026-06-24) — Local model providers actually run, and OAuth/login hygiene: Ollama requests now carry an explicit `num_ctx` so jeo's large system prompt no longer overflows Ollama's small default window (the "ollama 모델이 안 돌아간다" blocker), LM Studio reasoning models that emit the whole reply on the reasoning channel are recovered instead of dying empty, GGUF chat templates that can't render the `tools` array are retried with native tools stripped, the OAuth success tab auto-closes with a clear hint, the effective-credential picker prefers a verified OAuth login over a stray API key, and abandoned idle `jeo` tmux REPL sessions are reaped on launch.
 - **[0.7.8]** (2026-06-24) — Long-session performance & resource hygiene: the detached memory-distill worker now always terminates itself (closing the `jeo memory-distill` orphan pileup that pinned each session's transcript in RSS), the live reasoning/output block re-wraps only its trailing window (O(tail) per frame instead of O(len²) over a long stream), the team loop stops reprinting the todo guide every iteration, and the readline caret stays aligned after an image attach.
 - **[0.7.7]** (2026-06-23) — Long-running-process hygiene & input robustness: backgrounded grandchildren (`next dev &`, daemons) are now reaped at the turn boundary via per-command process groups — closing the climbing `next-server` RSS leak — while the prompt gains recursive fuzzy `@path` search, ANSI-safe and idle-merged bracketed paste, a configurable OSC 52 clipboard cap, per-role ralplan model routing, and leaked-reasoning-tag stripping on salvaged answers.
 - **[0.7.6]** (2026-06-23) — Release & docs plumbing: the running version's release notes now travel inside the `--compile` single binary (so `/whats-new` works offline and from a global install), the in-TUI markdown table renderer stops splitting on escaped `\|` pipes, and the release pipeline gains a cross-compiled standalone-binary matrix — macOS/Linux **plus a first-class Windows x64 `.exe`** — built on one Linux runner and auto-attached to each GitHub release.
-- **[0.7.5]** (2026-06-23) — Startup & loop latency: redundant re-reads that fired on every subagent spawn and every loop step are now memoized behind cheap `stat`-signature caches, so cold paths stay correct (edits/deletes still picked up immediately) while warm paths skip the disk and the re-parse. Targets the per-turn and per-spawn overhead that dominates perceived slowness in team/ralph/autopilot fan-outs.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full history.
 <!-- CHANGELOG:END -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jeo-code",
-  "version": "0.7.12",
+  "version": "0.7.14",
   "description": "Clean, highly optimized AI coding agent using spec-first loop",
   "type": "module",
   "main": "src/cli.ts",

package/src/agent/engine.ts

@@ -272,6 +272,11 @@ export interface AgentLoopResult {
   doneReason?: string;
   /** Summed provider token usage across the turn's steps, when reported. */
   usage?: { inputTokens: number; outputTokens: number };
+  /** Repo-relative paths of files this turn SUCCESSFULLY wrote/edited, sorted and
+   *  de-duplicated. Lets a caller (task/team subagent, external orchestrator) collect
+   *  the run's code artifacts instead of inferring an empty change set after real edits.
+   *  Omitted when the turn mutated no file. */
+  mutatedFiles?: string[];
 }
 
 
@@ -364,7 +369,14 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
   let step = 1;
   const acc = { inputTokens: 0, outputTokens: 0 };
   let sawUsage = false;
-  const finish = (r: AgentLoopResult): AgentLoopResult => (sawUsage ? { ...r, usage: { ...acc } } : r);
+  // Repo-relative paths of files this turn successfully wrote/edited. Surfaced on the
+  // result so callers can collect the run's code artifacts rather than report an empty
+  // change set after real edits (the "finalArtifacts is empty" orchestrator failure).
+  const mutatedFiles = new Set<string>();
+  const finish = (r: AgentLoopResult): AgentLoopResult => {
+    const withArtifacts = mutatedFiles.size ? { ...r, mutatedFiles: [...mutatedFiles].sort() } : r;
+    return sawUsage ? { ...withArtifacts, usage: { ...acc } } : withArtifacts;
+  };
   // Salvage a spin-stop into a useful answer (C): instead of returning a bare
   // "Stopped: …" — throwing away everything found this turn — do ONE final no-tools
   // call asking the model to answer with what it already has. Mirrors the
@@ -1042,7 +1054,15 @@ export async function runAgentLoop(history: Message[], opts: AgentLoopOptions):
     for (let i = 0; i < toolCalls.length; i++) {
       if (!results[i].executed || !results[i].success) continue;
       const t = toolCalls[i].tool;
-      if (t === "write" || t === "edit") sawMutation = true;
+      if (t === "write" || t === "edit") {
+        sawMutation = true;
+        // Record the actual file so the run's artifacts can be collected/returned.
+        const rawPath = toolCalls[i].arguments?.filePath ?? toolCalls[i].arguments?.path;
+        if (typeof rawPath === "string" && rawPath.trim()) {
+          const rel = path.relative(cwd, path.resolve(cwd, rawPath)) || rawPath;
+          mutatedFiles.add(rel.split(path.sep).join("/"));
+        }
+      }
       else if (t === "bash") {
         const cmd = String(toolCalls[i].arguments?.command ?? "");
         if (isVerificationSignal(cmd, results[i].output)) sawVerification = true;

package/src/agent/task-tool.ts

@@ -207,12 +207,12 @@ export function createTaskTool(opts: TaskToolOptions): ToolHandler {
     const trace: string[] = [];
     let lastTarget = "";
     let currentStep = 0;
-    // Round-8 (architect ref 7-Round7Workflow): count the subagent's SUCCESSFUL
-    // calls so the parent can audit a "Changed Files:" claim against observed
-    // reality. File-writing tools (write/edit/mkdir/delete) are tracked apart from
-    // bash: read-only bash (e.g. `bun test`) MUST NOT count as edit evidence, but
-    // bash CAN mutate, so the audit message distinguishes the two cases.
-    let fileMutations = 0;
+    // Round-8 (architect ref 7-Round7Workflow): track whether the subagent ran any
+    // bash so the parent can audit a "Changed Files:" claim against observed reality.
+    // The actual set of written/edited files comes from the engine result
+    // (result.mutatedFiles); bash is tracked apart because read-only bash (e.g.
+    // `bun test`) is not edit evidence, yet bash CAN mutate — so the audit can tell
+    // "no action at all" from "only bash ran".
     let bashRuns = 0;
     emit({ role: role.id, kind: "start", detail: taskText, maxSteps, model });
     const result = await runAgentLoop(history, {
@@ -236,10 +236,7 @@ export function createTaskTool(opts: TaskToolOptions): ToolHandler {
           }
         },
         onToolResult: (tool, success, output) => {
-          if (success) {
-            if (tool === "write" || tool === "edit" || tool === "mkdir" || tool === "delete") fileMutations++;
-            else if (tool === "bash") bashRuns++;
-          }
+          if (success && tool === "bash") bashRuns++;
           const label = lastTarget || tool;
           const summary = firstUsefulLine(output);
           const suffix = summary ? ` — ${summary}` : "";
@@ -263,16 +260,24 @@ export function createTaskTool(opts: TaskToolOptions): ToolHandler {
     const tokNote = result.usage ? `, ${result.usage.inputTokens + result.usage.outputTokens} tok` : "";
     const header = `[${role.title} subagent] ${complete ? "completed" : "stopped"} in ${result.steps} step(s) on ${model}${tokNote}.`;
     const body = trace.length ? `\nSteps:\n${trace.join("\n")}` : "";
+    // Collect/return the run's code artifacts: the engine reports every file the
+    // subagent actually wrote/edited, so the parent (and any orchestrator above it)
+    // gets a CONCRETE change set instead of an unverifiable "Changed Files:" prose
+    // claim. Empty list ⇒ no observed file mutation.
+    const changedFiles = result.mutatedFiles ?? [];
+    const artifactNote = changedFiles.length
+      ? `\nChanged files (${changedFiles.length}): ${changedFiles.join(", ")}`
+      : "";
     // Parent-side audit: a mutating role that "completed" without a successful file
-    // mutation (write/edit/mkdir/delete) likely changed nothing — flag the claim.
-    // bash is tracked separately: it CAN mutate, so an only-bash run downgrades to
-    // "verify independently" instead of the stronger UNVERIFIED.
-    const audit = complete && !role.readOnly && fileMutations === 0
+    // mutation (write/edit) likely changed nothing — flag the claim. bash is tracked
+    // separately: it CAN mutate, so an only-bash run downgrades to "verify
+    // independently" instead of the stronger UNVERIFIED.
+    const audit = complete && !role.readOnly && changedFiles.length === 0
       ? bashRuns === 0
         ? `\n[parent audit] No successful write/edit/bash was observed in this run — treat any "Changed Files:" claims above as UNVERIFIED.`
         : `\n[parent audit] No successful write/edit was observed (only bash ran); bash may or may not have mutated files — verify any "Changed Files:" claims above independently.`
       : "";
-    return { success: complete, output: `${header}${body}\n\nResult:\n${fenceSubagentReport(detail)}${audit}` };
+    return { success: complete, output: `${header}${body}${artifactNote}\n\nResult:\n${fenceSubagentReport(detail)}${audit}` };
   };
 
   return async (args: Record<string, any>, cwd: string): Promise<ToolResult> => {

package/src/ai/providers/anthropic.ts

@@ -135,7 +135,7 @@ function anthropicThinkingMode(model: string): AnthropicThinkingMode {
   const v = parseAnthropicVersion(model);
   if (!v) return "budget";
   if (v.major > 4 || (v.major === 4 && v.minor >= 6)) return "adaptive";
-  if (v.major === 4 && v.minor === 5) return "budget-effort";
+  
   return "budget";
 }
 
@@ -266,7 +266,7 @@ export function anthropicPayload(
       // Budget-based extended thinking. `display: "summarized"` keeps human-readable thought
       // streaming. The 4.5 (budget-effort) transport also carries an output_config effort.
       payload.thinking = { type: "enabled", budget_tokens: thinkingBudget, display: "summarized" };
-      if (thinkingMode === "budget-effort") payload.output_config = { effort: anthropicAdaptiveEffort(effort) };
+      
     }
   } else if (includeTemperature && options.temperature !== undefined) {
     payload.temperature = options.temperature;
@@ -281,6 +281,7 @@ export function anthropicPayload(
   if (stream) payload.stream = true;
   const system = anthropicSystemBlocks(systemPrompt, model, credential, payload);
   if (system) payload.system = system;
+  console.log("PAYLOAD:", JSON.stringify(payload));
   return JSON.stringify(payload);
 }
 

package/src/cli/runner.ts

@@ -299,6 +299,7 @@ export function renderHelp(ctx: DispatchContext): string {
   lines.push("Options:");
   lines.push("  -v, --version    Show version.");
   lines.push("  -h, --help       Show help.");
+  lines.push("  -q, --quiet      Suppress startup banners and logs.");
   lines.push("      --model <id>             Use a session model for launch/one-shot.");
   lines.push("      --provider <name>        Start launch on a provider default (anthropic/openai/gemini/antigravity/ollama).");
   lines.push("      --smol|--slow|--plan     Start launch with the configured model role tier.");
@@ -320,7 +321,7 @@ export function renderCommandHelp(spec: CommandSpec, ctx: DispatchContext): stri
 const VALUE_FLAGS = new Set(["--worktree", "--model", "--provider", "--thinking", "--max-steps", "--append-system-prompt", "--skills", "--tools", "--system-prompt"]);
 const OPTIONAL_UUID_FLAGS = new Set(["--resume", "--continue", "-c"]);
 const VALUE_PREFIXES = ["--worktree=", "--model=", "--provider=", "--thinking=", "--max-steps=", "--append-system-prompt=", "--skills=", "--tools=", "--system-prompt="];
-const LAUNCH_ONLY_FLAGS = new Set(["--tmux", "--no-tui", "--no-session", "--list", "--smol", "--slow", "--plan", "-p", "--print", "--no-skills", "--no-tools"]);
+const LAUNCH_ONLY_FLAGS = new Set(["--tmux", "--no-tui", "--no-session", "--list", "--smol", "--slow", "--plan", "-p", "--print", "-q", "--quiet", "--no-skills", "--no-tools"]);
 const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
 function flagName(arg: string): string {

package/src/commands/launch/flags.ts

@@ -20,6 +20,7 @@ export interface LaunchFlags {
   thinking?: ThinkLevel;
   errors: string[];
   print?: boolean;
+  quiet: boolean;
   appendSystemPromptRaw?: string;
   appendSystemPrompt?: string;
   noSkills: boolean;
@@ -63,7 +64,7 @@ export function fastThinkingLevelForModel(modelId: string): ThinkLevel | undefin
 }
 
 export function parseFlags(args: string[], cwd: string = process.cwd()): LaunchFlags {
-  const flags: LaunchFlags = { list: false, resume: false, noSession: false, noTui: false, maxSteps: 0, message: "", tmux: false, errors: [], print: false, noSkills: false, noTools: false };
+  const flags: LaunchFlags = { list: false, resume: false, noSession: false, noTui: false, maxSteps: 0, message: "", tmux: false, errors: [], print: false, quiet: false, noSkills: false, noTools: false };
   const rest: string[] = [];
   const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
   for (let i = 0; i < args.length; i++) {
@@ -77,6 +78,8 @@ export function parseFlags(args: string[], cwd: string = process.cwd()): LaunchF
     } else if (a === "-p" || a === "--print") {
       flags.print = true;
       flags.noTui = true;
+    } else if (a === "-q" || a === "--quiet") {
+      flags.quiet = true;
     } else if (a === "--tmux") {
       flags.tmux = true;
     } else if (a === "--worktree") {

package/src/commands/launch.ts

@@ -309,6 +309,7 @@ export function formatResumeHint(sessionId: string): string {
 export async function runLaunchCommand(args: string[]): Promise<void> {
   let cwd = process.cwd();
   const flags = parseFlags(args, cwd);
+  const isQuiet = flags.quiet || flags.print || jeoEnv("QUIET") === "1";
   if (flags.errors.length) {
     for (const err of flags.errors) {
       console.error(`error: ${err}`);
@@ -322,7 +323,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
     if (wt !== cwd) {
       process.chdir(wt);
       cwd = wt;
-      if (jeoEnv("TMUX_LAUNCHED") !== "1") console.log(`Using worktree: ${wt}`);
+      if (jeoEnv("TMUX_LAUNCHED") !== "1" && !isQuiet) console.log(`Using worktree: ${wt}`);
     }
   }
   let branch: string | undefined;
@@ -656,7 +657,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
     if (flags.resume) {
       const id = flags.resumeId ?? (await latestSessionId(cwd));
       if (!id) {
-        console.log("No session to resume. Starting a new one.");
+        if (!isQuiet) console.log("No session to resume. Starting a new one.");
         sessionId = (await createSession(cwd, undefined, sessionModel)).id;
       } else {
         try {
@@ -667,9 +668,9 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
           // pinned one (flags.model/role/provider → initialSessionModel wins).
           if (!initialSessionModel && header.model) sessionModel = header.model;
           const modelNote = sessionModel ? ` · model ${sessionModel}` : "";
-          console.log(`Resumed session ${id} (${messages.length} messages).${modelNote}`);
+          if (!isQuiet) console.log(`Resumed session ${id} (${messages.length} messages).${modelNote}`);
         } catch (err) {
-          console.log(`Could not resume ${id}: ${(err as Error).message}. Starting fresh.`);
+          if (!isQuiet) console.log(`Could not resume ${id}: ${(err as Error).message}. Starting fresh.`);
           sessionId = (await createSession(cwd, undefined, sessionModel)).id;
         }
       }
@@ -1266,7 +1267,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
     renderWelcome({ ...welcomeData, cols: terminalSize().cols });
   // gjc-style fresh-start clear so the banner opens atop a clean screen. TTY only,
   // never mid-turn (scrollback flood). ponytail: add an opt-out env if anyone misses their scrollback.
-  if (process.stdout.isTTY) process.stdout.write(clearScreen());
+  if (process.stdout.isTTY && !isQuiet) process.stdout.write(clearScreen());
   // Launch sweep: the forge mark's gradient loops seamlessly (default 2 full
   // cycles, JEO_WELCOME_ANIM_CYCLES overrides), ending on the static banner.
   // Truecolor TTYs only; JEO_NO_WELCOME_ANIM=1 opts out.
@@ -1276,8 +1277,10 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
     detectColorLevel(process.env, true) === ColorLevel.TrueColor &&
     jeoEnv("NO_WELCOME_ANIM") !== "1";
   const sweepCycles = Math.min(10, Math.max(1, Number(jeoEnv("WELCOME_ANIM_CYCLES")) || 2));
-  if (sweepable) await playWelcomeSweep(welcomeData, { cycles: sweepCycles });
-  else console.log(renderWelcome(welcomeData).join("\n"));
+  if (!isQuiet) {
+    if (sweepable) await playWelcomeSweep(welcomeData, { cycles: sweepCycles });
+    else console.log(renderWelcome(welcomeData).join("\n"));
+  }
 
   // Surface the "New version" banner reliably: render ONCE from the on-disk cache
   // instantly (no network wait, works offline — the common path after the first
@@ -1285,7 +1288,7 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
   // bump still shows it this launch. Both must run BEFORE the prompt is armed.
   let updateBannerShown = false;
   const showUpdateBanner = (u: { current: string; latest: string; updateAvailable: boolean } | null): void => {
-    if (updateBannerShown || !u?.updateAvailable) return;
+    if (updateBannerShown || !u?.updateAvailable || isQuiet) return;
     updateBannerShown = true;
     console.log(renderUpdateBox(u.current, u.latest).join("\n"));
   };
@@ -1294,15 +1297,17 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
   // First launch after a version bump: surface the bundled release notes ONCE
   // (offline, from the new package's CHANGELOG.md) and record the seen version
   // so it never repeats. Screen-safe: prints BEFORE the prompt is armed.
-  try {
-    const whatsNew = await consumeLaunchWhatsNew({
-      cols: Math.min(100, Math.max(40, (process.stdout.columns ?? 80) - 2)),
-      unicode: supportsUnicode(),
-      color: welcomeTheme.color,
-    });
-    if (whatsNew && whatsNew.length) console.log(whatsNew.join("\n"));
-  } catch { /* release notes are a courtesy; never block launch */ }
-  if (!LaunchTui.usable(flags.noTui)) console.log("(plain output)");
+  if (!isQuiet) {
+    try {
+      const whatsNew = await consumeLaunchWhatsNew({
+        cols: Math.min(100, Math.max(40, (process.stdout.columns ?? 80) - 2)),
+        unicode: supportsUnicode(),
+        color: welcomeTheme.color,
+      });
+      if (whatsNew && whatsNew.length) console.log(whatsNew.join("\n"));
+    } catch { /* release notes are a courtesy; never block launch */ }
+  }
+  if (!LaunchTui.usable(flags.noTui) && !isQuiet) console.log("(plain output)");
 
   const useTui = LaunchTui.usable(flags.noTui);
   const runSkillInvocation = async (skill: SkillDoc, intent: string, invokedAs?: string): Promise<void> => {
@@ -4425,11 +4430,11 @@ export async function runLaunchCommand(args: string[]): Promise<void> {
   // of blocking up to 20s on a final LLM call. The child writes MEMORY.md atomically.
   if (sessionUsage.turns > 0) {
     const spawned = await spawnDetachedDistill(history, cwd, sessionModel || defaultModel);
-    if (spawned) console.log(chalk.gray("(session memory distilling in background)"));
+    if (spawned && !isQuiet) console.log(chalk.gray("(session memory distilling in background)"));
   }
   // gjc-parity resume pointer (logs/gjc-tui-study analysis Gap C): leave the exact
   // resume command in scrollback on exit, mirroring the --list handler's convention.
-  if (sessionId && !flags.noSession) console.log(formatResumeHint(sessionId));
+  if (sessionId && !flags.noSession && !isQuiet) console.log(formatResumeHint(sessionId));
   process.removeListener("SIGINT", handleCtrlC);
   process.stdin.off("data", handleCtrlCByte);
   drainPromptListeners();

package/src/commands/team.ts

@@ -431,8 +431,8 @@ async function executeTaskWithAgent(ctx: RalphSubagentPromptContext & { cwd: str
     // LLM summary failure does not halt team
   }
 
-  let fileMutations = 0; // round-8 parent audit: successful write/edit/mkdir/delete
   let bashRuns = 0;      // bash counted apart so read-only bash isn't edit evidence
+                        // (the actual write/edit set comes from result.mutatedFiles)
   const result = await runAgentLoop(history, {
     cwd: ctx.cwd,
     model,
@@ -458,10 +458,7 @@ async function executeTaskWithAgent(ctx: RalphSubagentPromptContext & { cwd: str
         }
       },
       onToolResult: (tool, ok) => {
-        if (ok) {
-          if (tool === "write" || tool === "edit" || tool === "mkdir" || tool === "delete") fileMutations++;
-          else if (tool === "bash") bashRuns++;
-        }
+        if (ok && tool === "bash") bashRuns++;
         log(formatRalphStreamEvent(ok ? "complete" : "error", `tool ${tool}`, renderOpts));
       },
       onNotice: msg => log(formatRalphStreamEvent("step", msg, renderOpts)),
@@ -486,7 +483,15 @@ async function executeTaskWithAgent(ctx: RalphSubagentPromptContext & { cwd: str
     return false;
   }
 
-  if (!role.readOnly && fileMutations === 0) {
+  // Collect/return the run's code artifacts: the engine reports every file the
+  // subagent actually wrote/edited, so the task's change set is concrete instead of
+  // an unverifiable prose claim. An empty list ⇒ no observed file mutation.
+  const changedFiles = result.mutatedFiles ?? [];
+  if (changedFiles.length > 0) {
+    log(formatRalphStreamEvent("complete", `${role.title} changed ${changedFiles.length} file(s): ${changedFiles.join(", ")}`, renderOpts));
+  }
+
+  if (!role.readOnly && changedFiles.length === 0) {
     // Round-8: a mutating role finished without a successful file mutation — the
     // task may be legitimately read-only, but its "Changed Files:" claim is
     // unverified. bash is tracked apart: an only-bash run MIGHT have mutated.

package/src/tui/components/transcript.ts

@@ -108,19 +108,45 @@ export function formatTranscript(messages: readonly Message[], opts: TranscriptO
       continue;
     }
     // assistant: a JSON tool call (compact ledger lines) or a prose/done reply.
-    // A tool-call message IS a JSON object (optionally inside a ```json fence) — so
-    // only parse when the content actually begins with `{` after stripping a leading
-    // fence. This renders fenced/decorated tool calls as cards (the "/resume shows
-    // raw JSON and breaks the TUI" bug — naive JSON.parse failed on any fence and
-    // dumped the block) while prose that merely CONTAINS tool-like JSON stays prose.
-    const stripped = m.content.trim().replace(/^```(?:json)?[ \t]*\r?\n?/i, "").trimStart();
-    const looksLikeCall = stripped.startsWith("{");
-    const parsed = looksLikeCall
-      ? tryExtractJsonObject<{ tool?: unknown; tools?: unknown; arguments?: unknown }>(
-          m.content,
-          { preferKeys: ["tool", "tools"] },
-        )
-      : null;
+    // A tool-call message is a JSON object that may be preceded by a ```json fence
+    // AND/OR by model "think-aloud" prose — gpt/qwen-style replies narrate a sentence
+    // and then append the JSON tool call in the SAME message. Extract the embedded
+    // call from anywhere in the content (mirroring the engine's own extractJsonObject)
+    // instead of gating on a leading `{`: that gate classified every prose-prefixed
+    // call as plain prose and dumped the raw object — including escaped multi-line
+    // edit/write payloads — verbatim into scrollback (the "/resume reads a wall of
+    // broken escaped data" bug). The narration is kept (dimmed); the raw JSON never is.
+    const parsed = tryExtractJsonObject<{ tool?: unknown; tools?: unknown; arguments?: unknown }>(
+      m.content,
+      { preferKeys: ["tool", "tools"] },
+    );
+    const isCall = !!parsed && (typeof parsed.tool === "string" || Array.isArray(parsed.tools));
+    // The protocol allows a leading `"reasoning"` field on a tool call; surface that
+    // narration (clipped) instead of losing it, and never re-dump it as raw JSON.
+    const reasoningText = parsed && typeof (parsed as { reasoning?: unknown }).reasoning === "string"
+      ? String((parsed as { reasoning?: unknown }).reasoning).trim()
+      : "";
+    // `looksLikeToolAttempt` flags a (possibly malformed/truncated) tool call so its
+    // raw JSON is suppressed even when parsing fails — e.g. a bounced reply the model
+    // later resent. Prose narrating a call is the text BEFORE the first `{` (the start
+    // of the parsed object): a prose-prefixed call keeps its lead-in; a JSON-first or
+    // reasoning-first call has none (its narration comes from `reasoningText`).
+    const looksLikeToolAttempt = /\{\s*"tools?"\s*:/.test(m.content);
+    const firstBrace = m.content.indexOf("{");
+    const prosePrefix = firstBrace > 0
+      ? m.content.slice(0, firstBrace).replace(/```(?:json)?[ \t]*\r?\n?/i, "").trim()
+      : "";
+
+    // A reply whose content (after an optional ```json fence) STARTS with `{` is a JSON
+    // emission, not prose — even a giant malformed reasoning blob the model couldn't close.
+    const startsWithJson = m.content.trimStart().replace(/^```(?:json)?[ \t]*\r?\n?/i, "").startsWith("{");
+    // Any JSON object/tool-call emission — fenced, prose-prefixed, reasoning-prefixed,
+    // or one we could not parse into a renderable call — must never reach scrollback as
+    // raw escaped JSON (the "/resume reads a wall of broken data" report).
+    const isJsonEmission = looksLikeToolAttempt || startsWithJson;
+    const narration = prosePrefix || reasoningText;
+
+
     const calls: { tool: string; arguments?: unknown }[] =
       parsed && typeof parsed.tool === "string"
         ? [{ tool: parsed.tool, arguments: parsed.arguments }]
@@ -130,13 +156,27 @@ export function formatTranscript(messages: readonly Message[], opts: TranscriptO
               .map(c => ({ tool: c.tool as string, arguments: c.arguments }))
           : [];
     const toolCalls = calls.filter(c => c.tool !== "done");
-    if (toolCalls.length > 0) {
+    // A genuine tool-call turn is FOLLOWED by its `Tool [x] result` user message and the
+    // JSON is the final token; an illustrative JSON snippet quoted inside a prose reply is
+    // not, and it carries meaningful prose AFTER the object. Use both signals so a real
+    // prose-prefixed call renders as a ledger line while a sentence that merely shows
+    // `{"tool":...}` as an example stays prose.
+    const next = messages[i + 1];
+    const hasResult = next?.role === "user" && TOOL_RESULT_RE.test(next.content);
+    const lastBrace = m.content.lastIndexOf("}");
+    const trailing = lastBrace >= 0 ? m.content.slice(lastBrace + 1).trim() : "";
+    // A reply that STARTS with `{` is never illustrative prose — it is a (possibly
+    // malformed) JSON emission whose raw body must stay out of scrollback.
+    const looksIllustrative = !startsWithJson && !hasResult && trailing.length > 12 && /[A-Za-z]/.test(trailing);
+
+    if (toolCalls.length > 0 && !looksIllustrative) {
       if (lines.length > 0 && lines[lines.length - 1] !== "") {
         lines.push("");
       }
-      // The matching `Tool [x] result (ok|fail)` user message follows; for a batch it
-      // is ONE message with several blocks. Parse verdicts in call order.
-      const next = messages[i + 1];
+      // Pre-call narration (dimmed) keeps the "why" of each step without the raw JSON.
+      if (narration) for (const l of clipBody(narration, bodyCap)) lines.push(dim(l));
+      // For a batch the result is ONE user message with several blocks; parse verdicts
+      // in call order.
       const verdicts = next?.role === "user" ? parseToolVerdicts(next.content) : [];
       toolCalls.forEach((c, ci) => {
         const v = verdicts[ci] ?? verdicts.find(x => x.tool === c.tool);
@@ -147,14 +187,22 @@ export function formatTranscript(messages: readonly Message[], opts: TranscriptO
       });
       continue;
     }
-    // No tool calls → a lone `{tool:"done", reason}` (show its reason), a JSON object
-    // that isn't a renderable call (skip — never dump raw JSON), or genuine prose.
-    const reason =
-      parsed && parsed.tool === "done"
-        ? String((parsed.arguments as { reason?: unknown } | undefined)?.reason ?? "")
-        : looksLikeCall
-          ? ""
-          : m.content;
+    // No rendered tool call → a lone `done` call (reason + narration), a malformed/raw
+    // JSON or tool-call emission (show narration only — never dump the raw object), or
+    // genuine prose (which may merely quote a JSON snippet).
+    const doneCall = calls.find(c => c.tool === "done");
+    const doneReason = doneCall
+      ? String((doneCall.arguments as { reason?: unknown } | undefined)?.reason ?? "")
+      : "";
+    const reason = doneCall
+      ? [narration, doneReason].filter(s => s.trim()).join("\n\n")
+      : isJsonEmission && !looksIllustrative
+        ? narration // JSON/tool-call emission we couldn't render — keep narration, drop raw JSON
+        : m.content;
+
+
+
+
     if (!reason.trim()) continue;
     // Persisted thinking (gjc "think → answer" order): show the turn's reasoning,
     // dimmed, above the reply so the durable record carries it across /resume + export.