feat(sessions): return a hit's whole passage on request

[bompus]

A codegraph_sessions hit shows about 24 tokens of text. For hosts stored in SQLite (OpenCode, Devin, AGY) there is no transcript file to open for the rest, and for JSONL hosts an agent has to read a large file that also holds the tool traffic the index excludes. The index already stores the whole passage (at most 4,000 characters), so this returns it.

• full: true on the MCP tool and --full on the CLI return each hit's stored passage instead of the snippet. The default is unchanged.
• One shared budget of 16,000 bytes, spent in rank order. A hit past it keeps its snippet, and the answer says how many were cut. --json carries text per hit and fullCut.
• No schema change, no new tool, no new source. Role, session and since filters apply as before.

Measured on this project's index (35,107 passages): median passage 198 characters, 90th percentile 1,885, 99th 3,702. The top 10 hits for four real queries came to 2.7, 11.5, 11.9 (5 hits) and 3.3 KB in full.

Not in this change: stable hit references and neighboring passages (they need a stored ordinal and a migration), and redaction of secrets in expanded text. Expanded text is what an agent could already read from the transcript; the docs say so.

Tests: three new cases in sessions-index (stored passage beside an unchanged snippet and printed as a quoted block, budget spent as a ranked prefix with the cut count, role filter) and a CLI end-to-end case; the related suites pass (77 tests); tsc --noEmit clean. Run live on this project, it printed whole passages.
README rows checked: the CLI command line and the codegraph_sessions row in the tools table (both updated), plus the site CLI and MCP pages, server instructions and CHANGELOG. No number the README quotes moves.

Summary by CodeRabbit

• New Features
  • Session searches can now return complete stored passages using --full in the CLI or full: true in the MCP tool. Full passages share a 16,000-byte limit; remaining results keep their snippets, with the response indicating how many were limited.
• Documentation
  • Updated CLI and MCP reference documentation to describe the full-passage option.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository YAML (base), Organization UI (inherited)
• Review profile: CHILL
• Plan: Advanced
• Run ID: dec03018-bc6c-4710-90b4-bb6a228beb23

---

📥 Commits

Reviewing files that changed from the base of the PR and between 63ec6dc and 41fd804.

---

📒 Files selected for processing (10)

• CHANGELOG.md
• README.md
• __tests__/cli-sessions-command.test.ts
• __tests__/sessions-index.test.ts
• site/src/content/docs/reference/cli.md
• site/src/content/docs/reference/mcp-server.md
• src/bin/codegraph.ts
• src/mcp/server-instructions.ts
• src/mcp/tools.ts
• src/sessions/index.ts

---

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 4 remain after this review.

---

---

📝 Walkthrough

Walkthrough

Session search can return complete stored passages when requested through the CLI or MCP tool. The results apply a shared 16,000-byte limit in hit order and retain snippets for passages beyond that limit.

Changes

Full Passage Session Search

Layer / File(s)	Summary
Budgeted passage results src/sessions/index.ts, __tests__/sessions-index.test.ts	Session query results include full passage text when requested. A 16,000-byte aggregate limit applies in hit order; later passages retain snippets, and fullCut reports the number omitted. Formatting displays available full passages and adds a notice when passages are limited. Tests cover the limit, fallback behavior, role filtering, and formatting.
CLI and MCP request integration src/bin/codegraph.ts, src/mcp/tools.ts, src/mcp/server-instructions.ts, __tests__/cli-sessions-command.test.ts, README.md, site/src/content/docs/reference/*, CHANGELOG.md	The CLI adds --full, and the MCP tool adds the optional full input. Both pass the option to session search. The CLI test checks full output and fullCut; documentation and the changelog describe the option and byte limit.

---

Priority: ➖ Normal

Merge Risk | ⚪ Minimal · up to 41fd8

Merge Risk: ⚪ Minimal · up to 41fd8

The full-passage option appears mergeable after normal checks; no actionable issue remains identified.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 41fd8

Whole passages are returned only when explicitly requested, and existing project selection and search filters remain in effect. More historical conversation text reaches the requesting client, however, and the size limit does not redact sensitive content or make historical instructions trustworthy.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• observed — Full output reaches the requesting MCP client or CLI output stream. Scope remains the selected project's existing session index and ingestion configuration, including the pre-existing transcript-directory override. Existing MCP projectPath resolution can select other indexed projects accessible to the process; project selection is not a newly introduced tenant authorization boundary.

Security Findings and Attack Paths

• inferred — The relevant exposure path is historical session prose through full-mode retrieval into client or agent context. This increases disclosure beyond snippets, but inspected code only returns text and establishes no execution or privilege elevation. No supplied retained finding or inspected evidence confirms secret disclosure or downstream instruction exploitation.

Trust Boundaries and Controls

• observed — MCP enables full output only for the literal boolean true. Existing project resolution, sessions opt-out, and parameterized search predicates remain in the request path. Role, time, and session filters constrain selection; they do not establish caller identity or authorization.

Resilience and Maintainability Implications

• observed — The supported CLI and MCP paths share one passage-budget implementation, reducing interface-specific control drift. Its protection is per request: callers can narrow or repeat searches, so the byte cap is not an aggregate disclosure quota.

Hardening Proposals

• proposed — Document whole passages as potentially sensitive, untrusted historical data, and assess optional redaction or a full-output policy for consumers with narrower access than the local account. These are hardening proposals, not fixes for an established vulnerability.

---

Pre-merge checks | 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: session search hits can return their whole stored passage when requested.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Suppressions Explained		The pull-request diff adds no lint, type-check, compiler-suppression directive, or ignore configuration. The changed files contain feature code, tests, and documentation only, and the added-line scan …
User-Visible Changes Documented		The diff adds the CLI --full flag and the codegraph_sessions MCP full argument. It updates README.md, site/src/content/docs/reference/cli.md, and `site/src/content/docs/reference/mcp-server.…

---

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

---

---

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}