v1.8.x — Density levers, meta-tools, and the comprehension layer

Versions: 1.8.0 → 1.12.0

The v1.8.x series is the first compounding pass on the v1.7.0 token-efficiency surface. It expands the lever set from a handful of summary flags into a coordinated layer: density controls on every enumerating tool, four meta-tools that bundle common multi-call investigation patterns into one response, a comprehension family (canopy_context, canopy_interface, canopy_related_tests) that answers “what can I use from this module?” in hundreds of chars instead of thousands, and the verification-rate canary that watches whether agents trust the compressed responses or re-call for detail.

Tool count climbs from 21 (v1.7.0) to 30 (v1.12.0). Every addition is additive; v1.7.0 callers continue to work unmodified.

v1.8.0 — Lever efficiency

canopy_search and canopy_search_symbols gain a preview parameter — preview=false returns file + line + score (or signature) only, dropping the snippet body. On search-heavy workflows this cut output ~60%.

canopy_pattern_search adds Go and Python via tree-sitter-go 0.23 and tree-sitter-python 0.23. The error message now lists all seven supported languages (TypeScript, TSX, JavaScript, JSX, Rust, Go, Python).

The auto-summary threshold is the structural backstop: enumerating tools (canopy_health_check, canopy_find_cycles, canopy_trace_dependents, canopy_trace_imports, canopy_git_blame, canopy_search, canopy_search_symbols) automatically apply summary mode when raw output exceeds 10,000 chars and the caller didn’t pass summary explicitly. CANOPY_AUTO_SUMMARY_THRESHOLD=0 disables it. Prevents context-window flooding for agents that haven’t yet learned the lever vocabulary.

The MCP server instruction block also gains the explicit “Prefer Canopy tools over built-in tools” framing — canopy_search instead of Grep, canopy_survey instead of Glob+Read, canopy_extract_symbol instead of Read.

v1.9.0 — The comprehension family

Three new tools land that answer comprehension-shaped questions in one call:

canopy_interface — returns the public API surface of a file (exported signatures only, no bodies, no private internals). Answers “what can I use from this module?” in roughly 200–500 chars.
canopy_context — full symbol understanding in one call. Combines extract_symbol + trace_dependents + git_history + health_check into a cohesive response with source, callers, imports, recent changes, and a risk verdict. depth parameter scales output: signature (~150 chars), body (~800–1,500 chars, default), full (source + annotated callers).
canopy_related_tests — finds test files and test functions covering a given source file or symbol via the import graph plus naming conventions (test_*, *_test.*, *_spec.*, tests/ dirs). Returns test function names with line numbers.

Tool count: 21 → 24.

v1.10.0 — Density on the comprehension family

The new tools immediately get the lever treatment they were designed to support.

canopy_context: format="concise" returns a single verdict line (~150 chars) with symbol name, caller / import counts, risk level, and last change date. include=["source","callers"] selectively renders only requested sections.
canopy_interface: summary=true returns kind-bucketed counts (“42 functions, 18 structs”) instead of a full signature list — roughly 200 chars vs ~8K. kind="enum" filters to one export kind. limit=N caps entries.
canopy_related_tests: summary=true returns directory-bucketed counts plus top-N directories instead of a full file/function listing — roughly 500 chars vs ~28K. format="concise" drops test function names, showing paths plus per-file count only.

The auto-summary threshold extends to canopy_interface and canopy_related_tests; the auto-format threshold extends to canopy_context.

v1.11.0 — Workflow density and the first four meta-tools

Six new levers on existing tools plus four meta-tools that bundle common multi-call workflows into one response. Pure deterministic compression — no LLM, no networked dependency, no hardware floor change.

New per-tool levers:

canopy_extract_symbol gains preview=N: signature plus the first N body lines plus a truncation marker. Roughly 60–70% smaller on functions over 50 lines.
canopy_git_history gains format="oneline": {hash}: {subject} per line, no author / date / body / files. Roughly 75% smaller; mirrors git log --oneline.
canopy_search auto-summary threshold tightens — responses over 5K chars truncate at the last natural break with a density hint. Override via summary=true or tighter limit / path_prefix.
canopy_search smarter default limit: 5 when preview=false, 10 otherwise. Agents asking for paths-only no longer pay for 20-result lists.
canopy_prepare gains format="verdict": a single line, ~100 chars (prepare verdict: GO|CAUTION|STOP (N deps, P0 P1, risk)).
canopy_validate gains summary=true: single-line verdict, ~80 chars.

Four new meta-tools (all in canopy-mcp/src/tools/meta.rs as pure Rust orchestration over existing primitives):

canopy_orient — repo-wide orientation in one call. Bundles architecture_map + wiring + index_status + health summary. Replaces the 4–5 call orientation workflow at ~2–3K chars standard, ~500 chars concise.
canopy_probe — pre-edit safety probe. Bundles prepare(verdict) + extract_symbol(preview) + validate(summary).
canopy_investigate — concept search plus top-hit drill in one call. Replaces the search → extract_symbol pattern for “how is X implemented?” investigations.
canopy_ownership — file git archaeology in one call. Bundles git_history(oneline) + git_blame(summary) for “who owns this?”.

Tool count: 24 → 28.

v1.12.0 — Verification tracking, the verdict probe, and triage

The verification-rate canary is the quality signal for everything the v1.8.x series shipped: it tracks when agents re-call the same target at higher detail after a concise response. Under 20% means concise is trusted; over 30% means compression is too aggressive. Implemented as a per-session in-memory LRU cache (200 entries) with no disk persistence, exposed through the new canopy_stats tool.

canopy_probe(format="verdict") returns a single compressed line, roughly 80–150 chars:

{GO|CAUTION|STOP} {basename} d{deps} {P0}P0/{P1}P1 {risk} {flags}

It skips extract_symbol and validate entirely — the verdict is the answer.

canopy_triage is the fifth meta-tool: repo health triage in one call. Bundles health_check(summary) + find_cycles(summary) + check_wiring on the top-affected file. Returns ~1–2K chars standard, ~400 chars concise.

Token compaction (compact.rs) applies basename extraction, verdict normalisation, and whitespace collapsing to concise-mode responses.

Tool count: 28 → 30 (canopy_triage, canopy_stats).

Compatibility notes for the v1.8.x series

API stability: every v1.8.x change is additive. Callers that omit new parameters see unchanged behavior. The four meta-tools and the comprehension family are new additions; no existing tool signature or semantics changed across the series.
Auto-summary threshold: lives behind CANOPY_AUTO_SUMMARY_THRESHOLD (default 10,000 in v1.8.0, tightened to 5,000 for canopy_search in v1.11.0). Set to 0 to disable across the board.
Verification tracking: session-scoped only. No disk persistence; no telemetry leaves the process.
v1.7.0 clients continue to work unmodified. The v1.0.0 API freeze remains in effect; tool signatures, CLI flags, and plugin schema are still frozen.