Module debug_log 

Opt-in human-readable debug log of intercepted tool activity (#520).

Off by default. Enable with the LEAN_CTX_DEBUG_LOG env var (truthy) or the debug_log = true config key. Records two kinds of events to <state_dir>/logs/debug.log:

1. MCP tool calls handled by the lean-ctx server (ctx_*) — tool name, a redacted argument summary, a one-line result preview, byte size, token savings and wall time.
2. Hook routing decisions — for every native tool call lean-ctx can intercept (shell / Read / Grep), whether it was routed to lean-ctx or left to the editor’s native tool, and why. This is #520’s core ask: explain why one call used lean-ctx and the next fell back to the native Read/Grep tool.

All writes are best-effort and never panic — logging must never break a hook subprocess or a tool call. Secrets in arguments/commands/results are scrubbed via crate::core::redaction::redact_text before they hit disk.

Enums

Route

Where a hook sent an intercepted native tool call.

Functions

clear

Delete the debug log (and its rotated backup). Returns a status line.

is_enabled

Whether the opt-in debug log is active.

log_hook_decision

Record a hook routing decision for an intercepted native tool call.

log_mcp_call

Record an MCP tool call handled by the lean-ctx server.

log_mcp_error

Record an MCP tool call that failed before producing a result.

log_path

<state_dir>/logs/debug.log. Returns None if the state dir cannot be resolved or the logs/ directory cannot be created.

read_log

Return the log content for display (most-recent tail_lines, 0 = all).