feat(server): add read-only inspect_session tool for session state introspection (#193)

[m2ux]

Summary

Adds a read-only inspect_session MCP tool that lets close-out activities read session state through a first-class, schema-versioned projection, eliminating the ad-hoc python3 -c reads of session.json (observed 8 times in a single meta + client run) that each triggered a non-suppressible permission prompt.

🐛 Issue 📐 Engineering 🧪 Test Plan

---

Motivation

Close-out activities need to read a session's own state back out of session.json — the variable bag, checkpoint responses, completed/skipped activity lists, the history event stream, and embedded child sessions under triggeredWorkflows[].state. The server offered no first-class way to obtain that state, so workers fell back to inline python3 -c reads. Each inline call is a unique command string that triggers a non-suppressible permission prompt for the supervising user; the location-scoped allow-hook refuses -c inline code by design, so the form can never be allow-listed; and the projection logic was regenerated per call, where a wrong-key probe silently reports nothing — a correctness risk for close-out summaries.

---

Changes

• Session inspection tool - Added the read-only inspect_session tool. It accepts four parameters — session_index (required), view (defaults to the summary view), optional child_index, and optional variable — and returns a compact structured projection built from the shared session read path, never the raw session.json. Seven views are supported: summary, identity, variables, checkpoints, activities, history, and children. child_index performs a one-level positional descent into an embedded child session; variable narrows the variables view to a single entry. The tool is strictly read-only — it never advances or saves the session and stays usable while a checkpoint is active — and is excluded from execution-flow tracing.
• Projection parity - The view projections were ported to typed pure functions matching the normative reference contract, so tool output is identical to the reference projection for the same session.
• Tests - Added 9 cases covering each view, variable narrowing, child_index descent (including the not-found path), read-only invariance, behaviour while a checkpoint is active, and byte-parity against the reference implementation. The full suite (557 tests) passes.
• Documentation - Updated the README tool count and tool table, added the inspect_session entry to the API reference, and registered the tool in the generated site data (tool groups and guide) so the documentation-site drift guard stays green.

Companion workflows-content change: requirement (b) of #193 — advisory inspect_session notes on the four close-out techniques (verify-outcomes, generate-summary, retrospective, select-next) — is delivered on the separate branch workflow/193-inspect-session-notes, which targets the workflows orphan branch, not main. It is part of #193 but lands via the workflows-content branch and is intentionally not merged into this PR.

---

🤖 AI Assistance

• Assistant / Model: claude / claude-opus-4-8
• Context scope: repo-only
• Prompt classes: code-generation, test-writing, docs
• Provenance log: provenance-log.md

Commits are DCO signed-off (git commit -s) per repo convention; the DCO attestation is recorded in the provenance log.

---

📌 Submission Checklist

• Changes are backward-compatible (or flagged if breaking)
• Pull request description explains why the change is needed
• Self-reviewed the diff
• I have included a change file, or skipped for this reason: additive MCP tool, no changelog convention in this repo
• If the changes introduce a new feature, I have bumped the node minor version
• Update documentation (if relevant)
• No new todos introduced

---

🔱 Fork Strategy

• Node Runtime Update
• Node Client Update
• Other
• N/A

---

🗹 TODO before merging

• Ready for review