Harden sidecar evidence recording

Author: chenbo

docs/getting-started.md

@@ -48,7 +48,7 @@ opencode-plusplus --pure
 
 `opencode-plusplus` runs preflight, ensures `.agent-context`, writes `.opencode/plugins/opencode-plusplus.ts`, prepares OpenCode commands/agent files, prints a compact readiness summary, and launches `opencode .`.
 
-The sidecar listens for `tool.execute.before`, `tool.execute.after`, `file.edited`, and `session.idle` events. Before a tool runs, it blocks dangerous commands, hallucinated package scripts / Makefile targets, and protected / secret paths. After a tool runs, it records command evidence under `.agent-context/traces/`, including exit code, timestamps, stdout/stderr hashes, working-tree hashes, and touched files. On idle, it runs dirty/debounced incremental verification.
+The sidecar listens for `tool.execute.before`, `tool.execute.after`, `file.edited`, and `session.idle` events. Before a tool runs, it blocks dangerous commands, hallucinated package scripts / Makefile targets, and protected / secret paths. After a tool runs, it records command evidence under `.agent-context/traces/`, including exit code when available, timestamps, stdout/stderr hashes, sanitized and truncated output previews, working-tree hashes, and touched files. Long stdout/stderr is passed through a JSON evidence file instead of CLI arguments. On idle, it runs dirty/debounced incremental verification.
 
 For the full interactive flow, generated files, and mode comparison, read [OpenCode Transparent Sidecar Mode](integrations/opencode-sidecar.md).
 

docs/integrations/opencode-sidecar.md

@@ -64,7 +64,7 @@ opencode-plusplus
 The generated OpenCode plugin listens for:
 
 - `tool.execute.before`: blocks dangerous commands, hallucinated package scripts / Makefile targets, protected paths, and secret paths.
-- `tool.execute.after`: records command, exit code, timestamps, stdout/stderr hashes, working-tree hashes, and touched files.
+- `tool.execute.after`: records command, exit code when available, timestamps, stdout/stderr hashes, sanitized and truncated output previews, working-tree hashes, and touched files. Large output is passed to `record-tool` through a JSON evidence file instead of command-line arguments.
 - `file.edited` and `file.watcher.updated`: marks the repository dirty.
 - `session.idle`: runs dirty/debounced incremental verification.
 
@@ -82,10 +82,11 @@ The generated OpenCode plugin listens for:
 .agent-context/sidecar/hallucination.md
 .agent-context/sidecar/regression.md
 .agent-context/traces/opencode-sidecar-events.jsonl
+.agent-context/traces/tool-evidence/opencode-tool-*.json
 .agent-context/traces/opencode-session-<id>.json
 ```
 
-`.agent-context/traces/opencode-sidecar-events.jsonl` is the low-level event stream. `.agent-context/traces/opencode-session-<id>.json` is the normalized execution trace consumed by Evidence Guard and Policy Engine.
+`.agent-context/traces/opencode-sidecar-events.jsonl` is the low-level event stream. `.agent-context/traces/tool-evidence/opencode-tool-*.json` stores sanitized after-tool evidence payloads used by `record-tool`; it does not store raw long stdout/stderr. `.agent-context/traces/opencode-session-<id>.json` is the normalized execution trace consumed by Evidence Guard and Policy Engine.
 
 ## Common Commands
 

docs/reference/cli-reference.md

@@ -97,7 +97,7 @@ Use `--quiet` for sidecar automation; it only prints when blockers are found.
 
 `opencode-plusplus sidecar check-command` is the pre-execution command guard used by the OpenCode sidecar `tool.execute.before` hook. It checks package scripts from `package.json`, Makefile targets, dangerous shell patterns, and protected / secret paths. It exits non-zero when execution should be blocked.
 
-`opencode-plusplus sidecar record-tool` is an internal post-execution evidence recorder used by the OpenCode sidecar `tool.execute.after` hook. It writes `.agent-context/traces/opencode-sidecar-events.jsonl` and `.agent-context/traces/opencode-session-<id>.json` with command, exit code, timestamps, stdout/stderr hashes, working-tree hashes, and touched files. Users normally do not call it manually.
+`opencode-plusplus sidecar record-tool` is an internal post-execution evidence recorder used by the OpenCode sidecar `tool.execute.after` hook. The sidecar normally calls it with `--input-json <path>` so long stdout/stderr is not exposed through command-line arguments. It writes `.agent-context/traces/opencode-sidecar-events.jsonl`, `.agent-context/traces/tool-evidence/opencode-tool-*.json`, and `.agent-context/traces/opencode-session-<id>.json` with command, exit code when available, timestamps, stdout/stderr hashes, sanitized/truncated output previews, working-tree hashes, and touched files. Missing exit code is recorded as `unknown`, not success. Users normally do not call it manually.
 
 ## OpenCode Preset
 

src/cli/commands/sidecar.ts

@@ -1,4 +1,5 @@
 import type { Command } from "commander";
+import { readFileSync } from "node:fs";
 import {
   checkOpencodeSidecarCommand,
   recordOpencodeSidecarTool,
@@ -46,7 +47,7 @@ export function registerSidecarCommands(program: Command): void {
   sidecar
     .command("record-tool")
     .argument("[repo]", "repository path", ".")
-    .requiredOption("--tool <tool>", "OpenCode tool name that just executed")
+    .option("--tool <tool>", "OpenCode tool name that just executed")
     .option("--command <command>", "command executed by the tool")
     .option("--exit-code <code>", "tool or command exit code", parseNullableInteger)
     .option("--started-at <iso>", "tool start timestamp")
@@ -55,10 +56,17 @@ export function registerSidecarCommands(program: Command): void {
     .option("--stderr <text>", "captured stderr text")
     .option("--stdout-hash <sha256>", "stdout content hash")
     .option("--stderr-hash <sha256>", "stderr content hash")
+    .option("--stdout-preview <text>", "sanitized stdout preview")
+    .option("--stderr-preview <text>", "sanitized stderr preview")
+    .option("--stdout-truncated", "stdout preview was truncated")
+    .option("--stderr-truncated", "stderr preview was truncated")
+    .option("--stdout-redacted", "stdout preview was redacted")
+    .option("--stderr-redacted", "stderr preview was redacted")
     .option("--working-tree-hash-before <sha256>", "working tree hash before tool execution")
     .option("--working-tree-hash-after <sha256>", "working tree hash after tool execution")
     .option("--session-id <id>", "OpenCode session id")
     .option("--path <path...>", "path(s) touched by the tool")
+    .option("--input-json <path>", "JSON evidence payload path produced by the OpenCode++ sidecar plugin")
     .option("--json", "print machine-readable tool record result")
     .description("Record OpenCode tool.execute.after evidence into sidecar event logs and execution traces.")
     .action(
@@ -74,29 +82,106 @@ export function registerSidecarCommands(program: Command): void {
           stderr?: string;
           stdoutHash?: string;
           stderrHash?: string;
+          stdoutPreview?: string;
+          stderrPreview?: string;
+          stdoutTruncated?: boolean;
+          stderrTruncated?: boolean;
+          stdoutRedacted?: boolean;
+          stderrRedacted?: boolean;
           workingTreeHashBefore?: string;
           workingTreeHashAfter?: string;
           sessionId?: string;
           path?: string[];
+          inputJson?: string;
           json?: boolean;
         }
       ) => {
+        const payload = readRecordToolInput(options.inputJson);
         const result = recordOpencodeSidecarTool(repo, {
-          tool: options.tool,
-          command: options.command,
-          exitCode: options.exitCode,
-          startedAt: options.startedAt,
-          finishedAt: options.finishedAt,
-          stdout: options.stdout,
-          stderr: options.stderr,
-          stdoutHash: options.stdoutHash,
-          stderrHash: options.stderrHash,
-          workingTreeHashBefore: options.workingTreeHashBefore,
-          workingTreeHashAfter: options.workingTreeHashAfter,
-          sessionId: options.sessionId,
-          paths: options.path
+          ...payload,
+          tool: options.tool ?? payload.tool,
+          command: options.command ?? payload.command,
+          exitCode: options.exitCode ?? payload.exitCode,
+          startedAt: options.startedAt ?? payload.startedAt,
+          finishedAt: options.finishedAt ?? payload.finishedAt,
+          stdout: options.stdout ?? payload.stdout,
+          stderr: options.stderr ?? payload.stderr,
+          stdoutHash: options.stdoutHash ?? payload.stdoutHash,
+          stderrHash: options.stderrHash ?? payload.stderrHash,
+          stdoutPreview: options.stdoutPreview ?? payload.stdoutPreview,
+          stderrPreview: options.stderrPreview ?? payload.stderrPreview,
+          stdoutTruncated: options.stdoutTruncated ?? payload.stdoutTruncated,
+          stderrTruncated: options.stderrTruncated ?? payload.stderrTruncated,
+          stdoutRedacted: options.stdoutRedacted ?? payload.stdoutRedacted,
+          stderrRedacted: options.stderrRedacted ?? payload.stderrRedacted,
+          workingTreeHashBefore: options.workingTreeHashBefore ?? payload.workingTreeHashBefore,
+          workingTreeHashAfter: options.workingTreeHashAfter ?? payload.workingTreeHashAfter,
+          sessionId: options.sessionId ?? payload.sessionId,
+          paths: options.path ?? payload.paths
         });
         console.log(options.json ? JSON.stringify(result, null, 2) : renderOpencodeSidecarToolRecord(result));
       }
     );
 }
+
+function readRecordToolInput(inputJson?: string): RecordToolInputPayload {
+  if (!inputJson) return {};
+  const parsed = JSON.parse(readFileSync(inputJson, "utf8")) as Record<string, unknown>;
+  return {
+    tool: stringValue(parsed.tool),
+    command: stringValue(parsed.command),
+    exitCode: numberOrNull(parsed.exitCode),
+    startedAt: stringValue(parsed.startedAt),
+    finishedAt: stringValue(parsed.finishedAt),
+    stdout: stringValue(parsed.stdout),
+    stderr: stringValue(parsed.stderr),
+    stdoutHash: stringValue(parsed.stdoutHash),
+    stderrHash: stringValue(parsed.stderrHash),
+    stdoutPreview: stringValue(parsed.stdoutPreview),
+    stderrPreview: stringValue(parsed.stderrPreview),
+    stdoutTruncated: booleanValue(parsed.stdoutTruncated),
+    stderrTruncated: booleanValue(parsed.stderrTruncated),
+    stdoutRedacted: booleanValue(parsed.stdoutRedacted),
+    stderrRedacted: booleanValue(parsed.stderrRedacted),
+    workingTreeHashBefore: stringValue(parsed.workingTreeHashBefore),
+    workingTreeHashAfter: stringValue(parsed.workingTreeHashAfter),
+    sessionId: stringValue(parsed.sessionId),
+    paths: Array.isArray(parsed.paths) ? parsed.paths.filter((item): item is string => typeof item === "string") : undefined
+  };
+}
+
+interface RecordToolInputPayload {
+  tool?: string;
+  command?: string;
+  exitCode?: number | null;
+  startedAt?: string;
+  finishedAt?: string;
+  stdout?: string;
+  stderr?: string;
+  stdoutHash?: string;
+  stderrHash?: string;
+  stdoutPreview?: string;
+  stderrPreview?: string;
+  stdoutTruncated?: boolean;
+  stderrTruncated?: boolean;
+  stdoutRedacted?: boolean;
+  stderrRedacted?: boolean;
+  workingTreeHashBefore?: string;
+  workingTreeHashAfter?: string;
+  sessionId?: string;
+  paths?: string[];
+}
+
+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 numberOrNull(value: unknown): number | null | undefined {
+  if (typeof value === "number") return value;
+  if (value === null) return null;
+  return undefined;
+}

src/harness/observability/execution-trace.ts

@@ -28,6 +28,12 @@ export interface ExecutionTraceStep {
   finishedAt?: string;
   stdoutHash?: string;
   stderrHash?: string;
+  stdoutPreview?: string;
+  stderrPreview?: string;
+  stdoutTruncated?: boolean;
+  stderrTruncated?: boolean;
+  stdoutRedacted?: boolean;
+  stderrRedacted?: boolean;
   workingTreeHashBefore?: string;
   workingTreeHashAfter?: string;
 }
@@ -66,6 +72,12 @@ export interface TraceStepInput {
   finishedAt?: string;
   stdoutHash?: string;
   stderrHash?: string;
+  stdoutPreview?: string;
+  stderrPreview?: string;
+  stdoutTruncated?: boolean;
+  stderrTruncated?: boolean;
+  stdoutRedacted?: boolean;
+  stderrRedacted?: boolean;
   workingTreeHashBefore?: string;
   workingTreeHashAfter?: string;
 }
@@ -138,6 +150,12 @@ export function appendExecutionTraceStep(root: string, traceId: string, input: T
     finishedAt: input.finishedAt,
     stdoutHash: input.stdoutHash,
     stderrHash: input.stderrHash,
+    stdoutPreview: input.stdoutPreview,
+    stderrPreview: input.stderrPreview,
+    stdoutTruncated: input.stdoutTruncated,
+    stderrTruncated: input.stderrTruncated,
+    stdoutRedacted: input.stdoutRedacted,
+    stderrRedacted: input.stderrRedacted,
     workingTreeHashBefore: input.workingTreeHashBefore,
     workingTreeHashAfter: input.workingTreeHashAfter
   });

src/integrations/opencode/output-sanitizer.ts

@@ -0,0 +1,54 @@
+import { createHash } from "node:crypto";
+
+const PREVIEW_EDGE_CHARS = 400;
+const REDACTION_PATTERNS: Array<{ pattern: RegExp; replacement: string }> = [
+  { pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/gi, replacement: "[REDACTED_PRIVATE_KEY]" },
+  { pattern: /\bauthorization\s*:\s*(?:Bearer|Basic)?\s*[^ \r\n]+/gi, replacement: "[REDACTED_AUTH]" },
+  { pattern: /\b(?:api[_-]?key|token|secret|password|passwd|pwd|cookie|authorization)\s*[:=]\s*["']?[^"'\s]+/gi, replacement: "[REDACTED_SECRET]" },
+  { pattern: /\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, replacement: "[REDACTED_AUTH]" },
+  { pattern: /\b[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\b/g, replacement: "[REDACTED_JWT]" },
+  { pattern: /\b(?:sk|pk|ghp|gho|github_pat|xox[baprs])[-_A-Za-z0-9]{16,}\b/gi, replacement: "[REDACTED_TOKEN]" }
+];
+
+export interface SanitizedOutput {
+  hash: string;
+  preview: string;
+  truncated: boolean;
+  redacted: boolean;
+  bytes: number;
+}
+
+export function sanitizeToolOutput(value: unknown): SanitizedOutput {
+  const text = String(value ?? "");
+  const hash = hashText(text);
+  const redacted = redactSecrets(text);
+  const truncated = redacted.text.length > PREVIEW_EDGE_CHARS * 2;
+  const preview = truncated
+    ? `${redacted.text.slice(0, PREVIEW_EDGE_CHARS)}\n...[truncated ${redacted.text.length - PREVIEW_EDGE_CHARS * 2} chars]...\n${redacted.text.slice(-PREVIEW_EDGE_CHARS)}`
+    : redacted.text;
+  return {
+    hash,
+    preview,
+    truncated,
+    redacted: redacted.redacted,
+    bytes: Buffer.byteLength(text, "utf8")
+  };
+}
+
+export function hashText(text: unknown): string {
+  return createHash("sha256")
+    .update(String(text ?? ""))
+    .digest("hex");
+}
+
+function redactSecrets(text: string): { text: string; redacted: boolean } {
+  let redacted = false;
+  let result = text;
+  for (const { pattern, replacement } of REDACTION_PATTERNS) {
+    result = result.replace(pattern, () => {
+      redacted = true;
+      return replacement;
+    });
+  }
+  return { text: result, redacted };
+}

src/integrations/opencode/plugin-runtime/index.ts

@@ -1,7 +1,10 @@
 import { spawnSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { sanitizeToolOutput } from "../output-sanitizer.js";
 import { runCommandGuard } from "./command-guard.js";
 import { createSidecarRecorder, type OpenCodeSidecarRuntimeContext } from "./events.js";
-import { exitCodeFromOutput, outputText, toolKey } from "./evidence.js";
+import { exitCodeFromOutput, hashText, outputText, stableJson, toolKey } from "./evidence.js";
 import { createIdleVerifier } from "./idle-verify.js";
 import { commandFromTool, pathsFromTool } from "./paths.js";
 import { currentSidecarWorkingTreeHash } from "./worktree-hash.js";
@@ -37,32 +40,35 @@ export async function createOpenCodePlusPlusSidecar(context: OpenCodeSidecarRunt
       };
       toolStarts.delete(key);
 
-      const cliArgs = [
-        "sidecar",
-        "record-tool",
-        context.directory,
-        "--json",
-        "--tool",
-        String(tool),
-        "--exit-code",
-        String(exitCodeFromOutput(output) ?? 0),
-        "--started-at",
-        started.startedAt,
-        "--finished-at",
-        new Date().toISOString(),
-        "--working-tree-hash-before",
-        started.workingTreeHashBefore,
-        "--working-tree-hash-after",
-        currentSidecarWorkingTreeHash(context.directory)
-      ];
-      if (command) cliArgs.push("--command", command);
+      const finishedAt = new Date().toISOString();
+      const exitCode = exitCodeFromOutput(output);
       const sessionId = inputRecord.sessionID ?? inputRecord.sessionId ?? outputRecord.sessionID ?? outputRecord.sessionId;
-      if (sessionId) cliArgs.push("--session-id", String(sessionId));
       const stdout = outputText(output, ["stdout", "output", "text"]);
       const stderr = outputText(output, ["stderr", "error"]);
-      if (stdout) cliArgs.push("--stdout", stdout);
-      if (stderr) cliArgs.push("--stderr", stderr);
-      for (const file of paths) cliArgs.push("--path", file);
+      const stdoutEvidence = sanitizeToolOutput(stdout);
+      const stderrEvidence = sanitizeToolOutput(stderr);
+      const payload = {
+        tool: String(tool),
+        command,
+        exitCode,
+        startedAt: started.startedAt,
+        finishedAt,
+        workingTreeHashBefore: started.workingTreeHashBefore,
+        workingTreeHashAfter: currentSidecarWorkingTreeHash(context.directory),
+        sessionId: sessionId ? String(sessionId) : undefined,
+        paths,
+        stdoutHash: stdoutEvidence.hash,
+        stdoutPreview: stdoutEvidence.preview,
+        stdoutTruncated: stdoutEvidence.truncated,
+        stdoutRedacted: stdoutEvidence.redacted,
+        stderrHash: stderrEvidence.hash,
+        stderrPreview: stderrEvidence.preview,
+        stderrTruncated: stderrEvidence.truncated,
+        stderrRedacted: stderrEvidence.redacted
+      };
+      const inputJson = writeToolEvidenceInput(context.directory, tool, args, payload);
+
+      const cliArgs = ["sidecar", "record-tool", context.directory, "--json", "--input-json", inputJson];
 
       const recordResult = spawnSync("opencode-plusplus", cliArgs, {
         cwd: context.directory,
@@ -115,3 +121,11 @@ export async function createOpenCodePlusPlusSidecar(context: OpenCodeSidecarRunt
     }
   };
 }
+
+function writeToolEvidenceInput(directory: string, tool: unknown, args: unknown, payload: Record<string, unknown>): string {
+  const dir = path.join(directory, ".agent-context", "traces", "tool-evidence");
+  mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, `opencode-tool-${Date.now()}-${hashText(`${String(tool ?? "unknown")}:${stableJson(args)}`).slice(0, 12)}.json`);
+  writeFileSync(file, `${JSON.stringify(payload)}\n`, "utf8");
+  return file;
+}