From 26b3d133fc5d696d7a070b09db67221b66356ee7 Mon Sep 17 00:00:00 2001
From: rgarcia <72655+rgarcia@users.noreply.github.com>
Date: Wed, 13 May 2026 19:23:08 +0000
Subject: [PATCH] Clarify harness use in agent README

---
 packages/agent/README.md | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/packages/agent/README.md b/packages/agent/README.md
index d7efbf9c..0da87ee1 100644
--- a/packages/agent/README.md
+++ b/packages/agent/README.md
@@ -49,8 +49,13 @@ const transcript = harness.getTranscript();
 console.log("messages in transcript:", transcript.length);
 ```
 
-Use `CuaAgent` when you want direct pi `Agent` control. Use `CuaHarness` when you
-want the harness-style constructor plus transcript-oriented helpers like
+Use `CuaAgent` when you want direct pi `Agent` control: raw transcript state,
+lifecycle events, custom streaming, and explicit prompt/continue/queue control.
+Reach for the harness shape when you want an app layer around the loop:
+session/transcript helpers, resource and prompt entry points, provider/auth
+hooks, active tool selection, compaction/tree workflows, and higher-level queue
+events. `CuaHarness` is the thin CUA version of that shape today: it installs
+CUA defaults, delegates runtime methods to the wrapped `Agent`, and adds
 `getTranscript()`.
 
 ## Core Concepts