Log every message an agent sends, and which way in it came

An agent's session kept the calls that reached a tool. So a refused
`conclude` was a row with no answer under it, and a call to a tool that
does not exist, a method this build has never heard of and a line that
was not JSON were not rows at all — which is exactly the traffic somebody
opens that screen to look at, since the question it gets opened for is
usually why nothing happened.

Now every line goes down: `tool` is null for the ones that reached no
tool and `method` says what arrived instead, `output` is what went back
whatever that was, and `error` is separate from `refused` because they
are opposite claims — a refusal is the method working and an error is
this app failing. `AgentSession.toolCalls` is the subset that got as far
as a tool, which is what the eval counts and what the screen's `n
call(s)` says, so a command line's handshake per call doesn't read as
twice the work.

And a line records whether it came in over MCP or from `--agent` at a
shell. Told to `McpSession` at construction rather than worked out: past
the handshake the two are the same protocol on the same socket, which is
the point of them, so the door is the only place that knows. It travels
as the last word of the handshake line, and a connection that says
nothing is MCP.

Leaving `output` null for a refusal was a deliberate call — the refusal
was already in `refused`, so writing it twice looked like the same
paragraph on disk twice. From outside it looked like a call the app
answered and did not log.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: pyricau

docs/shark-dive-changelog.md

@@ -85,9 +85,13 @@ uses, without the one for a newly recognized library leak:
   what an agent *said* it was doing, and a step taken on an answer that said nothing reads exactly like one
   taken on an answer that said everything until you open both. The `▸ {}` under a row is what opens it, and
   what was sent names the tool the agent called as well as what it sent to it — `describe_object` beside the
-  window's own word for it, which is the pair worth having when a step doesn't follow. `agent_log` hands an
-  agent the same text, so one agent can work out where another went wrong. Kept in `~/.shark-dive/agents/sessions`,
-  one file per session and the newest hundred kept, so a session outlives the window it was worked in.
+  window's own word for it, which is the pair worth having when a step doesn't follow. **The full traffic, not
+  only the calls that worked**: the handshake, a call naming a tool that doesn't exist and a line that wasn't
+  JSON are rows too, a refusal and an error are under `answered:` as the agent was handed them, and each row
+  says whether it came in over MCP or from `--agent` at a shell — because what this screen gets opened for is
+  often why *nothing* happened. `agent_log` hands an agent the same text, so one agent can work out where
+  another went wrong. Kept in `~/.shark-dive/agents/sessions`, one file per session and the newest hundred
+  kept, so a session outlives the window it was worked in.
   See [Hand it to an agent](shark-dive.md#hand-it-to-an-agent).
 * ✨ **The chain marks the faulty reference**: the one step going from an `Expected` object straight to a
   `Stuck` one reads `Holder.activity · faulty reference`, which is the leak itself rather than one of the

docs/shark-dive.md

@@ -419,10 +419,13 @@ unexplained steps cannot report a root cause, however sure it is, and what it ge
 objects to go and read.
 
 **What it did is on the *Agent logs* screen**, one row per agent that has connected to the app. Open a row
-and there is every call that agent made, in order and in words — what it did, which object it did it to, and
-the sentence it gave for doing it:
+and there is everything that agent sent, in order and in words — what each call did, which object it did it
+to, and the sentence it gave for doing it:
 
 ```
+08:23:01  Connected
+08:23:01  Sent the notification notifications/initialized
+08:23:02  Asked what the tools are
 08:23:04  Asked which heap dumps are open
           because: Seeing what there is to read before asking anything about it.
 08:23:11  Listed the leaks
@@ -454,14 +457,32 @@ rather than on to an answer:
           reference: the rules can only name one once something below it is known not to belong. […]
 ```
 
+**And so is every other line that arrived** — the three at the top of that session are the handshake. A call
+naming a tool that doesn't exist, a line that wasn't JSON at all, a read that failed: each is a row, and the
+ones nothing could answer say *Failed* rather than *Refused*, which is the opposite claim. A refusal is the
+method working; this is Shark Dive not working.
+
+```
+08:24:02  Called solve_the_leak 0x12d368b8
+          because: Trying my luck.
+          Failed: There is no tool called "solve_the_leak". This server has open_heap_dumps, […]
+08:24:09  Sent something this app could not read
+          Failed: That is not JSON: Unexpected JSON token at offset 0
+```
+
+Which is the point of keeping them: what this screen gets opened for is often why *nothing* happened, and a
+screen holding only the calls that worked is the one screen that can't answer that. It shows in the shape of a
+session — one sent from a shell is a *Connected* per call, `--agent` being a process per call — and the
+`n call(s)` above the rows counts the calls rather than the lines.
+
 **And every row unfolds onto the call itself** — the `▸ {}` under a row opens what the agent sent and what it
 read back, as the text each of them was, so a step you don't follow is one question rather than a dead end:
 
 ```
 11:37:31  Looked at 0x12d368b8
           because: The one App leak: a MainActivity the app watched. Reading what it is before the chain.
           ▾ {}
-            sent:
+            sent over MCP:
               describe_object {
                   "object": "0x12d368b8",
                   "reason": "The one App leak: a MainActivity the app watched. Reading what it is
@@ -484,12 +505,19 @@ read back, as the text each of them was, so a step you don't follow is one quest
 
 What it sent is the tool's own name and then the arguments under it, which is the call as the model wrote it:
 *Looked at* is this window's word for `describe_object`, and the pair is worth having side by side exactly
-when a step doesn't follow from the one before it.
+when a step doesn't follow from the one before it. And *over MCP* is which way in it came — a client holding a
+connection open, or `--agent` typed at this window — which is the one thing about a call that nothing else on
+the screen can tell you, since by the time anything answers one the two are the same protocol on the same
+socket.
 
 Whole, never a first line of it: what you open a call for is the part the sentence left out, so an answer cut
-to fit would be one where the field that misled the agent is the part that got cut. A refused call shows what
-it sent and no answer, its answer having been the refusal already on the row. And a session recorded by an
-older Shark Dive says so rather than opening onto a gap.
+to fit would be one where the field that misled the agent is the part that got cut. And a session recorded by
+an older Shark Dive says so rather than opening onto a gap.
+
+**Including the calls that came to nothing**, which is what this is most worth opening for. A refusal is
+under `answered:` as the agent was handed it, as well as in red on the row; so is an error, if a read failed
+or this app has a bug; so is the answer to a call naming a tool that doesn't exist. The only row with nothing
+under `answered:` is a notification, which is the one kind of message the protocol forbids answering.
 
 The mark is under the row rather than on the verb because a row is a sentence with one link in it, and a fold
 over its first words made hovering light up the half that isn't the link.
@@ -500,9 +528,9 @@ one that said everything, until you open both. Select and copy either half — i
 whoever handed you the dump, into a diff of two runs.
 
 A session is kept in `~/.shark-dive/agents/sessions`, one file per agent that connected and the newest
-hundred kept, a line of JSON per call, each carrying that call's `input` and `output` — so it outlives the
-window and can be read by something other than this app. `agent_log` hands an agent the same text, which is
-how one agent works out where another went wrong. **And the reads each call cost are in the run's log**, in
+hundred kept, a line of JSON per message, each carrying that message's `input` and `output` — so it outlives
+the window and can be read by something other than this app. `agent_log` hands an agent the same text, which
+is how one agent works out where another went wrong. **And the reads each call cost are in the run's log**, in
 `~/.shark-dive/logs`, where the reason it gave is followed by the work it caused:
 
 ```

shark/shark-dive/notes/agent-surface.md

@@ -27,27 +27,33 @@ descriptions that say when to reach for a tool. Re-measure it if the count doubl
 
 ## And what reading somebody else's session costs
 
-`agent_log` without a session id is a line per session and cheap. With one, it is now every call of that
-session *with what each one sent and read back*, which is the only form that answers "why did it do that
-next" — and the numbers are worth knowing before reaching for it. Measured on a five-call session against
-`leak_asynctask_o.hprof`, one `list_leaks` twice, a `describe_object`, a `chain_from_gc_root` and a refused
-`conclude`:
+`agent_log` without a session id is a line per session and cheap. With one, it is now every *message* of that
+session with what each one sent and read back, which is the only form that answers "why did it do that
+next" — and the numbers are worth knowing before reaching for it. Measured against a packaged run on
+`leak_asynctask_o.hprof`: four calls typed at `--agent` (two `list_leaks`, a refused `conclude`, a
+`solve_the_leak` that is no tool) and four messages pushed at the socket by hand (a line that is not JSON, a
+`resources/list`, a `tools/call` with no name, a notification):
 
 | | Measured |
 | --- | --- |
-| The five answers as recorded | 7,783 + 7,783 + 11,935 + 5,364 characters, and none for the refusal |
-| The five calls as sent | 95 + 81 + 150 + 121 + 163 characters — a rounding error beside the answers |
-| The whole `agent_log session=…` answer | 39,615 characters, ≈9,900 tokens |
-
-So **a session is roughly two thousand tokens a call**, and a thirty-call investigation read in full is most
-of a small context window. That is the tool being used for what it is for rather than a leak — it is the one
-call on this surface whose subject is somebody else's whole investigation — but it means the list form is
-what "worth reading before starting" points at, and the session form is what somebody reaches for when an
-investigation went wrong and the reasons on their own didn't say where.
+| The four tool-call rows | 8,783 + 8,775 + 1,750 + 987 characters — the answer is nearly all of each |
+| The four protocol rows | 37,313 characters, of which **32,976 is four `initialize` answers** |
+| The whole `agent_log session=…` answer | 57,693 characters, ≈14,400 tokens |
+
+So **a tool call is one to two thousand tokens** and a thirty-call investigation read in full is most of a
+small context window. That is the tool being used for what it is for rather than a leak — it is the one call
+on this surface whose subject is somebody else's whole investigation.
+
+**The handshakes are the surprise, and they are a command line's.** `initialize` answers with
+`AgentMethod.INSTRUCTIONS`, and `--agent` is a process per call, so a session of typed calls carries the
+method once per call: 57% of the answer above, handed to a reader that already has the same text in its own
+context. An MCP session pays it once. Nothing about that is a reason to record less — a session that keeps
+only what reached a tool cannot say why nothing did, which is the whole point of keeping the traffic — but if
+`agent_log` needs to be cheaper, **the handshake answers are where to look first**, and the shape to reach
+for is a way to ask for one message's exchange rather than a shorter version of every message's.
 
 Nothing truncates it, deliberately: a session cut to fit is one where the answer that misled an agent is the
-part that got cut. If this needs to be cheaper the answer is a way to ask for *one call's* exchange, not a
-shorter version of every call's.
+part that got cut.
 
 ## What the command line costs, now that there is one
 

shark/shark-dive/shark-dive-agent/AGENTS.md

@@ -91,8 +91,24 @@ same string `toolResult` puts in `content[0].text`, formatted once and then both
 down, so that a session can be compared against a client's own transcript character for character. Everything
 else on a call is derived, and a derived field is the one thing that is no use when the question is why an
 investigation went wrong: a step made on an answer that said nothing reads exactly like a step made on one
-that said everything. **A refused call has no `output`**, its answer having been the refusal that is already
-in `refused` — writing it twice would put the same paragraph on disk and on the screen twice over.
+that said everything.
+
+**`output` is what went back, whatever that was.** A refusal is in it as well as in `refused`, and an error as
+well as in `error`, and the two are not the same field said twice: `refused` and `error` are this app's
+reading — the method said no, this app could not answer — and `output` is the text the agent was handed. The
+first version left `output` null for a refusal on the grounds that the refusal was already written down, and
+what that looked like from outside was a call that got no answer at all. **Null on `output` means nothing went
+back**, which is a notification and nothing else.
+
+**And a line goes down for every message, not only the ones that reached a tool.** The handshake, a
+`tools/list`, a ping, a notification, a method this build has never heard of, a `tools/call` with no name or a
+name nothing answers to, and a line that was not JSON: all of them. `tool` is null for the ones that reached
+no tool and `method` says what arrived instead, `AgentSession.toolCalls` is the subset that got as far as a
+tool, and **that distinction is not cosmetic** — the eval counts calls, and a run scored on lines sent would
+have a number that moved with the transport. `AgentSessionCall.over` is which way in a line came, told to
+`McpSession` at construction because a command line and an MCP client are indistinguishable from the moment
+the handshake is past, which is the point of them. The word travels as the last field of `AgentServer`'s
+handshake line, and a connection that says nothing is MCP.
 
 The name is in `input` even though `tool` has it, and that is not an oversight: this field is read as one
 thing, and a set of arguments lifted away from what they are arguments *to* is the one form of a call nobody
@@ -114,8 +130,10 @@ answer printed twice.
 
 **The verbs are here rather than in the app.** `verbOfTool` is beside the tool names, so that a screen never
 spells them itself and drift is one list rather than two. `AgentSessionFileTest` asserts every tool in the
-registry has one; a tool added without a verb reads as its own name, which is the protocol showing through on
-the screen that exists to not show it.
+registry has one — **which is what makes the fallback mean something**: a name `verbOfTool` has no verb for is
+a name this build has no tool for, so a row reading `Called solve_the_leak` is a typo or a tool from a newer
+build, and the name is left exactly as it arrived because that string is what somebody is looking for. A
+message that reached no tool at all reads through `verbOfMethod` instead.
 
 **A verb stops where the thing it was about starts**, which is why several of them end mid-sentence: a row of
 that screen is prose with one link in it, and the link is the thing. So `list_leaks` is "Listed the" and
@@ -152,10 +170,10 @@ to one adapter and not the other is the mistake this shape exists to make imposs
 `notes/agent-surface.md`, which also has what a call costs.
 
 **A process per call would otherwise be a session per call**, and a session is what somebody reads afterwards.
-So the handshake is `token[ sessionName]` on one line, `AgentSessionFile.continuing` appends to the newest file
-whose name carries that id, and a command line defaults to `cli<the shell's pid>` — an agent's calls come out
-of one shell the way its MCP calls come out of one connection. A client that says nothing gets a session of
-its own, which is what every MCP client does.
+So the handshake is `token[ sessionName[ over]]` on one line, `AgentSessionFile.continuing` appends to the
+newest file whose name carries that id, and a command line defaults to `cli<the shell's pid>` — an agent's
+calls come out of one shell the way its MCP calls come out of one connection. A client that says nothing gets
+a session of its own, which is what every MCP client does, and its lines are recorded as MCP.
 
 **The name is checked at both ends**, because it becomes part of a file name: the command line refuses one
 that isn't letters and digits before calling anything, and `AgentServer` serves the connection anyway with a

shark/shark-dive/shark-dive-agent/src/main/java/shark/dive/agent/AgentCommandLine.kt

@@ -164,9 +164,11 @@ object AgentCommandLine {
   ): Int {
     val toApp = PrintWriter(OutputStreamWriter(socket.getOutputStream(), Charsets.UTF_8), true)
     val fromApp = BufferedReader(InputStreamReader(socket.getInputStream(), Charsets.UTF_8))
-    // The token, and then which session this call is one of: one line, because the alternative is a
-    // handshake that has to be answered before the protocol can start. See [AgentServer].
-    toApp.println("${run.token} $sessionName")
+    // The token, then which session this call is one of, then that it was typed rather than sent by a
+    // client: one line, because the alternative is a handshake that has to be answered before the protocol
+    // can start. Saying so here is the only chance there is — from the next line on this is indistinguishable
+    // from an MCP client, which is the point of it. See [AgentServer] and [AgentTransport].
+    toApp.println("${run.token} $sessionName ${AgentTransport.CLI.recorded}")
     if (fromApp.readLine() != AgentServer.ACCEPTED) {
       say("Shark Dive run ${run.pid} refused the token in ${run.file}, so it is not the run that wrote it")
       return NOTHING_ANSWERED

shark/shark-dive/shark-dive-agent/src/main/java/shark/dive/agent/AgentJson.kt

@@ -91,8 +91,16 @@ internal object AgentJson {
     put("session", session.sessionId)
     put("client", session.client)
     put("startedAt", session.startedAt?.toString())
-    put("calls", session.calls.size)
+    // Which way in it was talked to, and usually one: a session with both in it is somebody typing calls at
+    // the window a client is working in, which is worth knowing before reading it.
+    putJsonArray("over") { session.transports.forEach { add(it.recorded) } }
+    // The calls that reached a tool, and not every message of it: the protocol around them is in the session
+    // form below, and counting it here would make a command line's investigation — a handshake per call —
+    // read as twice the work it was. See [AgentSession.toolCalls].
+    put("calls", session.toolCalls.size)
     put("refused", session.refusedCount)
+    // And how many got no answer at all, which is this app failing rather than the surface saying no.
+    put("errors", session.errorCount)
     // What it concluded, which is the one thing a reader is looking for — and null for a session that
     // concluded nothing, which is most of them.
     put("concluded", session.calls.mapNotNull { it.outcome }.lastOrNull())
@@ -124,17 +132,24 @@ internal object AgentJson {
       session.calls.forEach { call ->
         addJsonObject {
           put("at", call.at.toString())
+          // Which way in it came, and what arrived: null on `tool` is a message that reached none, and the
+          // method is then the whole of what it was. Not only the calls, because a session that shows the
+          // ones that worked cannot answer why the others didn't. See [AgentSession.calls].
+          put("over", call.over?.recorded)
+          put("method", call.method)
           put("tool", call.tool)
           put("reason", call.reason)
           // What the call was about, as the agent wrote it: an address is that dump's address, and this is
           // read by something that can resolve it.
           put("about", call.subject)
           put("heapDumpPath", call.heapDumpPath)
           put("refused", call.refusal)
+          // And why nothing could be answered at all, which is a different thing from being told no.
+          put("error", call.error)
           put("outcome", call.outcome)
           // Last, and in that order, because they are the two long ones and they read as the call: this is
           // what went out, and this is what came back. Null on both for a session recorded by a build older
-          // than they are; null on `output` alone for a call whose answer was the refusal above it.
+          // than they are; null on `output` alone for a notification nothing was sent back for.
           put("input", call.input)
           put("output", call.output)
         }