Trace unexecuted tool calls in one place; tidy span lifecycles

Paused, denied, skipped and client-run tool calls all go through
trace_unexecuted_tool_call. The research synthesis, continuation and
workflow step spans use with-blocks instead of hand-rolled GeneratorExit
handling. Fixes blank lines and adds a missing hint and docstrings.

docsgpt/agents/research_agent.py

@@ -47,12 +47,6 @@ STEP_PROMPT = _load_prompt("step.txt")
 SYNTHESIS_PROMPT = _load_prompt("synthesis.txt")
 
 
-# ---------------------------------------------------------------------------
-# CitationManager
-# ---------------------------------------------------------------------------
-
-
-
 def _phase_span(phase: str, **attributes: Any) -> Any:
     """Open a trace span for one research phase (clarify, plan, a step, synthesis)."""
     return tracing.start_span(
@@ -61,6 +55,12 @@ def _phase_span(phase: str, **attributes: Any) -> Any:
         attributes={"docsgpt.research.phase": phase.split(" ")[0], **attributes},
     )
 
+
+# ---------------------------------------------------------------------------
+# CitationManager
+# ---------------------------------------------------------------------------
+
+
 class CitationManager:
     """Tracks and deduplicates citations across research steps."""
 
@@ -266,18 +266,10 @@ class ResearchAgent(BaseAgent):
                 "tokens_used": self._tokens_used,
             },
         }
-        synthesis_span = _phase_span("synthesis")
-        try:
+        with _phase_span("synthesis"):
             yield from self._synthesis_phase(
                 query, plan, intermediate_reports, tools_dict, log_context
             )
-        except GeneratorExit:
-            synthesis_span.end(tracing.STATUS_CANCELLED)
-            raise
-        except Exception as exc:
-            synthesis_span.end(error=exc)
-            raise
-        synthesis_span.end()
 
         # Sources and tool calls
         self.retrieved_docs = self.citations.get_all_docs()