Forward dropped SDK events to ACP clients

[m13v]

Summary

The claude-agent-acp runtime currently drops several Claude Agent SDK messages on the floor: api_retry, tool_progress, tool_use_summary, and rate_limit_event. ACP clients can't see that the SDK is retrying a 529, that a long-running tool is making progress, that the model summarized prior tool uses, or that a Claude.ai web-session rate limit fired.

This PR forwards those four events to clients via typed _claude/-namespaced extNotification calls, so clients that care can surface them without touching the transport.

What's forwarded

All four events are forwarded via this.client.extNotification("_claude/<name>", { sessionId, ...fields }):

1. _claude/api-retry — fired when the SDK retries a transient API error (overload, rate limit response, etc.)

   • httpStatus, errorType, attempt, maxRetries, retryDelayMs

2. _claude/tool-progress — periodic heartbeat from a long-running tool

   • toolUseId, toolName, elapsedTimeSeconds

3. _claude/tool-use-summary — model-generated summary of a group of prior tool uses

   • summary, precedingToolUseIds

4. _claude/rate-limit — Claude.ai web-session rate limit state change

   • status, resetsAt, rateLimitType, utilization, overageStatus, overageDisabledReason, isUsingOverage, surpassedThreshold

Why extNotification

Per reviewer feedback, these aren't first-class ACP session updates (the spec doesn't define them), so forwarding them as sessionUpdate entries would pollute the standard update stream. extNotification with a _claude/ prefix is the documented escape hatch for vendor-specific events, keeps the core ACP surface clean, and lets clients opt in by listening on the namespaced method.

Other changes

• Fall-through bug fix: the previous switch had hook_progress, hook_response, files_persisted, task_started, task_notification, task_progress, and elicitation_complete falling through into the newly-added api_retry handler. Each now has its own explicit break.
• Dropped sessionMeta() / _meta additions from earlier revisions — no longer needed once events are forwarded directly to the client as they happen.
• Logs api_retry at error level (same as before) so the CLI still shows retries in the terminal.

Field naming

Field names match the fazm ACP client's existing shape (toolUseId, httpStatus, retryDelayMs, precedingToolUseIds, etc.) so a client already consuming these from a monkey-patched bridge can swap over without changing its handler code.

Testing

• npm run build — clean
• npm test — all existing tests pass; mock Session objects updated to drop the removed totalCostUsd / lastTerminalReason fields

[SteffenDE]

I'd recommend to send this as a custom notification instead, e.g. this.client.extNotification("_claude/api-retry", ...)

[m13v]

Good call. Revised to use extNotification("_claude/api-retry", ...) and similarly _claude/rate-limit, _claude/tool-progress, _claude/tool-use-summary for all four dropped events.

[SteffenDE]

We already include total_cost_usd in the usage_update message.

[m13v]

You're right, removed. The sessionMeta() helper and the _meta additions to return values are gone. total_cost_usd is already carried by usage_update.

[SteffenDE]

I wouldn't do this. Content for a tool call should be based on the actual tool output. If you want progress, I'd recommend to send it as extNotification("_claude/tool-progress", ...) or similar.

Now, I'm thinking that instead of adding custom mappings for many more SDK messages, what if we'd allow you to pass a custom flag includeRawSDKMessages in session/new etc. and we'd then forward all SDK messages as custom session notifications, so you'd be able to handle them however you want in your client?

Then, in the future we might have "proper" ACP messages for errors / rate-limits and you could switch to those at some point.

[m13v]

Agreed. Switched to extNotification("_claude/tool-progress", ...) — passes toolCallId, toolName, and elapsedTimeSeconds as notification params rather than injecting text into the tool output content.

[SteffenDE]

In other places, we nest _meta as _meta: { claudeCode: ... }, so I'd recommend to do the same here.

That said, I'm not aware of a terminal_reason field in the SDK.

[m13v]

Since we switched fully to extNotification, the _meta nesting question is moot for these events — the method name (_claude/rate-limit etc.) provides the namespace. The _meta: { claudeCode: ... } pattern is preserved for the existing sessionUpdate calls that already use it.

[m13v]

On the includeRawSDKMessages suggestion (and your draft in #527) — that's a cleaner long-term shape than forwarding one event at a time, and I'd happily use it if it lands. The reason I kept this PR narrow to the four specific events is that they're the ones I've hit in practice where the current behaviour is strictly lossy: the SDK has information the client needs, the runtime sees it, and then drops it. Forwarding them as typed _claude/ notifications means clients that already care about these cases can consume them without having to opt into the full raw message firehose or parse SDK internals.

If #527 moves forward, this PR's handlers should be easy to either drop or rebase on top of it (they're small and self-contained). Happy to do whatever's cleanest — delete these in favor of includeRawSDKMessages, keep them as typed convenience notifications alongside it, or close this in favor of #527 entirely. Let me know which direction you'd prefer.