@bytesbrains/pi-tool-awareness-gate 1.0.3

package/AGENTS.md

@@ -0,0 +1,36 @@
+# Tool Awareness Gate — Agent Instructions
+
+This gate operates transparently. No special agent instructions needed — it injects limitation signals directly into tool result context.
+
+## How Agents Should Use Awareness Signals
+
+When you see a tool result prefixed with a limitation reminder:
+
+⚠️ [bash] conf:0% partial truncated
+   • Non-zero exit code: 1 • Output was truncated
+   → Check stderr output for error details before retrying
+
+**Do:**
+- Read the status icon (✅ success, ⚠️ partial, ❌ failure, ⏱️ timeout, 🔒 unauthorized)
+- Check `conf:N%` — confidence below 50% means the result may be unreliable
+- Read warnings — they explain what went wrong
+- Follow suggestions — they provide corrective actions
+- For `partial` results: consider retrying or narrowing scope
+- For `failure` results: do not treat the output as valid
+
+**Don't:**
+- Ignore the reminder and treat the result as authoritative
+- Proceed with downstream actions based on partial/failed results without verification
+- Ignore truncation warnings — you may be missing critical data
+
+## Rich Payload Access
+
+The full envelope is available in `details._awareness` for programmatic inspection. Agents that need to make meta-decisions (retry? escalate? ask user?) should inspect:
+
+```typescript
+details._awareness.status        // "success" | "partial" | "failure" | "timeout" | "unauthorized"
+details._awareness.quality       // { confidence, completeness, freshness, accuracy }
+details._awareness.limitations   // { truncated, stale, limited_scope, requires_human_review, ... }
+details._awareness.warnings      // string[]
+details._awareness.suggestions   // string[] (optional)
+```

package/README.md

@@ -0,0 +1,176 @@
+# Tool Awareness Gate for Pi
+
+> Intercepts every tool result, infers quality signals, injects limitation reminders into agent context, and logs structured envelopes for evaluation. **Zero code changes required in other gates.**
+
+## Install
+
+```bash
+pi install npm:pi-tool-awareness-gate
+```
+
+Or add to `.pi/settings.json`:
+
+```json
+{
+  "packages": ["npm:pi-tool-awareness-gate"]
+}
+```
+
+## What It Does
+
+Every tool your agent calls — bash, read, write, edit, browser, CI, doctor — returns a result. But how reliable is that result? The awareness gate intercepts every `tool_result` event and adds:
+
+| Signal | What It Tells the Agent |
+|---|---|
+| **Status** | `success`, `partial`, `failure`, `timeout`, `unauthorized` |
+| **Confidence** | 0-1 score — how reliable is this result? |
+| **Completeness** | `full`, `partial`, `minimal` — did we get everything? |
+| **Truncation** | Was output cut off? |
+| **Freshness** | How stale is the data? |
+| **Warnings** | Human + agent readable caveats |
+| **Suggestions** | Actionable next steps ("retry with narrower scope") |
+
+## How It Works
+
+```
+Tool executes → tool_result event fires
+     │
+     ▼
+┌─────────────────────────────┐
+│ 1. Infer quality signals    │  ← heuristic analysis of raw output
+│ 2. Detect limitation flags  │  ← truncated? stale? scoped?
+│ 3. Generate warnings        │  ← "Output was truncated"
+│ 4. Format short reminder    │  ← 1-2 line summary
+│ 5. Inject into agent context│  ← prepended to result text
+│ 6. Log rich payload         │  ← .awareness/envelopes.log
+└─────────────────────────────┘
+```
+
+### Short Reminder Example
+
+When a tool result has issues, the agent sees:
+
+```
+⚠️ [bash] conf:0% partial truncated
+   • Non-zero exit code: 1 • Output was truncated
+   → Check stderr output for error details before retrying
+
+$ ls /nonexistent
+ls: /nonexistent: No such file or directory
+```
+
+### Rich Payload Example
+
+Logged to `.awareness/envelopes.log`:
+
+```json
+{
+  "timestamp": "2026-05-15T10:30:00.000Z",
+  "tool": "bash",
+  "invocation_id": "bash-42",
+  "status": "partial",
+  "latency_ms": 45,
+  "quality": {
+    "confidence": 0.8,
+    "completeness": "full",
+    "freshness": 0.5,
+    "accuracy": 0.8
+  },
+  "limitations": { "truncated": false },
+  "warnings": [],
+  "suggestions": []
+}
+```
+
+## Tool-Specific Inference
+
+The gate has tool-specific heuristics for richer signals:
+
+| Tool | Extra Signals Detected |
+|---|---|
+| `bash` | Exit code, stderr presence, timeout |
+| `read` | Truncation at limit, offset/limit awareness |
+| `write`/`edit` | Bytes written vs expected |
+| `browser_*` | HTTP errors, OCR failures, timeouts |
+| `ci_*` | API errors, Gitea connectivity issues |
+| `doctor_*` | Informational — no warnings |
+
+## Configuration
+
+Create `.awarenessrc.yml` in your project root (optional — sensible defaults):
+
+```yaml
+# Enable/disable the awareness layer
+enabled: true
+
+# Inject short reminders into agent context
+injectReminders: true
+
+# Log rich payloads for evaluation
+logEnvelopes: true
+
+# Where to write envelope logs
+envelopeLogPath: .awareness/envelopes.log
+
+# Max warnings to include per short reminder (before truncation)
+maxWarningsInReminder: 3
+
+# Quality thresholds
+thresholds.lowConfidence: 0.5
+thresholds.staleFreshness: 0.3
+thresholds.maxWarningsBeforeCritical: 5
+
+# Tools to skip awareness tracking (comma-separated)
+excludedTools:
+```
+
+## Architecture
+
+```
+tool-awareness-gate/
+├── package.json
+├── src/
+│   ├── index.ts      ← Hooks pi.on("tool_result"), main orchestration
+│   ├── types.ts      ← ToolResultEnvelope<T>, QualitySignals, LimitationFlags
+│   ├── infer.ts      ← Heuristic inference from raw tool outputs
+│   ├── format.ts     ← Short reminder + rich payload formatters
+│   ├── config.ts     ← .awarenessrc.yml loader
+│   └── helpers.ts    ← Invocation IDs, text extraction, log appending
+└── README.md
+```
+
+## Integration with Other Gates
+
+**No code changes needed.** The awareness gate works at the framework level, intercepting events from all gates automatically.
+
+When a gate wants to provide domain-specific quality signals (richer than what inference can detect), it imports the envelope types:
+
+```typescript
+import type { ToolResultEnvelope } from "pi-tool-awareness-gate/src/types";
+
+// Gate enriches its own result with domain-specific quality signals
+return {
+  content: [...],
+  details: {
+    ...details,
+    _awareness: {
+      quality: { freshness: 0.95 },  // CI just fetched live data
+      limitations: { truncated: false },
+    },
+  },
+};
+```
+
+The awareness gate will **merge** gate-provided signals with its own inference, preferring the gate's signals when available.
+
+## Benefits
+
+- **More trustworthy agents** — agents know when to doubt results
+- **Better debugging** — structured logs show tool quality over time
+- **Reduced overconfidence** — agents see explicit confidence scores
+- **Progressive adoption** — works automatically, gates enrich when ready
+- **Zero breaking changes** — no modifications to existing tool code
+
+## License
+
+MIT © [nandal](https://github.com/nandal)

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@bytesbrains/pi-tool-awareness-gate",
+  "version": "1.0.3",
+  "description": "Tool limitation awareness layer for AI agents — intercepts tool results, infers quality signals, injects limitation reminders, and logs structured envelopes for evaluation.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "tool-awareness",
+    "quality-signals",
+    "limitation-detection",
+    "agent-protocol",
+    "observability"
+  ],
+  "author": "nandal <nandal@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nandal/pi-ext",
+    "directory": "tool-awareness-gate"
+  },
+  "homepage": "https://github.com/nandal/pi-ext/tree/main/tool-awareness-gate",
+  "bugs": {
+    "url": "https://github.com/nandal/pi-ext/issues"
+  },
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "AGENTS.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "vitest": "^2.0.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,69 @@
+/**
+ * pi-tool-awareness-gate — Config
+ *
+ * Loads .awarenessrc.yml from project root.
+ * Falls back to sensible defaults if not present.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AwarenessConfig } from "./types";
+import { DEFAULT_AWARENESS_CONFIG } from "./types";
+
+export function loadConfig(cwd: string): AwarenessConfig {
+  const configPath = path.join(cwd, ".awarenessrc.yml");
+  const config: AwarenessConfig = { ...DEFAULT_AWARENESS_CONFIG };
+
+  if (!fs.existsSync(configPath)) return config;
+
+  try {
+    const content = fs.readFileSync(configPath, "utf-8");
+    const result: Record<string, string> = {};
+
+    for (const line of content.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const m = trimmed.match(/^\s*([\w][\w.]*):\s*(.+)$/);
+      if (m) {
+        let v = m[2].trim();
+        // Strip surrounding quotes
+        if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+          v = v.slice(1, -1);
+        }
+        result[m[1]] = v;
+      }
+    }
+
+    // Top-level booleans
+    if ("enabled" in result) config.enabled = result["enabled"] !== "false";
+    if ("injectReminders" in result) config.injectReminders = result["injectReminders"] !== "false";
+    if ("logEnvelopes" in result) config.logEnvelopes = result["logEnvelopes"] !== "false";
+
+    // Strings
+    if (result["envelopeLogPath"]) config.envelopeLogPath = result["envelopeLogPath"];
+    if (result["excludedTools"]) {
+      config.excludedTools = result["excludedTools"].split(",").map(s => s.trim()).filter(Boolean);
+    }
+
+    // Numbers
+    if (result["maxWarningsInReminder"]) {
+      const n = parseInt(result["maxWarningsInReminder"], 10);
+      if (!isNaN(n)) config.maxWarningsInReminder = n;
+    }
+    if (result["thresholds.lowConfidence"]) {
+      const n = parseFloat(result["thresholds.lowConfidence"]);
+      if (!isNaN(n)) config.thresholds.lowConfidence = n;
+    }
+    if (result["thresholds.staleFreshness"]) {
+      const n = parseFloat(result["thresholds.staleFreshness"]);
+      if (!isNaN(n)) config.thresholds.staleFreshness = n;
+    }
+    if (result["thresholds.maxWarningsBeforeCritical"]) {
+      const n = parseInt(result["thresholds.maxWarningsBeforeCritical"], 10);
+      if (!isNaN(n)) config.thresholds.maxWarningsBeforeCritical = n;
+    }
+
+    return config;
+  } catch {
+    return config;
+  }
+}

package/src/format.ts

@@ -0,0 +1,201 @@
+/**
+ * pi-tool-awareness-gate — Formatters
+ *
+ * Formats ToolResultEnvelope into:
+ * 1. Short reminders — 1-2 line summaries injected into agent context
+ * 2. Rich payloads — structured JSON for logging and evaluation
+ */
+import type {
+  ToolResultEnvelope,
+  ShortReminder,
+  AwarenessConfig,
+} from "./types";
+
+// ── Icons ─────────────────────────────────────────────────────────────────────
+
+const STATUS_ICONS: Record<string, string> = {
+  success: "✅",
+  partial: "⚠️",
+  failure: "❌",
+  timeout: "⏱️",
+  unauthorized: "🔒",
+};
+
+const WARNING_PREFIX: Record<string, string> = {
+  info: "ℹ️",
+  warn: "⚠️",
+  critical: "🚨",
+};
+
+// ── Short Reminder ────────────────────────────────────────────────────────────
+
+/**
+ * Format a short reminder (1-2 lines) for injection into agent context.
+ */
+export function formatShortReminder(
+  envelope: ToolResultEnvelope,
+  config: AwarenessConfig,
+): ShortReminder {
+  const parts: string[] = [];
+  const icon = STATUS_ICONS[envelope.status] || "❓";
+  const truncatedWarnings = envelope.warnings.slice(0, config.maxWarningsInReminder);
+
+  // Build a compact one-liner starting with tool name
+  let summary = `[${envelope.meta.tool_name}] ${icon}`;
+
+  // Add key quality signals as compact badges
+  if (envelope.quality.confidence !== undefined) {
+    const pct = Math.round(envelope.quality.confidence * 100);
+    summary += ` conf:${pct}%`;
+  }
+  if (envelope.quality.completeness && envelope.quality.completeness !== "full") {
+    summary += ` ${envelope.quality.completeness}`;
+  }
+  if (envelope.limitations.truncated) {
+    summary += " truncated";
+  }
+  if (envelope.limitations.stale) {
+    summary += " stale";
+  }
+
+  parts.push(summary);
+
+  // Add warnings as a second line if any
+  if (truncatedWarnings.length > 0) {
+    const warnText = truncatedWarnings
+      .map(w => `• ${w}`)
+      .join(" | ");
+    parts.push(`   ${warnText}`);
+  }
+
+  if (envelope.warnings.length > config.maxWarningsInReminder) {
+    const remaining = envelope.warnings.length - config.maxWarningsInReminder;
+    parts.push(`   ... +${remaining} more warnings`);
+  }
+
+  // Add top suggestion if available
+  if (envelope.suggestions && envelope.suggestions.length > 0) {
+    parts.push(`   → ${envelope.suggestions[0]}`);
+  }
+
+  // Determine severity level
+  let level: ShortReminder["level"] = "info";
+  if (envelope.status === "failure" || envelope.status === "timeout") {
+    level = "critical";
+  } else if (
+    envelope.warnings.length >= config.thresholds.maxWarningsBeforeCritical
+  ) {
+    level = "critical";
+  } else if (
+    envelope.warnings.length > 0 ||
+    envelope.status === "partial"
+  ) {
+    level = "warn";
+  }
+
+  return {
+    tool: envelope.meta.tool_name,
+    summary: `${WARNING_PREFIX[level]} ${parts.join("\n")}`,
+    level,
+  };
+}
+
+/**
+ * Inject a short reminder into a tool result's content.
+ * Prepends the reminder to the first text block.
+ */
+export function injectReminder(
+  result: unknown,
+  reminder: ShortReminder,
+): unknown {
+  if (!result || typeof result !== "object") return result;
+
+  const r = result as Record<string, unknown>;
+
+  // Only inject if result has a content array (standard pi tool result)
+  if (!Array.isArray(r.content) || r.content.length === 0) return result;
+
+  const blocks = r.content as Array<Record<string, unknown>>;
+  const firstTextIdx = blocks.findIndex(
+    b => b.type === "text" && typeof b.text === "string",
+  );
+
+  if (firstTextIdx === -1) return result;
+
+  const original = blocks[firstTextIdx].text as string;
+  blocks[firstTextIdx] = {
+    type: "text",
+    text: `${reminder.summary}\n\n${original}`,
+  };
+
+  return { ...r, content: blocks };
+}
+
+// ── Rich Payload ──────────────────────────────────────────────────────────────
+
+/**
+ * Format the full ToolResultEnvelope as a loggable JSON object.
+ */
+export function formatEnvelopeLog(
+  envelope: ToolResultEnvelope,
+): Record<string, unknown> {
+  return {
+    timestamp: envelope.meta.timestamp,
+    tool: envelope.meta.tool_name,
+    invocation_id: envelope.meta.invocation_id,
+    status: envelope.status,
+    latency_ms: envelope.meta.latency_ms,
+    quality: envelope.quality,
+    limitations: envelope.limitations,
+    warnings: envelope.warnings,
+    suggestions: envelope.suggestions || [],
+  };
+}
+
+// ── Display Formatters ────────────────────────────────────────────────────────
+
+/**
+ * Format envelope as a human-readable text block (for supervisor_status-like tools).
+ */
+export function formatEnvelopeDisplay(envelope: ToolResultEnvelope): string {
+  const icon = STATUS_ICONS[envelope.status] || "❓";
+  const lines = [
+    `${icon} Tool: ${envelope.meta.tool_name}`,
+    `   Status: ${envelope.status}  |  Latency: ${envelope.meta.latency_ms}ms  |  Retries: ${envelope.meta.retries}`,
+    `   Invocation: ${envelope.meta.invocation_id}`,
+  ];
+
+  if (Object.keys(envelope.quality).length > 0) {
+    const q = envelope.quality;
+    const qParts: string[] = [];
+    if (q.confidence !== undefined) qParts.push(`confidence: ${(q.confidence * 100).toFixed(0)}%`);
+    if (q.completeness) qParts.push(`completeness: ${q.completeness}`);
+    if (q.freshness !== undefined) qParts.push(`freshness: ${(q.freshness * 100).toFixed(0)}%`);
+    lines.push(`   Quality: ${qParts.join(" | ")}`);
+  }
+
+  if (Object.keys(envelope.limitations).length > 0) {
+    const activeFlags = Object.entries(envelope.limitations)
+      .filter(([, v]) => v === true)
+      .map(([k]) => k);
+    if (activeFlags.length > 0) {
+      lines.push(`   Limitations: ${activeFlags.join(", ")}`);
+    }
+  }
+
+  if (envelope.warnings.length > 0) {
+    lines.push(`   Warnings (${envelope.warnings.length}):`);
+    for (const w of envelope.warnings) {
+      lines.push(`     • ${w}`);
+    }
+  }
+
+  if (envelope.suggestions && envelope.suggestions.length > 0) {
+    lines.push(`   Suggestions:`);
+    for (const s of envelope.suggestions) {
+      lines.push(`     → ${s}`);
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/helpers.ts

@@ -0,0 +1,124 @@
+/**
+ * pi-tool-awareness-gate — Helpers
+ *
+ * Utility functions for the awareness gate.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AwarenessConfig } from "./types";
+
+/**
+ * Generate a unique invocation ID for each tool call.
+ */
+export function generateInvocationId(): string {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 8);
+  return `${timestamp}-${random}`;
+}
+
+/**
+ * Get the envelope log path (relative to cwd).
+ */
+export function getEnvelopeLogPath(cwd: string, config: AwarenessConfig): string {
+  return path.join(cwd, config.envelopeLogPath);
+}
+
+/**
+ * Append a structured envelope to the log.
+ */
+export function appendEnvelopeLog(
+  cwd: string,
+  config: AwarenessConfig,
+  entry: Record<string, unknown>,
+): void {
+  if (!config.logEnvelopes) return;
+  const logPath = getEnvelopeLogPath(cwd, config);
+  const dir = path.dirname(logPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.appendFileSync(logPath, JSON.stringify(entry) + "\n", { encoding: "utf-8" });
+}
+
+/**
+ * Extract text content from a tool result, regardless of shape.
+ */
+export function extractTextContent(result: unknown): string {
+  if (!result || typeof result !== "object") return "";
+
+  const r = result as Record<string, unknown>;
+
+  // Standard pi tool result: { content: [{ type: "text", text: "..." }] }
+  if (Array.isArray(r.content)) {
+    const texts: string[] = [];
+    for (const block of r.content as Array<Record<string, unknown>>) {
+      if (block.type === "text" && typeof block.text === "string") {
+        texts.push(block.text);
+      }
+    }
+    return texts.join("\n");
+  }
+
+  // Raw string result
+  if (typeof r.text === "string") return r.text;
+  if (typeof r.message === "string") return r.message;
+
+  return "";
+}
+
+/**
+ * Check if text content appears truncated.
+ * Uses heuristics: sudden cutoffs, missing closing markers, etc.
+ */
+export function isTextTruncated(text: string): boolean {
+  if (!text || text.length < 100) return false;
+
+  // Truncation indicators in typical tool output
+  const truncationMarkers = [
+    /\.\.\.\s*(truncated|omitted|remaining|(?:more|d+) (?:lines|bytes))/i,
+    /\[truncated\]/i,
+    /<omitted\s*\/?>/i,
+    /\.\.\.\s*$/m,  // trailing ellipsis on last line
+    /\btruncated\b.*\b(?:output|result|response)\b/i,
+    // pi read tool truncation
+    /more lines in file/i,
+    /Use offset=\d+ to continue/i,
+  ];
+
+  for (const marker of truncationMarkers) {
+    if (marker.test(text)) return true;
+  }
+
+  // Heuristic: text ends mid-sentence with no punctuation
+  const lastChar = text.trim().slice(-1);
+  const lastLine = text.trim().split("\n").pop() || "";
+  if (
+    lastLine.length > 20 &&
+    !/[.!?;:)\]}"'>]$/.test(lastChar) &&
+    !/^[\s#*\-–—]/.test(lastLine)
+  ) {
+    // Could be truncated — moderate confidence
+    // Only flag if the last line looks like a natural sentence fragment
+    if (/[a-z]$/.test(lastLine) && lastLine.split(" ").length > 3) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Determine status from raw tool result.
+ */
+export function inferStatus(result: unknown, error?: unknown): string {
+  if (error) return "failure";
+
+  if (result && typeof result === "object") {
+    const r = result as Record<string, unknown>;
+    if (r.isError === true) return "failure";
+    if (r.status && typeof r.status === "string") return r.status;
+    if (r.timeout === true) return "timeout";
+  }
+
+  return "success";
+}

package/src/index.ts

@@ -0,0 +1,184 @@
+/**
+ * pi-tool-awareness-gate — Main Extension
+ *
+ * Intercepts every tool_result event, infers quality signals and limitation
+ * flags, injects short reminders into agent context, and logs structured
+ * envelopes for evaluation.
+ *
+ * Works automatically with ALL existing gates — no code changes required.
+ *
+ * Events hooked:
+ *   - tool_result    → infer quality, inject reminders, log envelopes
+ *   - tool_error     → flag as failure
+ *   - session_start  → initialize config + session state
+ *   - session_shutdown → flush logs
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "./config";
+import { inferQuality, inferLimitations, inferWarnings, inferSuggestions } from "./infer";
+import {
+  formatShortReminder,
+  formatEnvelopeLog,
+  injectReminder,
+} from "./format";
+import {
+  generateInvocationId,
+  appendEnvelopeLog,
+} from "./helpers";
+import type {
+  ToolResultEnvelope,
+  RawToolResult,
+  AwarenessConfig,
+} from "./types";
+
+// ── Module-level state ───────────────────────────────────────────────────────
+
+let config: AwarenessConfig | null = null;
+/** Track invocation start times to calculate latency */
+const invocationStarts = new Map<string, number>();
+let invocationCounter = 0;
+
+// ── Extension ────────────────────────────────────────────────────────────────
+
+export default function (pi: ExtensionAPI) {
+  // ── Session lifecycle ────────────────────────────────────────────────────
+
+  pi.on("session_start", (_event, ctx) => {
+    config = loadConfig(ctx.cwd);
+    invocationCounter = 0;
+    invocationStarts.clear();
+  });
+
+  pi.on("session_shutdown", () => {
+    invocationStarts.clear();
+    config = null;
+  });
+
+  // ── Track tool execution start for latency calculation ───────────────────
+
+  pi.on("tool_execution_start", (event) => {
+    if (!config?.enabled) return;
+    if (config.excludedTools.includes(event.toolName)) return;
+
+    invocationCounter++;
+    const invId = `${event.toolName}-${invocationCounter}`;
+    invocationStarts.set(event.toolCallId, Date.now());
+  });
+
+  // ── Main interception: tool_result ───────────────────────────────────────
+
+  pi.on("tool_result", async (event, ctx) => {
+    if (!config?.enabled) return;
+    if (config.excludedTools.includes(event.toolName)) return;
+
+    const startTime = invocationStarts.get(event.toolCallId);
+    const latencyMs = startTime ? Date.now() - startTime : 0;
+    invocationStarts.delete(event.toolCallId);
+
+    // Build raw input for inference
+    const raw: RawToolResult = {
+      toolName: event.toolName,
+      result: {
+        content: event.content,
+        details: event.details,
+        isError: event.isError,
+      },
+      error: event.isError ? "tool error" : undefined,
+      isError: event.isError,
+      content: event.content,
+      details: event.details,
+    };
+
+    // Infer quality signals
+    const quality = inferQuality(raw, config);
+    const limitations = inferLimitations(raw);
+    const warnings = inferWarnings(raw, quality, limitations, config);
+    const suggestions = inferSuggestions(raw, warnings, quality);
+
+    // Determine status
+    let status: ToolResultEnvelope["status"] = "success";
+    if (event.isError) {
+      status = "failure";
+    } else if (limitations.truncated || limitations.limited_scope ||
+               limitations.requires_human_review) {
+      status = "partial";
+    } else if (warnings.length > 0) {
+      status = "partial";
+    }
+
+    // Build envelope
+    const envelope: ToolResultEnvelope = {
+      status,
+      result: { content: event.content, details: event.details },
+      meta: {
+        tool_name: event.toolName,
+        invocation_id: `${event.toolName}-${invocationCounter}`,
+        latency_ms: latencyMs,
+        retries: 0,
+        timestamp: new Date().toISOString(),
+      },
+      quality,
+      limitations,
+      warnings,
+      suggestions: suggestions.length > 0 ? suggestions : undefined,
+    };
+
+    // Log rich payload
+    appendEnvelopeLog(ctx.cwd, config, formatEnvelopeLog(envelope));
+
+    // Inject short reminder into result content
+    if (config.injectReminders && (warnings.length > 0 || status !== "success")) {
+      const reminder = formatShortReminder(envelope, config);
+      const enriched = injectReminder(
+        { content: event.content, details: event.details, isError: event.isError },
+        reminder,
+      ) as { content?: Array<{ type: string; text?: string }>; details?: Record<string, unknown>; isError?: boolean };
+
+      return {
+        content: enriched?.content ?? event.content,
+        details: { ...event.details, _awareness: envelope },
+        isError: event.isError,
+      };
+    }
+
+    // Even without reminder injection, attach envelope to details
+    return {
+      details: { ...event.details, _awareness: envelope },
+    };
+  });
+
+  // ── Error tracking ───────────────────────────────────────────────────────
+
+  pi.on("tool_error", (event, ctx) => {
+    if (!config?.enabled) return;
+    if (config.excludedTools.includes(event.toolName)) return;
+
+    const startTime = invocationStarts.get(event.toolCallId);
+    const latencyMs = startTime ? Date.now() - startTime : 0;
+
+    const envelope: ToolResultEnvelope = {
+      status: "failure",
+      result: { error: String(event.error) },
+      meta: {
+        tool_name: event.toolName,
+        invocation_id: `${event.toolName}-${++invocationCounter}`,
+        latency_ms: latencyMs,
+        retries: 0,
+        timestamp: new Date().toISOString(),
+      },
+      quality: {
+        confidence: 0,
+        completeness: "minimal",
+        freshness: 0,
+        accuracy: 0,
+      },
+      limitations: {
+        requires_human_review: true,
+      },
+      warnings: [`Tool execution failed: ${String(event.error).substring(0, 200)}`],
+      suggestions: ["Check tool parameters and retry", "Consider fallback approach"],
+    };
+
+    appendEnvelopeLog(ctx.cwd, config, formatEnvelopeLog(envelope));
+  });
+}

package/src/infer.ts

@@ -0,0 +1,361 @@
+/**
+ * pi-tool-awareness-gate — Inference Engine
+ *
+ * Inspects raw tool results from the `tool_result` event and
+ * infers quality signals, limitation flags, and warnings.
+ *
+ * Inference is heuristic-based — domain-specific signals require
+ * gates to enrich their results using the ToolResultEnvelope types.
+ */
+import type {
+  RawToolResult,
+  QualitySignals,
+  LimitationFlags,
+  AwarenessConfig,
+} from "./types";
+import { extractTextContent, isTextTruncated, inferStatus } from "./helpers";
+
+/**
+ * Detect common bash error patterns in command output.
+ * pi's standard bash tool doesn't expose exitCode in details,
+ * so we detect errors from content text heuristics.
+ */
+function looksLikeBashError(content: string): boolean {
+  if (!content || content.length < 3) return false;
+
+  const errorPatterns = [
+    /No such file or directory/i,
+    /command not found/i,
+    /Permission denied/i,
+    /cannot access/i,
+    /not a directory/i,
+    /Is a directory/i,
+    /Operation not permitted/i,
+    /No space left on device/i,
+    /Connection refused/i,
+    /Could not resolve host/i,
+    /fatal:/i,
+    /error:/i,
+    /Error:/,
+    /ERROR:/,
+    /syntax error/i,
+    /unexpected token/i,
+    /npm error/i,
+    /npm ERR!/,
+    /exit code [1-9]/i,
+  ];
+
+  // Check first few lines — errors typically appear early
+  const firstLines = content.split("\n").slice(0, 10).join("\n");
+  for (const pattern of errorPatterns) {
+    if (pattern.test(firstLines)) return true;
+  }
+
+  return false;
+}
+
+/**
+ * Infer quality signals from a raw tool result.
+ */
+export function inferQuality(
+  raw: RawToolResult,
+  _config: AwarenessConfig,
+): QualitySignals {
+  const signals: QualitySignals = {};
+  const content = extractTextContent(raw.result);
+  const error = raw.error || (raw.result as any)?.isError;
+
+  // Confidence: penalized by errors, empty results, bash errors
+  if (error) {
+    signals.confidence = 0.0;
+  } else if (!content || content.length === 0) {
+    signals.confidence = 0.3;
+  } else if (raw.toolName === "bash" && looksLikeBashError(content)) {
+    signals.confidence = 0.3;
+  } else {
+    signals.confidence = 0.8; // Default for successful tool calls
+  }
+
+  // Completeness
+  if (!content || content.length === 0) {
+    signals.completeness = "minimal";
+  } else if (
+    isTextTruncated(content) ||
+    (raw.result as any)?.details?.truncated === true
+  ) {
+    signals.completeness = "partial";
+  } else {
+    signals.completeness = "full";
+  }
+
+  // Freshness — can't infer without timestamps in result
+  signals.freshness = 0.5; // Unknown by default
+
+  // Accuracy — correlated with confidence unless contradicted
+  signals.accuracy = signals.confidence;
+
+  return signals;
+}
+
+/**
+ * Infer limitation flags from raw result + tool name.
+ */
+export function inferLimitations(raw: RawToolResult): LimitationFlags {
+  const flags: LimitationFlags = {};
+  const content = extractTextContent(raw.result);
+  const result = raw.result as Record<string, unknown> | undefined;
+
+  // Truncated: check heuristic + explicit flag
+  flags.truncated = isTextTruncated(content) || result?.truncated === true;
+
+  // Limited scope: partial results, filtered output
+  if (result?.details) {
+    const details = result.details as Record<string, unknown>;
+    if (details.truncated === true) flags.truncated = true;
+    if (details.totalCount && details.count) {
+      flags.limited_scope = (details.count as number) < (details.totalCount as number);
+    }
+    // Pagination indicators
+    if (details.limit && details.total) {
+      flags.limited_scope = (details.limit as number) < (details.total as number);
+    }
+  }
+
+  // API response indicators
+  if (result) {
+    // HTTP error status
+    if (
+      (result.status && typeof result.status === "number" && result.status >= 400) ||
+      (result.statusCode && typeof result.statusCode === "number" && result.statusCode >= 400)
+    ) {
+      flags.requires_human_review = true;
+    }
+
+    // Rate limiting
+    if (
+      result.retryAfter !== undefined ||
+      (typeof result.text === "string" && /rate.?limit/i.test(result.text))
+    ) {
+      flags.limited_scope = true;
+    }
+  }
+
+  // Tool-specific inference
+  switch (raw.toolName) {
+    case "bash": {
+      // pi's standard bash tool doesn't include exitCode in details —
+      // detect errors from content text patterns instead
+      if (looksLikeBashError(content)) {
+        flags.requires_human_review = true;
+      }
+      break;
+    }
+    case "read": {
+      // Partial reads (details.offset/limit)
+      const rDetails = result?.details as Record<string, unknown> | undefined;
+      if (rDetails?.offset !== undefined || rDetails?.limit !== undefined) {
+        flags.limited_scope = true;
+      }
+      break;
+    }
+    case "browser_navigate":
+    case "browser_click":
+    case "browser_type":
+    case "browser_read":
+    case "browser_screenshot":
+    case "browser_scroll":
+    case "browser_evaluate": {
+      // Browser navigations may have HTTP errors
+      if (
+        typeof content === "string" &&
+        (content.includes("Error:") || content.includes("ERR_") || content.includes("timeout"))
+      ) {
+        flags.limited_scope = true;
+      }
+      break;
+    }
+    case "write":
+    case "edit": {
+      // File writes are usually fine but check for partial writes
+      const wDetails = result?.details as Record<string, unknown> | undefined;
+      if (wDetails?.bytesWritten && wDetails?.bytesExpected) {
+        flags.truncated =
+          (wDetails.bytesWritten as number) < (wDetails.bytesExpected as number);
+      }
+      break;
+    }
+  }
+
+  return flags;
+}
+
+/**
+ * Generate warnings from the inferred signals + tool context.
+ */
+export function inferWarnings(
+  raw: RawToolResult,
+  quality: QualitySignals,
+  limitations: LimitationFlags,
+  config: AwarenessConfig,
+): string[] {
+  const warnings: string[] = [];
+
+  // Confidence warnings
+  if (quality.confidence !== undefined && quality.confidence < config.thresholds.lowConfidence) {
+    warnings.push(
+      `Low confidence (${(quality.confidence * 100).toFixed(0)}%) — result may be unreliable`,
+    );
+  }
+
+  // Freshness warnings
+  if (quality.freshness !== undefined && quality.freshness < config.thresholds.staleFreshness) {
+    warnings.push("Data may be stale — freshness score is low");
+  }
+
+  // Completeness warnings
+  if (quality.completeness === "minimal") {
+    warnings.push("Minimal result returned — data may be incomplete");
+  } else if (quality.completeness === "partial") {
+    warnings.push("Partial result — not all requested data was returned");
+  }
+
+  // Truncation
+  if (limitations.truncated) {
+    warnings.push("Output was truncated — some content may be missing");
+  }
+
+  // Limited scope
+  if (limitations.limited_scope) {
+    warnings.push("Result is scoped/limited — may not cover full request");
+  }
+
+  // Human review
+  if (limitations.requires_human_review) {
+    warnings.push("Human review recommended before acting on this result");
+  }
+
+  // Sensitive content
+  if (limitations.sensitive_content) {
+    warnings.push("Result may contain sensitive data — handle with care");
+  }
+
+  // Staleness (explicit flag)
+  if (limitations.stale) {
+    warnings.push("Data may be outdated — verify freshness");
+  }
+
+  // Tool-specific warnings
+  const result = raw.result as Record<string, unknown> | undefined;
+  const detailsWarn = result?.details as Record<string, unknown> | undefined;
+  const content = extractTextContent(raw.result);
+
+  switch (raw.toolName) {
+    case "bash": {
+      if (looksLikeBashError(content)) {
+        // Extract the first error line for the warning
+        const errLine = content.split("\n").find(l =>
+          /error|Error|ERROR|cannot|denied|not found|No such/i.test(l)
+        );
+        if (errLine) {
+          warnings.push(`Bash error: ${errLine.trim().substring(0, 100)}`);
+        } else {
+          warnings.push("Command produced error output");
+        }
+      }
+      if (detailsWarn?.timedOut) {
+        warnings.push("Command timed out");
+      }
+      break;
+    }
+    case "read": {
+      if (detailsWarn?.truncated) {
+        warnings.push("File read was truncated at limit");
+      }
+      break;
+    }
+    case "browser_navigate":
+    case "browser_read": {
+      if (content.includes("screenshot/OCR failed") || content.includes("OCR unavailable")) {
+        warnings.push("OCR/rendering failure — page content may be incomplete");
+      }
+      break;
+    }
+    case "ci_get_logs":
+    case "ci_list_runs":
+    case "ci_get_run": {
+      if (content.includes("❌") || content.includes("Failed")) {
+        warnings.push("CI API returned errors — check Gitea connectivity");
+      }
+      break;
+    }
+    case "doctor_audit":
+    case "doctor_check_file": {
+      // Doctor tools are informational — no warnings needed
+      break;
+    }
+  }
+
+  return warnings;
+}
+
+/**
+ * Generate actionable suggestions based on warnings and tool type.
+ */
+export function inferSuggestions(
+  raw: RawToolResult,
+  warnings: string[],
+  quality: QualitySignals,
+): string[] {
+  const suggestions: string[] = [];
+
+  if (warnings.length === 0) return suggestions;
+
+  // Generic suggestions based on limitation types
+  if (quality.completeness === "partial" || quality.completeness === "minimal") {
+    suggestions.push("Consider retrying with narrower scope or pagination parameters");
+  }
+
+  if (quality.freshness !== undefined && quality.freshness < 0.3) {
+    suggestions.push("Verify time-sensitive claims against a real-time source");
+  }
+
+  // Tool-specific suggestions
+  switch (raw.toolName) {
+    case "bash": {
+      const result = raw.result as Record<string, unknown> | undefined;
+      const details = result?.details as Record<string, unknown> | undefined;
+      const bashContent = extractTextContent(raw.result);
+      if (looksLikeBashError(bashContent)) {
+        suggestions.push("Check the error output above and adjust the command");
+      }
+      if (details?.timedOut) {
+        suggestions.push("Increase timeout or break command into smaller operations");
+      }
+      break;
+    }
+    case "read": {
+      if (raw.details?.truncated) {
+        suggestions.push("Use offset and limit parameters to read remaining content");
+      }
+      break;
+    }
+    case "browser_navigate":
+    case "browser_click":
+    case "browser_read": {
+      if (extractTextContent(raw.result).includes("OCR unavailable")) {
+        suggestions.push("Install tesseract.js for OCR support: npm install tesseract.js");
+      }
+      break;
+    }
+    case "ci_get_logs":
+    case "ci_list_runs": {
+      if (extractTextContent(raw.result).includes("Failed")) {
+        suggestions.push("Verify Gitea instance is running and reachable");
+        suggestions.push("Check .circ.yml configuration for correct Gitea URL");
+      }
+      break;
+    }
+  }
+
+  return suggestions;
+}

package/src/types.ts

@@ -0,0 +1,138 @@
+/**
+ * pi-tool-awareness-gate — Types
+ *
+ * Universal ToolResult envelope for all tool invocations.
+ * Gates can import these types for domain-specific enrichment.
+ */
+
+// ── Tool Result Envelope ──────────────────────────────────────────────────────
+
+export interface ToolResultMeta {
+  /** Name of the tool that produced this result */
+  tool_name: string;
+  /** Unique invocation identifier */
+  invocation_id: string;
+  /** Wall-clock latency in milliseconds */
+  latency_ms: number;
+  /** Number of retries before this result */
+  retries: number;
+  /** ISO 8601 timestamp of invocation start */
+  timestamp: string;
+}
+
+export interface QualitySignals {
+  /** 0-1 confidence in the result correctness */
+  confidence?: number;
+  /** How complete the result is relative to what was requested */
+  completeness?: "full" | "partial" | "minimal" | "unknown";
+  /** 0-1 freshness — 1 = real-time, 0 = stale/unknown */
+  freshness?: number;
+  /** 0-1 estimated accuracy */
+  accuracy?: number;
+  /** Additional tool-specific quality fields */
+  [key: string]: unknown;
+}
+
+export interface LimitationFlags {
+  /** Result was truncated (output, pagination, context window) */
+  truncated?: boolean;
+  /** Data may be stale/outdated */
+  stale?: boolean;
+  /** Result covers only a subset of what was requested */
+  limited_scope?: boolean;
+  /** Human review recommended before acting on this result */
+  requires_human_review?: boolean;
+  /** Result may contain sensitive data */
+  sensitive_content?: boolean;
+  /** Additional tool-specific limitation flags */
+  [key: string]: boolean | undefined;
+}
+
+export type ToolResultStatus =
+  | "success"   // Complete, no known issues
+  | "partial"   // Incomplete or degraded
+  | "failure"   // Tool execution failed
+  | "timeout"   // Tool timed out
+  | "unauthorized"; // Auth/permission error
+
+export interface ToolResultEnvelope<T = unknown> {
+  /** Deterministic status for control flow decisions */
+  status: ToolResultStatus;
+  /** The raw tool output payload */
+  result: T;
+  /** Execution metadata */
+  meta: ToolResultMeta;
+  /** Quality signals — how reliable is this result? */
+  quality: QualitySignals;
+  /** Binary limitation flags — what should the agent be cautious about? */
+  limitations: LimitationFlags;
+  /** Human + agent readable warnings */
+  warnings: string[];
+  /** Actionable next steps for the agent */
+  suggestions?: string[];
+}
+
+// ── Short Reminder ───────────────────────────────────────────────────────────
+
+export interface ShortReminder {
+  /** Tool name */
+  tool: string;
+  /** 1-2 sentence summary of limitations */
+  summary: string;
+  /** Severity level */
+  level: "info" | "warn" | "critical";
+}
+
+// ── Awareness Config ─────────────────────────────────────────────────────────
+
+export interface AwarenessConfig {
+  /** Enable/disable the awareness layer */
+  enabled: boolean;
+  /** Inject short reminders into agent context (default: true) */
+  injectReminders: boolean;
+  /** Log rich payloads for evaluation (default: true) */
+  logEnvelopes: boolean;
+  /** Path for envelope log (relative to cwd) */
+  envelopeLogPath: string;
+  /** Max warnings to include per short reminder */
+  maxWarningsInReminder: number;
+  /** Severity thresholds for quality signals */
+  thresholds: {
+    /** Confidence below this triggers a warning */
+    lowConfidence: number;
+    /** Freshness below this triggers a staleness warning */
+    staleFreshness: number;
+    /** Max warnings before escalating to critical */
+    maxWarningsBeforeCritical: number;
+  };
+  /** Tools to skip awareness tracking */
+  excludedTools: string[];
+}
+
+export const DEFAULT_AWARENESS_CONFIG: AwarenessConfig = {
+  enabled: true,
+  injectReminders: true,
+  logEnvelopes: true,
+  envelopeLogPath: ".awareness/envelopes.log",
+  maxWarningsInReminder: 3,
+  thresholds: {
+    lowConfidence: 0.5,
+    staleFreshness: 0.3,
+    maxWarningsBeforeCritical: 5,
+  },
+  excludedTools: [],
+};
+
+// ── Inference Input (what we have to work with from the tool_result event) ──
+
+export interface RawToolResult {
+  toolName: string;
+  result: unknown;
+  error?: unknown;
+  /** If the tool has isError flag */
+  isError?: boolean;
+  /** Content array if present */
+  content?: Array<{ type: string; text?: string }>;
+  /** Details object if present */
+  details?: Record<string, unknown>;
+}