feat: structured per-turn reply footer with platform-specific small-text styling

[Cigarrr]

Closes #773.

Note: this PR previously bundled an unrelated streaming-preview UX fix
(single-card under fully-quiet display) — that work has been split off
into #777, which can land independently. This PR is now strictly the
structured per-turn reply footer.

Summary

• Adds two optional Platform interfaces — StatusFooterSender (one-shot Send path) and StatusFooterUpdater (streaming-preview finalize path) — that take the body content and footer as separate strings, letting each platform decide how to render the footer block.
• Implements both interfaces in Feishu by emitting an extra tag: "markdown" card element with text_size: "notation" separated from the body by hr. Matches the convention used by larksuite/openclaw-lark.
• Adds a claudecode footer builder that consumes the four cache-token fields claudecode emits per turn; renders e.g. claude-opus-4-7[1m] · out 168 · in 1 cw 971 cr 40.8k · ctx 4% on line 1, ~/workspace/path on line 2. Falls back to the existing buildReplyFooter for other agents.
• Improves appendReplyFooter so multi-line footers don't break the italic span (each line individually *line*-wrapped) and inserts a markdown --- separator between body and footer for clearer visual boundaries on inline-rendering platforms.
• Adds three per-project config toggles (all default true):
  • reply_footer — master toggle for the per-turn reply footer.
  • show_context_indicator — controls the footer's first line (model · effort · token usage · ctx %). The legacy [ctx: ~N%] suffix on plain replies is removed; that information now lives in the footer's first line and is gated by this same flag.
  • show_workdir_indicator — controls the footer's second line (workspace directory).

Compatibility

• All new interfaces are optional. Platforms that don't opt in keep the existing inline behavior unchanged.
• All new methods are additive. The only signature change is streamPreview.finish (package-internal in core/).
• show_context_indicator is repurposed but its previous job (deciding whether to surface the ctx %) is now done in the new location (footer line 1). Operators who set it to false still get the same effect — a reply with no ctx % displayed.
• The default footer shape and content are preserved; when a platform implements StatusFooterSender, the same footer string is rendered with platform-specific small-text styling. Otherwise it goes through appendReplyFooter, with multi-line italic + --- improvements.

Why claudecode lives in core

Per CLAUDE.md rule 1 (no hardcoded platform/agent names in core), the claudecode-specific footer builder gates on the signal (presence of cache tokens in ContextUsage) rather than on agent.Name() == \"claudecode\". Any agent that populates CacheCreationInputTokens / CachedInputTokens in result events will get the same richer footer.

Detailed changes

• core/interfaces.go:
  • new StatusFooterSender / StatusFooterUpdater optional interfaces
  • ContextUsage gains CacheCreationInputTokens
• core/message.go: Event gains CacheCreationInputTokens / CacheReadInputTokens
• core/streaming.go:
  • streamPreview.finish accepts a statusFooter parameter; routes via StatusFooterUpdater when available, falls back to inline append otherwise
  • the "text unchanged since last UpdateMessage" short-circuit now requires no pending statusFooter as well, so a footer can never be silently dropped when the body matches
• core/engine.go:
  • track statusFooter separately from the response body
  • new sendChunksWithStatusFooter helper threads the footer through every EventResult send branch (toolCount > 0 unsent remainder, suppressDuplicate, p.Send fallback)
  • appendReplyFooter: per-line italic + --- separator
  • new buildClaudeStatusLineFooter + formatStatusTokenCount; takes precedence when cache tokens are present, gated by replyFooterEnabled × showContextIndicator × showWorkdirIndicator
  • buildReplyFooter (legacy single-line) also wires the per-line toggles for symmetry
  • removed the standalone [ctx: ~N%] suffix path (now subsumed by the footer)
• agent/claudecode/session.go:
  • capture model id from stream-json system init event
  • parse 4-field usage via shared parseClaudeUsage helper
  • read ContextWindow from the model id heuristic (opus-4-7[1m] → 1M, haiku-4-5 → 200k)
  • capture per-sub-call ContextUsage from each assistant event for input/cache fields, and only the result event's output_tokens for OutputTokens — the result aggregates cache_read_input_tokens across every sub-call (sums cache hits and clamps ctx % to 100% on long agentic turns), while per-assistant output_tokens in stream-json is a placeholder of 1 (only the result has the real total)
  • expose GetModel / GetWorkDir / GetContextUsage
• platform/feishu/feishu.go:
  • SendWithStatusFooter / UpdateMessageWithStatusFooter
  • buildCardJSONWithStatusFooter helper (markdown body + hr + markdown footer with text_size: \"notation\")
  • extracted patchCardMessage helper
• config/config.go + config.example.toml: ShowWorkdirIndicator field; comments and example updated for the three toggles
• core/management.go + cmd/cc-connect/main.go: load and reload all three toggles on startup, restart, and the management API PATCH path
• web/src/api/projects.ts + web/src/pages/Projects/ProjectDetail.tsx: show_workdir_indicator field + UI toggle

Tests

go test -count=1 -tags no_web ./... passes. New tests of note:

• core/claude_status_footer_test.go: full toggle matrix on buildClaudeStatusLineFooter (nil/no-cache/full-render/footer-disabled/hide-context/hide-workdir/hide-both); same matrix on the legacy buildReplyFooter; direct unit tests for sendChunksWithStatusFooter covering footer-sender success / inline fallback / no-footer / non-implementing platforms.
• core/streaming_test.go::TestStreamPreview_FinishAppliesFooterEvenWhenBodyUnchanged: regression for the short-circuit drop.
• agent/claudecode/session_test.go::TestHandleAssistantCapturesPerSubCallUsage: regression for the inflated cache_read aggregation; verifies input/cache come from the last assistant event, OutputTokens from the result.
• config/config_test.go::TestSaveProjectSettings_ExtraFields: round-trip for show_workdir_indicator.
• platform/feishu/card_test.go::TestBuildCardJSONWithStatusFooter + _EmptyFooterFallsThrough.

Test plan

• go build -tags no_web ./...
• go vet -tags no_web ./...
• go test -count=1 -tags no_web ./... (3 pre-existing failures in core/ are unrelated — they fail on the unmodified main branch as well on macOS due to a /var ↔ /private/var symlink in the path-resolution tests: TestProcessInteractiveEvents_AppendsReplyFooterWhenEnabled, _ReplyFooterPrefersSessionRuntimeState, TestResolveLocalDirPath_AcceptsSubdir)
• Live testing on Feishu — verified the notation-sized footer renders correctly under streaming-preview finalize and the inline fallback works for non-Feishu paths

🤖 Generated with Claude Code

[Cigarrr]

Closing to iterate — adding per-segment config controls (reply_footer toggle currently bypassed by the new CCD footer path; will re-open after that's resolved). Issue #773 stays open.

[chenhg5]

Review Summary

Comprehensive, well-architected reply footer system. Proper separation of concerns: agent provides usage data, engine composes footer, platform renders with native styling.

---

✅ Good:

• Clean interface design: StatusFooterSender / StatusFooterUpdater with inline fallback for unsupported platforms
• buildClaudeStatusLineFooter only activates when cache-token signals are present (other agents fall through to default footer)
• Per-sub-call usage tracking in claudeSession avoids the aggregated cache_read_input_tokens inflation problem — smart design, well-documented in code comments
• parseClaudeUsage helper centralizes token extraction (DRY)
• show_workdir_indicator config adds fine-grained control subordinate to reply_footer
• formatStatusTokenCount (1.0k style) is compact and readable
• appendReplyFooter now per-line italic wrapping + --- separator
• sp.finish() extended to accept statusFooter for streaming preview finalization
• Feishu card implementation uses notation text size for dim footer
• 420-line test file with thorough coverage (token formatting, model detection, effort, workdir, combined)
• Config changes wired through main.go, management API, web UI, config validation, and reload

---

🟡 Note: overlap with #765
Both PRs add claudeContextWindow / modelContextWindow and cache token handling in claudeSession. After both merge, one should be consolidated. Not a blocker — the behavior is compatible.

---

LGTM. Architecture sound, comprehensive tests, CI green. Closes #773.

[Cigarrr]

@chenhg5 @AaronZ345 — flagging a potential semantic conflict with #765 before either lands. Both PRs touch claudecode's [ctx: ~N%] indicator but compute "input" differently, and on real agentic turns the difference is large.

The disagreement

#765 in handleResult does inputTokens += cache_read_input_tokens + cache_creation_input_tokens. The PR text and review describe this as "matches how Anthropic bills context" — true for billing, but result.usage aggregates across all sub-calls in a tool-using turn, so feeding it into a context-occupancy indicator clamps ctx % at 100% on long turns.

#774 captures input/cache from each assistant event (per-sub-call) and uses the LAST one as the ctx snapshot.

Why I believe result.usage is aggregated, not last-call

From @anthropic-ai/claude-agent-sdk@0.2.119 sdk.d.ts:3071-3091:

SDKResultSuccess = {
  type: 'result';
  num_turns: number;
  total_cost_usd: number;             // unambiguously a sum
  usage: NonNullableUsage;            // sibling of total_cost_usd
  modelUsage: Record<string, ModelUsage>;
  ...
};

total_cost_usd is unambiguously aggregated, and modelUsage is structured as per-model totals. By structural symmetry usage is the per-turn aggregate, not a snapshot of the last call.

Empirical check on real transcripts

I measured this against three actual long turns from a CCD session on my machine (~/.claude/projects/<wid>/<sid>.jsonl — each assistant event has its own per-call usage):

Turn (sub-calls)	sum across sub-calls (input+cc+cr)	last sub-call only	ratio
121	14,250,540	195,005	73×
58	13,916,266	278,440	50×
48	20,532,706	451,655	45×

For any sane window (200k or 1M), the aggregated value clamps ctx % at 100% on long agentic turns. The last sub-call's value is the actual current prompt size — which is what users mentally model when looking at an indicator.

(Reproducible on any CCD transcript: each assistant event's cache_read_input_tokens grows turn-over-turn as the cached prefix accumulates; summing all of them across sub-calls gives a value that has nothing to do with current context occupancy.)

Codex precedent in this repo

agent/codex/context_usage.go:290 already faces this exact problem and chooses LastTokenUsage over TotalTokenUsage for the context indicator. Same split applies here.

Suggested resolution: both numbers are useful, just for different questions

Question	Right source	Notes
"How full is my context right now?" (UI footer ctx %)	Last assistant event's per-call usage	Snapshot — won't clamp
"How much did this turn cost in tokens / dollars?" (telemetry, /cost)	result.usage (aggregated)	Real billing total

This PR already preserves both: lastUsage (per-sub-call, drives the footer ctx %) and EventResult.CacheCreationInputTokens / CacheReadInputTokens (from result.usage, aggregated, kept around for billing/log). They live side-by-side without conflict.

Bonus: SDK already exposes contextWindow

ModelUsage.contextWindow: number (sdk.d.ts:1086) is in result.modelUsage[model]. Both PRs currently parse the window from the model-id string ([1m] substring). Reading the SDK field directly would be more robust to future model variants — but that's a follow-up cleanup, not a blocker for either PR.

---

Happy to be told I've misread the SDK types or that result.usage has different semantics. If result.usage is in fact last-call (not aggregated), then #765 is correct as-is and this whole concern goes away. The transcript measurement is reproducible on any CCD session, if anyone wants to confirm independently.

[AaronZ345]

Thanks for the careful analysis @Cigarrr — the per-sub-call snapshot vs. result-aggregate distinction is a fair point, and the codex precedent (agent/codex/context_usage.go:290 choosing LastTokenUsage over TotalTokenUsage) plus your transcript measurements are convincing. The per-model context window part of #765 is also already covered by your claudeContextWindow helper in #774, so #765 is fully subsumed.

Closing #765 in favor of #774. 🙏

[AaronZ345]

@Cigarrr Thanks for the careful breakdown — you're right.

The codex precedent (agent/codex/context_usage.go:290 choosing LastTokenUsage over TotalTokenUsage) plus your transcript measurements (45×–73× ratio on long agentic turns) make it clear that result.usage is the per-turn aggregate, not a per-call snapshot. Summing cache_read_input_tokens from there into the ctx % indicator clamps it at 100% on long turns, exactly as you measured. The per-sub-call snapshot captured in handleAssistant is the right source for "context used right now."

[Cigarrr]

Closing — superseded by #796.

#796 refactors footer rendering to flow through BuildRichCard's new statusFooter string parameter (方案 B), which composes cleanly with the rich-card path and obsoletes this PR's StatusFooterSender / StatusFooterUpdater interface design. The structured footer ends up rendered inside the cardkit-v1 rich card with proper dim/notation styling, instead of inline-appended at the bottom of the markdown body.

Issue #773 stays open as the underlying bug; #796 is the active implementation.