pi-usereq 0.7.0 → 0.11.0

package/src/core/reference-payload.ts

@@ -97,26 +97,16 @@ export interface ReferenceSymbolEntry extends ReferenceLineRange {
 
 /**
  * @brief Describes one per-file references payload entry.
- * @details Stores canonical path identity, filesystem status, line metrics, structured imports, structured symbols, structured comment evidence, and optional file-level Doxygen metadata. The interface is compile-time only and introduces no runtime cost.
+ * @details Stores canonical identity, line metrics, structured imports, structured symbols, structured comment evidence, and optional file-level Doxygen metadata. Derivable identity and filesystem-probe fields are intentionally omitted to reduce token cost. The interface is compile-time only and introduces no runtime cost.
  */
 export interface ReferenceToolFileEntry extends ReferenceLineRange {
-  request_index: number;
-  input_path: string;
   canonical_path: string;
-  absolute_path: string;
-  file_name: string;
-  file_extension: string;
-  language_id?: string;
-  language_name?: string;
   status: ReferenceFileStatus;
-  exists: boolean;
-  is_file: boolean;
   import_count: number;
   symbol_count: number;
   comment_count: number;
   standalone_comment_count: number;
   doxygen_field_count: number;
-  file_description_text?: string;
   file_doxygen?: StructuredDoxygenFields;
   imports: ReferenceImportEntry[];
   symbols: ReferenceSymbolEntry[];
@@ -170,12 +160,10 @@ export interface ReferenceRepositoryTreeNode {
 
 /**
  * @brief Describes the repository section of the references payload.
- * @details Stores the base path, configured source-directory scope, canonical file list, and structured directory tree used during analysis. The interface is compile-time only and introduces no runtime cost.
+ * @details Stores configured source-directory scope, the canonical analyzed file list, and the structured directory tree used during analysis. Static root-path echoes are intentionally omitted to reduce token cost. The interface is compile-time only and introduces no runtime cost.
  */
 export interface ReferenceToolRepositorySection {
-  root_directory_path: string;
   source_directory_paths: string[];
-  file_count: number;
   file_canonical_paths: string[];
   directory_tree: ReferenceRepositoryTreeNode;
 }
@@ -474,8 +462,6 @@ function analyzeReferenceFile(
   verbose: boolean,
 ): ReferenceToolFileEntry {
   const canonicalPath = canonicalizeReferencePath(absolutePath, baseDir);
-  const fileName = path.basename(absolutePath);
-  const fileExtension = path.extname(absolutePath).toLowerCase();
   const languageId = detectLanguage(absolutePath);
   if (!languageId) {
     if (verbose) {
@@ -483,15 +469,8 @@ function analyzeReferenceFile(
     }
     return {
       ...buildLineRange(0, 0),
-      request_index: requestIndex,
-      input_path: inputPath,
       canonical_path: canonicalPath,
-      absolute_path: absolutePath,
-      file_name: fileName,
-      file_extension: fileExtension,
       status: "skipped",
-      exists: true,
-      is_file: true,
       import_count: 0,
       symbol_count: 0,
       comment_count: 0,
@@ -507,10 +486,9 @@ function analyzeReferenceFile(
   try {
     const elements = analyzer.analyze(absolutePath, languageId);
     analyzer.enrich(elements, languageId, absolutePath);
-    const languageSpec = analyzer.specs[languageId.toLowerCase().trim().replace(/^\./, "")];
     const fileContent = fs.readFileSync(absolutePath, "utf8");
     const lineCount = fileContent === "" ? 0 : fileContent.split(/\r?\n/).length - (fileContent.endsWith("\n") ? 1 : 0);
-    const [docForDef, standaloneCommentsRaw, fileDescriptionRaw] = buildCommentMaps(elements);
+    const [docForDef, standaloneCommentsRaw] = buildCommentMaps(elements);
     const fileLevelDoxygen = collectFileLevelDoxygenFields(elements);
     const structuredFileDoxygen = structureDoxygenFields(fileLevelDoxygen);
     const imports = elements
@@ -560,8 +538,8 @@ function analyzeReferenceFile(
         visibility: element.visibility,
         parent_symbol_name: parentSymbolName,
         parent_qualified_name: parentQualifiedName,
-        child_symbol_names: [],
-        child_qualified_names: [],
+        child_symbol_names: [] as string[],
+        child_qualified_names: [] as string[],
         depth: element.depth,
         inherits_text: element.inherits,
         decorator_text: decoratorByTargetLine.get(element.lineStart),
@@ -608,23 +586,13 @@ function analyzeReferenceFile(
     }
     return {
       ...buildLineRange(lineCount > 0 ? 1 : 0, lineCount),
-      request_index: requestIndex,
-      input_path: inputPath,
       canonical_path: canonicalPath,
-      absolute_path: absolutePath,
-      file_name: fileName,
-      file_extension: fileExtension,
-      language_id: languageId,
-      language_name: languageSpec?.name,
       status: "analyzed",
-      exists: true,
-      is_file: true,
       import_count: imports.length,
       symbol_count: symbols.length,
       comment_count: commentCount,
       standalone_comment_count: standaloneComments.length,
       doxygen_field_count: doxygenFieldCount,
-      file_description_text: structuredFileDoxygen.brief?.[0] ? undefined : fileDescriptionRaw || undefined,
       file_doxygen: Object.keys(structuredFileDoxygen).length > 0 ? structuredFileDoxygen : undefined,
       imports,
       symbols,
@@ -637,16 +605,8 @@ function analyzeReferenceFile(
     }
     return {
       ...buildLineRange(0, 0),
-      request_index: requestIndex,
-      input_path: inputPath,
       canonical_path: canonicalPath,
-      absolute_path: absolutePath,
-      file_name: fileName,
-      file_extension: fileExtension,
-      language_id: languageId,
       status: "error",
-      exists: true,
-      is_file: true,
       import_count: 0,
       symbol_count: 0,
       comment_count: 0,
@@ -682,23 +642,14 @@ export function buildReferenceToolPayload(options: BuildReferenceToolPayloadOpti
   const files: ReferenceToolFileEntry[] = requestedPaths.map((requestedPath, requestIndex) => {
     const absolutePath = path.resolve(absoluteBaseDir, requestedPath);
     const canonicalPath = canonicalizeReferencePath(absolutePath, absoluteBaseDir);
-    const fileName = path.basename(absolutePath);
-    const fileExtension = path.extname(absolutePath).toLowerCase();
     if (!fs.existsSync(absolutePath)) {
       if (verbose) {
         console.error(`  SKIP  ${requestedPath} (file not found)`);
       }
       return {
         ...buildLineRange(0, 0),
-        request_index: requestIndex,
-        input_path: requestedPath,
         canonical_path: canonicalPath,
-        absolute_path: absolutePath,
-        file_name: fileName,
-        file_extension: fileExtension,
         status: "skipped",
-        exists: false,
-        is_file: false,
         import_count: 0,
         symbol_count: 0,
         comment_count: 0,
@@ -717,15 +668,8 @@ export function buildReferenceToolPayload(options: BuildReferenceToolPayloadOpti
       }
       return {
         ...buildLineRange(0, 0),
-        request_index: requestIndex,
-        input_path: requestedPath,
         canonical_path: canonicalPath,
-        absolute_path: absolutePath,
-        file_name: fileName,
-        file_extension: fileExtension,
         status: "skipped",
-        exists: true,
-        is_file: false,
         import_count: 0,
         symbol_count: 0,
         comment_count: 0,
@@ -777,9 +721,7 @@ export function buildReferenceToolPayload(options: BuildReferenceToolPayloadOpti
       symbol_kind_counts: orderedSymbolKindCounts,
     },
     repository: {
-      root_directory_path: absoluteBaseDir,
       source_directory_paths: sourceDirectoryPaths.map((sourceDirectoryPath) => canonicalizeReferencePath(sourceDirectoryPath, absoluteBaseDir)),
-      file_count: repositoryFileCanonicalPaths.length,
       file_canonical_paths: repositoryFileCanonicalPaths,
       directory_tree: buildRepositoryTree(repositoryFileCanonicalPaths),
     },

package/src/core/resources.ts

@@ -1,7 +1,7 @@
 /**
  * @file
  * @brief Resolves installation-owned bundled resource locations.
- * @details Encapsulates installation-path discovery, bundled-resource validation, prompt enumeration, and prompt loading directly from the installed extension payload. Runtime is proportional to directory-entry enumeration and prompt file size. Side effects are limited to filesystem reads.
+ * @details Encapsulates installation-path discovery, bundled-resource validation, prompt enumeration, prompt loading, and bundled instruction loading directly from the installed extension payload. Runtime is proportional to directory-entry enumeration and resource file size. Side effects are limited to filesystem reads.
  */
 
 import fs from "node:fs";
@@ -19,7 +19,7 @@ export function getBundledResourceRoot(): string {
 
 /**
  * @brief Validates that installed bundled resources are accessible.
- * @details Verifies that the installation-owned resource root plus `prompts`, `templates`, and `guidelines` directories exist before prompt or tool execution. Runtime is O(1) plus bounded filesystem metadata checks. Side effects are limited to filesystem reads.
+ * @details Verifies that the installation-owned resource root plus `prompts`, `instructions`, `templates`, and `guidelines` directories exist before prompt or tool execution. Runtime is O(1) plus bounded filesystem metadata checks. Side effects are limited to filesystem reads.
  * @return {string} Absolute bundled resource root path.
  * @throws {Error} Propagates a deterministic error when required installed resource directories are missing.
  */
@@ -28,7 +28,7 @@ export function ensureBundledResourcesAccessible(): string {
   if (!fs.existsSync(resourceRoot) || !fs.statSync(resourceRoot).isDirectory()) {
     throw new Error(`Missing bundled resources at ${resourceRoot}`);
   }
-  for (const requiredDirectoryName of ["prompts", "templates", "guidelines"]) {
+  for (const requiredDirectoryName of ["prompts", "instructions", "templates", "guidelines"]) {
     const requiredDirectoryPath = path.join(resourceRoot, requiredDirectoryName);
     if (!fs.existsSync(requiredDirectoryPath) || !fs.statSync(requiredDirectoryPath).isDirectory()) {
       throw new Error(`Missing bundled resource directory at ${requiredDirectoryPath}`);
@@ -37,6 +37,22 @@ export function ensureBundledResourcesAccessible(): string {
   return resourceRoot;
 }
 
+/**
+ * @brief Reads one bundled markdown resource by logical name and directory.
+ * @details Resolves the installed markdown file under the requested bundled resource directory, validates resource accessibility, and loads the file as UTF-8 text. Time complexity is O(n) in file size. Side effects are limited to filesystem reads.
+ * @param[in] directoryName {"prompts" | "instructions"} Installation-owned markdown resource directory.
+ * @param[in] resourceName {string} Resource identifier without the `.md` suffix.
+ * @return {string} Raw bundled markdown content.
+ * @throws {Error} Propagates `fs.readFileSync` errors when the resource file is missing or unreadable.
+ */
+function readBundledMarkdownResource(
+  directoryName: "prompts" | "instructions",
+  resourceName: string,
+): string {
+  const filePath = path.join(ensureBundledResourcesAccessible(), directoryName, `${resourceName}.md`);
+  return fs.readFileSync(filePath, "utf8");
+}
+
 /**
  * @brief Reads one bundled markdown prompt by logical prompt name.
  * @details Resolves the prompt file under the installation-owned `resources/prompts` directory, validates resource accessibility, and loads it as UTF-8 text. Time complexity is O(n) in file size. Side effects are limited to filesystem reads.
@@ -45,8 +61,48 @@ export function ensureBundledResourcesAccessible(): string {
  * @throws {Error} Propagates `fs.readFileSync` errors when the prompt file is missing or unreadable.
  */
 export function readBundledPrompt(promptName: string): string {
-  const filePath = path.join(ensureBundledResourcesAccessible(), "prompts", `${promptName}.md`);
-  return fs.readFileSync(filePath, "utf8");
+  return readBundledMarkdownResource("prompts", promptName);
+}
+
+/**
+ * @brief Extracts the YAML-front-matter `description` field from one bundled prompt.
+ * @details Parses only the leading front-matter block, resolves the first scalar `description` entry, strips one matching pair of wrapping quotes, and unescapes quoted apostrophe or quote characters used in prompt metadata. Runtime is O(n) in prompt length. Side effects are limited to filesystem reads delegated through `readBundledPrompt(...)`.
+ * @param[in] promptName {string} Prompt identifier without the `.md` suffix.
+ * @return {string} Normalized prompt description or the empty string when the front matter does not declare one.
+ */
+export function readBundledPromptDescription(promptName: string): string {
+  const promptText = readBundledPrompt(promptName);
+  const frontMatterMatch = promptText.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!frontMatterMatch) {
+    return "";
+  }
+  const descriptionLine = frontMatterMatch[1]
+    .split(/\r?\n/)
+    .find((line) => line.startsWith("description:"));
+  if (!descriptionLine) {
+    return "";
+  }
+  const rawValue = descriptionLine.slice("description:".length).trim();
+  const unquotedValue = rawValue.length >= 2
+    && ((rawValue.startsWith('"') && rawValue.endsWith('"'))
+      || (rawValue.startsWith("'") && rawValue.endsWith("'")))
+    ? rawValue.slice(1, -1)
+    : rawValue;
+  return unquotedValue
+    .replace(/\\"/g, '"')
+    .replace(/\\'/g, "'")
+    .trim();
+}
+
+/**
+ * @brief Reads one bundled markdown instruction by logical instruction name.
+ * @details Resolves the instruction file under the installation-owned `resources/instructions` directory, validates resource accessibility, and loads it as UTF-8 text. Time complexity is O(n) in file size. Side effects are limited to filesystem reads.
+ * @param[in] instructionName {string} Instruction identifier without the `.md` suffix.
+ * @return {string} Raw instruction markdown content.
+ * @throws {Error} Propagates `fs.readFileSync` errors when the instruction file is missing or unreadable.
+ */
+export function readBundledInstruction(instructionName: string): string {
+  return readBundledMarkdownResource("instructions", instructionName);
 }
 
 /**

package/src/core/runtime-project-paths.ts

@@ -1,7 +1,7 @@
 /**
  * @file
  * @brief Derives runtime-only repository facts.
- * @details Centralizes git-repository probing and repository-root resolution for extension status, tool execution, and CLI flows. Runtime is dominated by git subprocess execution plus path normalization. Side effects are limited to subprocess spawning.
+ * @details Centralizes git-repository probing, repository-root resolution, and active-branch lookup for extension status, tool execution, and CLI flows. Runtime is dominated by git subprocess execution plus path normalization. Side effects are limited to subprocess spawning.
  */
 
 import path from "node:path";
@@ -67,4 +67,24 @@ export function resolveRuntimeGitPath(executionPath: string): string | undefined
   return isSameOrAncestorPath(gitRoot, normalizedExecutionPath) ? gitRoot : undefined;
 }
 
+/**
+ * @brief Resolves the active branch name for one runtime execution path.
+ * @details Resolves the enclosing git work tree from the supplied execution path, reads `git branch --show-current`, and falls back to `unknown` when the path is outside git or HEAD has no branch name. Runtime is dominated by git execution. Side effects include subprocess creation.
+ * @param[in] executionPath {string} Runtime execution path.
+ * @return {string} Active branch name or `unknown` when unavailable.
+ * @satisfies REQ-121, REQ-283
+ */
+export function resolveRuntimeGitBranchName(executionPath: string): string {
+  const gitRoot = resolveRuntimeGitPath(executionPath);
+  if (!gitRoot) {
+    return "unknown";
+  }
+  const result = runGitCapture(["git", "branch", "--show-current"], gitRoot);
+  if (result.error || result.status !== 0) {
+    return "unknown";
+  }
+  const branchName = result.stdout.trim();
+  return branchName === "" ? "unknown" : branchName;
+}
+
 

package/src/core/settings-menu.ts

@@ -9,13 +9,15 @@ import { Container, SettingsList, Text, type Component, type SettingItem, type S
 
 /**
  * @brief Describes one selectable pi-usereq settings-menu choice.
- * @details Stores the stable action identifier, left-column label, right-column current value, optional value-tone override, and bottom-line description consumed by the shared settings-menu renderer. The interface is compile-time only and introduces no runtime cost.
+ * @details Stores the stable action identifier, left-column label, optional label and value tone overrides, optional disabled state, right-column current value, and bottom-line description consumed by the shared settings-menu renderer. The interface is compile-time only and introduces no runtime cost.
  */
 export interface PiUsereqSettingsMenuChoice {
   id: string;
   label: string;
+  labelTone?: "default" | "dim";
   value: string;
   valueTone?: "default" | "dim";
+  disabled?: boolean;
   description: string;
 }
 
@@ -160,7 +162,7 @@ function createImmediateSelectionComponent(choiceId: string, done: (value?: stri
 
 /**
  * @brief Builds `SettingsList` items from one menu-choice vector.
- * @details Copies labels, current values, value-tone overrides, and descriptions into `SettingItem` records and attaches a submenu that resolves the outer custom UI with the selected choice identifier. Runtime is O(n) in choice count. No external state is mutated.
+ * @details Copies labels, current values, label-tone overrides, value-tone overrides, disabled-state semantics, and descriptions into `SettingItem` records and attaches a submenu that resolves the outer custom UI with the selected choice identifier only for enabled rows. Runtime is O(n) in choice count. No external state is mutated.
  * @param[in] theme {PiUsereqSettingsTheme} Callback-local pi theme adapter.
  * @param[in] choices {PiUsereqSettingsMenuChoice[]} Ordered menu-choice vector.
  * @param[in] done {(value?: string) => void} Outer custom-UI completion callback.
@@ -173,18 +175,22 @@ function buildSettingItems(
 ): SettingItem[] {
   return choices.map((choice) => ({
     id: choice.id,
-    label: choice.label,
+    label: choice.labelTone === "dim"
+      ? theme.fg("dim", choice.label)
+      : choice.label,
     description: choice.description,
     currentValue: choice.valueTone === "dim"
       ? theme.fg("dim", choice.value)
       : choice.value,
-    submenu: () => createImmediateSelectionComponent(choice.id, done),
+    submenu: choice.disabled
+      ? undefined
+      : () => createImmediateSelectionComponent(choice.id, done),
   }));
 }
 
 /**
  * @brief Renders one shared pi-usereq settings menu and resolves the selected action.
- * @details Uses `ctx.ui.custom(...)` plus `SettingsList` so every configuration menu shares pi.dev styling, right-aligned current values, circular scrolling, and bottom-line descriptions. The returned custom component also exposes an offline bridge for deterministic tests and debug harnesses. Runtime is O(n) in visible choice count plus user interaction cost. Side effects are limited to transient custom-UI rendering.
+ * @details Uses `ctx.ui.custom(...)` plus `SettingsList` so every configuration menu shares pi.dev styling, right-aligned current values, circular scrolling, bottom-line descriptions, and optional disabled rows. The returned custom component also exposes an offline bridge for deterministic tests and debug harnesses. Runtime is O(n) in visible choice count plus user interaction cost. Side effects are limited to transient custom-UI rendering.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in] title {string} Menu title displayed in the heading and offline bridge.
  * @param[in] choices {PiUsereqSettingsMenuChoice[]} Ordered menu-choice vector.
@@ -242,7 +248,7 @@ export async function showPiUsereqSettingsMenu(
           const choice = choices.find(
             (candidate) => candidate.label === label || candidate.id === label,
           );
-          if (!choice) {
+          if (!choice || choice.disabled) {
             return false;
           }
           done(choice.id);

package/src/core/source-analyzer.ts

@@ -702,7 +702,7 @@ export class SourceAnalyzer {
 
   /**
    * @brief Derives single-line signatures for non-comment elements.
-   * @details Uses the first extracted line, trims structural suffixes such as trailing `{`, `:`, or `;`, and stores the result as `element.signature`. Runtime is O(n). Side effect: mutates `element.signature`.
+   * @details Uses the first extracted line, preserves leading tabs when present, trims structural suffixes such as trailing `{`, `:`, or `;`, and stores the result as `element.signature`. Runtime is O(n). Side effect: mutates `element.signature`.
    * @param[in,out] elements {SourceElement[]} Elements to enrich.
    * @return {void} No return value.
    */
@@ -710,7 +710,7 @@ export class SourceAnalyzer {
     const skipTypes = new Set([ElementType.COMMENT_SINGLE, ElementType.COMMENT_MULTI, ElementType.IMPORT, ElementType.DECORATOR]);
     for (const element of elements) {
       if (skipTypes.has(element.elementType)) continue;
-      let signature = (element.extract.split("\n")[0] ?? "").trim();
+      let signature = normalizeSourceLineForExtraction(element.extract.split("\n")[0] ?? "");
       for (const suffix of [" {", "{", ":", ";"]) {
         if (signature.endsWith(suffix) && !signature.endsWith("::")) {
           signature = signature.slice(0, -suffix.length).trimEnd();
@@ -1455,9 +1455,29 @@ export function collectFileLevelDoxygenFields(elements: SourceElement[]): Record
   return {};
 }
 
+/**
+ * @brief Normalizes one source-derived line for markdown extraction output.
+ * @details Preserves the full leading whitespace prefix when the line indentation contains at least one tab and otherwise trims leading whitespace while always trimming trailing whitespace. Runtime is O(n) in line length. No external state is mutated.
+ * @param[in] line {string} Source-derived line candidate.
+ * @return {string} Normalized line for markdown output.
+ */
+function normalizeSourceLineForExtraction(line: string): string {
+  const content = line.trim();
+  if (!content) {
+    return "";
+  }
+
+  const leading = line.slice(0, line.length - line.trimStart().length);
+  if (leading.includes("\t")) {
+    return `${leading}${content}`;
+  }
+
+  return content;
+}
+
 /**
  * @brief Renders analyzed source elements as the repository reference-markdown format.
- * @details Builds file metadata, imports, top-level definitions, child elements, comments, and a symbol index while incorporating Doxygen fields and optional legacy annotations. Runtime is O(n log n) in element count. No side effects occur.
+ * @details Builds file metadata, imports, top-level definitions, child elements, comments, and a symbol index while incorporating Doxygen fields, optional legacy annotations, and preserved leading tabs in source-derived lines. Runtime is O(n log n) in element count. No side effects occur.
  * @param[in] elements {SourceElement[]} Enriched source elements.
  * @param[in] filePath {string} Display file path.
  * @param[in] language {string} Canonical analyzer language identifier.
@@ -1500,14 +1520,14 @@ export function formatMarkdown(
   if (imports.length > 0) {
     out.push("## Imports");
     out.push("```");
-    imports.forEach((imp) => out.push((imp.extract.split("\n")[0] ?? "").trim()));
+    imports.forEach((imp) => out.push(normalizeSourceLineForExtraction(imp.extract.split("\n")[0] ?? "")));
     out.push("```");
     out.push("");
   }
 
   const decoratorMap: Record<number, string> = {};
   elements.filter((element) => element.elementType === ElementType.DECORATOR).forEach((element) => {
-    decoratorMap[element.lineStart] = (element.extract.split("\n")[0] ?? "").trim();
+    decoratorMap[element.lineStart] = normalizeSourceLineForExtraction(element.extract.split("\n")[0] ?? "");
   });
 
   const definitions = elements.filter((element) => !skipTypes.has(element.elementType)).sort((a, b) => a.lineStart - b.lineStart);
@@ -1554,7 +1574,7 @@ export function formatMarkdown(
 
       const isInline = inlineTypes.has(element.elementType) || element.lineStart === element.lineEnd;
       if (isInline) {
-        const firstLine = (element.extract.split("\n")[0] ?? "").trim();
+        const firstLine = normalizeSourceLineForExtraction(element.extract.split("\n")[0] ?? "");
         let line = `- ${kind} \`${firstLine}\`${visibility} (L${element.lineStart})`;
         if (includeLegacyAnnotations && docText) line += ` — ${docText}`;
         out.push(line);
@@ -1563,7 +1583,7 @@ export function formatMarkdown(
       }
 
       if (element.elementType === ElementType.IMPL) {
-        signature = ((element.extract.split("\n")[0] ?? "").trim()).replace(/\s*\{$/, "");
+        signature = normalizeSourceLineForExtraction(element.extract.split("\n")[0] ?? "").replace(/\s*\{$/, "");
       }
       out.push(`### ${kind} \`${signature}\`${inherit}${visibility}${decorator} (${location})`);
       if (doxygenMarkdown.length > 0) {

package/src/core/token-counter.ts

@@ -50,30 +50,17 @@ export interface CountFileMetricsResult {
 
 /**
  * @brief Describes one file entry in the agent-oriented token payload.
- * @details Orders direct-access path identifiers before source facts and numeric metrics so agents can branch without reparsing formatted strings. Optional metadata captures markdown headings or Doxygen file fields when they can be derived from the source content. The interface is compile-time only and introduces no runtime cost.
+ * @details Stores only the canonical identity, stable status, essential numeric metrics, and optional heading or Doxygen metadata needed for downstream reasoning. Derivable identity and filesystem-probe fields are intentionally omitted to reduce token cost. The interface is compile-time only and introduces no runtime cost.
  */
 export interface TokenToolFileEntry {
-  request_index: number;
-  input_path: string;
   canonical_path: string;
-  absolute_path: string;
-  file_name: string;
-  file_extension: string;
-  language_name?: string;
   status: TokenFileStatus;
-  exists: boolean;
-  is_file: boolean;
-  start_line_number: number;
-  end_line_number: number;
   line_count: number;
   primary_heading_text?: string;
   doxygen_file_fields?: DoxygenFieldMap;
   token_count: number;
   character_count: number;
   byte_count: number;
-  token_share: number;
-  character_share: number;
-  byte_share: number;
   error_message?: string;
 }
 
@@ -95,7 +82,7 @@ export interface TokenToolRequestSection {
 
 /**
  * @brief Describes the summary section of the agent-oriented token payload.
- * @details Exposes aggregate counts, sizes, totals, and per-file averages as numeric fields with explicit units so agents can branch on totals without reparsing formatted strings. The interface is compile-time only and introduces no runtime cost.
+ * @details Exposes only aggregate counts and totals that cannot be reconstructed cheaply from caller-known inputs. Derivable per-file averages are omitted to reduce token cost. The interface is compile-time only and introduces no runtime cost.
  */
 export interface TokenToolSummarySection {
   processable_file_count: number;
@@ -106,10 +93,6 @@ export interface TokenToolSummarySection {
   total_character_count: number;
   total_byte_count: number;
   total_line_count: number;
-  average_token_count_per_counted_file: number;
-  average_character_count_per_counted_file: number;
-  average_byte_count_per_counted_file: number;
-  average_line_count_per_counted_file: number;
 }
 
 /**
@@ -395,20 +378,6 @@ function extractLeadingDoxygenFields(content: string): DoxygenFieldMap | undefin
   return undefined;
 }
 
-/**
- * @brief Rounds one ratio to six decimal places.
- * @details Preserves zero exactly and otherwise limits floating-point noise so share fields remain stable across executions. Runtime is O(1). No side effects occur.
- * @param[in] numerator {number} Partial numeric value.
- * @param[in] denominator {number} Total numeric value.
- * @return {number} Rounded ratio in range `[0, 1]` when the denominator is positive; `0` otherwise.
- */
-function roundRatio(numerator: number, denominator: number): number {
-  if (denominator <= 0 || numerator <= 0) {
-    return 0;
-  }
-  return Number((numerator / denominator).toFixed(6));
-}
-
 /**
  * @brief Probes one requested path before token counting.
  * @details Resolves whether the target exists and is a regular file while capturing a stable skip reason for missing or non-file inputs. Runtime is dominated by one filesystem stat. Side effects are limited to filesystem reads.
@@ -524,7 +493,6 @@ export function buildTokenToolPayload(options: BuildTokenToolPayloadOptions): To
     const pathProbe = probeRequestedPath(absolutePath);
     return {
       requestIndex: index + 1,
-      inputPath,
       absolutePath,
       canonicalPath: canonicalizeTokenPath(absolutePath, baseDir),
       pathProbe,
@@ -538,55 +506,27 @@ export function buildTokenToolPayload(options: BuildTokenToolPayloadOptions): To
   });
   const files: TokenToolFileEntry[] = requestedEntries.map((entry) => {
     const measured = measuredByRequestIndex.get(entry.requestIndex);
-    const fileExtension = measured?.fileExtension ?? path.extname(entry.absolutePath).toLowerCase();
-    const languageName = measured?.languageName ?? inferLanguageName(entry.absolutePath);
     if (!entry.pathProbe.isFile) {
       return {
-        request_index: entry.requestIndex,
-        input_path: entry.inputPath,
         canonical_path: entry.canonicalPath,
-        absolute_path: entry.absolutePath.split(path.sep).join("/"),
-        file_name: path.basename(entry.canonicalPath),
-        file_extension: fileExtension,
-        language_name: languageName,
         status: "skipped",
-        exists: entry.pathProbe.exists,
-        is_file: false,
-        start_line_number: 0,
-        end_line_number: 0,
         line_count: 0,
         token_count: 0,
         character_count: 0,
         byte_count: 0,
-        token_share: 0,
-        character_share: 0,
-        byte_share: 0,
         error_message: entry.pathProbe.reason ?? "not a file",
       };
     }
     const status: TokenFileStatus = measured?.error ? "error" : "counted";
     return {
-      request_index: entry.requestIndex,
-      input_path: entry.inputPath,
       canonical_path: entry.canonicalPath,
-      absolute_path: entry.absolutePath.split(path.sep).join("/"),
-      file_name: path.basename(entry.canonicalPath),
-      file_extension: fileExtension,
-      language_name: languageName,
       status,
-      exists: true,
-      is_file: true,
-      start_line_number: measured?.startLineNumber ?? 0,
-      end_line_number: measured?.endLineNumber ?? 0,
       line_count: measured?.lines ?? 0,
       primary_heading_text: measured?.primaryHeadingText,
       doxygen_file_fields: measured?.doxygenFileFields,
       token_count: measured?.tokens ?? 0,
       character_count: measured?.chars ?? 0,
       byte_count: measured?.bytes ?? 0,
-      token_share: 0,
-      character_share: 0,
-      byte_share: 0,
       error_message: measured?.error,
     };
   });
@@ -602,15 +542,9 @@ export function buildTokenToolPayload(options: BuildTokenToolPayloadOptions): To
   const totalLineCount = files
     .filter((entry) => entry.status === "counted")
     .reduce((sum, entry) => sum + entry.line_count, 0);
-  const filesWithShares = files.map((entry) => ({
-    ...entry,
-    token_share: roundRatio(entry.token_count, totalTokenCount),
-    character_share: roundRatio(entry.character_count, totalCharacterCount),
-    byte_share: roundRatio(entry.byte_count, totalByteCount),
-  }));
-  const countedFileCount = filesWithShares.filter((entry) => entry.status === "counted").length;
-  const errorFileCount = filesWithShares.filter((entry) => entry.status === "error").length;
-  const skippedFileCount = filesWithShares.filter((entry) => entry.status === "skipped").length;
+  const countedFileCount = files.filter((entry) => entry.status === "counted").length;
+  const errorFileCount = files.filter((entry) => entry.status === "error").length;
+  const skippedFileCount = files.filter((entry) => entry.status === "skipped").length;
   return {
     summary: {
       processable_file_count: countedFileCount + errorFileCount,
@@ -621,12 +555,8 @@ export function buildTokenToolPayload(options: BuildTokenToolPayloadOptions): To
       total_character_count: totalCharacterCount,
       total_byte_count: totalByteCount,
       total_line_count: totalLineCount,
-      average_token_count_per_counted_file: countedFileCount === 0 ? 0 : Number((totalTokenCount / countedFileCount).toFixed(6)),
-      average_character_count_per_counted_file: countedFileCount === 0 ? 0 : Number((totalCharacterCount / countedFileCount).toFixed(6)),
-      average_byte_count_per_counted_file: countedFileCount === 0 ? 0 : Number((totalByteCount / countedFileCount).toFixed(6)),
-      average_line_count_per_counted_file: countedFileCount === 0 ? 0 : Number((totalLineCount / countedFileCount).toFixed(6)),
     },
-    files: filesWithShares,
+    files,
   };
 }