Inspection as Tools, and a Plan You Can Read

#ai#kodr#local-models#agents#tools#context

kodr has a structural index and a ranked repo-map. These three phases put that inspection to work three ways: as tools for the model, as commands for me, and as a pre-computed plan that does the navigating up front.

Phase 62: inspection as two narrow tools

Tool-mode runs had list_files, read_file, and run_command - enough for simple tasks, but it forced the model to read whole files just to answer “what functions are here?” or “where is this used?”. Phase 62 adds two structural tools:

  • inspect_symbols - compact symbol records with path, name, kind, line range.
  • find_references - compact references for a named symbol.

There is deliberately no inspect_file tool, because it would overlap with read_file, and small local models get indecisive when two tools sound alike. The split stays crisp: inspect_symbols for structure, find_references for usage, read_file for source text. Both are read-only and workspace-jailed, cap their entry count, and cap serialized output around 8 KB - truncating with an explicit marker rather than flooding the next turn. The reusable lesson: tool shape is part of model behaviour. Adding a verb is cheap in code, but every overlapping verb makes a small model less decisive, so the navigation surface stays narrow on purpose.

Phase 63: the same inspection, for the human

Phase 62 gave the model bounded inspection; phase 63 gives it to me. The CLI grows file-focused inspection alongside the existing --symbol:

kodr inspect --file src/app.mjs

The TUI gets local slash commands - /inspect <file>, /inspect <symbol>, /refs <symbol> - that are explicitly not model turns. They route through a local inspect channel request, render line-oriented output, and return immediately. That preserves the channel boundary: every surface can ask the harness for deterministic facts without duplicating logic or firing an accidental prompt. The pointed product choice was to not add a /context command - exposing the heavy packed-context blob would just tempt me to inspect the same token-budget artifact the model consumes. The better human affordance is narrower: symbols, structure, references.

Phase 64: hand over the plan, not the puzzle

Inspection-aware context gave the model better chunks, but still left it to infer an edit plan from them. Phase 64 makes that first step deterministic. When inspection context is available, kodr writes an inspection-plan.json - likely target files, likely target symbols, related tests, suggested verification commands, risk notes - with no model call. It ranks symbols against the request, avoids picking tests as primary edit targets when source symbols exist, and finds nearby test files. The suggested verification commands are run through the verification allowlist before they can appear, so kodr never suggests a command its own verifier would later reject.

The rendered plan gets injected before the user’s request, giving a small model a concrete hint - “edit src/app.mjs, inspect runPrompt, run node --test test/app.test.mjs” - instead of asking it to derive the same path from the full context. This also closed a workflow gap: the cycle runner now forwards the inspection plan and prior scratchpad as a compact handoff between turns. The honest caveat is that the plan is heuristic, not a type system, so it’s framed as targeting guidance, not a hard edit boundary - the model can still wander when it needs to, kodr just makes the likely path obvious.

Links: