feat: add evidence receipt hash chain prototype (#279)

Disabled-by-default audit feature (EVIDENCE_RECEIPTS_ENABLED): appends a
hash-chained JSONL receipt per finished/failed toolcall under
<DATA_DIR>/flow-<id>/evidence/receipts.jsonl, recording toolcall
provenance plus SHA-256 hashes of args/result (no raw content).

Integration adapted to current main: the original PR built the receipt
from a database.Toolcall returned by ce.db.UpdateToolcall*Result, which
the executor no longer uses after the ToolCallLogProvider (tclp) refactor.
Receipts are now built from the in-scope toolcall data at the tclp log
sites and recorded non-fatally, so a receipt failure is logged and never
fails an otherwise-successful toolcall.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: 2 people

.env.example

@@ -100,6 +100,9 @@ EXECUTION_MONITOR_ENABLED=
 EXECUTION_MONITOR_SAME_TOOL_LIMIT=
 EXECUTION_MONITOR_TOTAL_TOOL_LIMIT=
 
+## Evidence receipt hash chain
+EVIDENCE_RECEIPTS_ENABLED=false
+
 ## Agent execution tool calls limit
 MAX_GENERAL_AGENT_TOOL_CALLS=
 MAX_LIMITED_AGENT_TOOL_CALLS=

backend/docs/config.md

@@ -127,17 +127,18 @@ The environment variables documented below remain the source of truth for config
 
 These settings control basic application behavior and are foundational for the system's operation.
 
-| Option           | Environment Variable        | Default Value                                                                | Description                                                              |
-| ---------------- | --------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| DatabaseURL      | `DATABASE_URL`              | `postgres://pentagiuser:pentagipass@pgvector:5432/pentagidb?sslmode=disable` | Connection string for the PostgreSQL database with pgvector extension    |
-| DBMaxOpenConns   | `DATABASE_MAX_OPEN_CONNS`   | `25`                                                                         | Maximum open connections in the shared `sql.DB` pool (sqlc + GORM combined). See [database.md §Connection Pooling](database.md#connection-pooling). |
-| DBMaxIdleConns   | `DATABASE_MAX_IDLE_CONNS`   | `5`                                                                          | Maximum idle connections kept open between requests                      |
-| DBVectorMaxConns | `DATABASE_VECTOR_MAX_CONNS` | `10`                                                                         | Maximum connections in the shared `pgxpool` for all pgvector stores      |
-| Debug            | `DEBUG`                     | `false`                                                                      | Enables debug mode with additional logging                               |
-| DataDir          | `DATA_DIR`                  | `./data`                                                                     | Directory for storing persistent data                                    |
-| AskUser          | `ASK_USER`                  | `false`                                                                      | When enabled, requires explicit user confirmation for certain operations |
-| InstallationID   | `INSTALLATION_ID`           | *(none)*                                                                     | Unique installation identifier for PentAGI Cloud API communication       |
-| LicenseKey       | `LICENSE_KEY`               | *(none)*                                                                     | License key for PentAGI Cloud API authentication and feature activation  |
+| Option                  | Environment Variable        | Default Value                                                                | Description                                                              |
+| ----------------------- | --------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| DatabaseURL             | `DATABASE_URL`              | `postgres://pentagiuser:pentagipass@pgvector:5432/pentagidb?sslmode=disable` | Connection string for the PostgreSQL database with pgvector extension    |
+| DBMaxOpenConns          | `DATABASE_MAX_OPEN_CONNS`   | `25`                                                                         | Maximum open connections in the shared `sql.DB` pool (sqlc + GORM combined). See [database.md §Connection Pooling](database.md#connection-pooling). |
+| DBMaxIdleConns          | `DATABASE_MAX_IDLE_CONNS`   | `5`                                                                          | Maximum idle connections kept open between requests                      |
+| DBVectorMaxConns        | `DATABASE_VECTOR_MAX_CONNS` | `10`                                                                         | Maximum connections in the shared `pgxpool` for all pgvector stores      |
+| Debug                   | `DEBUG`                     | `false`                                                                      | Enables debug mode with additional logging                               |
+| DataDir                 | `DATA_DIR`                  | `./data`                                                                     | Directory for storing persistent data                                    |
+| AskUser                 | `ASK_USER`                  | `false`                                                                      | When enabled, requires explicit user confirmation for certain operations |
+| EvidenceReceiptsEnabled | `EVIDENCE_RECEIPTS_ENABLED` | `false`                                                                      | Enables export-only toolcall evidence receipts                           |
+| InstallationID          | `INSTALLATION_ID`           | *(none)*                                                                     | Unique installation identifier for PentAGI Cloud API communication       |
+| LicenseKey              | `LICENSE_KEY`               | *(none)*                                                                     | License key for PentAGI Cloud API authentication and feature activation  |
 
 ### Usage Details
 
@@ -1845,6 +1846,10 @@ The supervision settings work together as a comprehensive system:
    ```
    Disabled supervision for debugging to observe natural agent behavior.
 
+## Evidence Receipt Settings
+
+When `EVIDENCE_RECEIPTS_ENABLED=true`, PentAGI writes hash-chain-only JSONL receipts for finished and failed tool calls to `<DATA_DIR>/flow-<flow_id>/evidence/receipts.jsonl`. Receipts include toolcall provenance metadata plus hashes of arguments and results, not raw argument or result content. Ed25519 signing and report bundle export are deferred to a later evidence-chain milestone.
+
 ## Observability Settings
 
 These settings control the observability and monitoring capabilities, including telemetry and trace collection for system performance and debugging.

backend/pkg/config/config.go

@@ -23,6 +23,9 @@ type Config struct {
 	DataDir     string `env:"DATA_DIR" envDefault:"./data"`
 	AskUser     bool   `env:"ASK_USER" envDefault:"false"`
 
+	// === Evidence Receipt Prototype ===
+	EvidenceReceiptsEnabled bool `env:"EVIDENCE_RECEIPTS_ENABLED" envDefault:"false"`
+
 	// === PentAGI Cloud Service Integration ===
 	InstallationID string `env:"INSTALLATION_ID"`
 	LicenseKey     string `env:"LICENSE_KEY"`

backend/pkg/config/config_test.go

@@ -269,7 +269,7 @@ func clearConfigEnv(t *testing.T) {
 	t.Helper()
 
 	envVars := []string{
-		"DATABASE_URL", "DEBUG", "DATA_DIR", "ASK_USER", "INSTALLATION_ID", "LICENSE_KEY",
+		"DATABASE_URL", "DEBUG", "DATA_DIR", "ASK_USER", "EVIDENCE_RECEIPTS_ENABLED", "INSTALLATION_ID", "LICENSE_KEY",
 		"DOCKER_INSIDE", "DOCKER_NET_ADMIN", "DOCKER_SOCKET", "DOCKER_NETWORK",
 		"DOCKER_PUBLIC_IP", "DOCKER_WORK_DIR", "DOCKER_DEFAULT_IMAGE", "DOCKER_DEFAULT_IMAGE_FOR_PENTEST", "TERMINAL_TOOL_TIMEOUT",
 		"SERVER_PORT", "SERVER_HOST", "SERVER_USE_SSL", "SERVER_SSL_KEY", "SERVER_SSL_CRT",
@@ -331,6 +331,7 @@ func TestNewConfig_Defaults(t *testing.T) {
 	assert.Equal(t, "0.0.0.0", config.ServerHost)
 	assert.Equal(t, false, config.Debug)
 	assert.Equal(t, "./data", config.DataDir)
+	assert.Equal(t, false, config.EvidenceReceiptsEnabled)
 	assert.Equal(t, false, config.ServerUseSSL)
 	assert.Equal(t, "openai", config.EmbeddingProvider)
 	assert.Equal(t, 512, config.EmbeddingBatchSize)
@@ -511,6 +512,20 @@ func TestNewConfig_CorsOrigins(t *testing.T) {
 	assert.Equal(t, []string{"*"}, config.CorsOrigins)
 }
 
+func TestNewConfig_EvidenceReceipts(t *testing.T) {
+	clearConfigEnv(t)
+	t.Chdir(t.TempDir())
+
+	config, err := NewConfig()
+	require.NoError(t, err)
+	assert.Equal(t, false, config.EvidenceReceiptsEnabled)
+
+	t.Setenv("EVIDENCE_RECEIPTS_ENABLED", "true")
+	config, err = NewConfig()
+	require.NoError(t, err)
+	assert.Equal(t, true, config.EvidenceReceiptsEnabled)
+}
+
 func TestNewConfig_OllamaDefaults(t *testing.T) {
 	clearConfigEnv(t)
 	t.Chdir(t.TempDir())