client-workflow.md

Client Workflow

This document describes how an MCP client or agent should consume CodeInsight for a multi-step code-reading task.

Standard Flow

1. Call agent_first_read with root, task, and token_budget for the default first read.
2. Read context_pack.files[] by following reading_plan[] order in the returned route payload. Use agent_first_read.current_reading_step as the first checklist row. Treat reading_plan[].focus as the compact scan label, reading_plan[].question as the local checklist for the selected file, reading_plan[].reason as the instruction for the current step, reading_plan[].selection_rank as the candidate rank audit trail, and reading_plan[].selection_reason as the compact evidence for why that file was selected.
3. Use context_pack.read_less as reporting evidence for the source-line baseline, selected-line count, avoided-line count, reduction, and ratio.
4. Execute reading_plan[].suggested_tool when a selected file needs deeper local navigation.
5. Use continuation_summary and omitted_candidates[] when more context is needed after the first selected pack.
6. Run the deferred impact_analysis before edits or refactors, then rerun it when the target changes.

When a client needs custom routing or partial refresh control, it can call the lower-level tools directly: index_project, project_overview, context_pack, then impact_analysis.

Client invariants:

• Never run a reading_plan[].suggested_tool before reading the matching selected context file.
• Never run continuation_summary.suggested_tool before the selected context has been consumed.
• Always treat impact_analysis as the pre-edit planning gate, then verify changes with normal local checks.
• Never use context_pack.read_less as permission to skip selected files; it is display and reporting evidence.
• Use raw broad file search only after CodeInsight has pointed to a file, the selected context is insufficient, or the user named a specific location.

First Agent Route Call

For the first broad task after MCP setup, call agent_first_read with the repository root, the user's task, and a bounded token budget:

{
  "name": "agent_first_read",
  "arguments": {
    "root": "/absolute/path/to/repo",
    "task": "understand the main application entrypoint",
    "token_budget": 6000
  }
}

Then apply the returned payload in this order:

1. Read context_pack.files[] using context_pack.reading_plan[].
2. Use context_pack.reading_plan[].question as the local checklist for the selected file.
3. Use agent_first_read.execution_plan[] as the client checklist.
4. Run the current step's suggested_tool only after selected context is read.
5. Display context_pack.read_less when users need first-read source-line reduction evidence.
6. Run the deferred impact_analysis suggested by the final execution step before edits.

The first call is healthy when the response has either selected context or an explicit blocked state.

For repositories where CodeInsight can infer a source seed, expect:

• response_mode set to compact
• response_budget.estimated_tokens within the requested response budget
• at least one context_pack.files[] entry
• context_pack.reading_plan[].focus for the compact scan label
• context_pack.reading_plan[].question for the local reading checklist
• context_pack.reading_plan[].reason for the current reading instruction
• context_pack.reading_plan[].selection_rank for the candidate rank
• context_pack.reading_plan[].selection_reason for selection evidence
• context_pack.read_less for first-read source-line reduction evidence
• context_pack.continuation_summary.next_action for the post-read continuation decision
• routing_decision.route_quality.decision_summary for a one-line route explanation that can be shown directly in an agent UI
• routing_decision.route_quality.confidence_factors[], warnings[], and verification_steps[] for why the first file was selected, what still needs review, and what the agent should verify before editing
• execution_plan[0].action set to read_selected_context
• execution_plan[0].instruction naming the first reading file, candidate rank, and first reading focus/question
• a ready execution_plan[].suggested_tool for focused follow-up navigation
• impact_status set to deferred_by_request when an impact seed is available

For empty repositories or repositories where no source seed can be inferred, agent_first_read should still return a structured response instead of a JSON-RPC tool failure. In that case, expect:

• route[] with the context_pack step status set to blocked_no_seed
• context_pack.seed_strategy set to auto_no_seed
• no context_pack.files[] entries and no current_reading_step
• context_pack.continuation_summary.status set to blocked_no_seed
• context_pack.continuation_summary.next_action set to provide_seed_file_or_symbol
• execution_plan[] preserving the normal action order with blocked or manual statuses
• impact_status set to skipped_no_seed

For explicit seeds that cannot be used, keep the same structured shape:

• blocked_invalid_seed: the seed file could not be resolved under the project root; ask for an existing seed file or symbol.
• blocked_no_context: the explicit seed resolved as input but produced no readable context; ask for a matching seed file or symbol.

Agent Policy Prompt

Use this policy in MCP client instructions or agent system prompts when CodeInsight is available. For copy-paste task variants, see Agent prompt templates.

When working in a repository with CodeInsight MCP available:

1. Before broad code reading, call agent_first_read with root, task, and
   token_budget for the default first read.
2. Read context_pack.files in reading_plan order. Treat reading_plan.focus as
   the compact scan label, reading_plan.reason as the current-step instruction,
   reading_plan.question as the local reading checklist,
   reading_plan.selection_rank as the candidate rank audit trail, and
   reading_plan.selection_reason as the selection evidence.
3. Use routing_decision.route_quality.decision_summary, confidence_factors,
   warnings, and verification_steps to explain why the route was chosen and
   what still needs review before editing.
4. Use context_pack.read_less as reporting evidence for first-read source-line
   reduction; do not use it as a substitute for selected context.
5. Prefer reading_plan[].suggested_tool for deeper evidence on the current
   file. Prefer continuation_summary.suggested_tool only after the selected
   context has been consumed.
6. If continuation_summary.status is complete, do not fetch more context unless
   the user asks a narrower follow-up or the selected context does not answer
   the task.
7. Before editing, run the deferred impact_analysis. If the edit target differs
   from the first-read seed, call impact_analysis with the
   selected files or symbols and run or report the suggested_checks that apply.
8. Use index_project, project_overview, context_pack, and impact_analysis
   directly only when custom routing or partial refresh control is needed.
9. Treat CodeInsight call graphs and references as best-effort navigation
   evidence, not compiler-grade proof.

The intent is to reduce blind rg / cat exploration. Agents should still use normal file reads when CodeInsight points to a file or when the user requests a specific source location.

Task Routing Matrix

User intent	First CodeInsight call after indexing	Follow-up rule
"Understand this repo"	agent_first_read	Read reading_plan[]; continue only if continuation_summary suggests it.
"Where is the entrypoint?"	project_overview	Inspect entrypoints[]; call context_pack for the highest-confidence source entrypoint when needed.
"Explain this module/file"	context_pack with files[] set to the named file	Use file_outline from reading_plan[].suggested_tool for local structure.
"Explain this class/function"	symbol_search, then context_pack with the symbol	Use callers or callees only when the task asks about flow or dependencies.
"What happens if I change this?"	impact_analysis with the file or symbol	Review risk_level, impact_counts, impacted_files, paths, and suggested_checks.
"Find references"	find_references	Use context_pack with selected files if references need surrounding context.
"Trace calls"	callers or callees	Use impact_analysis when the trace should become edit-planning evidence.
"Need more context"	continuation_summary.suggested_tool when present	Prefer omitted-candidate follow-ups after selected context, not before.

Project Overview

agent_first_read returns the default bounded first-read bundle: context_pack, routing_decision, current_reading_step, and the execution plan. It uses compact structured content and defers impact analysis until the agent is ready to edit. Use advanced agent_route when a client needs the full overview, backend evidence, or a synchronous impact preview.

Use agent_first_read.execution_plan[] as the machine-readable client sequence:

1. read_selected_context: read context_pack.files[] in reading_plan[] order.
2. use_current_reading_step_suggested_tool: call the current reading step's suggested_tool only when deeper evidence is needed for that file.
3. use_continuation_if_needed: inspect continuation_summary after selected context is consumed.
4. review_impact_before_edits: run the suggested impact_analysis before editing, then run or report the returned suggested_checks[].

route[] describes the tools CodeInsight already ran. execution_plan[] describes what the client or agent should do next. routing_decision is the compact display/audit projection: first seed, first reading file, read-less metrics, continuation state, and impact status. Use the nested context_pack and execution_plan[] objects for actual reading and tool execution.

project_overview is the lower-level repository briefing. Clients should render:

• summary
• main_directories
• entrypoints
• recommended_next_tools
• dependency_summary.type_relation_edges
• dependency_summary.top_type_relation_targets
• index_status

Use recommended_next_tools[] for the first actionable calls. Sort by priority, preserving response order for equal priority values. The default first-read recommendation is a context_pack call with a repository root, task text, and token budget.

When type-relation signals are present, surface them as navigation hints and prefer the suggested dependency_graph follow-up for inheritance, implementation, or trait-oriented questions. Clients that need only these edges can call dependency_graph with kinds: ["base_type"]. Do not treat them as a complete type graph.

First Context Pack

For first reads, call context_pack with root, task, and token_budget. Omit symbols and files unless the user already named a specific entrypoint, symbol, or file.

Clients should render these fields:

• summary
• seed_strategy
• selected_seeds
• semantic_status
• budget
• continuation_summary
• reading_plan
• files

When seed_strategy is auto_task_match, show selected_seeds[].matched_keywords before broad file reading so the user can see why CodeInsight chose that first-read seed.

Treat files[] as the selected context payload. Treat reading_plan[] as the ordered path for reading that payload. It contains no excerpts, so it is safe to show as navigation and routing metadata.

Reading Selected Context

For each reading_plan[] step:

1. Show file, selection_rank, focus, question, reason, selection_reason, and ranges[].
2. Read the matching excerpts from files[].
3. Offer suggested_tool when the user or agent needs deeper evidence.

Use reading_plan[].focus as the compact scan label for the selected file. Use reading_plan[].question as the local checklist for what the selected file must answer. Use reading_plan[].reason as the executable instruction for the agent: it combines that question, the suggested follow-up tool, and the selection rationale. Use reading_plan[].selection_rank to preserve the candidate order that produced the selected pack. Use reading_plan[].selection_reason only when you need the raw ranking reason without the action guidance.

Do not treat selection_reason as a replacement for question or reason: it explains why the file made the budgeted pack, while question says what the file must answer and reason explains what to do with that file now. Continuation actions should wait until the selected files[] excerpts have been read in this order.

Common suggested tools:

• file_outline for seed files or symbol definitions.
• impact_analysis for references and call graph expansion.
• dependency_graph for dependency-driven context.
• File-scoped context_pack for semantic or fallback continuation.

Suggested tools are MCP-ready, but clients may still adjust task text, limits, or file filters when the user asks a narrower question.

Continuing After Budget Limits

Use continuation_summary as the compact UI decision point after the selected context is read.

Important statuses:

• complete: read the selected context first; no continuation is required.
• blocked_no_seed: provide a seed file or symbol, then retry context_pack or agent_first_read.
• blocked_invalid_seed: provide an existing seed file or symbol, then retry.
• blocked_no_context: provide a matching seed file or symbol, then retry.
• omitted_candidates_available: offer the included suggested_tool as a "continue" action.
• token_budget_exhausted: ask for a larger budget or a narrower task.
• minimum_budget_applied: continue with the selected context; the server used its minimum budget.
• lower_ranked_context_omitted: narrow the task or seed if the omitted lower ranked context matters.

omitted_candidates[] lists bounded, excerpt-free follow-up candidates. Use it after reading_plan[], not before the selected context. Each entry includes range metadata and a focused context_pack call.

Before Editing

Before making code changes, call impact_analysis with the selected files or symbols. Render:

• risk_level
• impact_counts
• impacted_files
• paths
• suggested_checks

Use suggested_checks[] to decide which local commands or review steps to run. In agent_first_read, the review_impact_before_edits execution step mirrors these checks and includes an impact_analysis suggested_tool for reopening the full evidence payload. Recommendation priority does not imply safety. Risk comes from impact_analysis evidence, not from context_pack ranking.

Minimal Client Policy

A simple client can implement this policy:

1. Run agent_first_read.
2. If context_pack.continuation_summary.status is blocked_no_seed, ask for a seed file or symbol and do not broad-read the repository.
3. Present selected files[] in reading_plan[] order, using agent_first_read.current_reading_step for the first checklist row, reading_plan[].focus as the compact scan label, reading_plan[].question as the local checklist, and reading_plan[].reason as the current-step instruction.
4. Display context_pack.read_less as optional source-line reduction evidence.
5. Execute the current step's suggested_tool when the user asks for detail.
6. If the selected context is insufficient, execute continuation_summary.suggested_tool when present.
7. Run the deferred impact_analysis before edits, and rerun it for changed targets.

For field-level contracts, see First-read workflow and Recommendation contract. For copyable Codex, Claude Code, Cursor, and generic MCP examples, see Client integration examples.