pi-delegation-policy 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -2,7 +2,13 @@
 
 ## Unreleased
 
-No unreleased changes.
+## 0.9.1 - 2026-09-08
+
+### Fixed
+
+- Make ContextShunt declared-read limits line-based, measure known textual results with real UTF-8 bytes and shared newline handling, and keep rejected requests out of the admitted-request window.
+- Keep the one-time `allow TOKEN MAX_LINES MAX_BYTES` command while binding its authorization to one tool call and immutable input snapshot; enforce its byte maximum against the real result.
+- Continue accepting the deprecated schema-4 `readerOutputBytes` field for compatibility while ignoring it, omitting it from new saves, and removing its inert panel control.
 
 ## 0.9.0 - 2026-09-07
 

package/CONTRIBUTING.md

@@ -19,7 +19,8 @@ Pull requests should:
 - use fictional examples and provider-agnostic documentation;
 - preserve exact role references and the absence of model fallbacks;
 - preserve the boundary: this package does not create, launch, route, or supervise subagents; ContextShunt can only redirect the main agent and never starts a worker from a hook;
-- preserve ContextShunt defaults and controls: `off` performs no classification, metrics, I/O, or interception; preserve originals when an artifact, permission, or recognized contract is unavailable;
+- preserve ContextShunt defaults and controls: `off` performs no classification, metrics, I/O, or interception; declared preflight limits count lines, post-result limits use returned UTF-8 bytes and lines, and rejected requests do not consume the admitted-request window;
+- preserve originals when an artifact, permission, or recognized contract is unavailable; keep one-time exceptions user-authorized, short-lived, and bound to the exact tool call and input, with byte limits checked against the returned result;
 - avoid project configuration, credential handling, telemetry, and network requests;
 - run `npm run format:check`, `npm run lint`, `npm run typecheck`, `npm test`, and `npm run build`.
 

package/README.md

@@ -39,7 +39,7 @@ pi install npm:pi-delegation-policy
 4. Run `/delegate status`. `disabled`, `not configured`, and exact references remain distinct. `D:ERR` means no policy is injected.
 5. The applied state affects the **next** agent run.
 
-Global defaults are stored at `~/.pi/agent/delegation-policy.json` and new values use schema version 4. Schema 2 and 3 defaults and session entries are read and normalized in memory without rewriting them. Schema 3 stores `null` for an explicitly disabled ordinary role. Session changes write a schema 2 `off` guard before the schema 4 state; saving defaults changes only the global file.
+Global defaults are stored at `~/.pi/agent/delegation-policy.json` and new values use schema version 4. The legacy positive `contextShunt.limits.readerOutputBytes` field remains accepted when reading schema 4, but is ignored and omitted from new saves. Schema 2 and 3 defaults and session entries are read and normalized in memory without rewriting them. Schema 3 stores `null` for an explicitly disabled ordinary role. Session changes write a schema 2 `off` guard before the schema 4 state; saving defaults changes only the global file.
 
 Before downgrading to a package that does not read schema 4, set global and branch ContextShunt to `off`; the guarded branch write already presents schema 2 `off` to older versions. Before downgrading to `0.6.0`, also change the global intensity to `off`, `normal`, or `aggressive` and run `/delegate off` in every active branch. For `<=0.5.0`, convert global defaults to schema 2 and replace ordinary `null` values with exact model references. Schema 2 never accepts `orchestrator`. See the configuration reference for details.
 
@@ -63,7 +63,7 @@ See the [getting-started guide](https://yivas.github.io/pi-delegation-policy/get
 
 The editor is a bounded, keyboard-first panel. Every model selector pins **Use global default** and **Disable for this session** before searchable models. It shows model ID first and `[provider]` last, fuzzy-searches provider, model ID, and display name, and shows at most 10 model rows. It also shows a compact effective-policy preview, field explanations, and public model metadata when Pi supplies it. Changes are drafts until **Apply changes**; saving effective configuration as defaults updates only the global file without applying the draft, and closing a modified draft requires explicit discard.
 
-**Context advanced** in `/delegate` edits the requested reader role, limits, and comma-separated patterns, with per-field global inheritance and a ContextShunt draft reset. In `enforce`, an oversized recognized read receives a bounded-read or user-confirmed one-time exception path. Large known text results are compacted only after their original is stored in a private, session-only artifact with a quota and an absolute 30-minute TTL from creation; scheduled cleanup runs while the process is active, recovery does not renew it, and shutdown removes the temporary directory. Crashes or OS suspension can delay deletion. `context_shunt_recover` accepts either a bounded line range or byte range. Errors, valid JSON of every root type, images, mixed content, and unknown tool contracts remain unchanged. The package declares `agents/pi-delegation-policy.bulk-reader.md` for discovery by a compatible executor. It allows only `read`, `grep`, `find`, and `ls`; it remains a guided profile, not an automatic bridge or a claim of executor isolation. It is not copied into user agent directories or launched automatically. If an executor cannot discover a path-based profile, use the guided redirection only.
+**Context advanced** in `/delegate` edits the requested reader role, limits, and comma-separated patterns, with per-field global inheritance and a ContextShunt draft reset. In `enforce`, an oversized recognized read receives a bounded-read or user-confirmed one-time exception path. Preguards use declared lines, while postguards use real UTF-8 bytes and returned line counts; rejected reads do not consume the shared declared-request window. Large known text results are compacted only after their original is stored in a private, session-only artifact with a quota and an absolute 30-minute TTL from creation; scheduled cleanup runs while the process is active, recovery does not renew it, and shutdown removes the temporary directory. Crashes or OS suspension can delay deletion. `context_shunt_recover` accepts either a bounded line range or byte range. Errors, valid JSON of every root type, images, mixed content, and unknown tool contracts remain unchanged. The package declares `agents/pi-delegation-policy.bulk-reader.md` for discovery by a compatible executor. It allows only `read`, `grep`, `find`, and `ls`; it remains a guided profile, not an automatic bridge or a claim of executor isolation. It is not copied into user agent directories or launched automatically. If an executor cannot discover a path-based profile, use the guided redirection only.
 
 ## Development
 

package/SECURITY.md

@@ -4,7 +4,7 @@
 
 This project is a local Pi extension. It stores delegation policy data and model identifiers in global defaults and session entries. ContextShunt is off by default. When explicitly enforced, it may keep a known successful text result in a private, session-only temporary file to serve bounded recovery; the file has an opaque ID, quota, cancellation check, and an absolute 30-minute TTL from creation. Cleanup is scheduled while the process is active and runs at shutdown, but crashes or OS suspension can delay deletion. It does not store credentials, execute subagents, or make network requests.
 
-ContextShunt is not a sandbox or a worker bridge. It preserves permissions and backends, does not inspect files before tool authorization, and leaves errors, structured/mixed results, images, binaries, and unknown contracts unchanged. The policy guides the main agent. It cannot guarantee that another system will follow a configured role or thinking choice. Review local configuration before using it.
+ContextShunt is not a sandbox or a worker bridge. It preserves permissions and backends, does not inspect files before tool authorization, and leaves errors, structured/mixed results, images, binaries, invalid inputs, and unknown contracts unchanged. One-time exceptions are user-authorized, short-lived, bound to one call and immutable input snapshot, and capped by declared lines plus real returned UTF-8 bytes. The policy guides the main agent. It cannot guarantee that another system will follow a configured role or thinking choice. Review local configuration before using it.
 
 ## Reporting
 

package/examples/global.json

@@ -22,8 +22,7 @@
       "fullReadLines": 350,
       "fullReadBytes": 16384,
       "targetedReadLines": 250,
-      "targetedReadBytes": 16384,
-      "readerOutputBytes": 8192
+      "targetedReadBytes": 16384
     },
     "shell": "conservative",
     "metrics": "memory",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-delegation-policy",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "private": false,
   "description": "A Pi extension for configurable delegation intensity and exact subagent role model references.",
   "type": "module",

package/schema/delegation-policy.schema.json

@@ -48,7 +48,11 @@
             "fullReadBytes": { "$ref": "#/$defs/positiveLimit" },
             "targetedReadLines": { "$ref": "#/$defs/positiveLimit" },
             "targetedReadBytes": { "$ref": "#/$defs/positiveLimit" },
-            "readerOutputBytes": { "$ref": "#/$defs/positiveLimit" }
+            "readerOutputBytes": {
+              "$ref": "#/$defs/positiveLimit",
+              "deprecated": true,
+              "description": "Legacy accepted field. It is validated then ignored and is not written by current versions."
+            }
           },
           "additionalProperties": false
         },

package/src/config.ts

@@ -46,8 +46,8 @@ const DEFAULT_LIMITS = {
   fullReadBytes: 16384,
   targetedReadLines: 250,
   targetedReadBytes: 16384,
-  readerOutputBytes: 8192,
 } as const;
+const LEGACY_LIMIT_KEYS = [...Object.keys(DEFAULT_LIMITS), "readerOutputBytes"] as const;
 const MAX_LIMIT = 1024 * 1024;
 
 export type ConfigDiagnostic = { message: string; reportWhenOff?: boolean };
@@ -154,10 +154,11 @@ function parseShunt(value: unknown): ContextShuntSettings | undefined {
   if (value.metrics !== undefined && value.metrics !== "memory") return undefined;
   let limits: ContextShuntLimits | undefined;
   if (value.limits !== undefined) {
-    if (!isRecord(value.limits) || !only(value.limits, Object.keys(DEFAULT_LIMITS)))
-      return undefined;
+    if (!isRecord(value.limits) || !only(value.limits, LEGACY_LIMIT_KEYS)) return undefined;
     if (Object.values(value.limits).some((item) => !validLimit(item))) return undefined;
-    limits = { ...value.limits } as ContextShuntLimits;
+    const effectiveLimits = { ...value.limits };
+    delete effectiveLimits.readerOutputBytes;
+    if (Object.keys(effectiveLimits).length) limits = effectiveLimits as ContextShuntLimits;
   }
   const exceptionPatterns =
     value.exceptionPatterns === undefined ? undefined : patterns(value.exceptionPatterns);

package/src/context-shunt-adapter.ts

@@ -36,10 +36,13 @@ export class ContextShuntAdapter {
     settings: EffectiveContextShunt,
     isBuiltinTool = true,
   ): { block: true; reason: string } | undefined {
-    if (settings.mode === "off" || (settings.mode === "enforce" && !isBuiltinTool))
+    if (settings.mode === "off") {
+      this.clearPending();
       return undefined;
+    }
+    if (settings.mode === "enforce" && !isBuiltinTool) return undefined;
 
-    const decision = this.engine.decide(event.toolName, event.input, settings);
+    const decision = this.engine.decide(event.toolName, event.input, settings, event.toolCallId);
     if (decision.action !== "block") return undefined;
 
     this.expirePending();
@@ -73,7 +76,13 @@ export class ContextShuntAdapter {
     const pending = this.pending.get(token);
     this.pending.delete(token);
     if (!pending || pending.expiresAt <= this.now()) return false;
-    return this.engine.allowOnce(pending.toolName, pending.input, maxLines, maxBytes);
+    return this.engine.allowOnce(
+      pending.toolName,
+      pending.input,
+      maxLines,
+      maxBytes,
+      pending.expiresAt,
+    );
   }
 
   async onToolResult(
@@ -82,12 +91,29 @@ export class ContextShuntAdapter {
     signal?: AbortSignal,
     isBuiltinTool = true,
   ): Promise<ToolResultPatch | undefined> {
-    if (settings.mode !== "enforce" || !isBuiltinTool || signal?.aborted) return undefined;
+    if (settings.mode !== "enforce" || !isBuiltinTool || signal?.aborted) {
+      this.engine.clearCall(event.toolCallId);
+      return undefined;
+    }
 
-    const text = shouldCompact(event.toolName, event.isError, event.content, settings);
-    if (!text) return undefined;
-    const artifactId = await this.artifacts.archive(text, signal);
-    if (!artifactId) return undefined;
+    const exception = this.engine.takeConsumed(event.toolCallId, event.toolName, event.input);
+    const decision = shouldCompact(
+      event.toolName,
+      event.input,
+      event.isError,
+      event.content,
+      settings,
+      exception,
+    );
+    if (decision.kind === "skip") {
+      if (decision.reason.startsWith("uncovered")) this.engine.metrics.uncoveredResults += 1;
+      return undefined;
+    }
+    const artifactId = await this.artifacts.archive(decision.text, signal);
+    if (!artifactId) {
+      this.engine.metrics.archiveFailures += 1;
+      return undefined;
+    }
 
     this.engine.metrics.boundedResults += 1;
     return {
@@ -113,9 +139,17 @@ export class ContextShuntAdapter {
     return "error" in result ? result : { text: result.text, range: result.range };
   }
 
-  async close(): Promise<void> {
+  clearConsumed(): void {
+    this.engine.clearConsumed();
+  }
+
+  clearPending(): void {
     this.pending.clear();
     this.engine.clear();
+  }
+
+  async close(): Promise<void> {
+    this.clearPending();
     await this.artifacts.close();
   }
 

package/src/context-shunt.ts

@@ -10,6 +10,7 @@ const MAX_ARTIFACTS = 8;
 const ARTIFACT_TTL_MS = 30 * 60 * 1000;
 const WINDOW_TTL_MS = 60_000;
 const EXCEPTION_TTL_MS = 60_000;
+const MAX_CONSUMED_EXCEPTIONS = 8;
 
 export type ShuntDecision = { action: "allow" | "block" | "skip"; reason: string };
 export type ShuntMetrics = {
@@ -17,16 +18,19 @@ export type ShuntMetrics = {
   wouldBlock: number;
   boundedResults: number;
   manualOverrides: number;
+  archiveFailures: number;
+  uncoveredResults: number;
 };
-type Window = { requestedLines: number; requestedBytes: number; updatedAt: number };
+type Window = { requestedLines: number; updatedAt: number };
 type Exception = { expiresAt: number; maxLines: number; maxBytes: number };
+export type ConsumedException = Exception & { toolName: string; input: string };
 type Clock = () => number;
 
 function positiveInteger(value: unknown): value is number {
-  return typeof value === "number" && Number.isInteger(value) && value > 0;
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
 }
 
-type ReadInput = { path: string; offset?: number; limit?: number };
+type ReadInput = { path: string; offset?: number; limit?: number; targeted: boolean };
 
 function readInput(value: unknown): ReadInput | undefined {
   if (!value || typeof value !== "object") return undefined;
@@ -34,7 +38,7 @@ function readInput(value: unknown): ReadInput | undefined {
   if (typeof input.path !== "string" || !input.path) return undefined;
   if (
     input.offset !== undefined &&
-    (typeof input.offset !== "number" || !Number.isInteger(input.offset) || input.offset < 0)
+    (typeof input.offset !== "number" || !Number.isSafeInteger(input.offset) || input.offset < 1)
   ) {
     return undefined;
   }
@@ -43,6 +47,7 @@ function readInput(value: unknown): ReadInput | undefined {
     path: input.path,
     ...(typeof input.offset === "number" ? { offset: input.offset } : {}),
     ...(typeof input.limit === "number" ? { limit: input.limit } : {}),
+    targeted: input.offset !== undefined,
   };
 }
 
@@ -59,7 +64,7 @@ function shellReadInput(toolName: string, value: unknown): ReadInput | undefined
   if (!match?.groups?.path || !match.groups.limit) return undefined;
   const limit = Number(match.groups.limit);
   return Number.isSafeInteger(limit) && positiveInteger(limit)
-    ? { path: `shell:${match.groups.path}`, limit }
+    ? { path: `shell:${match.groups.path}`, limit, targeted: false }
     : undefined;
 }
 
@@ -79,107 +84,143 @@ function matchesPattern(path: string, patterns: readonly string[]): boolean {
   });
 }
 
-export function inputFingerprint(toolName: string, input: unknown): string {
-  return `${toolName}\u0000${JSON.stringify(input)}`;
+export function inputFingerprint(toolName: string, input: unknown): string | undefined {
+  try {
+    const serialized = JSON.stringify(input);
+    return serialized === undefined ? undefined : `${toolName}\u0000${serialized}`;
+  } catch {
+    return undefined;
+  }
 }
 
 export class ContextShuntEngine {
   private readonly windows = new Map<string, Window>();
   private readonly exceptions = new Map<string, Exception>();
+  private readonly consumed = new Map<string, ConsumedException>();
   private readonly now: Clock;
   readonly metrics: ShuntMetrics = {
     blocked: 0,
     wouldBlock: 0,
     boundedResults: 0,
     manualOverrides: 0,
+    archiveFailures: 0,
+    uncoveredResults: 0,
   };
 
   constructor(now: Clock = Date.now) {
     this.now = now;
   }
 
-  decide(toolName: string, input: unknown, settings: EffectiveContextShunt): ShuntDecision {
+  decide(
+    toolName: string,
+    input: unknown,
+    settings: EffectiveContextShunt,
+    toolCallId?: string,
+  ): ShuntDecision {
     if (settings.mode === "off") return { action: "skip", reason: "off" };
 
     const read = declaredRead(toolName, input);
-    if (!read) return { action: "skip", reason: "unsupported or unknown tool contract" };
+    if (!read) return { action: "skip", reason: "unknown-contract" };
 
-    this.expire(this.now());
+    const now = this.now();
+    this.expire(now);
     const fingerprint = inputFingerprint(toolName, input);
-    const exception = this.exceptions.get(fingerprint);
-    if (exception) {
+    const exception = fingerprint ? this.exceptions.get(fingerprint) : undefined;
+    if (exception && fingerprint && read.limit !== undefined) {
       this.exceptions.delete(fingerprint);
-      const declaredLines = read.limit ?? 0;
-      const declaredBytes = declaredLines * 80;
-      if (
-        exception.expiresAt > this.now() &&
-        declaredLines <= exception.maxLines &&
-        declaredBytes <= exception.maxBytes
-      ) {
+      if (exception.expiresAt > now && read.limit <= exception.maxLines && toolCallId) {
+        this.consumed.delete(toolCallId);
+        if (this.consumed.size >= MAX_CONSUMED_EXCEPTIONS) {
+          const oldestToolCallId = this.consumed.keys().next().value;
+          if (oldestToolCallId) this.consumed.delete(oldestToolCallId);
+        }
+        this.consumed.set(toolCallId, { ...exception, toolName, input: fingerprint });
         this.metrics.manualOverrides += 1;
-        return { action: "allow", reason: "one-time user exception" };
+        return { action: "allow", reason: "one-time-exception" };
       }
     }
 
     if (matchesPattern(read.path, settings.exceptionPatterns)) {
-      return {
-        action: "allow",
-        reason: "matches ContextShunt exemption; tool permissions unchanged",
-      };
-    }
-
-    if (read.limit === undefined) {
-      return { action: "allow", reason: "size unknown; post-result guard applies" };
+      return { action: "allow", reason: "configured-exemption" };
     }
+    if (read.limit === undefined) return { action: "allow", reason: "size-unknown" };
 
-    const requestedBytes = read.limit * 80;
-    const targeted = read.offset !== undefined;
-    const lineBudget = targeted ? settings.limits.targetedReadLines : settings.limits.fullReadLines;
-    const byteBudget = targeted ? settings.limits.targetedReadBytes : settings.limits.fullReadBytes;
+    const lineBudget = read.targeted
+      ? settings.limits.targetedReadLines
+      : settings.limits.fullReadLines;
     const windowKey = `${toolName}\u0000${read.path}`;
     const previous = this.windows.get(windowKey);
     const totalLines = (previous?.requestedLines ?? 0) + read.limit;
-    const totalBytes = (previous?.requestedBytes ?? 0) + requestedBytes;
-    const excessive =
-      read.limit > lineBudget ||
-      requestedBytes > byteBudget ||
-      totalLines > settings.limits.fullReadLines ||
-      totalBytes > settings.limits.fullReadBytes;
-    this.windows.set(windowKey, {
-      requestedLines: totalLines,
-      requestedBytes: totalBytes,
-      updatedAt: this.now(),
-    });
+    const excessive = read.limit > lineBudget || totalLines > settings.limits.fullReadLines;
+
     if (settings.mode === "observe") {
-      if (excessive) this.metrics.wouldBlock += 1;
+      if (excessive) {
+        this.metrics.wouldBlock += 1;
+        return { action: "allow", reason: "would-block-lines" };
+      }
+      this.windows.set(windowKey, { requestedLines: totalLines, updatedAt: now });
+      return { action: "allow", reason: "declared-bounded" };
+    }
+    if (excessive) {
+      this.metrics.blocked += 1;
       return {
-        action: "allow",
-        reason: excessive ? "would block declared excessive range" : "declared bounded range",
+        action: "block",
+        reason: `${matchesPattern(read.path, settings.delegationHintPatterns) ? "delegation-hinted-" : ""}lines-exceed-budget`,
       };
     }
-    if (!excessive) return { action: "allow", reason: "declared bounded range" };
-    this.metrics.blocked += 1;
-    return {
-      action: "block",
-      reason: `${
-        matchesPattern(read.path, settings.delegationHintPatterns) ? "delegation-hinted " : ""
-      }declared range exceeds ContextShunt budget; use a bounded read or a user-authorized one-time exception`,
-    };
+    this.windows.set(windowKey, { requestedLines: totalLines, updatedAt: now });
+    return { action: "allow", reason: "declared-bounded" };
   }
 
-  allowOnce(toolName: string, input: unknown, maxLines: number, maxBytes: number): boolean {
-    if (!positiveInteger(maxLines) || !positiveInteger(maxBytes)) return false;
-    this.exceptions.set(inputFingerprint(toolName, input), {
-      expiresAt: this.now() + EXCEPTION_TTL_MS,
-      maxLines,
-      maxBytes,
-    });
+  allowOnce(
+    toolName: string,
+    input: unknown,
+    maxLines: number,
+    maxBytes: number,
+    expiresAt = this.now() + EXCEPTION_TTL_MS,
+  ): boolean {
+    const fingerprint = inputFingerprint(toolName, input);
+    if (
+      !positiveInteger(maxLines) ||
+      !positiveInteger(maxBytes) ||
+      !fingerprint ||
+      expiresAt <= this.now()
+    )
+      return false;
+    this.exceptions.set(fingerprint, { expiresAt, maxLines, maxBytes });
     return true;
   }
 
+  takeConsumed(
+    toolCallId: string,
+    toolName: string,
+    input: unknown,
+  ): ConsumedException | undefined {
+    const exception = this.consumed.get(toolCallId);
+    this.consumed.delete(toolCallId);
+    if (
+      !exception ||
+      exception.expiresAt <= this.now() ||
+      exception.toolName !== toolName ||
+      exception.input !== inputFingerprint(toolName, input)
+    ) {
+      return undefined;
+    }
+    return exception;
+  }
+
+  clearCall(toolCallId: string): void {
+    this.consumed.delete(toolCallId);
+  }
+
+  clearConsumed(): void {
+    this.consumed.clear();
+  }
+
   clear(): void {
     this.windows.clear();
     this.exceptions.clear();
+    this.consumed.clear();
   }
 
   private expire(now: number): void {
@@ -189,6 +230,9 @@ export class ContextShuntEngine {
     for (const [key, exception] of this.exceptions) {
       if (exception.expiresAt <= now) this.exceptions.delete(key);
     }
+    for (const [key, exception] of this.consumed) {
+      if (exception.expiresAt <= now) this.consumed.delete(key);
+    }
   }
 }
 
@@ -206,7 +250,7 @@ function isUtf8Boundary(source: Buffer, offset: number): boolean {
   return byte !== undefined && (byte & 0b1100_0000) !== 0b1000_0000;
 }
 
-function splitLines(text: string): string[] {
+export function splitLines(text: string): string[] {
   const lines: string[] = [];
   let start = 0;
   const endings = /\r\n|\n|\r/g;
@@ -435,23 +479,50 @@ function isJsonDocument(text: string): boolean {
   }
 }
 
+export type CompactionDecision =
+  | { kind: "compact"; text: string; reason: "result-exceeds-budget" | "exception-exceeds-budget" }
+  | {
+      kind: "skip";
+      reason:
+        | "off"
+        | "uncovered-contract"
+        | "uncovered-result"
+        | "within-budget"
+        | "exception-within-budget";
+    };
+
 export function shouldCompact(
   toolName: string,
+  input: unknown,
   isError: unknown,
   content: unknown,
   settings: EffectiveContextShunt,
-): string | undefined {
-  if (
-    settings.mode !== "enforce" ||
-    isError ||
-    !["read", "bash", "powershell", "grep"].includes(toolName)
-  ) {
-    return undefined;
-  }
+  exception?: Pick<ConsumedException, "maxLines" | "maxBytes">,
+): CompactionDecision {
+  if (settings.mode !== "enforce") return { kind: "skip", reason: "off" };
+  if (!["read", "bash", "powershell", "grep"].includes(toolName))
+    return { kind: "skip", reason: "uncovered-contract" };
+  const read = declaredRead(toolName, input);
+  if (!read) return { kind: "skip", reason: "uncovered-contract" };
   const text = textResult(content);
-  if (text === undefined || isJsonDocument(text) || text.includes("\u0000")) return undefined;
-  return Buffer.byteLength(text, "utf8") > settings.limits.fullReadBytes ||
-    text.split(/\r?\n/).length > settings.limits.fullReadLines
-    ? text
-    : undefined;
+  if (isError || text === undefined || isJsonDocument(text) || text.includes("\u0000"))
+    return { kind: "skip", reason: "uncovered-result" };
+
+  const targeted = read.targeted;
+  const lineBudget =
+    exception?.maxLines ??
+    (targeted ? settings.limits.targetedReadLines : settings.limits.fullReadLines);
+  const byteBudget =
+    exception?.maxBytes ??
+    (targeted ? settings.limits.targetedReadBytes : settings.limits.fullReadBytes);
+  if (text.length === 0) return { kind: "skip", reason: "within-budget" };
+  const exceeds =
+    Buffer.byteLength(text, "utf8") > byteBudget || splitLines(text).length > lineBudget;
+  if (!exceeds)
+    return { kind: "skip", reason: exception ? "exception-within-budget" : "within-budget" };
+  return {
+    kind: "compact",
+    text,
+    reason: exception ? "exception-exceeds-budget" : "result-exceeds-budget",
+  };
 }

package/src/delegate-panel.ts

@@ -51,7 +51,6 @@ const ADVANCED_FIELDS = [
   "fullReadBytes",
   "targetedReadLines",
   "targetedReadBytes",
-  "readerOutputBytes",
   "exceptionPatterns",
   "delegationHintPatterns",
   "resetContextShunt",
@@ -63,7 +62,6 @@ const LIMIT_FIELDS = [
   "fullReadBytes",
   "targetedReadLines",
   "targetedReadBytes",
-  "readerOutputBytes",
 ] as const;
 type LimitField = (typeof LIMIT_FIELDS)[number];
 type EditableAdvancedField = Exclude<AdvancedField, "readerRole" | "resetContextShunt" | "back">;
@@ -718,7 +716,6 @@ export class DelegatePanel implements Component, Focusable {
         case "fullReadBytes":
         case "targetedReadLines":
         case "targetedReadBytes":
-        case "readerOutputBytes":
           return String(limit(field));
         case "exceptionPatterns":
           return effective.exceptionPatterns.length
@@ -757,7 +754,6 @@ export class DelegatePanel implements Component, Focusable {
       fullReadBytes: "Full read bytes",
       targetedReadLines: "Targeted read lines",
       targetedReadBytes: "Targeted read bytes",
-      readerOutputBytes: "Reader output bytes",
       exceptionPatterns: "Exempt patterns",
       delegationHintPatterns: "Delegation hint patterns",
       resetContextShunt: "Reset ContextShunt draft",
@@ -807,7 +803,6 @@ export class DelegatePanel implements Component, Focusable {
       fullReadBytes: "Full read bytes",
       targetedReadLines: "Targeted read lines",
       targetedReadBytes: "Targeted read bytes",
-      readerOutputBytes: "Reader output bytes",
       exceptionPatterns: "Exempt patterns",
       delegationHintPatterns: "Delegation hint patterns",
     };

package/src/index.ts

@@ -80,19 +80,38 @@ function updateStatus(ctx: ExtensionContext, state: RuntimeState): void {
   ctx.ui.setStatus(STATUS_KEY, ctx.ui.theme.fg("dim", statusLabel(state)));
 }
 
+function contextStatusText(state: RuntimeState, shunt: ContextShuntAdapter): string {
+  const context = state.effective.contextShunt;
+  const limits = context.limits;
+  const metrics = shunt.engine.metrics;
+  return `${statusText(state)} | context-limits=preflight-lines full=${limits.fullReadLines} targeted=${limits.targetedReadLines}; postresult-utf8-bytes full=${limits.fullReadBytes} targeted=${limits.targetedReadBytes} | context-coverage=known builtin text only; unknown contracts and invalid inputs are unchanged | context-events=blocked:${metrics.blocked},would-block:${metrics.wouldBlock},bounded:${metrics.boundedResults},exceptions:${metrics.manualOverrides},archive-failures:${metrics.archiveFailures},uncovered:${metrics.uncoveredResults}`;
+}
+
 function isBuiltinTool(pi: ExtensionAPI, toolName: string): boolean {
   return pi
     .getAllTools()
     .some((tool) => tool.name === toolName && tool.sourceInfo.source === "builtin");
 }
+function isContextShuntDisabled(state: RuntimeState): boolean {
+  return (
+    state.effective.intensity === "off" ||
+    state.effective.contextShunt.mode === "off" ||
+    state.effective.contextShunt.suspended
+  );
+}
+function synchronizeContextShunt(shunt: ContextShuntAdapter, state: RuntimeState): void {
+  if (isContextShuntDisabled(state)) shunt.clearPending();
+}
 async function openEditor(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
   setRuntime: (state: RuntimeState) => void,
+  shunt: ContextShuntAdapter,
 ): Promise<void> {
   await openDelegateEditor(ctx, pi);
   const state = await loadRuntime(ctx);
   setRuntime(state);
+  synchronizeContextShunt(shunt, state);
   updateStatus(ctx, state);
 }
 export function statusText(state: RuntimeState): string {
@@ -233,27 +252,36 @@ export default function piDelegationPolicy(pi: ExtensionAPI): void {
     getArgumentCompletions,
     handler: async (args, ctx) => {
       const action = parseCommand(args);
-      if (action.kind === "open") return openEditor(pi, ctx, rememberRuntime);
+      if (action.kind === "open") return openEditor(pi, ctx, rememberRuntime, shunt);
       if (action.kind === "status" || action.kind === "context-status") {
         const state = await refreshRuntime(ctx);
-        ctx.ui.notify(statusText(state), hasRuntimeError(state) ? "error" : "info");
+        ctx.ui.notify(
+          action.kind === "context-status" ? contextStatusText(state, shunt) : statusText(state),
+          hasRuntimeError(state) ? "error" : "info",
+        );
         return;
       }
       if (action.kind === "reset") {
-        rememberRuntime(await resetSession(pi, ctx));
+        const state = rememberRuntime(await resetSession(pi, ctx));
+        synchronizeContextShunt(shunt, state);
         return;
       }
       if (action.kind === "intensity") {
-        rememberRuntime(await setSessionIntensity(pi, ctx, action.intensity));
+        const state = rememberRuntime(await setSessionIntensity(pi, ctx, action.intensity));
+        synchronizeContextShunt(shunt, state);
         return;
       }
       if (action.kind === "context-mode") {
-        rememberRuntime(await setContextMode(pi, ctx, action.mode));
+        const state = rememberRuntime(await setContextMode(pi, ctx, action.mode));
+        synchronizeContextShunt(shunt, state);
         return;
       }
       if (action.kind === "context-allow") {
         const state = await refreshRuntime(ctx);
-        const allowed = shunt.allowPending(action.token, action.maxLines, action.maxBytes);
+        synchronizeContextShunt(shunt, state);
+        const allowed =
+          !isContextShuntDisabled(state) &&
+          shunt.allowPending(action.token, action.maxLines, action.maxBytes);
         ctx.ui.notify(
           allowed
             ? "One-time ContextShunt exception is ready for the matching next call."
@@ -271,12 +299,13 @@ export default function piDelegationPolicy(pi: ExtensionAPI): void {
   });
   pi.registerShortcut("alt+g", {
     description: "Open delegation policy",
-    handler: async (ctx) => openEditor(pi, ctx, rememberRuntime),
+    handler: async (ctx) => openEditor(pi, ctx, rememberRuntime, shunt),
   });
   pi.on("session_start", async (_event, ctx) => {
     await refreshRuntime(ctx);
   });
   pi.on("session_tree", async (_event, ctx) => {
+    shunt.clearPending();
     await refreshRuntime(ctx);
   });
   pi.on("before_agent_start", async (event, ctx) => {
@@ -284,14 +313,23 @@ export default function piDelegationPolicy(pi: ExtensionAPI): void {
     const policy = buildDelegationPolicy(state);
     return policy ? { systemPrompt: `${event.systemPrompt}\n\n${policy}` } : undefined;
   });
+  pi.on("agent_end", async () => {
+    shunt.clearConsumed();
+  });
   pi.on("tool_call", async (event) => {
     const settings = latestRuntime?.effective.contextShunt;
-    if (!settings || settings.mode === "off") return undefined;
+    if (!settings || settings.mode === "off") {
+      shunt.clearPending();
+      return undefined;
+    }
     return shunt.onToolCall(event, settings, isBuiltinTool(pi, event.toolName));
   });
   pi.on("tool_result", async (event, ctx) => {
     const settings = latestRuntime?.effective.contextShunt;
-    if (!settings || settings.mode === "off") return undefined;
+    if (!settings || settings.mode === "off") {
+      shunt.clearPending();
+      return undefined;
+    }
     return shunt.onToolResult(event, settings, ctx.signal, isBuiltinTool(pi, event.toolName));
   });
   pi.on("session_shutdown", async (_event, ctx) => {

package/src/types.ts

@@ -25,7 +25,6 @@ export type ContextShuntLimits = {
   fullReadBytes?: number;
   targetedReadLines?: number;
   targetedReadBytes?: number;
-  readerOutputBytes?: number;
 };
 export type ContextShuntSettings = {
   mode?: ContextShuntMode;