Add verbose flow logging for agent tool calls and results

[alexkroman]

Summary

Adds structured logging of the agent's tool-call loop when running in verbose mode (-v), making it possible to debug stalled spoken turns by seeing which tools the agent reached for and what they returned.

Changes

• brain.py:

  • Added _run_graph() to conditionally stream the graph's state snapshots in verbose mode instead of invoking it once, enabling incremental logging
  • Added _log_flow() to extract and log tool calls, tool results, and interim assistant messages from state snapshots using the coding agent's event vocabulary
  • Added _clip() to truncate long tool outputs (capped at 500 chars) so a single large result doesn't bury the rest of the flow log
  • Integrated verbose logging into build_completer() via _run_graph() instead of direct invoke()
  • Logs are emitted at INFO level to aai_cli.agent_cascade.brain logger so plain -v surfaces them

• test_agent_cascade_brain.py:

  • Added _StreamingGraph test fixture that yields scripted state snapshots to verify streaming behavior
  • Added test_run_graph_streams_and_logs_flow_when_verbose() to verify the loop streams with stream_mode="values" and logs tool calls with args, tool results (clipped), and interim assistant lines
  • Added test_run_graph_invokes_when_not_verbose() to verify non-verbose mode uses plain invoke()
  • Added test_run_graph_invokes_when_graph_cannot_stream() to verify fallback to invoke() when graph lacks stream() method
  • Added test_log_flow_ignores_non_list_messages() for defensive handling
  • Added test_clip_passes_short_text_and_truncates_long_text() to verify truncation behavior
  • Moved ToolMessage import to module level (used in existing test)

Implementation Details

• Streaming only activates when debuglog.active() returns True (verbose mode) AND the graph has a stream() method, ensuring backward compatibility with test fakes and non-streaming graphs
• _log_flow() reuses the coding agent's message_events() vocabulary (AssistantText, ToolCall, ToolResult) so the flow log speaks the same language as the TUI
• The high-water mark pattern (seen counter) ensures each snapshot only logs newly-added messages, avoiding duplicates across growing state snapshots
• Result truncation preserves the original length in the log message so users can see when output was clipped

https://claude.ai/code/session_01T3YQmYYiZDEZkDvWqXYk6D

[aikido-pr-checks]

tool result content is logged verbatim (event.content via _clip). Sanitize, escape, or redact sensitive fields before logging.

Details

✨ AI Reasoning
​The change logs tool results at INFO level: _FLOW_LOG.info("tool result %s -> %s", event.name, _clip(event.content)). Even though _clip truncates length, it does not sanitize or escape CR/LF, templates, or sensitive content. Logging raw external content risks personal-data leakage and log injection.

🔧 How do I fix it?
Keep sensitive data such as emails, passwords, and tokens out of logs. When logging values tied to a user, prefer a safe identifier like a user ID over the raw input, and strip line breaks from any user-provided text you do log.

_{Reply @AikidoSec feedback: [FEEDBACK] to get better review comments in the future.
Reply @AikidoSec ignore: [REASON] to ignore this issue.
More info}

[alexkroman]

Addressed the actionable part in eb60cff: _clip now collapses all whitespace (CR/LF included) to single spaces before truncating, so untrusted tool output can't forge extra [aai_cli.…] log lines.

On the redaction part: this is opt-in -v debug output to the user's own stderr on a single-user local CLI, deliberately showing the tool content the user asked to see — and registered secrets (API key / session JWT) are already masked across every record by the debuglog redacting formatter. So beyond the newline-injection fix, redacting the content further would defeat the feature without closing a real leak.

---

Generated by Claude Code