@czottmann/pi-automode 1.6.0 → 1.7.0

package/README.md

@@ -35,7 +35,7 @@ pi -e ./extensions/auto-mode.ts
 /automode reload    # reload config from disk
 /automode reset     # reset denial counters only
 /automode defaults  # print the built-in rule lists
-/automode config    # current effective config + diagnostics
+/automode config    # effective config, resolved log file path, + diagnostics
 /automode denials   # denial history for this session
 /automode model     # open classifier model selector and save to ~/.pi/agent/automode.json
 /automode model provider/model-id # save classifier model to ~/.pi/agent/automode.json
@@ -52,14 +52,15 @@ AM● a:12 d:2 ca:5 cd:1
 ```
 
 - `AM` — auto-mode prefix; `●` when enabled, `○` when disabled (via config or `/automode off`).
-- `a:` — actions allowed so far (checked minus blocked).
-- `d:` — actions blocked so far, for any reason (permission rule, deterministic hard-deny, or classifier).
-- `ca:` / `cd:` — classifier decisions split into allowed vs denied. These segments appear only after the classifier has run at least once; `d:` counts all blocks, so `d:` is always `>= cd:`.
+- `a:` — actions allowed so far (checked minus denied).
+- `d:` — actions denied so far, for any reason (permission rule, deterministic hard-deny, or classifier).
+- `ca:` / `cd:` — classifier decisions split into allowed vs denied. These segments appear only after the classifier has run at least once; `d:` counts all denials, so `d:` is always `>= cd:`.
 
 ## Docs
 
 - [Defaults and rule-list behavior](docs/defaults.md)
 - [Auto-mode classifier flow](docs/automode-classifier-flow.md)
+- [Observability logging](docs/observability-logging.md)
 
 ## Configuration
 
@@ -73,6 +74,18 @@ It reads `autoMode` from Pi-owned config only:
 
 It deliberately does not read `autoMode` from shared project `.pi/automode.json`, because a checked-in repo should not be able to weaken auto-mode rules. Shared project config may still contribute `permissions.deny` and `permissions.ask`.
 
+To disable pi-automode for the current project, create or edit `.pi/automode.local.json`:
+
+```json
+{
+  "autoMode": {
+    "enabled": false
+  }
+}
+```
+
+This is project-local and should not be committed. Shared project `.pi/automode.json` cannot disable auto-mode.
+
 Set a global default classifier model in `~/.pi/agent/automode.json`; override it per project in `.pi/automode.local.json`.
 
 Example:
@@ -107,6 +120,23 @@ Example:
 
 See [Defaults and rule-list behavior](docs/defaults.md) for built-in `environment`, `allow`, `protectedPaths`, `soft_deny`, and `hard_deny` entries, plus replacement behavior when `$defaults` is omitted.
 
+### Observability logging
+
+Auto mode can write a JSONL decision log next to the current Pi session file, so you can see what it allowed or blocked and how. It is off by default.
+
+```json
+{
+  "autoMode": {
+    "log": {
+      "enabled": true,
+      "classifierIo": false
+    }
+  }
+}
+```
+
+See [Observability logging](docs/observability-logging.md) for the log file location, entry schema, and the `classifierIo` privacy tradeoff. Run `/automode config` to see the resolved log file path.
+
 ### Permission patterns
 
 Permission patterns use Pi tool names, for example `bash(...)`, `write(...)`, `edit(...)`, `read(...)`. The parser accepts capitalized names like `Bash(...)` for convenience, but the documented form is lowercase because Pi tool names are lowercase.

package/docs/automode-classifier-flow.md

@@ -80,6 +80,18 @@ The effective config combines these sources:
 
 Shared project `.pi/automode.json` cannot change `autoMode` rules. That is deliberate: a checked-in repo must not be able to weaken auto-mode. It may still add Pi permission rules.
 
+To disable pi-automode for the current project, set `autoMode.enabled` to `false` in `.pi/automode.local.json`:
+
+```json
+{
+  "autoMode": {
+    "enabled": false
+  }
+}
+```
+
+This affects only that project-local config. Shared project `.pi/automode.json` cannot disable auto-mode.
+
 List settings such as `allow`, `soft_deny`, `hard_deny`, `environment`, and `protectedPaths` support `$defaults`. Omitting `$defaults` replaces the built-ins for that section only. See [Defaults and rule-list behavior](defaults.md).
 
 ## Context captured before classification
@@ -157,7 +169,7 @@ At the moment, all non-read-only actions reach the classifier anyway, so the pro
 
 The classifier call is made by `defaultClassifyAction`.
 
-The model receives a system prompt and one user message.
+The model receives a system prompt and one user message. To inspect exactly what's sent on each call — and the model's raw response — enable `autoMode.log.classifierIo`; see [Observability logging](observability-logging.md).
 
 ### System prompt
 

package/docs/observability-logging.md

@@ -0,0 +1,93 @@
+# Observability logging
+
+Auto mode can write a JSONL decision log next to the current Pi session file, so you can see what it allowed or blocked, and how. It is off by default and fail-open: a write error never changes an allow/block decision.
+
+## Enabling
+
+Set `autoMode.log` in any Pi-owned config source (`~/.pi/agent/automode.json`, `.pi/automode.local.json`, or `PI_AUTOMODE_SETTINGS_JSON`):
+
+```json
+{
+  "autoMode": {
+    "log": {
+      "enabled": true,
+      "classifierIo": false
+    }
+  }
+}
+```
+
+- `enabled` — write one `decision` line per tool-call decision.
+- `classifierIo` — also write the classifier's prompt, raw model responses, and parsed decision for classifier-routed actions. Off by default; see [Privacy](#privacy) below.
+
+Fields merge independently across config scopes (set `enabled` globally and `classifierIo` per project, for example). Shared project `.pi/automode.json` cannot set `log` — it follows the same `autoMode` exclusion as the rest of the config. Shape is validated and reported by `/automode config`.
+
+Logging only writes entries while auto-mode is **enabled**. With auto-mode off, no tool calls reach the hook, so no entries are produced.
+
+## Log file location
+
+The log file is colocated with the current Pi session file, with `-pi-automode` inserted before the extension:
+
+```text
+<session-file>                       →  <dir>/<id>.jsonl
+<session-file>-pi-automode.jsonl     →  <dir>/<id>-pi-automode.jsonl
+```
+
+For example: `~/.pi/agent/sessions/<slug>/<id>-pi-automode.jsonl`. If no session file is set, it falls back to `<sessionDir>/<sessionId>-pi-automode.jsonl`. Run `/automode config` to see the resolved path.
+
+There is one combined file per session. Each line is one JSON object with a `type` discriminator. Entries for the same tool call share a `decisionId`.
+
+## Entry types
+
+### `decision`
+
+One per tool-call decision. Every allow and every block goes through exactly one of these.
+
+| field | meaning |
+| --- | --- |
+| `ts` | ISO timestamp |
+| `decisionId` | links to the `classifier` entry (if any) for the same call |
+| `sessionId` | Pi session id |
+| `cwd` | working directory |
+| `tool` | tool name, e.g. `bash`, `write` |
+| `summary` | `actionSummary` — tool name + input JSON (truncated) |
+| `kind` | enforcement path: `permissions.deny`, `permissions.ask`, `deterministic-hard-deny`, `classifier`, or `read-only` |
+| `outcome` | `allow` or `block` |
+| `reason` | the reason string (classifier reason, or the deterministic/permission reason) |
+| `classifierModel` | the configured classifier model, when relevant |
+
+### `classifier`
+
+Written only for classifier-routed actions, and only when `classifierIo: true`. It precedes the matching `decision` line in the file.
+
+| field | meaning |
+| --- | --- |
+| `ts` | ISO timestamp |
+| `decisionId` | matches the `decision` entry for the same call |
+| `model` | classifier model used, e.g. `anthropic/claude-haiku-4` |
+| `prompt.system` | the full system prompt with `environment`/`allow`/`soft_deny`/`hard_deny` rules interpolated |
+| `prompt.user` | the full user message: loaded project instructions + transcript + action |
+| `attempts` | one entry per classifier attempt (see below) |
+| `durationMs` | total classifier time |
+| `parsed` | the final decision that was acted on (`{ decision, tier, reason }`) |
+
+Each `attempts[]` entry is `{ attempt, response?, parsed?, error?, durationMs }`:
+
+- `response` — `{ stopReason, text }`, the raw model output for that attempt.
+- `parsed` — the decision parsed from the response, or absent if it did not parse.
+- `error` — present when the call threw (network/auth); `response` is then absent.
+
+This records retries and fail-closed cases verbatim: a call that returned garbage, retried, then succeeded shows two attempts with the first `parsed` absent.
+
+## Privacy
+
+`prompt.user` is **exactly what is sent to the classifier model** — loaded project instructions, the recent transcript, and the action being classified. See [Auto-mode classifier flow → What is sent to the classifier](automode-classifier-flow.md#what-is-sent-to-the-classifier) for how that message is assembled and truncated.
+
+The log records this payload locally, but the same data is also sent to the classifier model endpoint on every classifier-routed call. If `classifierModel` points at a cloud provider, that payload leaves the machine. Enable `classifierIo` when debugging classifier behavior or tuning rules; leave it off for routine outcome logging.
+
+## Sizing
+
+- `decision` line: ~0.4–2 KB (driven by `summary`, which carries the tool input, capped at 6 KB).
+- `classifier` line: ~5 KB fixed (the system prompt) plus the transcript, which is variable. In a long session the transcript dominates — roughly 30–40 KB per classifier-routed action.
+
+The transcript is bounded by `autoMode.maxTranscriptLines` (default 80). Lowering it shrinks both the `classifier` log line and what the classifier receives, at the cost of less context for the classifier's decision.

package/extensions/auto-mode/classifier.ts

@@ -6,11 +6,13 @@ import type {
 } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { CLASSIFIER_SYSTEM_PROMPT } from "./constants.ts";
-import { parseModelSpec } from "./model.ts";
+import { formatModelSpec, parseModelSpec } from "./model.ts";
 import { buildTranscript } from "./transcript.ts";
 import type {
   ClassificationDecision,
   ClassifyAction,
+  ClassifierIoAttempt,
+  ClassifyResult,
   EffectiveConfig,
 } from "./types.ts";
 
@@ -71,19 +73,26 @@ export type RetryOptions = {
   maxAttempts?: number;
   maxTokens?: number;
   temperature?: number;
+  /** Receives each attempt's raw response (or error) and parsed decision, for observability logging. */
+  onAttempt?: (attempt: ClassifierIoAttempt) => void;
 };
 
-/** Parse the classifier's JSON-only response. Invalid output is handled fail-closed by the caller. */
-export function parseClassifierDecision(
-  message: AssistantMessage,
-): ClassificationDecision | undefined {
-  const text = message.content
+/** Concatenate all text blocks of an assistant message into a single string. */
+function extractAssistantText(message: AssistantMessage): string {
+  return message.content
     .filter(
       (block): block is { type: "text"; text: string } => block.type === "text",
     )
     .map((block) => block.text)
     .join("\n")
     .trim();
+}
+
+/** Parse the classifier's JSON-only response. Invalid output is handled fail-closed by the caller. */
+export function parseClassifierDecision(
+  message: AssistantMessage,
+): ClassificationDecision | undefined {
+  const text = extractAssistantText(message);
   const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i)?.[1];
   const candidates = [fenced, text, text.match(/\{[\s\S]*\}/)?.[0]].filter(
     Boolean,
@@ -133,9 +142,11 @@ export async function classifyWithRetry(
   const maxAttempts = options.maxAttempts ?? 2;
   const maxTokens = options.maxTokens ?? 1200;
   const temperature = options.temperature ?? 0;
+  const onAttempt = options.onAttempt;
   let lastReason =
     "Classifier response was not valid decision JSON; auto mode fails closed.";
   for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    const started = Date.now();
     let response: AssistantMessage;
     try {
       response = await completeFn(
@@ -150,15 +161,29 @@ export async function classifyWithRetry(
         },
       );
     } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      onAttempt?.({
+        attempt: attempt + 1,
+        error: message,
+        durationMs: Date.now() - started,
+      });
       return {
         decision: "block",
         tier: "none",
-        reason: `Classifier failed; auto mode fails closed: ${
-          error instanceof Error ? error.message : String(error)
-        }`,
+        reason: `Classifier failed; auto mode fails closed: ${message}`,
       };
     }
+    const durationMs = Date.now() - started;
     const decision = parseClassifierDecision(response);
+    onAttempt?.({
+      attempt: attempt + 1,
+      response: {
+        stopReason: response.stopReason,
+        text: extractAssistantText(response),
+      },
+      parsed: decision,
+      durationMs,
+    });
     if (decision) return decision;
     lastReason =
       response.stopReason === "length"
@@ -173,7 +198,7 @@ export const defaultClassifyAction: ClassifyAction = async (
   config,
   action,
   loadedContext,
-): Promise<ClassificationDecision> => {
+): Promise<ClassifyResult> => {
   const classifier = await resolveClassifier(ctx, config);
   if (!classifier) {
     return {
@@ -183,25 +208,35 @@ export const defaultClassifyAction: ClassifyAction = async (
     };
   }
 
+  const systemPrompt = buildClassifierPrompt(config);
+  const userText = `<loaded-project-instructions>\n${
+    loadedContext || "(none)"
+  }\n</loaded-project-instructions>\n\n<transcript>\n${
+    buildTranscript(ctx, config.maxTranscriptLines) || "(none)"
+  }\n</transcript>\n\nLatest action to classify:\n${action}`;
   const userMessage: UserMessage = {
     role: "user",
-    content: [
-      {
-        type: "text",
-        text: `<loaded-project-instructions>\n${
-          loadedContext || "(none)"
-        }\n</loaded-project-instructions>\n\n<transcript>\n${
-          buildTranscript(ctx, config.maxTranscriptLines) || "(none)"
-        }\n</transcript>\n\nLatest action to classify:\n${action}`,
-      },
-    ],
+    content: [{ type: "text", text: userText }],
     timestamp: Date.now(),
   };
 
-  return classifyWithRetry(
+  const attempts: ClassifierIoAttempt[] = [];
+  const started = Date.now();
+  const decision = await classifyWithRetry(
     complete,
     classifier,
-    { systemPrompt: buildClassifierPrompt(config), messages: [userMessage] },
+    { systemPrompt, messages: [userMessage] },
     ctx.signal,
+    { onAttempt: (attempt) => attempts.push(attempt) },
   );
+
+  return {
+    ...decision,
+    io: {
+      model: formatModelSpec(classifier.model),
+      prompt: { system: systemPrompt, user: userText },
+      attempts,
+      durationMs: Date.now() - started,
+    },
+  };
 };

package/extensions/auto-mode/config.ts

@@ -4,6 +4,7 @@ import {
   DEFAULT_ALLOW,
   DEFAULT_ENVIRONMENT,
   DEFAULT_HARD_DENY,
+  DEFAULT_LOG_CONFIG,
   DEFAULT_MAX_TRANSCRIPT_LINES,
   DEFAULT_PROTECTED_PATHS,
   DEFAULT_SOFT_DENY,
@@ -17,6 +18,7 @@ import type {
   ConfigLoadResult,
   EffectiveConfig,
   LoadedSettingsFile,
+  LogConfig,
   SettingsFile,
   SettingsSources,
   ToolPattern,
@@ -102,6 +104,7 @@ export function validateSettingsFile(
         "softDeny",
         "hard_deny",
         "hardDeny",
+        "log",
       ]);
       for (const key of Object.keys(autoMode)) {
         if (!knownAutoMode.has(key)) {
@@ -160,6 +163,9 @@ export function validateSettingsFile(
         "autoMode.hard_deny",
         diagnostics,
       );
+      if (hasOwn(autoMode, "log")) {
+        validateLogSetting(autoMode.log, source, diagnostics);
+      }
     }
   }
 
@@ -228,6 +234,37 @@ function finalizeRuleSetting(accumulator: RuleAccumulator): string[] {
   return [...new Set([...base, ...accumulator.entries])];
 }
 
+function validateLogSetting(
+  value: unknown,
+  source: string,
+  diagnostics: string[],
+): void {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    diagnostics.push(`${source}: autoMode.log must be an object`);
+    return;
+  }
+  const log = value as Record<string, unknown>;
+  if (hasOwn(log, "enabled") && typeof log.enabled !== "boolean") {
+    diagnostics.push(`${source}: autoMode.log.enabled must be a boolean`);
+  }
+  if (
+    hasOwn(log, "classifierIo") && typeof log.classifierIo !== "boolean"
+  ) {
+    diagnostics.push(`${source}: autoMode.log.classifierIo must be a boolean`);
+  }
+}
+
+function mergeLog(
+  base: LogConfig,
+  patch: Partial<LogConfig> | undefined,
+): LogConfig {
+  if (!patch) return base;
+  return {
+    enabled: patch.enabled ?? base.enabled,
+    classifierIo: patch.classifierIo ?? base.classifierIo,
+  };
+}
+
 function applyAutoModeScalars(
   base: EffectiveConfig,
   settings: AutoModeSettings | undefined,
@@ -238,6 +275,7 @@ function applyAutoModeScalars(
     enabled: settings.enabled ?? base.enabled,
     classifierModel: settings.classifierModel ?? base.classifierModel,
     maxTranscriptLines: settings.maxTranscriptLines ?? base.maxTranscriptLines,
+    log: mergeLog(base.log, settings.log),
   };
 }
 
@@ -276,6 +314,7 @@ export function buildEffectiveConfigFromSources(
     hardDeny: [...DEFAULT_HARD_DENY],
     permissionDeny: [],
     permissionAsk: [],
+    log: { ...DEFAULT_LOG_CONFIG },
   };
 
   const globalSettings = sources.globalSettings ?? [];

package/extensions/auto-mode/constants.ts

@@ -166,3 +166,9 @@ export const PROFILE_FILES = new Set([
 ]);
 
 export const READ_ONLY_TOOLS = new Set(["read", "grep", "find", "ls"]);
+
+/** Default observability log config: off, classifier I/O off. */
+export const DEFAULT_LOG_CONFIG = {
+  enabled: false,
+  classifierIo: false,
+};

package/extensions/auto-mode/extension.ts

@@ -19,6 +19,12 @@ import {
   writeGlobalClassifierModel,
 } from "./config.ts";
 import { deterministicHardDeny } from "./hard-deny.ts";
+import {
+  createLogger,
+  newDecisionId,
+  resolveLogPath,
+  type Logger,
+} from "./log.ts";
 import { formatModelSpec, parseModelSpec } from "./model.ts";
 import { promptForClassifierModel } from "./model-selector.ts";
 import { matchesToolPattern } from "./permissions.ts";
@@ -35,7 +41,9 @@ import { loadedContextFromSystemPromptOptions } from "./transcript.ts";
 import type {
   AutoModeState,
   ClassifyAction,
+  ClassifyResult,
   ConfigLoadResult,
+  DecisionKind,
   DenialRecord,
   EffectiveConfig,
 } from "./types.ts";
@@ -50,6 +58,31 @@ export type PiAutomodeOptions = {
   saveClassifierModel?: (classifierModel: string) => void;
 };
 
+type LogCtx = {
+  logger: Logger;
+  decisionId: string;
+  classifierModel?: string;
+};
+
+/** Append a classifier I/O entry when classifier logging is enabled. */
+function logClassifierIo(decision: ClassifyResult, log: LogCtx): void {
+  if (!log.logger.enabled || !log.logger.classifierIo || !decision.io) return;
+  log.logger.append({
+    type: "classifier",
+    ts: new Date().toISOString(),
+    decisionId: log.decisionId,
+    model: decision.io.model,
+    prompt: decision.io.prompt,
+    attempts: decision.io.attempts,
+    durationMs: decision.io.durationMs,
+    parsed: {
+      decision: decision.decision,
+      tier: decision.tier,
+      reason: decision.reason,
+    },
+  });
+}
+
 /** Create a Pi extension instance. Default export uses production dependencies. */
 export function createPiAutomode(options: PiAutomodeOptions = {}) {
   const loadConfigWithDiagnostics = options.loadConfig
@@ -101,6 +134,7 @@ export function createPiAutomode(options: PiAutomodeOptions = {}) {
     function block(
       ctx: ExtensionContext,
       denial: DenialRecord,
+      logCtx: LogCtx,
     ): { block: true; reason: string } {
       state.blockedActions += 1;
       state.lastDecision = "block";
@@ -108,6 +142,21 @@ export function createPiAutomode(options: PiAutomodeOptions = {}) {
       pushDenial(state, denial);
       persist();
       updateUi(ctx);
+      if (logCtx.logger.enabled) {
+        logCtx.logger.append({
+          type: "decision",
+          ts: new Date().toISOString(),
+          decisionId: logCtx.decisionId,
+          sessionId: ctx.sessionManager.getSessionId?.(),
+          cwd: ctx.cwd,
+          tool: denial.toolName,
+          summary: denial.action,
+          kind: denial.kind,
+          outcome: "block",
+          reason: denial.reason,
+          classifierModel: logCtx.classifierModel,
+        });
+      }
       if (ctx.hasUI) {
         ctx.ui.notify(
           `Auto mode blocked ${denial.toolName}: ${denial.reason}`,
@@ -117,6 +166,36 @@ export function createPiAutomode(options: PiAutomodeOptions = {}) {
       return { block: true, reason: `[pi-automode] ${denial.reason}` };
     }
 
+    function allow(
+      ctx: ExtensionContext,
+      kind: DecisionKind,
+      reason: string,
+      toolName: string,
+      summary: string,
+      logCtx: LogCtx,
+    ): undefined {
+      state.lastDecision = "allow";
+      state.lastReason = reason;
+      persist();
+      updateUi(ctx);
+      if (logCtx.logger.enabled) {
+        logCtx.logger.append({
+          type: "decision",
+          ts: new Date().toISOString(),
+          decisionId: logCtx.decisionId,
+          sessionId: ctx.sessionManager.getSessionId?.(),
+          cwd: ctx.cwd,
+          tool: toolName,
+          summary,
+          kind,
+          outcome: "allow",
+          reason,
+          classifierModel: logCtx.classifierModel,
+        });
+      }
+      return undefined;
+    }
+
     pi.on("session_start", (_event, ctx) => {
       loadResult = loadConfigWithDiagnostics(ctx.cwd);
       config = loadResult.config;
@@ -147,6 +226,17 @@ export function createPiAutomode(options: PiAutomodeOptions = {}) {
       const input = event.input as Record<string, unknown>;
       const summary = actionSummary(event.toolName, input);
       state.checkedActions += 1;
+      const logCtx: LogCtx = {
+        logger: createLogger({
+          enabled: cfg.log.enabled,
+          classifierIo: cfg.log.classifierIo,
+          sessionFile: ctx.sessionManager.getSessionFile?.(),
+          sessionDir: ctx.sessionManager.getSessionDir?.() ?? ctx.cwd,
+          sessionId: ctx.sessionManager.getSessionId?.() ?? "unknown",
+        }),
+        decisionId: newDecisionId(),
+        classifierModel: cfg.classifierModel,
+      };
 
       for (const pattern of cfg.permissionDeny) {
         if (matchesToolPattern(pattern, event.toolName, input, ctx.cwd)) {
@@ -156,7 +246,7 @@ export function createPiAutomode(options: PiAutomodeOptions = {}) {
             reason: `Blocked by permissions.deny: ${pattern.raw}`,
             action: summary,
             kind: "permissions.deny",
-          });
+          }, logCtx);
         }
       }
 
@@ -172,7 +262,7 @@ export function createPiAutomode(options: PiAutomodeOptions = {}) {
               `Matched permissions.ask (${pattern.raw}) but no UI is available`,
             action: summary,
             kind: "permissions.ask",
-          });
+          }, logCtx);
         }
         const allowed = await ctx.ui.confirm(
           "Auto mode permission ask",
@@ -186,7 +276,7 @@ export function createPiAutomode(options: PiAutomodeOptions = {}) {
             reason: `Declined permissions.ask: ${pattern.raw}`,
             action: summary,
             kind: "permissions.ask",
-          });
+          }, logCtx);
         }
       }
 
@@ -202,15 +292,18 @@ export function createPiAutomode(options: PiAutomodeOptions = {}) {
           reason: deterministicReason,
           action: summary,
           kind: "deterministic-hard-deny",
-        });
+        }, logCtx);
       }
 
       if (READ_ONLY_TOOLS.has(event.toolName)) {
-        state.lastDecision = "allow";
-        state.lastReason = `Read-only built-in tool: ${event.toolName}`;
-        persist();
-        updateUi(ctx);
-        return undefined;
+        return allow(
+          ctx,
+          "read-only",
+          `Read-only built-in tool: ${event.toolName}`,
+          event.toolName,
+          summary,
+          logCtx,
+        );
       }
 
       // Protected paths go to the classifier regardless of allow rules.
@@ -218,13 +311,17 @@ export function createPiAutomode(options: PiAutomodeOptions = {}) {
         const path = resolveInputPath(ctx.cwd, input.path);
         if (path && isProtectedPath(path, ctx.cwd, cfg.protectedPaths)) {
           const decision = await classify(ctx, cfg, summary, loadedContext);
+          logClassifierIo(decision, logCtx);
           if (decision.decision === "allow") {
             state.classifierAllowed += 1;
-            state.lastDecision = "allow";
-            state.lastReason = decision.reason;
-            persist();
-            updateUi(ctx);
-            return undefined;
+            return allow(
+              ctx,
+              "classifier",
+              decision.reason,
+              event.toolName,
+              summary,
+              logCtx,
+            );
           }
           state.classifierDenied += 1;
           return block(ctx, {
@@ -233,18 +330,22 @@ export function createPiAutomode(options: PiAutomodeOptions = {}) {
             reason: decision.reason,
             action: summary,
             kind: "classifier",
-          });
+          }, logCtx);
         }
       }
 
       const decision = await classify(ctx, cfg, summary, loadedContext);
+      logClassifierIo(decision, logCtx);
       if (decision.decision === "allow") {
         state.classifierAllowed += 1;
-        state.lastDecision = "allow";
-        state.lastReason = decision.reason;
-        persist();
-        updateUi(ctx);
-        return undefined;
+        return allow(
+          ctx,
+          "classifier",
+          decision.reason,
+          event.toolName,
+          summary,
+          logCtx,
+        );
       }
 
       state.classifierDenied += 1;
@@ -254,7 +355,7 @@ export function createPiAutomode(options: PiAutomodeOptions = {}) {
         reason: decision.reason,
         action: summary,
         kind: "classifier",
-      });
+      }, logCtx);
     });
 
     async function handleAutomodeCommand(
@@ -328,9 +429,18 @@ export function createPiAutomode(options: PiAutomodeOptions = {}) {
         return;
       }
       if (command === "config") {
+        const logFile = resolveLogPath(
+          ctx.sessionManager.getSessionFile?.(),
+          ctx.sessionManager.getSessionDir?.() ?? ctx.cwd,
+          ctx.sessionManager.getSessionId?.() ?? "unknown",
+        );
         ctx.ui.notify(
           safeJson(
-            { config: effectiveConfig(), diagnostics: configDiagnostics },
+            {
+              config: effectiveConfig(),
+              logFile,
+              diagnostics: configDiagnostics,
+            },
             16000,
           ),
           configDiagnostics.length > 0 ? "warning" : "info",

package/extensions/auto-mode/log.ts

@@ -0,0 +1,100 @@
+import { randomBytes } from "node:crypto";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { basename, dirname, extname, join } from "node:path";
+import type {
+  ClassifierIoAttempt,
+  ClassificationDecision,
+  DecisionKind,
+} from "./types.ts";
+
+/** A final allow/block decision for a tool call. */
+export type DecisionLogEntry = {
+  type: "decision";
+  ts: string;
+  decisionId: string;
+  sessionId?: string;
+  cwd: string;
+  tool: string;
+  summary: string;
+  kind: DecisionKind;
+  outcome: "allow" | "block";
+  reason: string;
+  classifierModel?: string;
+};
+
+/** The classifier prompt, raw responses, and parsed decision for one action. */
+export type ClassifierLogEntry = {
+  type: "classifier";
+  ts: string;
+  decisionId: string;
+  model: string;
+  prompt: { system: string; user: string };
+  attempts: ClassifierIoAttempt[];
+  durationMs: number;
+  parsed: ClassificationDecision;
+};
+
+export type LogEntry = DecisionLogEntry | ClassifierLogEntry;
+
+export type Logger = {
+  enabled: boolean;
+  classifierIo: boolean;
+  append(entry: LogEntry): void;
+};
+
+export type LoggerOptions = {
+  enabled: boolean;
+  classifierIo: boolean;
+  sessionFile?: string;
+  sessionDir: string;
+  sessionId: string;
+};
+
+/** Short id linking a classifier entry to its decision entry in the same file. */
+export function newDecisionId(): string {
+  return randomBytes(4).toString("hex");
+}
+
+/**
+ * Derive the log file path from the current session: the session file's
+ * directory with `-pi-automode` inserted before the extension. Falls back to
+ * `<sessionDir>/<sessionId>-pi-automode.jsonl` when no session file is set.
+ */
+export function resolveLogPath(
+  sessionFile: string | undefined,
+  sessionDir: string,
+  sessionId: string,
+): string {
+  if (sessionFile) {
+    const ext = extname(sessionFile);
+    const stem = ext ? basename(sessionFile, ext) : basename(sessionFile);
+    return join(dirname(sessionFile), `${stem}-pi-automode${ext}`);
+  }
+  return join(sessionDir, `${sessionId}-pi-automode.jsonl`);
+}
+
+/** Append one JSON object as a line. Failures are swallowed: logging must
+ *  never change a safety decision. */
+function appendJsonl(path: string, entry: unknown): void {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, `${JSON.stringify(entry)}\n`, "utf8");
+  } catch {
+    // Fail open.
+  }
+}
+
+/** Build a logger bound to one session's log path. No-ops when disabled. */
+export function createLogger(opts: LoggerOptions): Logger {
+  const { enabled, classifierIo } = opts;
+  const path = resolveLogPath(opts.sessionFile, opts.sessionDir, opts.sessionId);
+  return {
+    enabled,
+    classifierIo,
+    append(entry) {
+      if (!enabled) return;
+      if (entry.type === "classifier" && !classifierIo) return;
+      appendJsonl(path, entry);
+    },
+  };
+}

package/extensions/auto-mode/types.ts

@@ -1,5 +1,12 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
+/** Observability log configuration. Off by default. */
+export type LogConfig = {
+  enabled: boolean;
+  /** When true, also log classifier prompt/response payloads. */
+  classifierIo: boolean;
+};
+
 export type AutoModeSettings = {
   enabled?: boolean;
   classifierModel?: string;
@@ -11,6 +18,7 @@ export type AutoModeSettings = {
   softDeny?: unknown;
   hard_deny?: unknown;
   hardDeny?: unknown;
+  log?: Partial<LogConfig>;
 };
 
 export type SettingsFile = {
@@ -44,6 +52,7 @@ export type EffectiveConfig = {
   hardDeny: string[];
   permissionDeny: ToolPattern[];
   permissionAsk: ToolPattern[];
+  log: LogConfig;
 };
 
 export type AutoModeState = {
@@ -70,12 +79,35 @@ export type DenialRecord = {
     | "setup";
 };
 
+/** Denial kind plus the read-only fast path, used for decision log entries. */
+export type DecisionKind = DenialRecord["kind"] | "read-only";
+
 export type ClassificationDecision = {
   decision: "allow" | "block";
   tier: "hard_deny" | "soft_deny" | "allow" | "explicit_intent" | "none";
   reason: string;
 };
 
+/** One classifier attempt: the raw model response (or error) and parsed decision. */
+export type ClassifierIoAttempt = {
+  attempt: number;
+  response?: { stopReason?: string; text: string };
+  parsed?: ClassificationDecision;
+  error?: string;
+  durationMs: number;
+};
+
+/** Full classifier I/O for an action, surfaced for optional observability logging. */
+export type ClassifierIo = {
+  model: string;
+  prompt: { system: string; user: string };
+  attempts: ClassifierIoAttempt[];
+  durationMs: number;
+};
+
+/** Classification decision plus the I/O that produced it (when available). */
+export type ClassifyResult = ClassificationDecision & { io?: ClassifierIo };
+
 export type SettingsSources = {
   globalSettings?: SettingsFile[];
   projectLocalSettings?: SettingsFile[];
@@ -93,4 +125,4 @@ export type ClassifyAction = (
   config: EffectiveConfig,
   action: string,
   loadedContext: string,
-) => Promise<ClassificationDecision>;
+) => Promise<ClassifyResult>;

package/extensions/auto-mode.ts

@@ -11,6 +11,7 @@ export * from "./auto-mode/config.ts";
 export * from "./auto-mode/constants.ts";
 export * from "./auto-mode/extension.ts";
 export * from "./auto-mode/hard-deny.ts";
+export * from "./auto-mode/log.ts";
 export * from "./auto-mode/model.ts";
 export * from "./auto-mode/model-selector.ts";
 export * from "./auto-mode/paths.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@czottmann/pi-automode",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Claude Code-style auto mode guardrail for pi.",
   "repository": {
     "url": "https://github.com/czottmann/pi-automode"