feat: report_writer — LaTeX report generation (compile_document tool + skill + sub-agent)

[shoom1]

Summary

Adds LaTeX analysis-report generation to the framework + research_demo, validating the framework's Agent-Skills support with a real package:

• compile_document (framework tool, src/agentic_cli/tools/document/) — compiles a .tex to PDF via a host TeX engine (latexmk/pdflatex) as a guarded subprocess: never passes -shell-escape, a wall-clock timeout that kills the whole process group (so a runaway pdflatex grandchild can't outlive it), a scoped build dir. Returns a structured dict and never raises. Host-based provisioning (detect-and-instruct; no bundled distro). Built behind _run/_which seams so the logic is fully unit-tested offline; a real-engine compile test is gated on a TeX install (-m latex, LATEX_REQUIRE=1 to fail-loud).
• report-writer Agent-Skill (examples/research_demo/skills/report-writer/) — knowledge-only (no runnable scripts): a SKILL.md with the report structure, compile steps, and error-recovery loop, plus a base-package LaTeX template.
• report_writer sub-agent — wired into the research_demo coordinator. Holds [write_file, read_file, glob, compile_document, ask_clarification] — not sandbox_execute (capability separation: it can compile documents, not run arbitrary code). Its prompt is a settings-reading callable, so artifacts/build paths follow the configured workspace.

Design notes

• Compilation is decoupled from the container sandbox. data_analyst's figures reach report_writer via the host artifacts dir (existing sandbox copy-out); there is no LaTeX in any Docker image. The compiler is host latexmk/pdflatex, not tectonic — the docker sandbox is hard network-isolated, which tectonic's on-demand package fetch can't tolerate.
• Skill id is kebab report-writer (ADK 1.36 rejects underscore skill names by default); the agent stays report_writer (snake, like data_analyst).
• Purely additive / backward-compatible: one new tool module + one export, one demo sub-agent, one guarded settings default.

Testing

• 1867 offline passed, 1 skipped (the gated real-LaTeX test — no engine in CI/this env). New coverage: 10 compile_document unit tests (never-raise on run/copy/timeout, forced-engine validation, and a process-group group-kill mechanism test), 3 skill-resolution tests, 3 sub-agent wiring tests (including asserting sandbox_execute is absent).
• Task 5 (live end-to-end) is manual validation — run the demo, request a report, confirm a report.pdf in the artifacts dir with no .aux/.log litter. An automated -m llm+latex version is documented for a follow-on.

Review

Executed via subagent-driven development: each task was TDD-implemented → spec + code-quality reviewed → fixed. The whole-branch review (on opus) returned "With fixes"; both Important findings were applied — the process-group timeout kill, and honestly scoping the "shell-escape disabled" claim to the pdflatex path (documenting that latexmk reads .latexmkrc, i.e. arbitrary Perl, from the build dir/home).

Documented deferrals

• OS-sandbox filesystem confinement for compilation / the latexmk .latexmkrc code-exec vector (hardening for untrusted .tex).
• Typst engine variant; real citations (biblatex/biber).
• Minor test cosmetics (ruff E702 semicolons; genericized test names).

https://claude.ai/code/session_01SwkKXQpy3JLEqrPkQA8QRv