fix(core): redact image bytes from debug dumps by default

CHANGELOG.md

@@ -18,6 +18,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   `TranscriptWriter::append` call it instead of duplicating the filter. The caller's in-memory
   `Message` is unaffected; only the persisted copy is stripped.
 
+- `zeph-core`: debug dumps (`[debug] enabled = true`) no longer write full raw base64
+  `MessagePart::Image` bytes to disk by default. Both dump formats — `json` (typed message
+  serialization) and `raw` (provider wire payload, covering Claude/OpenAI/Gemini/Ollama
+  vision request shapes) — now redact image payloads to a
+  `<redacted image: {mime_type}, {n} bytes, blake3:{prefix}>` marker. A new opt-in
+  `[debug] include_raw_images` config flag (default `false`) restores the previous
+  full-byte behavior for developers who explicitly need wire-payload fidelity (#6306).
+
 ## [0.22.1] - 2026-07-15
 ### Fixed
 

book/src/advanced/debug-dump.md

@@ -70,6 +70,7 @@ Both the streaming and non-streaming LLM code paths are instrumented. Tool outpu
 [debug]
 enabled = false             # Enable at startup (default: false)
 output_dir = ".zeph/debug" # Base directory for dump files (default: ".zeph/debug")
+include_raw_images = false # Include full raw base64 image bytes instead of a redacted marker (default: false)
 ```
 
 The `--debug-dump` CLI flag overrides both fields: if `PATH` is provided it overrides `output_dir`; if omitted, `output_dir` is used. If neither the flag nor `enabled = true` is set, no files are written.
@@ -80,6 +81,8 @@ The `--debug-dump` CLI flag overrides both fields: if `PATH` is provided it over
 
 Dump files contain the full conversation context including any secrets, tokens, or sensitive data present in messages and tool output. Do not store dump directories in version-controlled or publicly accessible locations.
 
+Image content (`MessagePart::Image`, vision requests) is redacted by default: instead of the full base64 payload, dump files contain a `<redacted image: {mime_type}, {n} bytes, blake3:{prefix}>` marker — enough to identify format, size, and correlate the same image across dumps without ever writing raw image bytes to disk. Set `[debug] include_raw_images = true` only when you explicitly need full wire-payload fidelity for image-related debugging; the raw bytes are then written exactly as sent to the provider.
+
 Add `.zeph/debug/` to `.gitignore` (covered by the `.zeph/*` rule in the default `.gitignore`) to keep dumps out of your repository.
 
 ## See Also

book/src/reference/configuration.md

@@ -814,6 +814,7 @@ max_files = 7                 # Rotated log files to retain (default: 7)
 [debug]
 enabled = false             # Enable debug dump at startup (default: false)
 output_dir = "/absolute/path/to/debug"  # Optional override; omit to use the platform default in the user data dir (%LOCALAPPDATA%\Zeph\debug on Windows)
+include_raw_images = false  # Include full raw base64 image bytes instead of a redacted marker (default: false)
 
 # Requires `classifiers` feature.
 # ML-backed injection detection and PII detection via Candle/DeBERTa models.

config/default.toml

@@ -1011,6 +1011,10 @@ enabled = false
 #   "trace" — OpenTelemetry-compatible OTLP JSON spans written to trace.json at session end
 #             Use --dump-format trace on the CLI to override at runtime.
 format = "json"
+# Include full raw base64 image bytes (MessagePart::Image) in debug dumps instead of a
+# redacted "<redacted image: ...>" marker. Default false — leave disabled unless a developer
+# explicitly needs full wire-payload fidelity for image-related debugging (#6306).
+include_raw_images = false
 
 [debug.traces]
 # OTLP gRPC endpoint for trace export (only used when format = "trace" and otel feature enabled).

crates/zeph-config/src/features.rs

@@ -1596,6 +1596,15 @@ pub struct DebugConfig {
     pub format: crate::dump_format::DumpFormat,
     /// `OTel` trace configuration (only used when `format = "trace"`).
     pub traces: TraceConfig,
+    /// Include full raw base64 `MessagePart::Image` bytes in debug dumps instead of a
+    /// redacted `<redacted image: ...>` marker (#6306).
+    ///
+    /// Default: `false`. Image payloads are redacted by default to avoid writing
+    /// potentially large or sensitive binary data to disk on an opt-in debugging feature.
+    /// Enable only when a developer explicitly needs full wire-payload fidelity for
+    /// image-related debugging.
+    #[serde(default)]
+    pub include_raw_images: bool,
 }
 
 impl Default for DebugConfig {
@@ -1604,6 +1613,7 @@ impl Default for DebugConfig {
             enabled: false,
             output_dir: super::defaults::default_debug_output_dir(),
             format: crate::dump_format::DumpFormat::default(),
+            include_raw_images: false,
             traces: TraceConfig::default(),
         }
     }