pi-advisor-flow 0.2.8 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to this project are documented here.
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.3.0
+
+### Added
+
+- Added discretionary, sequential Advisor file handoff: when globally enabled, the Executor can attach explicitly named tracked working-tree files with `includeTrackedFiles` after the Advisor says it cannot review one. Tracked and untracked attachments remain separate consent paths and share bounded, redacted disclosure limits.
+
+## 0.2.9
+
+### Fixed
+
+- Preserved custom numeric values when stepping `/advisor-settings` controls instead of resetting off-preset budgets and disclosure caps.
+- Kept recorded session blocks enforced after `/advisor-off`, restored configuration after failed activation, and charged Advisor-call budgets only when consultation execution begins.
+- Kept conversation and repository disclosure within their configured caps and explicitly identified disabled repository context as withheld.
+- Made concurrent outcome records append safely with one exclusively initialized digest salt, and stopped superseded manual consultations from entering session summaries.
+- Preserved and ignored forward-compatible `advisor.json` fields with a warning, and made malformed configuration errors actionable in every Advisor command.
+- Isolated call budgets, repeated-action counters, and safety blocks between concurrent same-process sessions.
+- Kept the repository-context withheld warning visible when its disclosure budget is zero.
+
 ## 0.2.8
 
 ### Fixed

package/README.md

@@ -8,17 +8,22 @@ A configurable second-opinion workflow for <a href="https://github.com/earendil-
 
 </div>
 
-This extension introduces a strategic "Executor/Advisor" workflow.
+`pi-advisor-flow` keeps one model focused on execution and makes a second, smarter model available for consequential decisions, stalled work, and final reviews. The Executor still owns the work. The Advisor challenges assumptions, exposes risks, and suggests verification steps without taking over or running tools.
 
-`pi-advisor-flow` keeps one model focused on execution and makes a second, smarter model available for consequential decisions, stalled work, and final reviews. The Executor still owns the work. The Advisor provides a concise review, answers questions and can provide help; it does not take over planning or run tools.
+The idea is simple: keep implementation on a fast model and borrow frontier reasoning only when decisions matter. [Read why this workflow is useful](https://philipbrembeck.com/writings/2026/07/only-as-much-intelligence-as-you-need).
 
-The concept is simple, keep implementation on a fast model, borrow frontier reasoning only when decisions actually matter. [Read more about Advisors here](https://philipbrembeck.com/writings/2026/07/only-as-much-intelligence-as-you-need).
+## Features
 
-## Install
+- **On-demand second opinions** through the `ask_advisor` tool or `/advisor-manual`.
+- **Configurable review gates** before plans, after repeated failures, and before declaring completion.
+- **Automatic loop detection** for repeated tool calls, with explicit proceed, revise, or blocked decisions.
+- **Separate model and reasoning controls** for the Executor and Advisor.
+- **Privacy controls** for conversation history, repository context, explicit tracked/untracked file handoff, tool results, secret redaction, and outcome logging.
+- **Optional persistent activation, Simple mode, session summaries, and Herdr integration.**
 
-Requires Pi 0.80.7 or later. The extension installs no dependencies of its own; Pi supplies the modules it uses at runtime.
+## Install
 
-Install into your Pi agent environment:
+Current release: **0.3.0**. Requires Pi 0.80.7 or later. The extension installs no dependencies of its own; Pi supplies its runtime modules.
 
 ```bash
 # npm
@@ -27,197 +32,65 @@ pi install npm:pi-advisor-flow
 # GitHub
 pi install git:github.com/philipbrembeck/pi-advisor.git
 
-# local checkout, useful during development
+# local checkout
 pi install /path/to/pi-advisor
 ```
 
-Restart or reload Pi after installation, then run `/advisor` in a session.
+Restart or reload Pi after installation.
 
-## Start using it
+## Quick start
 
 1. Run `/advisor` to enable the flow and register `ask_advisor`.
 2. Run `/advisor-models` to choose the Executor and Advisor models.
-3. Run `/advisor-settings` to set Simple mode, persistent activation, context, gates, privacy controls, and output limits.
-
-Enable with models in one command when preferred:
-
-```text
-/advisor executor=anthropic/claude-sonnet-5 advisor=openai/gpt-5.6-sol
-```
-
-`/advisor contextMaxChars=30000` sets the reconstructed-context limit for the current session. Use `0` for no history. The `ALL` option in settings represents the complete current branch and is still subject to the Advisor model's context limit.
-
-## Commands
-
-| Command                   | Purpose                                                                                                                                         |
-| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/advisor`                | Enable the flow, select the configured Executor, and register `ask_advisor`. Accepts `executor=`, `advisor=`, and `contextMaxChars=` overrides. |
-| `/advisor-manual [focus]` | Start a parallel Advisor consultation without interrupting the current Executor turn.                                                           |
-| `/advisor-models`         | Choose Executor and Advisor models plus their reasoning effort.                                                                                 |
-| `/advisor-settings`       | Open all Advisor settings in one keyboard-navigable screen.                                                                                     |
-| `/advisor-off`            | Disable the flow and remove `ask_advisor` from the active session.                                                                              |
-
-### `ask_advisor`
-
-The Executor calls `ask_advisor({})` for a general review of the current task and reconstructed conversation. It can pass a `question` for a targeted review, or a concise `draft` for plan and completion reviews. A draft should name proposed work, validation, and remaining risks; it is an unverified claim, not evidence.
-
-Successful calls return an opaque `adviceId`. When global outcome logging is enabled, the Executor may voluntarily call `record_advisor_outcome` once with that ID, an adoption value, and a final validation status.
-
-Use the Advisor after the Executor has investigated and formed a candidate direction. It is intended to challenge assumptions, expose risks, and confirm the next verification step—not to replace the Executor's work.
-
-Normal consultations preserve the provider's final Markdown and never block execution. When the Advisor has no material concern or recommendation, it may begin with the exact first line `Verdict: sound`; Pi renders that response with the static `◆ ADVISOR · SOUND` header, for both `ask_advisor` results and `/advisor-manual`.
+3. Run `/advisor-settings` to configure review gates, context, privacy, and limits.
 
-## Automatic loop gate
+Unknown fields in `advisor.json` are preserved for forward compatibility and reported as non-blocking warnings. Invalid recognized values remain errors, and Advisor commands show the configuration problem without crashing their handlers.
 
-The optional loop gate detects consecutive calls with the same normalized tool signature. By default, it consults the Advisor after three repeats.
-
-Unlike ordinary consultations, a loop-gate reply must start with exactly one decision header:
+You can also enable the flow and select both models at once:
 
 ```text
-Decision: proceed
-Decision: revise
-Decision: blocked
-```
-
-| Decision  | Effect                                              |
-| --------- | --------------------------------------------------- |
-| `proceed` | Reset the repeat counter and allow the tool action. |
-| `revise`  | Block the repeated tool action.                     |
-| `blocked` | Apply the configured gate-failure policy.           |
-
-Malformed, missing, duplicate, or contradictory decisions are gate failures. The same policy also applies when the Advisor is unavailable or the shared call budget is exhausted.
-
-| Failure mode              | Effect                              |
-| ------------------------- | ----------------------------------- |
-| `block-session` (default) | Block the session.                  |
-| `block-tool`              | Block only the current tool action. |
-| `warn-and-continue`       | Show a warning and continue.        |
-
-| Condition                                                | `block-session` | `block-tool`      | `warn-and-continue` |
-| -------------------------------------------------------- | --------------- | ----------------- | ------------------- |
-| Advisor unavailable or timed out                         | Block session   | Block tool action | Warn and continue   |
-| Missing, malformed, duplicate, or contradictory decision | Block session   | Block tool action | Warn and continue   |
-| Shared budget exhausted                                  | Block session   | Block tool action | Warn and continue   |
-| `Decision: blocked`                                      | Block session   | Block tool action | Warn and continue   |
-
-`advisorBlockOnBlocked` controls whether a session block immediately aborts the active run. It never turns a session block into a tool-only block.
-
-## Settings and configuration
-
-`/advisor-models` and `/advisor-settings` save to global `advisor.json` in the Pi agent directory. Repository-controlled project `advisor.json` files are not applied; models, prompts, gates, budgets, disclosure, redaction, integrations, and consent remain under the user's global configuration.
-
-All fields are optional. This example shows the available settings and their normal defaults:
-
-```json
-{
-  "executor": "openai/gpt-5.6-luna",
-  "advisor": "anthropic/claude-fable-5",
-  "executorEffort": "medium",
-  "advisorEffort": "xhigh",
-  "contextMaxChars": 25000,
-
-  "advisorPlanGate": true,
-  "advisorFailureGate": true,
-  "advisorCompletionGate": true,
-  "advisorCustomInvocation": "before changing a production deployment",
-  "advisorCollapseResponses": false,
-
-  "advisorAutoLoopGate": true,
-  "advisorLoopThreshold": 3,
-  "advisorMaxCallsPerSession": 5,
-  "advisorBlockOnBlocked": true,
-  "gateFailureMode": "block-session",
-
-  "advisorSessionSummary": false,
-  "advisorGitContext": "summary",
-  "advisorGitContextMaxChars": 20000,
-  "simpleMode": false,
-  "alwaysOn": false,
-  "advisorHerdrIntegration": true,
-  "advisorToolResultMaxLines": 2000,
-  "advisorToolResultMaxBytes": 51200,
-
-  "advisorRedactSecrets": false,
-  "advisorUntrackedContent": false,
-  "advisorOutcomeLogging": false,
-  "advisorToolPolicies": {
-    "bash": "summary",
-    "deploy": "exclude"
-  }
-}
+/advisor executor=anthropic/claude-sonnet-5 advisor=openai/gpt-5.6-sol
 ```
 
-### Simple mode and persistent activation
-
-- `simpleMode` defaults to `false`. When enabled, `ask_advisor` and `/advisor-manual` remain available for voluntary second opinions, while plan/failure/completion rules, loop gates, blocking, call budgets, and session summaries are disabled. Context limits, result caps, redaction, and tool disclosure policies still apply.
-- `alwaysOn` defaults to `false`. When enabled, Pi restores the configured Executor and activates `ask_advisor` for new, resumed, forked, and reloaded sessions. While the Advisor flow is active, an explicit `/model` selection becomes the persisted Executor for the next activation; a model restored with a session does not change the saved Executor. `/advisor-off` turns `alwaysOn` off so the flow stays disabled in later sessions.
-- In Simple mode, settings keeps the Context window/history slider alongside Simple mode and Always on; advanced values remain saved and take effect when Simple mode is disabled.
-
-### Repository context
-
-- `advisorGitContext` defaults to `summary`. It controls how much of the working tree reaches the Advisor:
-  - `off` sends no repository information.
-  - `summary` sends changed file names, change status, and line counts. It never sends file contents.
-  - `full` additionally sends the patch.
-- Changes are measured against the last commit and cover staged and unstaged work. Untracked files are always listed by name only; their contents are never sent by `gitContext: full`.
-- `advisorUntrackedContent` defaults to false. When enabled, `includeUntracked` can attach only exact named, repository-relative, untracked regular files. Files are redacted and capped before egress; sibling files remain withheld.
-- `advisorGitContextMaxChars` defaults to `20000`. Repository context may claim its own cap or half of `contextMaxChars`, whichever is smaller, so it cannot crowd out the conversation.
-- The Executor may pass `gitContext` to `ask_advisor` as `none`, `summary`, or `full`. `advisorGitContext` is the ceiling: a larger request is narrowed to the configured level and the Advisor is told that a fuller view was withheld, so it does not claim verification it could not perform.
-- `summary` deliberately excludes diff hunk headers. Git derives those from surrounding file content, so a hunk header can reproduce a line the change never touched, including a credential.
-- Redaction runs before the region is capped, and repository content is labelled as untrusted data in the request. Paths and patch text are escaped so a crafted path cannot close the region early and have the remainder read as instructions.
-- File names themselves can be sensitive. `summary` withholds file contents, not file names; use `off` when names must not leave the machine.
-- Collection shares a single overall time budget across its git commands and degrades to a stated failure rather than implying a clean tree.
-
-### Project preferences and outcomes
+## How it works
 
-In a trusted project only, `.pi/advisor-preferences.md` may provide a short local brief. It is never written by pi-advisor, is treated as lower-priority untrusted text, and is redacted/capped before egress. Symlinks, unreadable files, and paths outside the project are ignored.
+1. The Executor investigates the task and forms its own candidate direction.
+2. For a consequential decision, stalled attempt, or final review, it calls `ask_advisor` with the reconstructed conversation and allowed repository context.
+3. The Advisor returns a concise review. It may challenge assumptions, identify risks, or recommend the next verification step.
+4. The Executor decides what to adopt, performs the work, and validates the result.
 
-`advisorOutcomeLogging` defaults to false and is global-only: a project config cannot enable it. When enabled, `~/.pi/agent/advisor-outcomes.jsonl` stores bounded rotating JSONL records with only a version, timestamp, salted truncated advice digest, trigger, adoption, and validation status. It stores no prompt, advice, paths, tool output, repository data, session ID, or advice ID.
+A normal consultation never blocks execution. The optional automatic loop gate is different: it evaluates repeated tool calls and applies the configured failure policy when the Advisor says to revise, reports a block, is unavailable, or returns an invalid decision.
 
-### Context and limits
+Successful calls return an opaque `adviceId`. If global outcome logging is enabled, the Executor can call `record_advisor_outcome` once to record whether the advice was adopted and whether final validation passed.
 
-- `contextMaxChars` defaults to `15000`. It preserves complete semantic entries and adds an omission marker rather than splitting a message.
-- Set `contextMaxChars` to `0` to omit reconstructed history. `9007199254740991` is the persisted value for `ALL`.
-- Tool results default to Pi's `2000` lines and `50 KiB` limits. Oversized results preserve their beginning and end with an omission marker.
-- `advisorLoopThreshold` is an integer of at least `2`; its default is `3`.
-- Omit `advisorMaxCallsPerSession` for an unlimited shared budget. Otherwise it must be a non-negative safe integer.
-
-### Privacy controls
-
-Advisor context can contain user messages, tool calls, and tool results. Configure disclosure deliberately:
-
-- `advisorRedactSecrets` defaults to `false`. When enabled, pi-advisor locally redacts common credential patterns before including context in an Advisor request.
-- `advisorToolPolicies` matches an **exact tool name**. Each tool may use `full`, `summary`, or `exclude`.
-  - `full` includes the call arguments and capped result output.
-  - `summary` omits call arguments and result output but includes result status and size metadata.
-  - `exclude` omits both call details and output.
-- Tools not listed in `advisorToolPolicies`, including custom and newly added tools, use `full` for backward compatibility.
-
-Redaction and output limits reduce accidental disclosure; they are not a data-classification system and cannot guarantee every secret is found. Use tool policies for content that must not be sent to the Advisor.
+## Commands
 
-### Session summary and Herdr
+| Command | Purpose |
+| --- | --- |
+| `/advisor` | Enable the flow and optionally override the Executor, Advisor, or context limit. |
+| `/advisor-manual [focus]` | Start a parallel consultation without interrupting the current Executor turn. |
+| `/advisor-models` | Choose both models and their reasoning effort. |
+| `/advisor-settings` | Configure behavior, context, gates, privacy, and output limits. |
+| `/advisor-off` | Disable the flow and turn off persistent activation. |
 
-The optional Session Advisor Summary defaults to off. When enabled, it is local and in-memory only, appears after a non-blocked settled run, and is never persisted.
+The Executor calls `ask_advisor({})` for a general review. It can pass a targeted `question` or a concise `draft` describing proposed work, validation, and remaining risks. If the Advisor explicitly says it cannot review a specifically named file, the Executor may make a sequential follow-up call with `includeTrackedFiles` when global consent is enabled and the file is relevant. Draft claims give the Advisor review context; they are not verification evidence.
 
-It distinguishes regular Markdown advice from gate decisions and records the trigger, model, usage/cost when available, failures, budget, and execution effect.
+## What gets sent to the Advisor
 
-[Herdr](https://github.com/ogulcancelik/herdr) integration is enabled by default. It reports Advisor activity and a bounded, redacted blocked-state summary through Herdr's metadata paths; disable it with `advisorHerdrIntegration`. Previously reported state is still cleared when integration is disabled.
+Advisor context can include user messages, tool calls, tool results, and repository information. Secret redaction is off by default, and tools without an explicit disclosure policy default to full context. Review the privacy settings before using the extension with sensitive work.
 
-## Development
+Repository context is configurable from no access through changed-file summaries to a capped patch. When context is disabled or its budget is zero, the Advisor is told it was withheld rather than shown an apparently clean tree. Explicit tracked and untracked file contents require separate global opt-ins; attachments are capped, redacted when configured, and sent as untrusted data.
 
-```bash
-git clone git@github.com:philipbrembeck/pi-advisor.git
-cd pi-advisor
-bun install
+## Documentation
 
-bun test
-bun run typecheck
-bun run lint
-```
+- [Configuration and automatic loop gates](https://github.com/philipbrembeck/pi-advisor/blob/main/docs/configuration.md)
+- [Privacy and data handling](https://github.com/philipbrembeck/pi-advisor/blob/main/docs/privacy.md)
+- [Development](https://github.com/philipbrembeck/pi-advisor/blob/main/docs/development.md)
+- [Documentation index](https://github.com/philipbrembeck/pi-advisor/blob/main/docs/README.md)
 
 ## Links
 
-- [MIT LICENSE](LICENSE)
+- [MIT License](LICENSE)
 - [Changelog](CHANGELOG.md)
 - [npm package](https://www.npmjs.com/package/pi-advisor-flow)
 - [Why use an Advisor flow?](https://philipbrembeck.com/writings/2026/07/only-as-much-intelligence-as-you-need)

package/extensions/index.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerCommands } from "../src/commands.js";
 import { setHerdrBlockedEmitter } from "../src/herdr.js";
+import { AdvisorSessionState } from "../src/session-state.js";
 import {
   consultAdvisor as consultAdvisorImplementation,
   parseAutomaticDecision as parseAutomaticDecisionImplementation,
@@ -29,9 +30,10 @@ export const runAdvisorGate = (
 ) => runAdvisorGateImplementation(...args);
 
 export default function (pi: ExtensionAPI) {
+  const sessionState = new AdvisorSessionState();
   setHerdrBlockedEmitter((active, label) =>
     pi.events.emit("herdr:blocked", { active, label })
   );
-  registerAdvisorTool(pi);
-  registerCommands(pi);
+  registerAdvisorTool(pi, sessionState);
+  registerCommands(pi, { sessionState });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-advisor-flow",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "author": "Philip Brembeck",
   "repository": {
     "type": "git",
@@ -62,7 +62,8 @@
     "*.{json,jsonc,ts}": "bun run lint:fix --"
   },
   "overrides": {
-    "brace-expansion": "5.0.8"
+    "brace-expansion": "5.0.9",
+    "undici": "8.9.0"
   },
   "pi": {
     "extensions": [

package/src/commands.ts

@@ -9,6 +9,7 @@ import {
   advisorMaxCallsPerSessionRef,
   advisorRef,
   alwaysOnRef,
+  contextMaxCharsRef,
   executorEffortRef,
   executorRef,
   getAdvisorSettings,
@@ -38,6 +39,7 @@ import {
   setAdvisorToolPoliciesRef,
   setAdvisorToolResultMaxBytesRef,
   setAdvisorToolResultMaxLinesRef,
+  setAdvisorTrackedFileContentRef,
   setAdvisorUntrackedContentRef,
   setAlwaysOnRef,
   setContextMaxCharsRef,
@@ -47,10 +49,11 @@ import {
   splitRef,
 } from "./config.js";
 import { herdrAdvisorActivity, notifyHerdrAdvisorFailure } from "./herdr.js";
+import type { AdvisorSessionState } from "./session-state.js";
 import {
   adviceForDisplay,
-  advisorSessionState,
   consultAdvisor,
+  advisorSessionState as defaultAdvisorSessionState,
   hasSoundVerdict,
   renderAdvisorCallBox,
   renderAdvisorResponseHeader,
@@ -138,8 +141,13 @@ const findConfiguredModel = (ctx: ExtensionContext, ref: string) => {
 
 export const registerCommands = (
   pi: ExtensionAPI,
-  dependencies: { consult?: ManualConsult } = {}
+  dependencies: {
+    consult?: ManualConsult;
+    sessionState?: AdvisorSessionState;
+  } = {}
 ) => {
+  const advisorSessionState =
+    dependencies.sessionState ?? defaultAdvisorSessionState;
   const flowEnabled = () => pi.getActiveTools().includes("ask_advisor");
   const requestAdvisor =
     dependencies.consult ??
@@ -155,15 +163,15 @@ export const registerCommands = (
     herdrAdvisorActivity.start();
     return requestAdvisor(ctx, question, controller.signal)
       .then(({ markdown }) => {
+        if (controller.signal.aborted) {
+          return;
+        }
         advisorSessionState.recordInvocation({
           executionEffect: "continued",
           kind: "markdown",
           model: advisorRef,
           trigger: "manual",
         });
-        if (controller.signal.aborted) {
-          return;
-        }
         pi.sendMessage(
           {
             content: `Manual Advisor consultation${question ? ` (${question})` : ""}:\n\n${markdown}`,
@@ -232,19 +240,48 @@ export const registerCommands = (
     return {};
   };
 
+  const loadCommandConfig = (ctx: ExtensionContext) => {
+    try {
+      loadConfig(ctx);
+      return true;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      notify(
+        ctx,
+        `Advisor command could not load configuration: ${message} Fix advisor.json and retry.`,
+        "error"
+      );
+      return false;
+    }
+  };
+
   const activateAdvisor = async (
     args: string,
     ctx: ExtensionContext,
     announce = true
   ) => {
-    loadConfig(ctx);
+    if (!loadCommandConfig(ctx)) {
+      return;
+    }
+    const previous = {
+      advisor: advisorRef,
+      contextMaxChars: contextMaxCharsRef,
+      executor: executorRef,
+    };
+    const restoreRefs = () => {
+      setAdvisorRef(previous.advisor);
+      setContextMaxCharsRef(previous.contextMaxChars);
+      setExecutorRef(previous.executor);
+    };
     const argumentError = parseArgs(args);
     if (argumentError) {
+      restoreRefs();
       notify(ctx, argumentError, "error");
       return;
     }
     const { error } = await resolveActivationModels(ctx);
     if (error) {
+      restoreRefs();
       notify(ctx, error, "error");
       return;
     }
@@ -356,7 +393,9 @@ export const registerCommands = (
     description:
       "Consult the Advisor in parallel; accepts an optional focused question and fans its response out to the Executor",
     handler: (args, ctx) => {
-      loadConfig(ctx);
+      if (!loadCommandConfig(ctx)) {
+        return Promise.resolve();
+      }
       if (
         !(
           isSimpleMode() ||
@@ -396,8 +435,7 @@ export const registerCommands = (
     description:
       "Select and persist the Executor and Advisor models with reasoning levels",
     handler: async (_args, ctx) => {
-      loadConfig(ctx);
-      if (!ctx.hasUI) {
+      if (!(loadCommandConfig(ctx) && ctx.hasUI)) {
         return;
       }
       const refs = ctx.modelRegistry
@@ -475,8 +513,7 @@ export const registerCommands = (
     description: "Configure Advisor context and reasoning effort",
     // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one settings form maps every persisted control.
     handler: async (_args, ctx) => {
-      loadConfig(ctx);
-      if (!ctx.hasUI) {
+      if (!(loadCommandConfig(ctx) && ctx.hasUI)) {
         return;
       }
 
@@ -523,6 +560,7 @@ export const registerCommands = (
       setAdvisorGitContextRef(settings.gitContext ?? "summary");
       setAdvisorGitContextMaxCharsRef(settings.gitContextMaxChars ?? 20_000);
       setAdvisorToolPoliciesRef(settings.toolPolicies ?? {});
+      setAdvisorTrackedFileContentRef(settings.trackedFileContent ?? false);
       setAdvisorUntrackedContentRef(settings.untrackedContent ?? false);
       setAdvisorOutcomeLoggingRef(settings.outcomeLogging ?? false);
       const path = saveConfig(ctx);

package/src/config.ts

@@ -64,6 +64,7 @@ export let advisorGitContextMaxCharsRef = DEFAULT_ADVISOR_GIT_CONTEXT_MAX_CHARS;
 export let advisorToolPoliciesRef: AdvisorToolPolicies = {};
 export let advisorOutcomeLoggingRef = false;
 export let advisorUntrackedContentRef = false;
+export let advisorTrackedFileContentRef = false;
 
 export const setExecutorRef = (ref: string) => {
   executorRef = ref;
@@ -166,6 +167,9 @@ export const setAdvisorOutcomeLoggingRef = (enabled: boolean) => {
 export const setAdvisorUntrackedContentRef = (enabled: boolean) => {
   advisorUntrackedContentRef = enabled;
 };
+export const setAdvisorTrackedFileContentRef = (enabled: boolean) => {
+  advisorTrackedFileContentRef = enabled;
+};
 
 /**
  * Returns the current live settings state. Use this at UI boundaries instead of
@@ -195,6 +199,7 @@ export const getAdvisorSettings = () => ({
   toolPolicies: { ...advisorToolPoliciesRef },
   toolResultMaxBytes: advisorToolResultMaxBytesRef,
   toolResultMaxLines: advisorToolResultMaxLinesRef,
+  trackedFileContent: advisorTrackedFileContentRef,
   untrackedContent: advisorUntrackedContentRef,
 });
 
@@ -231,6 +236,7 @@ export interface AdvisorConfig {
   advisorToolPolicies?: AdvisorToolPolicies;
   advisorToolResultMaxBytes?: number;
   advisorToolResultMaxLines?: number;
+  advisorTrackedFileContent?: boolean;
   advisorUntrackedContent?: boolean;
   alwaysOn?: boolean;
   contextMaxChars?: number;
@@ -260,6 +266,7 @@ const CONFIG_KEYS = new Set<keyof AdvisorConfig>([
   "alwaysOn",
   "advisorToolResultMaxBytes",
   "advisorToolResultMaxLines",
+  "advisorTrackedFileContent",
   "advisorRedactSecrets",
   "advisorUntrackedContent",
   "advisorOutcomeLogging",
@@ -280,6 +287,7 @@ const BOOLEAN_CONFIG_KEYS = [
   "simpleMode",
   "alwaysOn",
   "advisorHerdrIntegration",
+  "advisorTrackedFileContent",
   "advisorRedactSecrets",
   "advisorUntrackedContent",
   "advisorOutcomeLogging",
@@ -305,16 +313,10 @@ const invalidConfigValue = (
   );
 };
 
-const validateKnownKeys = (config: ConfigRecord, path: string) => {
-  const unknownKeys = Object.keys(config).filter(
+const unknownConfigKeys = (config: ConfigRecord) =>
+  Object.keys(config).filter(
     (key) => !CONFIG_KEYS.has(key as keyof AdvisorConfig)
   );
-  if (unknownKeys.length > 0) {
-    throw new TypeError(
-      `Invalid advisor configuration at ${path}: unknown key(s) ${unknownKeys.map((key) => JSON.stringify(key)).join(", ")}. Remove them or upgrade pi-advisor.`
-    );
-  }
-};
 
 const validateStringValues = (config: ConfigRecord, path: string) => {
   for (const key of STRING_CONFIG_KEYS) {
@@ -406,7 +408,6 @@ export const validateConfig = (
     );
   }
   const config = value as ConfigRecord;
-  validateKnownKeys(config, path);
   validateStringValues(config, path);
   validateBooleanValues(config, path);
   validateNumericValues(config, path);
@@ -467,6 +468,7 @@ const resetDefaults = () => {
   advisorToolPoliciesRef = {};
   advisorOutcomeLoggingRef = false;
   advisorUntrackedContentRef = false;
+  advisorTrackedFileContentRef = false;
 };
 
 const applyOptionalConfig = <Key extends keyof AdvisorConfig>(
@@ -568,6 +570,11 @@ const applyConfig = (config: AdvisorConfig) => {
     "advisorUntrackedContent",
     setAdvisorUntrackedContentRef
   );
+  applyOptionalConfig(
+    config,
+    "advisorTrackedFileContent",
+    setAdvisorTrackedFileContentRef
+  );
 };
 
 const readConfig = (path: string): AdvisorConfig => {
@@ -587,10 +594,12 @@ const configCache = new Map<
   string,
   { config: AdvisorConfig; identity: string }
 >();
+const warnedUnknownConfigIdentities = new Set<string>();
 
 /** Drops the parsed-configuration cache; the next load re-reads from disk. */
 export const resetConfigCache = () => {
   configCache.clear();
+  warnedUnknownConfigIdentities.clear();
 };
 
 /**
@@ -626,6 +635,19 @@ export const loadConfig = (_ctx: ExtensionContext) => {
     : undefined;
   if (globalConfig) {
     applyConfig(globalConfig);
+    const unknownKeys = unknownConfigKeys(globalConfig as ConfigRecord);
+    const warningIdentity = `${global}:${configIdentity(global)}`;
+    if (
+      unknownKeys.length > 0 &&
+      _ctx.hasUI &&
+      !warnedUnknownConfigIdentities.has(warningIdentity)
+    ) {
+      _ctx.ui.notify(
+        `Advisor configuration at ${global} contains unrecognized key(s) ${unknownKeys.map((key) => JSON.stringify(key)).join(", ")}. They were preserved but ignored; check for typos or upgrade pi-advisor.`,
+        "warning"
+      );
+      warnedUnknownConfigIdentities.add(warningIdentity);
+    }
   }
   // Repository-controlled project configuration is never applied. Models,
   // prompts, gates, budgets, disclosure, redaction, integrations, and consent
@@ -675,6 +697,7 @@ export const saveConfig = (_ctx: ExtensionContext) => {
     advisorToolPolicies: advisorToolPoliciesRef,
     advisorToolResultMaxBytes: advisorToolResultMaxBytesRef,
     advisorToolResultMaxLines: advisorToolResultMaxLinesRef,
+    advisorTrackedFileContent: advisorTrackedFileContentRef,
     advisorUntrackedContent: advisorUntrackedContentRef,
     alwaysOn: alwaysOnRef,
     gateFailureMode: advisorFailureModeRef,