pi-usereq 0.5.0 → 0.6.0

package/pi-usereq/docs/REQUIREMENTS.md

@@ -1,7 +1,7 @@
 ---
 title: "PI-useReq Requirements"
 description: Software requirements specification
-version: "0.0.35"
+version: "0.0.36"
 date: "2026-04-19"
 author: "OpenAI Codex"
 scope:
@@ -153,6 +153,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-171**: MUST render `pushover` immediately after `sound`, showing `on` or `off` from the Pushover successful-prompt enable setting.
 - **REQ-172**: MUST make the Pushover submenu expose a `global disable` toggle that suppresses all Pushover delivery without mutating the successful-prompt enable setting.
 - **REQ-159**: MUST increase `Σ` by each normally completed prompt duration and MUST NOT change `Σ` on escape-triggered cancellation.
+- **REQ-173**: MUST optimize every agent-tool response for minimum token usage by excluding caller-known, static, duplicated, and registration-described facts from runtime payloads.
 - **REQ-010**: MUST count tokens with `js-tiktoken` `cl100k_base`, count characters and lines, and make `files-tokens` emit agent-oriented JSON containing structured per-file metrics, extracted facts, and aggregate metrics.
 - **REQ-011**: MUST generate explicit-file references by analyzing supported source files and emitting agent-oriented JSON with per-file metadata, imports, symbol records, and optional residual text.
 - **REQ-012**: MUST compress supported source files by removing comments and blank lines, preserving indentation for Python, Haskell, and Elixir, and optionally preserving original line numbers.
@@ -161,40 +162,40 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-015**: MUST make CLI project-scope compression scan configured `src-dir` files and emit one compressed markdown block per supported file.
 - **REQ-016**: MUST make `find` scan configured `src-dir` files using the requested tag filter and regular expression.
 - **REQ-017**: MUST make `tokens` count only existing canonical docs `REQUIREMENTS.md`, `WORKFLOW.md`, and `REFERENCES.md`, reuse the structured `files-tokens` JSON contract, and fail when none exist.
-- **REQ-069**: MUST order `files-tokens` and `tokens` JSON sections as `request`, `summary`, `files`, and `guidance`, and order fields inside each section from canonical identifiers to source facts, metrics, and derived guidance.
+- **REQ-069**: MUST make `files-tokens` and `tokens` runtime payloads expose only `summary`, `files`, and `execution`, omitting request echoes and derived guidance from runtime responses.
 - **REQ-070**: MUST emit counts, sizes, line counts, line ranges, and derived totals as JSON numbers with explicit unit-specific field names, keeping display strings optional and never as the sole carrier of numeric facts.
 - **REQ-071**: MUST normalize `files-tokens` and `tokens` text fields by removing decorative formatting, isolating canonical paths, separating source-derived facts from guidance, and stripping non-semantic presentation artifacts.
-- **REQ-072**: MUST register `files-tokens` and `tokens` with agent-oriented descriptions covering purpose, inputs, output schema, output format, specialized behaviors, configuration options, invocation modes, and failure conditions.
+- **REQ-072**: MUST register `files-tokens` and `tokens` with agent-oriented descriptions carrying static scope, encoding, canonical-doc selection, and failure facts omitted from runtime responses.
 - **REQ-073**: MUST expose file-derived facts needed for direct access, including canonical path, language, existence, line counts, line ranges, and Doxygen-derived metadata, as dedicated JSON fields when available.
 - **REQ-074**: MUST keep monolithic text summaries optional, place them after structured fields, and omit any fact from text-only representation when the same fact can be emitted as dedicated JSON.
-- **REQ-075**: MUST make `files-tokens` and `tokens` guidance fields explicitly distinguish source observations, derived recommendations, and actionable next-step hints.
-- **REQ-076**: MUST order `files-references` and `references` JSON sections from request metadata to repository summary, file records, and optional residual text.
+- **REQ-075**: MUST surface `files-tokens` and `tokens` skip or read-error observations through per-file status fields and execution diagnostics instead of a dedicated guidance section.
+- **REQ-076**: MUST make `files-references` and `references` runtime payloads expose only `summary`, `repository`, `files`, and `execution`, omitting request echoes from runtime responses.
 - **REQ-077**: MUST expose symbol kind, path, declaration lines, counts, and line ranges as dedicated numeric or array fields, never only inside free-form strings.
 - **REQ-078**: MUST expose parsed Doxygen fields as tag-specific JSON objects or arrays, keeping monolithic `text` only for unsplittable residual content.
 - **REQ-079**: MUST normalize `files-references` and `references` text fields by removing decorative markdown artifacts and preserving only parser-relevant residual content.
-- **REQ-080**: MUST register `files-references` and `references` with agent-oriented descriptions covering purpose, inputs, configuration, output schema, specialized behaviors, and failure conditions.
-- **REQ-081**: MUST make agent-tool `files-compress` and `compress` return structured JSON sections ordered as `request`, `summary`, `repository`, `files`, and `execution`.
+- **REQ-080**: MUST register `files-references` and `references` with agent-oriented descriptions carrying static scope, configuration, and failure facts omitted from runtime responses.
+- **REQ-081**: MUST make agent-tool `files-compress` and `compress` return structured JSON sections ordered as `summary`, `repository`, `files`, and `execution`.
 - **REQ-082**: MUST expose canonical paths, absolute paths, language IDs, source line counts, source line ranges, compressed line counts, and removed line counts as dedicated typed compression fields.
 - **REQ-083**: MUST expose compressed excerpts through structured `compressed_lines` arrays and a separate `compressed_source_text` field, never only inside markdown headers, fences, or prefixed display strings.
 - **REQ-084**: MUST expose file-level and symbol-level Doxygen fields as structured tag-specific JSON objects, and emit symbol records with declaration kind, canonical path, signatures, and numeric declaration line ranges.
 - **REQ-085**: MUST keep residual monolithic text optional, place it after structured fields, and omit decorative markdown artifacts from compression JSON field values.
-- **REQ-086**: MUST register `files-compress` and `compress` with agent-oriented descriptions covering scope, parameters, line-number behavior, output schema, project-scope selection rules, output format, and failure conditions.
+- **REQ-086**: MUST register `files-compress` and `compress` with agent-oriented descriptions carrying static scope, line-number behavior, selection rules, and failure facts omitted from runtime responses.
 - **REQ-087**: MUST expose skipped inputs, unsupported extensions, compression failures, and zero-processable requests as structured statuses and stable error reasons, while keeping stderr diagnostics optional.
 - **REQ-088**: MUST mirror the structured compression payload into tool `content[0].text` and tool `details`, with execution metadata nested under the mirrored JSON object.
-- **REQ-089**: MUST make agent-tool `files-find` and `find` return structured JSON sections ordered as `request`, `summary`, `repository`, `files`, and `execution`.
+- **REQ-089**: MUST make agent-tool `files-find` and `find` return structured JSON sections ordered as `summary`, `repository`, `files`, and `execution`.
 - **REQ-090**: MUST expose find request scope facts as dedicated fields, including tag filter, regex pattern, line-number mode, requested paths, configured source directories, and supported tags by language.
 - **REQ-091**: MUST expose per-file and per-match find facts as dedicated fields, including canonical path, language, construct kind, symbol name, signature, declaration order, numeric line ranges, and stripped code lines.
 - **REQ-092**: MUST expose parsed find Doxygen fields as tag-specific JSON objects or arrays for file-level and construct-level metadata, keeping monolithic residual text only when safe splitting is impossible.
 - **REQ-093**: MUST emit find counts, file totals, match totals, line numbers, and line ranges as JSON numbers with explicit unit-specific field names, never only inside display strings.
 - **REQ-094**: MUST normalize `files-find` and `find` text fields by removing markdown headers, fences, bullets, and other presentation-only artifacts from structured JSON values.
-- **REQ-095**: MUST register `files-find` and `find` with agent-oriented descriptions covering purpose, scope, input schema, output schema, `enableLineNumbers`, regex semantics, supported tags by language, and failure conditions.
+- **REQ-095**: MUST register `files-find` and `find` with agent-oriented descriptions carrying static regex semantics, supported tags by language, and failure facts omitted from runtime responses.
 - **REQ-096**: MUST expose structured statuses for skipped files, unsupported languages, invalid tag filters, invalid regex patterns, no-match outcomes, and analysis failures, while keeping stderr diagnostics optional.
 - **REQ-097**: MUST mirror the structured find payload into tool `content[0].text` and tool `details`, with execution metadata nested under the mirrored JSON object.
 - **REQ-098**: MUST keep monolithic find `text` fields optional, place them after structured fields, and omit any fact from text-only representation when a dedicated JSON field can carry it.
-- **REQ-099**: MUST make every agent-tool response expose a JSON-first tree whose specialized fields are directly accessible, while monolithic text remains optional and subordinate to the structured payload.
-- **REQ-100**: MUST encode quantitative facts as JSON numbers in unit-specific fields, keep textual fields free of decorative formatting and textual units, and avoid duplicating facts already exposed by specialized fields.
-- **REQ-101**: MUST register every agent tool with machine-oriented metadata describing purpose, required and optional parameters, configuration and invocation variants, output schema and format, specialized behaviors, and stable error conditions.
-- **REQ-102**: MUST make every structured agent-tool execute result mirror the same JSON object into `content[0].text` and `details`, nesting execution metadata under dedicated `execution` fields.
+- **REQ-099**: MUST make every agent-tool response expose a JSON-first tree whose runtime fields are directly accessible and whose caller-known or registration-described facts are omitted.
+- **REQ-100**: MUST encode quantitative facts as JSON numbers in unit-specific fields, keep textual fields free of decorative formatting, and avoid duplicate or derivable facts in runtime payloads.
+- **REQ-101**: MUST register every agent tool with machine-oriented metadata describing purpose, parameters, static scope facts, omitted response facts, output schema, specialized behaviors, and stable error conditions.
+- **REQ-102**: MUST make every structured agent-tool execute result mirror the same JSON object into `content[0].text` and `details`, nesting only residual execution metadata under dedicated `execution` fields.
 - **REQ-018**: MUST expose the `test-static-check` driver only through standalone CLI `--test-static-check`, dispatching `dummy` or `command` checker subcommands directly.
 - **REQ-019**: MUST resolve each explicit static-check file by extension and run every configured checker for that language while capturing only failing checker output.
 - **REQ-020**: MUST parse user `--enable-static-check` specs in `LANG=Command,CMD[,PARAM...]` format and normalize supported language names plus `Command` case-insensitively.
@@ -287,13 +288,13 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-019**: MUST verify offline harness command and tool replay invoke registered handlers, preserve requested cwd semantics, and capture prompt payloads, tool results, and UI side effects.
 - **TST-020**: MUST verify SDK parity comparison reports aligned inventories as clean, reports requested mismatch categories, and `package.json` declares the `debug:ext*` harness scripts.
 - **TST-021**: MUST verify `scripts/pi-usereq-debug.sh tool` forwards `--params` unchanged and converts `--args` text into the JSON object forwarded through `--params`.
-- **TST-022**: MUST verify `files-references` and `references` JSON outputs expose repository, file, symbol, location, and Doxygen facts through dedicated structured fields.
-- **TST-023**: MUST verify harness inspection surfaces agent-oriented `files-references` and `references` tool descriptions with output schema, configuration, specialized behaviors, and failure details.
-- **TST-024**: MUST verify `files-find` and `find` JSON outputs expose request, repository, file, match, location, and Doxygen facts through dedicated structured fields.
+- **TST-022**: MUST verify `files-references` and `references` JSON outputs expose repository, file, symbol, location, and Doxygen facts through dedicated structured fields while omitting request echoes.
+- **TST-023**: MUST verify harness inspection surfaces agent-oriented `files-references` and `references` tool descriptions with output schema, static scope facts, specialized behaviors, and failure details.
+- **TST-024**: MUST verify `files-find` and `find` JSON outputs expose summary, repository, file, match, location, and Doxygen facts through dedicated structured fields while omitting request echoes.
 - **TST-025**: MUST verify harness inspection surfaces agent-oriented `files-find` and `find` tool descriptions with input schema, output schema, line-number behavior, regex semantics, supported tags by language, and failure details.
-- **TST-026**: MUST verify `files-compress` and `compress` JSON outputs expose structured request, repository, line, symbol, status, and Doxygen facts through dedicated fields.
+- **TST-026**: MUST verify `files-compress` and `compress` JSON outputs expose structured summary, repository, line, symbol, status, and Doxygen facts through dedicated fields while omitting request echoes.
 - **TST-027**: MUST verify harness inspection surfaces agent-oriented `files-compress` and `compress` tool descriptions with parameters, line-number behavior, output schema, specialization triggers, and failure conditions.
-- **TST-028**: MUST verify path, static-check, git, docs, and worktree agent-tool outputs expose structured JSON request, result, status, execution, and derived runtime path facts through dedicated fields.
+- **TST-028**: MUST verify path, static-check, git, docs, and worktree agent-tool outputs expose structured JSON result, summary, file, and execution facts while omitting request echoes and runtime-path duplication.
 - **TST-029**: MUST verify harness inspection surfaces machine-oriented descriptions for path, static-check, git, docs, and worktree tools, including parameters, output schema, specialization triggers, and failure conditions.
 - **TST-039**: MUST verify `.github/workflows/release-npm.yml` keeps the existing tag filter, gates downstream release work on `origin/master`, runs npm publication, and creates the GitHub Release from generated changelog text.
 - **TST-042**: MUST verify `package.json` keeps `name` equal to `pi-usereq` so npm publication resolves to `https://www.npmjs.com/package/pi-usereq`.

package/pi-usereq/docs/WORKFLOW.md

@@ -641,17 +641,16 @@
               - `extractPrimaryHeadingText(...)`: extract the first markdown heading when present [`src/core/token-counter.ts`]
               - `extractLeadingDoxygenFields(...)`: extract file-level Doxygen fields when present [`src/core/token-counter.ts`]
                 - `parseDoxygenComment(...)`: parse normalized Doxygen fields [`src/core/doxygen-parser.ts`]
-          - `orderPathsByMetric(...)`: derive stable counted-path orderings for guidance [`src/core/token-counter.ts`]
         - `buildTokenToolExecuteResult(...)`: wrap token payloads into tool content and structured details [`src/index.ts`]
           - `buildTokenToolExecutionStderr(...)`: serialize skipped and error observations into stderr text [`src/index.ts`]
           - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
-        - `buildReferenceToolPayload(...)`: construct agent-oriented references JSON with repository structure, symbols, and Doxygen fields [`src/core/reference-payload.ts`]
+        - `buildReferenceToolPayload(...)`: construct token-optimized references JSON with repository structure, symbols, and Doxygen fields [`src/core/reference-payload.ts`]
           - `canonicalizeReferencePath(...)`: normalize request and file paths against the project base [`src/core/reference-payload.ts`]
           - `analyzeReferenceFile(...)`: analyze one processable file into structured imports, symbols, and comments [`src/core/reference-payload.ts`]
           - `buildRepositoryTree(...)`: materialize the repository directory tree as structured JSON [`src/core/reference-payload.ts`]
         - `buildReferenceToolExecuteResult(...)`: wrap references payloads into tool content and structured details [`src/index.ts`]
           - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
-        - `buildCompressToolPayload(...)`: construct agent-oriented compression JSON with structured line facts, symbols, and Doxygen fields [`src/core/compress-payload.ts`]
+        - `buildCompressToolPayload(...)`: construct token-optimized compression JSON with structured line facts, symbols, and Doxygen fields [`src/core/compress-payload.ts`]
           - `analyzeCompressFile(...)`: compress one requested file and attach symbol metadata when available [`src/core/compress-payload.ts`]
             - `compressFileDetailed(...)`: compress one file into structured lines and rendered text [`src/core/compress.ts`]
             - `analyzeCompressedFileSymbols(...)`: extract symbol and Doxygen records for compressed files [`src/core/compress-payload.ts`]
@@ -661,7 +660,7 @@
         - `buildFindToolSchemaDescription(...)`: synthesize find parameter-schema descriptions [`src/index.ts`]
         - `buildFindToolPromptGuidelines(...)`: synthesize agent-oriented find guidance strings [`src/index.ts`]
           - `buildFindToolSupportedTagGuidelines(...)`: emit per-language supported-tag guidance lines [`src/index.ts`]
-        - `buildFindToolPayload(...)`: construct agent-oriented construct-search JSON with structured file statuses, matches, line facts, and Doxygen fields [`src/core/find-payload.ts`]
+        - `buildFindToolPayload(...)`: construct token-optimized construct-search JSON with structured file statuses, matches, line facts, and Doxygen fields [`src/core/find-payload.ts`]
           - `validateTagFilter(...)`: normalize requested construct tags [`src/core/find-payload.ts`]
           - `validateRegexPattern(...)`: compile the construct-name regex [`src/core/find-payload.ts`]
           - `analyzeFindFile(...)`: analyze one requested file into structured search status and match records [`src/core/find-payload.ts`]
@@ -672,20 +671,20 @@
           - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
         - `runGitPath(...)`: query the resolved git-path value [`src/core/tool-runner.ts`]
         - `runGetBasePath(...)`: query the resolved base-path value [`src/core/tool-runner.ts`]
-        - `buildPathQueryToolPayload(...)`: structure path-query payloads for `git-path` and `get-base-path` [`src/core/agent-tool-json.ts`]
+        - `buildPathQueryToolPayload(...)`: structure token-optimized path-query payloads for `git-path` and `get-base-path` [`src/core/agent-tool-json.ts`]
         - `runFilesStaticCheck(...)`: execute configured checkers for explicit-file requests [`src/core/tool-runner.ts`]
         - `collectProjectStaticCheckSelection(...)`: derive project static-check file selections and fixture exclusions [`src/index.ts`]
         - `runProjectStaticCheck(...)`: execute configured checkers for project source and test selections [`src/core/tool-runner.ts`]
-        - `buildStaticCheckToolPayload(...)`: structure static-check request, file-selection, and execution facts [`src/core/agent-tool-json.ts`]
+        - `buildStaticCheckToolPayload(...)`: structure token-optimized static-check summary, file-selection, and execution facts [`src/core/agent-tool-json.ts`]
         - `runGitCheck(...)`: validate runtime repository cleanliness [`src/core/tool-runner.ts`]
-        - `buildGitCheckToolPayload(...)`: structure git-validation status and execution facts [`src/core/agent-tool-json.ts`]
-        - `buildDocsCheckToolPayload(...)`: structure canonical-doc presence and remediation facts [`src/core/agent-tool-json.ts`]
+        - `buildGitCheckToolPayload(...)`: structure token-optimized git-validation status and execution facts [`src/core/agent-tool-json.ts`]
+        - `buildDocsCheckToolPayload(...)`: structure token-optimized canonical-doc presence and remediation facts [`src/core/agent-tool-json.ts`]
         - `runGitWtName(...)`: generate the standardized worktree name [`src/core/tool-runner.ts`]
-        - `buildWorktreeNameToolPayload(...)`: structure worktree-name generation facts [`src/core/agent-tool-json.ts`]
+        - `buildWorktreeNameToolPayload(...)`: structure token-optimized worktree-name generation facts [`src/core/agent-tool-json.ts`]
         - `runGitWtCreate(...)`: create a dedicated worktree and branch [`src/core/tool-runner.ts`]
         - `runGitWtDelete(...)`: delete a dedicated worktree and branch [`src/core/tool-runner.ts`]
-        - `buildWorktreeMutationToolPayload(...)`: structure worktree create/delete facts [`src/core/agent-tool-json.ts`]
-        - `buildToolExecutionSection(...)`: normalize stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
+        - `buildWorktreeMutationToolPayload(...)`: structure token-optimized worktree create-delete facts [`src/core/agent-tool-json.ts`]
+        - `buildToolExecutionSection(...)`: normalize residual stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
         - `normalizeToolFailure(...)`: convert `ReqError` failures into structured execution records [`src/core/agent-tool-json.ts`]
     - `runSdkSmoke(...)`: replay offline `session_start`, probe the official SDK runtime, and compare inventories [`scripts/lib/sdk-smoke.ts`]
       - `replaySessionStart(...)`: capture the offline `session_start` contract [`scripts/lib/extension-debug-harness.ts`]
@@ -780,16 +779,10 @@
           - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
         - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
           - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
-      - `buildSharedRuntimePathFacts(...)`: derive shared runtime path facts for path, git, docs, worktree, and static-check payloads [`src/index.ts`]
-        - `buildRuntimePathContext(...)`: derive installation, execution, base, config, docs, tests, source, and git paths [`src/core/path-context.ts`]
-          - `getInstallationPath(...)`: resolve the installed extension root from the executing module [`src/core/path-context.ts`]
-          - `getConfigPath(...)`: derive the `.pi-usereq/config.json` path [`src/core/path-context.ts`]
-        - `buildRuntimePathFacts(...)`: convert runtime paths into payload-facing path strings [`src/core/path-context.ts`]
-          - `formatRuntimePathForDisplay(...)`: serialize user-home-relative paths with environment variables [`src/core/path-context.ts`]
       - `runGitPath(...)`: query the resolved git-path value [`src/core/tool-runner.ts`]
       - `runGetBasePath(...)`: query the resolved base-path value [`src/core/tool-runner.ts`]
-      - `buildPathQueryToolPayload(...)`: structure path-query payloads for `git-path` and `get-base-path` [`src/core/agent-tool-json.ts`]
-      - `buildTokenToolPayload(...)`: construct agent-oriented token JSON with separated source facts, metrics, and guidance [`src/core/token-counter.ts`]
+      - `buildPathQueryToolPayload(...)`: structure token-optimized path-query payloads for `git-path` and `get-base-path` [`src/core/agent-tool-json.ts`]
+      - `buildTokenToolPayload(...)`: construct token-optimized token JSON with direct-access source facts and metrics [`src/core/token-counter.ts`]
         - `probeRequestedPath(...)`: classify requested paths as readable files, missing inputs, or non-file inputs [`src/core/token-counter.ts`]
         - `countFilesMetrics(...)`: read readable files and extract token, character, byte, line, heading, and optional Doxygen facts [`src/core/token-counter.ts`]
           - `buildCountFileMetricsResult(...)`: assemble direct-access per-file metrics and metadata [`src/core/token-counter.ts`]
@@ -800,17 +793,16 @@
             - `extractPrimaryHeadingText(...)`: extract the first markdown heading when present [`src/core/token-counter.ts`]
             - `extractLeadingDoxygenFields(...)`: extract file-level Doxygen fields when present [`src/core/token-counter.ts`]
               - `parseDoxygenComment(...)`: parse normalized Doxygen fields [`src/core/doxygen-parser.ts`]
-        - `orderPathsByMetric(...)`: derive stable counted-path orderings for guidance [`src/core/token-counter.ts`]
       - `buildTokenToolExecuteResult(...)`: wrap token payloads into tool content and structured details [`src/index.ts`]
         - `buildTokenToolExecutionStderr(...)`: serialize skipped and error observations into stderr text [`src/index.ts`]
         - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
-      - `buildReferenceToolPayload(...)`: construct agent-oriented references JSON with repository structure, symbols, and Doxygen fields [`src/core/reference-payload.ts`]
+      - `buildReferenceToolPayload(...)`: construct token-optimized references JSON with repository structure, symbols, and Doxygen fields [`src/core/reference-payload.ts`]
         - `canonicalizeReferencePath(...)`: normalize request and file paths against the project base [`src/core/reference-payload.ts`]
         - `analyzeReferenceFile(...)`: analyze one processable file into structured imports, symbols, and comments [`src/core/reference-payload.ts`]
         - `buildRepositoryTree(...)`: materialize the repository directory tree as structured JSON [`src/core/reference-payload.ts`]
       - `buildReferenceToolExecuteResult(...)`: wrap references payloads into tool content and structured details [`src/index.ts`]
         - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
-      - `buildCompressToolPayload(...)`: construct agent-oriented compression JSON with structured line facts, symbols, and Doxygen fields [`src/core/compress-payload.ts`]
+      - `buildCompressToolPayload(...)`: construct token-optimized compression JSON with structured line facts, symbols, and Doxygen fields [`src/core/compress-payload.ts`]
         - `analyzeCompressFile(...)`: compress one requested file and attach symbol metadata when available [`src/core/compress-payload.ts`]
           - `compressFileDetailed(...)`: compress one file into structured lines and rendered text [`src/core/compress.ts`]
           - `analyzeCompressedFileSymbols(...)`: extract symbol and Doxygen records for compressed files [`src/core/compress-payload.ts`]
@@ -820,7 +812,7 @@
       - `buildFindToolSchemaDescription(...)`: synthesize find parameter-schema descriptions [`src/index.ts`]
       - `buildFindToolPromptGuidelines(...)`: synthesize agent-oriented find guidance strings [`src/index.ts`]
         - `buildFindToolSupportedTagGuidelines(...)`: emit per-language supported-tag guidance lines [`src/index.ts`]
-      - `buildFindToolPayload(...)`: construct agent-oriented construct-search JSON with structured file statuses, matches, line facts, and Doxygen fields [`src/core/find-payload.ts`]
+      - `buildFindToolPayload(...)`: construct token-optimized construct-search JSON with structured file statuses, matches, line facts, and Doxygen fields [`src/core/find-payload.ts`]
         - `validateTagFilter(...)`: normalize requested construct tags [`src/core/find-payload.ts`]
         - `validateRegexPattern(...)`: compile the construct-name regex [`src/core/find-payload.ts`]
         - `analyzeFindFile(...)`: analyze one requested file into structured search status and match records [`src/core/find-payload.ts`]
@@ -832,16 +824,16 @@
       - `runFilesStaticCheck(...)`: execute configured checkers for explicit-file requests [`src/core/tool-runner.ts`]
       - `collectProjectStaticCheckSelection(...)`: derive project static-check file selections and fixture exclusions [`src/index.ts`]
       - `runProjectStaticCheck(...)`: execute configured checkers for project source and test selections [`src/core/tool-runner.ts`]
-      - `buildStaticCheckToolPayload(...)`: structure static-check request, file-selection, and execution facts [`src/core/agent-tool-json.ts`]
+      - `buildStaticCheckToolPayload(...)`: structure token-optimized static-check summary, file-selection, and execution facts [`src/core/agent-tool-json.ts`]
       - `runGitCheck(...)`: validate runtime repository cleanliness [`src/core/tool-runner.ts`]
-      - `buildGitCheckToolPayload(...)`: structure git-validation status and execution facts [`src/core/agent-tool-json.ts`]
-      - `buildDocsCheckToolPayload(...)`: structure canonical-doc presence and remediation facts [`src/core/agent-tool-json.ts`]
+      - `buildGitCheckToolPayload(...)`: structure token-optimized git-validation status and execution facts [`src/core/agent-tool-json.ts`]
+      - `buildDocsCheckToolPayload(...)`: structure token-optimized canonical-doc presence and remediation facts [`src/core/agent-tool-json.ts`]
       - `runGitWtName(...)`: generate the standardized worktree name [`src/core/tool-runner.ts`]
-      - `buildWorktreeNameToolPayload(...)`: structure worktree-name generation facts [`src/core/agent-tool-json.ts`]
+      - `buildWorktreeNameToolPayload(...)`: structure token-optimized worktree-name generation facts [`src/core/agent-tool-json.ts`]
       - `runGitWtCreate(...)`: create a dedicated worktree and branch [`src/core/tool-runner.ts`]
       - `runGitWtDelete(...)`: delete a dedicated worktree and branch [`src/core/tool-runner.ts`]
-      - `buildWorktreeMutationToolPayload(...)`: structure worktree create/delete facts [`src/core/agent-tool-json.ts`]
-      - `buildToolExecutionSection(...)`: normalize stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
+      - `buildWorktreeMutationToolPayload(...)`: structure token-optimized worktree create-delete facts [`src/core/agent-tool-json.ts`]
+      - `buildToolExecutionSection(...)`: normalize residual stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
       - `normalizeToolFailure(...)`: convert `ReqError` failures into structured execution records [`src/core/agent-tool-json.ts`]
     - `registerConfigCommands(...)`: register interactive configuration commands [`src/index.ts`]
       - `configurePiUsereq(...)`: interactive configuration menu root [`src/index.ts`]