@badliveware/pi-tool-feedback 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BadLiveware
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# Pi Tool Feedback
+
+Generic watched-tool feedback for Pi. It records passive per-turn summaries when selected tools are used, and can optionally queue a non-user feedback task for the agent at the end of a prompt.
+
+Use it when you are dogfooding a tool, extension, MCP server, or workflow and want low-friction subjective signals such as “did this feel useful?”, “did output feel incomplete or noisy?”, and “would the agent use it again?”. Objective trace facts such as truncation and follow-up tool categories stay in passive summaries.
+
+> Caveat: this is an experiment I am trying on my own Pi setup. I do not yet know whether agent self-feedback is broadly useful or reliable; treat the results as noisy design signals, not proof that a tool works better.
+
+## How it works
+
+Configure tool names or prefixes to watch. The extension listens to Pi tool events, records sanitized turn summaries, and exposes a `tool_feedback` tool that the agent can call when prompted. Active feedback requests are delivered as Pi custom messages with `triggerTurn`, not as user messages. The request names the watched tools but does not include trace-derived facts, so the agent's self-report is less anchored by telemetry the extension already knows.
+
+It does not record raw tool inputs, raw outputs, prompts, file contents, or shell commands in its JSONL log. Optional free-form notes are stored in session entries, while logs keep only note length/hash.
+
+## What feedback can and cannot tell you
+
+Agent self-feedback is useful as noisy operational feedback, not as a faithful explanation of the model's hidden reasoning. Treat it like a lightweight post-task survey and compare it with trace data.
+
+Good questions ask about the agent's observable experience:
+
+- Was the output useful, incomplete, noisy, or too slow?
+- Would you use this tool again in a similar situation?
+- Was follow-up work routine or did it feel compensatory?
+- What one missing capability or improvement would help most?
+- How confident are you in this report?
+
+Weak questions ask the agent to reconstruct why its internal reasoning happened:
+
+- What was the real causal contribution of this tool to your final answer?
+- Which hidden prompt feature or bias changed your reasoning?
+- Did your chain-of-thought faithfully describe the reason you chose an action?
+- Exactly how much would the outcome have changed without this tool?
+
+The extension therefore keeps objective trace facts in passive summaries and asks active prompts for subjective/counterfactual judgments. Use self-reports as candidate design signals, not ground truth.
+
+## Install
+
+From a published package:
+
+```bash
+pi install @badliveware/pi-tool-feedback
+```
+
+From this repository workspace:
+
+```bash
+pi install ./agent/extensions/public/tool-feedback
+```
+
+## Configure
+
+Create `~/.pi/agent/tool-feedback.json` for user-wide settings or `.pi/tool-feedback.json` in a project. Project config overlays user config.
+
+Minimal example:
+
+```json
+{
+  "mode": "both",
+  "watch": [
+    { "prefix": "code_intel_" },
+    { "name": "process" }
+  ]
+}
+```
+
+Modes:
+
+| Mode | Behavior |
+| --- | --- |
+| `off` | Disable summaries and feedback prompts. |
+| `passive` | Record turn summaries only. |
+| `ask-agent` | Ask for structured feedback after a prompt that used watched tools. |
+| `both` | Record summaries and ask for feedback. |
+
+Other options:
+
+```json
+{
+  "excludeTools": ["tool_feedback", "tool_feedback_state"],
+  "cooldownTurns": 0,
+  "skipWhenPendingMessages": true,
+  "appendSessionEntries": true,
+  "log": true
+}
+```
+
+### Extra feedback fields
+
+The built-in feedback schema stays stable, but you can add project- or user-specific fields. The active prompt lists these fields and agents answer them inside `fieldResponses`.
+
+```json
+{
+  "mode": "both",
+  "watch": [{ "prefix": "code_intel_" }],
+  "feedbackFields": [
+    {
+      "name": "rankingQuality",
+      "type": "enum",
+      "values": ["good", "mixed", "poor", "unknown"],
+      "required": true,
+      "description": "How good was result ranking?"
+    },
+    {
+      "name": "latencyAcceptable",
+      "type": "yes_no_unknown"
+    }
+  ]
+}
+```
+
+Supported field types:
+
+| Type | Accepted values |
+| --- | --- |
+| `enum` | one of the configured `values` |
+| `yes_no_unknown` | `yes`, `no`, or `unknown` |
+| `boolean` | JSON boolean |
+| `number` | finite JSON number |
+
+Field names must match `/^[a-zA-Z][a-zA-Z0-9_]*$/`. Invalid, unknown, or missing required field responses are recorded in `fieldResponseErrors`; invalid values are not stored in `fieldResponses`.
+
+Set `PI_TOOL_FEEDBACK_CONFIG` to load an additional config file, `PI_TOOL_FEEDBACK_DIR` to change the JSONL log directory, or `PI_TOOL_FEEDBACK_LOG` to force one log file.
+
+Default log directory:
+
+```text
+~/.cache/pi-tool-feedback/<session-id>.jsonl
+```
+
+## Tools and command
+
+### `tool_feedback_state`
+
+Read-only state/config inspection. Use it to see the loaded mode, watch rules, config paths, diagnostics, and current prompt usage.
+
+### `tool_feedback`
+
+Records one structured feedback entry. Typical agent response after a feedback prompt:
+
+```json
+{
+  "watchedTools": ["code_intel_impact_map"],
+  "perceivedUsefulness": "medium",
+  "wouldUseAgainSameSituation": "yes",
+  "followupWasRoutine": "yes",
+  "followupNeededBecauseToolWasInsufficient": "unknown",
+  "outputSeemedTooNoisy": "no",
+  "outputSeemedIncomplete": "yes",
+  "missedImportantContext": "unknown",
+  "confidence": "medium",
+  "improvement": "better_summary",
+  "fieldResponses": {
+    "rankingQuality": "mixed"
+  }
+}
+```
+
+### `/tool-feedback`
+
+Show runtime status or set the runtime mode until reload:
+
+```text
+/tool-feedback
+/tool-feedback off
+/tool-feedback passive
+/tool-feedback ask-agent
+/tool-feedback both
+```
+
+## Loop prevention
+
+The extension avoids the common feedback-loop traps:
+
+- `tool_feedback` and `tool_feedback_state` are excluded by default.
+- The active prompt is asked at most once.
+- Feedback prompts are skipped when Pi already has pending messages if `skipWhenPendingMessages` is true.
+- If the agent already called `tool_feedback`, no follow-up prompt is sent.
+
+If the feedback prompt is annoying, run:
+
+```text
+/tool-feedback passive
+```
+
+or set:
+
+```json
+{ "mode": "off" }
+```

package/index.ts

@@ -0,0 +1,269 @@
+import { Type } from "@mariozechner/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { Text } from "@mariozechner/pi-tui";
+import {
+	appendLog,
+	categoryForTool,
+	feedbackLogPath,
+	feedbackPrompt,
+	feedbackRecord,
+	isRecord,
+	loadToolFeedbackConfig,
+	logSafeFeedbackRecord,
+	makeTurnSummary,
+	matchesWatch,
+	modeIncludesAsk,
+	modeIncludesPassive,
+	resultErrorKind,
+	resultOk,
+	resultTruncated,
+	stringValue,
+	unique,
+	type AgentUsage,
+	type FeedbackMode,
+	type LoadedConfig,
+	type TurnUsage,
+	type WatchedToolCall,
+	type WatchedToolResult,
+} from "./src/core.ts";
+
+export { feedbackLogPath, loadToolFeedbackConfig } from "./src/core.ts";
+
+const MESSAGE_TYPE_TOOL_FEEDBACK_REQUEST = "tool-feedback:request";
+
+interface FeedbackRequestDetails {
+	kind: "tool_feedback_request";
+	watchedTools: string[];
+}
+
+function runtimeModeFromArgs(args: string): FeedbackMode | undefined {
+	return args === "off" || args === "passive" || args === "ask-agent" || args === "both" ? args : undefined;
+}
+
+function statusText(loaded: LoadedConfig): string {
+	return `tool-feedback ${loaded.config.mode}; watching ${loaded.config.watch.map((rule) => rule.name ?? `${rule.prefix}*`).join(", ") || "nothing"}`;
+}
+
+function feedbackRequestDetails(agent: AgentUsage): FeedbackRequestDetails {
+	return {
+		kind: "tool_feedback_request",
+		watchedTools: unique(agent.watchedCalls.map((call) => call.toolName)),
+	};
+}
+
+function statePayload(loaded: LoadedConfig, agent: AgentUsage | undefined): Record<string, unknown> {
+	return {
+		mode: loaded.config.mode,
+		watch: loaded.config.watch,
+		excludeTools: loaded.config.excludeTools,
+		cooldownTurns: loaded.config.cooldownTurns,
+		skipWhenPendingMessages: loaded.config.skipWhenPendingMessages,
+		appendSessionEntries: loaded.config.appendSessionEntries,
+		log: loaded.config.log,
+		feedbackFields: loaded.config.feedbackFields,
+		loadedConfig: loaded.paths,
+		diagnostics: loaded.diagnostics,
+		currentAgent: agent ? {
+			watchedTools: unique(agent.watchedCalls.map((call) => call.toolName)),
+			watchedCallCount: agent.watchedCalls.length,
+			watchedResultCount: agent.watchedResults.length,
+			feedbackRecorded: agent.feedbackRecorded,
+			afterWatchedCategories: unique(agent.afterWatchedCategories),
+		} : undefined,
+	};
+}
+
+function registerFeedbackRequestRenderer(pi: ExtensionAPI): void {
+	pi.registerMessageRenderer<FeedbackRequestDetails>(MESSAGE_TYPE_TOOL_FEEDBACK_REQUEST, (message, _options, theme) => {
+		const details = message.details;
+		if (!details || details.kind !== "tool_feedback_request") return undefined;
+		const watched = details.watchedTools.join(", ") || "watched tools";
+		return new Text(`${theme.fg("warning", "✦ tool feedback requested ")}${theme.fg("accent", watched)}`);
+	});
+}
+
+export default function toolFeedback(pi: ExtensionAPI): void {
+	let loadedConfig: LoadedConfig | undefined;
+	let runtimeMode: FeedbackMode | undefined;
+	let activeTurnIndex = 0;
+	let sequence = 0;
+	let currentTurn: TurnUsage | undefined;
+	let currentAgent: AgentUsage | undefined;
+	let lastPromptedTurn = Number.NEGATIVE_INFINITY;
+	const pendingCalls = new Map<string, WatchedToolCall & { startedAt: number }>();
+
+	registerFeedbackRequestRenderer(pi);
+
+	const getLoadedConfig = (ctx: ExtensionContext): LoadedConfig => {
+		loadedConfig = loadToolFeedbackConfig(ctx);
+		if (runtimeMode) loadedConfig.config.mode = runtimeMode;
+		return loadedConfig;
+	};
+
+	const getConfig = (ctx: ExtensionContext) => getLoadedConfig(ctx).config;
+
+	const ensureTurn = (): TurnUsage => {
+		if (currentTurn) return currentTurn;
+		currentTurn = { turnIndex: activeTurnIndex, startedAt: Date.now(), toolCalls: [], watchedCalls: [], watchedResults: [] };
+		return currentTurn;
+	};
+
+	const ensureAgent = (): AgentUsage => {
+		if (currentAgent) return currentAgent;
+		currentAgent = { startedAt: Date.now(), watchedCalls: [], watchedResults: [], feedbackRecorded: false, afterWatchedCategories: [], turnSummaries: [] };
+		return currentAgent;
+	};
+
+	pi.registerTool({
+		name: "tool_feedback_state",
+		label: "Tool Feedback State",
+		description: "Inspect generic watched-tool feedback configuration and current prompt usage.",
+		parameters: Type.Object({}),
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			const payload = statePayload(getLoadedConfig(ctx), currentAgent);
+			return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }], details: payload };
+		},
+	});
+
+	pi.registerTool({
+		name: "tool_feedback",
+		label: "Tool Feedback",
+		description: "Record concise structured feedback after using watched tools. This stores feedback only; it does not change the watched tool.",
+		parameters: Type.Object({
+			watchedTools: Type.Array(Type.String(), { description: "Watched tool names this feedback covers." }),
+			perceivedUsefulness: Type.Union([Type.Literal("high"), Type.Literal("medium"), Type.Literal("low"), Type.Literal("none"), Type.Literal("unknown")], { description: "How useful the tool felt for this task. Allowed values are: `high`, `medium`, `low`, `none`, `unknown`." }),
+			wouldUseAgainSameSituation: Type.Union([Type.Literal("yes"), Type.Literal("no"), Type.Literal("unsure"), Type.Literal("unknown")], { description: "Whether you would use the same tool again for a similar situation. Allowed values are: `yes`, `no`, `unsure`, `unknown`." }),
+			followupWasRoutine: Type.Optional(Type.Union([Type.Literal("yes"), Type.Literal("no"), Type.Literal("unknown")], { description: "Whether follow-up work felt routine rather than caused by tool insufficiency. Allowed values are: `yes`, `no`, `unknown`." })),
+			followupNeededBecauseToolWasInsufficient: Type.Optional(Type.Union([Type.Literal("yes"), Type.Literal("no"), Type.Literal("unknown")], { description: "Whether follow-up work was needed because the watched tool was insufficient. Allowed values are: `yes`, `no`, `unknown`." })),
+			outputSeemedTooNoisy: Type.Optional(Type.Union([Type.Literal("yes"), Type.Literal("no"), Type.Literal("unknown")], { description: "Whether the output felt too noisy to use efficiently. Allowed values are: `yes`, `no`, `unknown`." })),
+			outputSeemedIncomplete: Type.Optional(Type.Union([Type.Literal("yes"), Type.Literal("no"), Type.Literal("unknown")], { description: "Whether the output felt incomplete for the task. Allowed values are: `yes`, `no`, `unknown`." })),
+			missedImportantContext: Type.Optional(Type.Union([Type.Literal("yes"), Type.Literal("no"), Type.Literal("unknown")], { description: "Whether important context was later found outside the watched tool output. Allowed values are: `yes`, `no`, `unknown`." })),
+			confidence: Type.Union([Type.Literal("high"), Type.Literal("medium"), Type.Literal("low")], { description: "Confidence in this subjective feedback. Allowed values are: `high`, `medium`, `low`." }),
+			improvement: Type.Optional(Type.Union([Type.Literal("better_ranking"), Type.Literal("higher_cap"), Type.Literal("better_summary"), Type.Literal("better_docs"), Type.Literal("less_noise"), Type.Literal("faster"), Type.Literal("other")], { description: "Most useful improvement area. Allowed values are: `better_ranking`, `higher_cap`, `better_summary`, `better_docs`, `less_noise`, `faster`, `other`." })),
+			fieldResponses: Type.Optional(Type.Record(Type.String(), Type.Unknown(), { description: "Responses for configured extra feedback fields. Use exact field names from the feedback prompt/config; invalid or unknown fields are recorded as errors and ignored." })),
+			note: Type.Optional(Type.String({ description: "Short optional note. Stored in the session entry; logs keep only length/hash." })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const config = getConfig(ctx);
+			const record = feedbackRecord(params as Record<string, unknown>, ctx, config);
+			ensureAgent().feedbackRecorded = true;
+			if (config.appendSessionEntries) pi.appendEntry("tool-feedback:agent-feedback", record);
+			appendLog(config, record.sessionId, logSafeFeedbackRecord(record));
+			const payload = { recorded: true, watchedTools: record.watchedTools, perceivedUsefulness: record.perceivedUsefulness, confidence: record.confidence, fieldResponseErrors: record.fieldResponseErrors };
+			return { content: [{ type: "text", text: `Recorded feedback for ${record.watchedTools.length || 0} watched tool(s).` }], details: payload };
+		},
+	});
+
+	pi.registerCommand("tool-feedback", {
+		description: "Show or set watched-tool feedback mode: status, off, passive, ask-agent, both",
+		handler: async (args, ctx) => {
+			runtimeMode = runtimeModeFromArgs(args.trim()) ?? runtimeMode;
+			ctx.ui.notify(statusText(getLoadedConfig(ctx)), "info");
+		},
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		const loaded = getLoadedConfig(ctx);
+		ctx.ui.setStatus("tool-feedback", loaded.config.mode === "off" || loaded.config.watch.length === 0 ? undefined : `tf:${loaded.config.mode}`);
+	});
+
+	pi.on("agent_start", async (_event, ctx) => {
+		getLoadedConfig(ctx);
+		currentAgent = { startedAt: Date.now(), watchedCalls: [], watchedResults: [], feedbackRecorded: false, afterWatchedCategories: [], turnSummaries: [] };
+	});
+
+	pi.on("turn_start", async (event) => {
+		activeTurnIndex = event.turnIndex;
+		currentTurn = { turnIndex: event.turnIndex, startedAt: event.timestamp, toolCalls: [], watchedCalls: [], watchedResults: [] };
+	});
+
+	pi.on("tool_call", async (event, ctx) => {
+		const config = getConfig(ctx);
+		const toolName = stringValue(event.toolName);
+		const toolCallId = stringValue(event.toolCallId);
+		if (!toolName || !toolCallId) return;
+
+		const category = categoryForTool(toolName, event.input);
+		const callSequence = ++sequence;
+		const turn = ensureTurn();
+		turn.toolCalls.push({ toolName, category, sequence: callSequence });
+
+		const agent = ensureAgent();
+		if (agent.lastWatchedSequence !== undefined && callSequence > agent.lastWatchedSequence) agent.afterWatchedCategories.push(category);
+		if (config.mode === "off" || !matchesWatch(toolName, config)) return;
+
+		const inputRecord = isRecord(event.input) ? event.input as Record<string, unknown> : undefined;
+		const watched: WatchedToolCall & { startedAt: number } = {
+			toolName,
+			toolCallId,
+			category,
+			confirmReferences: inputRecord ? stringValue(inputRecord.confirmReferences) : undefined,
+			turnIndex: turn.turnIndex,
+			sequence: callSequence,
+			startedAt: Date.now(),
+		};
+		pendingCalls.set(toolCallId, watched);
+		turn.watchedCalls.push(watched);
+		agent.watchedCalls.push(watched);
+		agent.lastWatchedSequence = callSequence;
+	});
+
+	pi.on("tool_result", async (event) => {
+		const toolName = stringValue(event.toolName);
+		const toolCallId = stringValue(event.toolCallId);
+		if (!toolName || !toolCallId) return;
+		const pending = pendingCalls.get(toolCallId);
+		pendingCalls.delete(toolCallId);
+		if (!pending) return;
+
+		const result: WatchedToolResult = {
+			...pending,
+			ok: resultOk(event.details, event.isError === true),
+			isError: event.isError === true,
+			truncated: resultTruncated(event.details),
+			errorKind: resultErrorKind(event.details, event.isError === true),
+			durationMs: Date.now() - pending.startedAt,
+		};
+		ensureTurn().watchedResults.push(result);
+		ensureAgent().watchedResults.push(result);
+	});
+
+	pi.on("turn_end", async (event, ctx) => {
+		const config = getConfig(ctx);
+		const turn = currentTurn;
+		if (!turn || turn.watchedCalls.length === 0) return;
+		const summary = makeTurnSummary(turn, ctx);
+		ensureAgent().turnSummaries.push(summary);
+		if (modeIncludesPassive(config.mode)) {
+			if (config.appendSessionEntries) pi.appendEntry("tool-feedback:turn-summary", summary);
+			appendLog(config, summary.sessionId, summary as unknown as Record<string, unknown>);
+		}
+		if (event.turnIndex === turn.turnIndex) currentTurn = undefined;
+	});
+
+	pi.on("agent_end", async (_event, ctx) => {
+		const config = getConfig(ctx);
+		const agent = currentAgent;
+		if (!agent || agent.watchedCalls.length === 0) return;
+		if (!modeIncludesAsk(config.mode)) return;
+		if (agent.feedbackRecorded) return;
+		if (config.skipWhenPendingMessages && ctx.hasPendingMessages()) return;
+		if (activeTurnIndex - lastPromptedTurn <= config.cooldownTurns) return;
+		lastPromptedTurn = activeTurnIndex;
+		pi.sendMessage(
+			{
+				customType: MESSAGE_TYPE_TOOL_FEEDBACK_REQUEST,
+				content: feedbackPrompt(config, agent),
+				display: true,
+				details: feedbackRequestDetails(agent),
+			},
+			{ triggerTurn: true },
+		);
+	});
+
+	pi.on("session_shutdown", async () => {
+		pendingCalls.clear();
+		currentTurn = undefined;
+		currentAgent = undefined;
+	});
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@badliveware/pi-tool-feedback",
+  "version": "0.1.0",
+  "description": "Generic watched-tool feedback prompts and passive summaries for Pi.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "feedback",
+    "telemetry"
+  ],
+  "license": "MIT",
+  "author": "BadLiveware",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BadLiveware/pi.git",
+    "directory": "agent/extensions/public/tool-feedback"
+  },
+  "bugs": {
+    "url": "https://github.com/BadLiveware/pi/issues"
+  },
+  "homepage": "https://github.com/BadLiveware/pi/tree/main/agent/extensions/public/tool-feedback#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "index.ts",
+    "src",
+    "package.json"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/core.ts

@@ -0,0 +1,511 @@
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+export type FeedbackMode = "off" | "passive" | "ask-agent" | "both";
+export type PerceivedUsefulness = "high" | "medium" | "low" | "none" | "unknown";
+export type YesNoUnknown = "yes" | "no" | "unknown";
+export type WouldUseAgain = "yes" | "no" | "unsure" | "unknown";
+export type FeedbackConfidence = "high" | "medium" | "low";
+export type FeedbackImprovement = "better_ranking" | "higher_cap" | "better_summary" | "better_docs" | "less_noise" | "faster" | "other";
+export type FeedbackFieldType = "enum" | "yes_no_unknown" | "boolean" | "number";
+
+export interface WatchRule {
+	name?: string;
+	prefix?: string;
+}
+
+export interface FeedbackFieldConfig {
+	name: string;
+	type: FeedbackFieldType;
+	description?: string;
+	values?: string[];
+	required: boolean;
+}
+
+export type FeedbackFieldValue = string | number | boolean;
+
+export interface FeedbackFieldError {
+	name: string;
+	reason: string;
+}
+
+export interface ToolFeedbackConfig {
+	mode: FeedbackMode;
+	watch: WatchRule[];
+	excludeTools: string[];
+	cooldownTurns: number;
+	skipWhenPendingMessages: boolean;
+	appendSessionEntries: boolean;
+	log: boolean;
+	taskPrompt: string;
+	feedbackFields: FeedbackFieldConfig[];
+}
+
+export interface LoadedConfig {
+	config: ToolFeedbackConfig;
+	paths: string[];
+	diagnostics: string[];
+}
+
+export interface WatchedToolCall {
+	toolName: string;
+	toolCallId: string;
+	category: string;
+	confirmReferences?: string;
+	turnIndex: number;
+	sequence: number;
+}
+
+export interface WatchedToolResult extends WatchedToolCall {
+	ok: boolean;
+	isError: boolean;
+	truncated: boolean;
+	errorKind?: string;
+	durationMs?: number;
+}
+
+export interface TurnUsage {
+	turnIndex: number;
+	startedAt: number;
+	toolCalls: Array<{ toolName: string; category: string; sequence: number }>;
+	watchedCalls: WatchedToolCall[];
+	watchedResults: WatchedToolResult[];
+}
+
+export interface AgentUsage {
+	startedAt: number;
+	watchedCalls: WatchedToolCall[];
+	watchedResults: WatchedToolResult[];
+	feedbackRecorded: boolean;
+	lastWatchedSequence?: number;
+	afterWatchedCategories: string[];
+	turnSummaries: TurnSummary[];
+}
+
+export interface TurnSummary {
+	version: 1;
+	kind: "turn_summary";
+	timestamp: string;
+	sessionId: string;
+	repoRoot: string;
+	turnIndex: number;
+	watchedTools: string[];
+	watchedCallCount: number;
+	watchedResultCount: number;
+	anyTruncated: boolean;
+	anyError: boolean;
+	confirmReferences: string[];
+	toolCategories: string[];
+	categoriesAfterFirstWatchedCall: string[];
+}
+
+export interface FeedbackRecord {
+	version: 1;
+	kind: "agent_feedback";
+	timestamp: string;
+	sessionId: string;
+	repoRoot: string;
+	watchedTools: string[];
+	perceivedUsefulness: PerceivedUsefulness;
+	wouldUseAgainSameSituation: WouldUseAgain;
+	followupWasRoutine?: YesNoUnknown;
+	followupNeededBecauseToolWasInsufficient?: YesNoUnknown;
+	outputSeemedTooNoisy?: YesNoUnknown;
+	outputSeemedIncomplete?: YesNoUnknown;
+	missedImportantContext?: YesNoUnknown;
+	confidence: FeedbackConfidence;
+	improvement?: FeedbackImprovement;
+	fieldResponses?: Record<string, FeedbackFieldValue>;
+	fieldResponseErrors?: FeedbackFieldError[];
+	note?: string;
+	noteLength?: number;
+	noteHash?: string;
+}
+
+const CONFIG_FILE_NAME = "tool-feedback.json";
+const DEFAULT_TASK_PROMPT = [
+	"You used watched tools in the previous prompt. Please call `tool_feedback` once with concise structured feedback.",
+	"Focus on your own experience using the tool: whether it seemed useful, whether it felt incomplete or noisy, whether follow-up work was routine or compensatory, whether you would use it again in the same situation, and what one improvement would help most.",
+	"This is a dogfood feedback request, not new implementation work.",
+].join("\n\n");
+
+const BASE_FIELD_PROMPT = [
+	"Base `tool_feedback` field values:",
+	"- perceivedUsefulness: `high`, `medium`, `low`, `none`, or `unknown`",
+	"- wouldUseAgainSameSituation: `yes`, `no`, `unsure`, or `unknown`",
+	"- followupWasRoutine, followupNeededBecauseToolWasInsufficient, outputSeemedTooNoisy, outputSeemedIncomplete, missedImportantContext: `yes`, `no`, or `unknown`",
+	"- confidence: `high`, `medium`, or `low`",
+	"- improvement (optional): `better_ranking`, `higher_cap`, `better_summary`, `better_docs`, `less_noise`, `faster`, or `other`",
+	"Use `fieldResponses` only for configured extra fields. You do not need to inspect extension source to answer this prompt.",
+].join("\n");
+
+export const DEFAULT_CONFIG: ToolFeedbackConfig = {
+	mode: "passive",
+	watch: [],
+	excludeTools: ["tool_feedback", "tool_feedback_state"],
+	cooldownTurns: 0,
+	skipWhenPendingMessages: true,
+	appendSessionEntries: true,
+	log: true,
+	taskPrompt: DEFAULT_TASK_PROMPT,
+	feedbackFields: [],
+};
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+export function stringValue(value: unknown): string | undefined {
+	return typeof value === "string" ? value : undefined;
+}
+
+function booleanValue(value: unknown): boolean | undefined {
+	return typeof value === "boolean" ? value : undefined;
+}
+
+function numberValue(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function normalizeMode(value: unknown, fallback: FeedbackMode): FeedbackMode {
+	return value === "off" || value === "passive" || value === "ask-agent" || value === "both" ? value : fallback;
+}
+
+export function normalizeStringArray(value: unknown): string[] {
+	return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string" && item.trim().length > 0).map((item) => item.trim()) : [];
+}
+
+function normalizeWatchRules(value: unknown): WatchRule[] {
+	if (!Array.isArray(value)) return [];
+	const rules: WatchRule[] = [];
+	for (const item of value) {
+		if (!isRecord(item)) continue;
+		const name = stringValue(item.name)?.trim();
+		const prefix = stringValue(item.prefix)?.trim();
+		if (!name && !prefix) continue;
+		rules.push({ name, prefix });
+	}
+	return rules;
+}
+
+function isFeedbackFieldType(value: unknown): value is FeedbackFieldType {
+	return value === "enum" || value === "yes_no_unknown" || value === "boolean" || value === "number";
+}
+
+function normalizeFieldName(value: unknown): string | undefined {
+	const name = stringValue(value)?.trim();
+	if (!name || name.length > 64) return undefined;
+	return /^[a-zA-Z][a-zA-Z0-9_]*$/.test(name) ? name : undefined;
+}
+
+function normalizeFeedbackFields(value: unknown, source: string, diagnostics: string[]): FeedbackFieldConfig[] {
+	if (!Array.isArray(value)) return [];
+	const fields: FeedbackFieldConfig[] = [];
+	const seen = new Set<string>();
+	for (const item of value) {
+		if (!isRecord(item)) {
+			diagnostics.push(`${source}: feedback field ignored because it is not an object`);
+			continue;
+		}
+		const name = normalizeFieldName(item.name);
+		if (!name) {
+			diagnostics.push(`${source}: feedback field ignored because name must match /^[a-zA-Z][a-zA-Z0-9_]*$/ and be <=64 chars`);
+			continue;
+		}
+		if (seen.has(name)) {
+			diagnostics.push(`${source}: duplicate feedback field "${name}" ignored`);
+			continue;
+		}
+		const type = isFeedbackFieldType(item.type) ? item.type : undefined;
+		if (!type) {
+			diagnostics.push(`${source}: feedback field "${name}" ignored because type is invalid`);
+			continue;
+		}
+		const values = type === "enum" ? normalizeStringArray(item.values).slice(0, 20) : undefined;
+		if (type === "enum" && (!values || values.length === 0)) {
+			diagnostics.push(`${source}: enum feedback field "${name}" ignored because values are missing`);
+			continue;
+		}
+		seen.add(name);
+		fields.push({
+			name,
+			type,
+			description: stringValue(item.description)?.trim().slice(0, 200) || undefined,
+			values,
+			required: booleanValue(item.required) ?? false,
+		});
+	}
+	return fields;
+}
+
+function agentDir(): string {
+	return process.env.PI_CODING_AGENT_DIR ?? process.env.PI_AGENT_DIR ?? path.join(os.homedir(), ".pi", "agent");
+}
+
+function configPaths(ctx: ExtensionContext): string[] {
+	const paths: string[] = [];
+	if (process.env.PI_TOOL_FEEDBACK_CONFIG) paths.push(process.env.PI_TOOL_FEEDBACK_CONFIG);
+	paths.push(path.join(agentDir(), CONFIG_FILE_NAME));
+	paths.push(path.join(ctx.cwd, ".pi", CONFIG_FILE_NAME));
+	return [...new Set(paths)];
+}
+
+function normalizeConfigPatch(input: unknown, base: ToolFeedbackConfig, source: string, diagnostics: string[]): ToolFeedbackConfig {
+	if (!isRecord(input)) {
+		diagnostics.push(`${source}: expected a JSON object`);
+		return base;
+	}
+	const next: ToolFeedbackConfig = { ...base };
+	next.mode = normalizeMode(input.mode, base.mode);
+	if ("watch" in input) next.watch = normalizeWatchRules(input.watch);
+	if ("excludeTools" in input) next.excludeTools = normalizeStringArray(input.excludeTools);
+	next.cooldownTurns = Math.max(0, Math.min(100, Math.floor(numberValue(input.cooldownTurns) ?? base.cooldownTurns)));
+	next.skipWhenPendingMessages = booleanValue(input.skipWhenPendingMessages) ?? base.skipWhenPendingMessages;
+	next.appendSessionEntries = booleanValue(input.appendSessionEntries) ?? base.appendSessionEntries;
+	next.log = booleanValue(input.log) ?? base.log;
+	next.taskPrompt = stringValue(input.taskPrompt)?.trim() || base.taskPrompt;
+	if ("feedbackFields" in input) next.feedbackFields = normalizeFeedbackFields(input.feedbackFields, source, diagnostics);
+	if (isRecord(input.feedback) && "fields" in input.feedback) next.feedbackFields = normalizeFeedbackFields(input.feedback.fields, source, diagnostics);
+	return next;
+}
+
+export function loadToolFeedbackConfig(ctx: ExtensionContext): LoadedConfig {
+	let config = { ...DEFAULT_CONFIG };
+	const loaded: string[] = [];
+	const diagnostics: string[] = [];
+	for (const configPath of configPaths(ctx)) {
+		if (!fs.existsSync(configPath)) continue;
+		try {
+			const parsed = JSON.parse(fs.readFileSync(configPath, "utf-8")) as unknown;
+			config = normalizeConfigPatch(parsed, config, configPath, diagnostics);
+			loaded.push(configPath);
+		} catch (error) {
+			diagnostics.push(`${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	return { config, paths: loaded, diagnostics };
+}
+
+export function sessionIdFromContext(ctx: ExtensionContext): string {
+	const manager = ctx.sessionManager as unknown as { getSessionId?: () => string } | undefined;
+	try {
+		const sessionId = manager?.getSessionId?.();
+		if (sessionId) return sessionId;
+	} catch {
+		// Fall through.
+	}
+	return `process:${process.pid}:${ctx.cwd}`;
+}
+
+function feedbackLogDir(): string {
+	return process.env.PI_TOOL_FEEDBACK_DIR ?? path.join(process.env.XDG_CACHE_HOME ?? path.join(os.homedir(), ".cache"), "pi-tool-feedback");
+}
+
+function safeSessionPathSegment(sessionId: string): string {
+	return sessionId.replace(/[^a-zA-Z0-9._-]+/g, "_").slice(0, 160) || "unknown";
+}
+
+export function feedbackLogPath(sessionId = "unknown"): string {
+	return process.env.PI_TOOL_FEEDBACK_LOG ?? path.join(feedbackLogDir(), `${safeSessionPathSegment(sessionId)}.jsonl`);
+}
+
+export function nowIso(): string {
+	return new Date().toISOString();
+}
+
+function shortHash(value: string): string {
+	return crypto.createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+
+export function unique(items: Array<string | undefined>): string[] {
+	return [...new Set(items.filter((item): item is string => typeof item === "string" && item.length > 0))];
+}
+
+export function categoryForTool(toolName: string, input: unknown): string {
+	if (toolName === "read") return "read";
+	if (toolName === "edit" || toolName === "write") return "edit";
+	if (toolName === "bash") {
+		const command = isRecord(input) ? stringValue(input.command)?.trim() : undefined;
+		if (!command) return "bash:unknown";
+		if (/\b(rg|grep|fd|find|ag)\b/.test(command)) return "bash:search";
+		if (/\b(npm|pnpm|yarn|bun)\s+(test|run\s+test|run\s+typecheck)|\b(pytest|go\s+test|cargo\s+test|dotnet\s+test)\b/.test(command)) return "bash:test";
+		if (/\b(git\s+(diff|status|show|log|grep)|gh\s+)/.test(command)) return "bash:vcs";
+		return "bash:other";
+	}
+	return toolName.startsWith("code_intel_") ? "code-intel" : "other";
+}
+
+export function matchesWatch(toolName: string, config: ToolFeedbackConfig): boolean {
+	if (config.excludeTools.includes(toolName)) return false;
+	return config.watch.some((rule) => rule.name === toolName || (rule.prefix !== undefined && toolName.startsWith(rule.prefix)));
+}
+
+export function resultOk(details: unknown, isError: boolean): boolean {
+	if (isError) return false;
+	if (isRecord(details) && details.ok === false) return false;
+	return true;
+}
+
+export function resultTruncated(details: unknown): boolean {
+	if (!isRecord(details)) return false;
+	if (details.truncated === true) return true;
+	return isRecord(details.coverage) && details.coverage.truncated === true;
+}
+
+export function resultErrorKind(details: unknown, isError: boolean): string | undefined {
+	if (isError) return "tool-error";
+	if (!isRecord(details)) return undefined;
+	if (typeof details.reason === "string") return "reason";
+	if (typeof details.diagnostic === "string") return "diagnostic";
+	return undefined;
+}
+
+export function appendLog(config: ToolFeedbackConfig, sessionId: string, event: Record<string, unknown>): void {
+	if (!config.log) return;
+	try {
+		const logPath = feedbackLogPath(sessionId);
+		fs.mkdirSync(path.dirname(logPath), { recursive: true });
+		fs.appendFileSync(logPath, `${JSON.stringify(event)}\n`);
+	} catch {
+		// Feedback logging must never affect tool execution.
+	}
+}
+
+export function makeTurnSummary(turn: TurnUsage, ctx: ExtensionContext): TurnSummary {
+	const firstWatchedSequence = Math.min(...turn.watchedCalls.map((call) => call.sequence));
+	return {
+		version: 1,
+		kind: "turn_summary",
+		timestamp: nowIso(),
+		sessionId: sessionIdFromContext(ctx),
+		repoRoot: ctx.cwd,
+		turnIndex: turn.turnIndex,
+		watchedTools: unique(turn.watchedCalls.map((call) => call.toolName)),
+		watchedCallCount: turn.watchedCalls.length,
+		watchedResultCount: turn.watchedResults.length,
+		anyTruncated: turn.watchedResults.some((result) => result.truncated),
+		anyError: turn.watchedResults.some((result) => !result.ok || result.isError),
+		confirmReferences: unique(turn.watchedCalls.map((call) => call.confirmReferences)),
+		toolCategories: unique(turn.toolCalls.map((call) => call.category)),
+		categoriesAfterFirstWatchedCall: unique(turn.toolCalls.filter((call) => call.sequence > firstWatchedSequence).map((call) => call.category)),
+	};
+}
+
+export function modeIncludesPassive(mode: FeedbackMode): boolean {
+	return mode === "passive" || mode === "both";
+}
+
+export function modeIncludesAsk(mode: FeedbackMode): boolean {
+	return mode === "ask-agent" || mode === "both";
+}
+
+function configuredFieldsPrompt(fields: FeedbackFieldConfig[]): string {
+	if (fields.length === 0) return "";
+	const lines = ["Configured extra feedback fields: answer these in `fieldResponses` using the exact field names and allowed values below."];
+	for (const field of fields) {
+		const required = field.required ? "required" : "optional";
+		const allowed = field.type === "enum" ? (field.values ?? []).join(" | ") : field.type === "yes_no_unknown" ? "yes | no | unknown" : field.type;
+		lines.push(`- ${field.name} (${required}, ${field.type}${field.description ? `, ${field.description}` : ""}): ${allowed}`);
+	}
+	return `\n\n${lines.join("\n")}`;
+}
+
+export function feedbackPrompt(config: ToolFeedbackConfig, usage: AgentUsage): string {
+	const watchedTools = unique(usage.watchedCalls.map((call) => call.toolName)).join(", ");
+	return `${config.taskPrompt}\n\nWatched tools used: ${watchedTools || "unknown"}.\n\n${BASE_FIELD_PROMPT}${configuredFieldsPrompt(config.feedbackFields)}`;
+}
+
+function perceivedUsefulness(value: unknown): PerceivedUsefulness {
+	return value === "high" || value === "medium" || value === "low" || value === "none" || value === "unknown" ? value : "unknown";
+}
+
+function yesNoUnknown(value: unknown): YesNoUnknown | undefined {
+	return value === "yes" || value === "no" || value === "unknown" ? value : undefined;
+}
+
+function wouldUseAgain(value: unknown): WouldUseAgain {
+	return value === "yes" || value === "no" || value === "unsure" || value === "unknown" ? value : "unknown";
+}
+
+function confidence(value: unknown): FeedbackConfidence {
+	return value === "high" || value === "medium" || value === "low" ? value : "low";
+}
+
+function improvement(value: unknown): FeedbackImprovement | undefined {
+	return value === "better_ranking" || value === "higher_cap" || value === "better_summary" || value === "better_docs" || value === "less_noise" || value === "faster" || value === "other" ? value : undefined;
+}
+
+function validateFieldValue(field: FeedbackFieldConfig, value: unknown): { value?: FeedbackFieldValue; error?: string } {
+	if (value === undefined) return field.required ? { error: "required field missing" } : {};
+	if (field.type === "enum") {
+		if (typeof value === "string" && (field.values ?? []).includes(value)) return { value };
+		return { error: `expected one of ${(field.values ?? []).join(" | ")}` };
+	}
+	if (field.type === "yes_no_unknown") {
+		if (value === "yes" || value === "no" || value === "unknown") return { value };
+		return { error: "expected yes | no | unknown" };
+	}
+	if (field.type === "boolean") {
+		if (typeof value === "boolean") return { value };
+		return { error: "expected boolean" };
+	}
+	if (field.type === "number") {
+		if (typeof value === "number" && Number.isFinite(value)) return { value };
+		return { error: "expected finite number" };
+	}
+	return { error: "unsupported field type" };
+}
+
+function validateFieldResponses(input: unknown, fields: FeedbackFieldConfig[]): { responses?: Record<string, FeedbackFieldValue>; errors?: FeedbackFieldError[] } {
+	if (fields.length === 0) return {};
+	const raw = isRecord(input) ? input : {};
+	const responses: Record<string, FeedbackFieldValue> = {};
+	const errors: FeedbackFieldError[] = [];
+	for (const field of fields) {
+		const result = validateFieldValue(field, raw[field.name]);
+		if (result.value !== undefined) responses[field.name] = result.value;
+		if (result.error) errors.push({ name: field.name, reason: result.error });
+	}
+	for (const name of Object.keys(raw)) {
+		if (!fields.some((field) => field.name === name)) errors.push({ name, reason: "unknown configured field" });
+	}
+	return {
+		responses: Object.keys(responses).length > 0 ? responses : undefined,
+		errors: errors.length > 0 ? errors : undefined,
+	};
+}
+
+export function feedbackRecord(input: Record<string, unknown>, ctx: ExtensionContext, config?: ToolFeedbackConfig): FeedbackRecord {
+	const note = stringValue(input.note)?.trim();
+	const fields = validateFieldResponses(input.fieldResponses, config?.feedbackFields ?? []);
+	return {
+		version: 1,
+		kind: "agent_feedback",
+		timestamp: nowIso(),
+		sessionId: sessionIdFromContext(ctx),
+		repoRoot: ctx.cwd,
+		watchedTools: normalizeStringArray(input.watchedTools),
+		perceivedUsefulness: perceivedUsefulness(input.perceivedUsefulness),
+		wouldUseAgainSameSituation: wouldUseAgain(input.wouldUseAgainSameSituation),
+		followupWasRoutine: yesNoUnknown(input.followupWasRoutine),
+		followupNeededBecauseToolWasInsufficient: yesNoUnknown(input.followupNeededBecauseToolWasInsufficient),
+		outputSeemedTooNoisy: yesNoUnknown(input.outputSeemedTooNoisy),
+		outputSeemedIncomplete: yesNoUnknown(input.outputSeemedIncomplete),
+		missedImportantContext: yesNoUnknown(input.missedImportantContext),
+		confidence: confidence(input.confidence),
+		improvement: improvement(input.improvement),
+		fieldResponses: fields.responses,
+		fieldResponseErrors: fields.errors,
+		note,
+		noteLength: note ? note.length : undefined,
+		noteHash: note ? shortHash(note) : undefined,
+	};
+}
+
+export function logSafeFeedbackRecord(record: FeedbackRecord): Record<string, unknown> {
+	const { note: _note, ...safe } = record;
+	return safe;
+}