Tool Call Chain of Custody Prompt Template

This prompt is designed for forensic investigators, compliance officers, and AI operations teams who need to produce a tamper-evident, cryptographically verifiable record of every tool interaction an agent performs. The core job-to-be-done is establishing a provable, sequential history of tool calls where each entry is linked to the previous one via a content-derived hash, ensuring that no record can be inserted, deleted, or modified without detection. Use this when the integrity of the audit trail is paramount—for example, in regulated financial transactions, healthcare data access logs, or security incident investigations where the chain of evidence must withstand external scrutiny.

The ideal user is a platform engineer or compliance architect integrating this prompt into an agent harness that already captures raw tool call data. The prompt requires a stream of tool call records as input, each containing at minimum a timestamp, actor identifier, tool name, and input/output payloads. It is not a real-time logging prompt; it is a post-hoc or batch processing prompt that transforms existing structured logs into a linked chain of custody. Do not use this prompt as a substitute for a secure logging infrastructure or a cryptographic signing service—it generates the logical structure and hash chain, but the security of the underlying storage and the initial record capture is your responsibility.

Avoid this prompt when you only need simple, human-readable audit logs or when the volume of tool calls is so high that sequential hashing becomes a latency bottleneck. For high-throughput systems, consider batching records or using a Merkle tree structure instead of a linear hash chain. Also, do not use this prompt if your raw tool call records lack stable, unique identifiers or consistent field schemas—garbage in, garbage out applies with full force to cryptographic integrity checks. Before deploying, ensure you have a validation step that recomputes and verifies the hash chain, and a human review process for any chain breaks or integrity failures that the automated system detects.

This prompt template produces a structured chain-of-custody entry for a single tool call. It is designed to be called immediately after a tool invocation completes, receiving the tool's input, output, and execution metadata as context. The model's job is not to execute the tool but to produce a verifiable record that links this tool call to the previous entry in the chain via a sequential hash. Use this template when you need forensic traceability across multi-step agent workflows, when compliance auditors require proof that tool outputs have not been tampered with, or when you are building an evidence packet for regulated decision-making. Do not use this prompt for real-time performance-critical paths where the hashing and record generation overhead is unacceptable; instead, batch the custody records asynchronously.

Below is the copy-ready prompt template. Replace each square-bracket placeholder with the actual values from your tool execution context before sending it to the model. The [PREVIOUS_CHAIN_HASH] field is critical: it must be the hash of the immediately preceding custody record in the session. For the first tool call in a session, use a known genesis hash value. The [TOOL_INPUT] and [TOOL_OUTPUT] fields should be the complete, unredacted payloads if the custody record is intended for internal audit; if the record will be shared externally, apply redaction before passing values into this template.

textCopy
You are a chain-of-custody record generator for agent tool interactions. Your output is a machine-readable JSON record that will be ingested by an audit system. Do not add commentary, markdown fences, or extra fields.

Generate a chain-of-custody entry for the following tool call. The entry must include a sequential hash that links this record to the previous entry in the chain.

PREVIOUS CHAIN HASH: [PREVIOUS_CHAIN_HASH]
TOOL NAME: [TOOL_NAME]
TOOL VERSION: [TOOL_VERSION]
ACTOR ID: [ACTOR_ID]
ACTOR TYPE: [ACTOR_TYPE]
SESSION ID: [SESSION_ID]
TASK ID: [TASK_ID]
PERMISSION CONTEXT: [PERMISSION_CONTEXT]
TOOL INPUT (complete): [TOOL_INPUT]
TOOL OUTPUT (complete): [TOOL_OUTPUT]
EXECUTION START TIMESTAMP: [EXECUTION_START]
EXECUTION END TIMESTAMP: [EXECUTION_END]
TOOL CALL STATUS: [STATUS]
ERROR DETAILS (if any): [ERROR_DETAILS]

OUTPUT SCHEMA (strict JSON):
{
  "chain_entry": {
    "entry_id": "<UUID v4>",
    "sequence_number": "<integer, incrementing from previous entry>",
    "previous_chain_hash": "<exact value from PREVIOUS CHAIN HASH>",
    "current_chain_hash": "<SHA-256 hash of this entire entry excluding the current_chain_hash field itself>",
    "timestamp": "<ISO 8601 UTC when this record was generated>",
    "tool_invocation": {
      "tool_name": "<from TOOL NAME>",
      "tool_version": "<from TOOL VERSION>",
      "input_hash": "<SHA-256 hash of the TOOL INPUT string>",
      "output_hash": "<SHA-256 hash of the TOOL OUTPUT string>",
      "execution_start": "<from EXECUTION START TIMESTAMP>",
      "execution_end": "<from EXECUTION END TIMESTAMP>",
      "status": "<from TOOL CALL STATUS>",
      "error_details": "<from ERROR DETAILS, or null>"
    },
    "actor": {
      "actor_id": "<from ACTOR ID>",
      "actor_type": "<from ACTOR TYPE>",
      "session_id": "<from SESSION ID>",
      "task_id": "<from TASK ID>"
    },
    "permission_context": {
      "policy_name": "<extracted from PERMISSION CONTEXT>",
      "policy_version": "<extracted from PERMISSION CONTEXT>",
      "scope_requested": "<extracted from PERMISSION CONTEXT>",
      "scope_granted": "<extracted from PERMISSION CONTEXT>"
    },
    "integrity_verification": {
      "hash_algorithm": "SHA-256",
      "previous_hash_matches": "<boolean, true if previous_chain_hash matches the hash stored in the prior record>",
      "input_hash_verified": "<boolean, true if input_hash matches a recomputed hash of TOOL INPUT>",
      "output_hash_verified": "<boolean, true if output_hash matches a recomputed hash of TOOL OUTPUT>",
      "chain_intact": "<boolean, true if all verification checks pass>"
    }
  }
}

CONSTRAINTS:
- Generate a new UUID v4 for entry_id. Do not reuse IDs.
- Compute current_chain_hash as SHA-256 of the entire JSON object excluding the current_chain_hash field. Use a deterministic serialization order.
- Set sequence_number to [PREVIOUS_SEQUENCE_NUMBER] + 1. If no previous number exists, start at 1.
- If TOOL CALL STATUS is "error" or "timeout", set output_hash to null and include ERROR DETAILS.
- If PERMISSION CONTEXT is empty or unavailable, set all permission_context fields to null.
- Do not hallucinate tool inputs or outputs. Use only the provided values.
- If any required field is missing, set the corresponding output field to null and set chain_intact to false.

After copying the template, wire it into your agent's post-tool-call hook so that every tool invocation automatically produces a custody record. Store the current_chain_hash from each record as the [PREVIOUS_CHAIN_HASH] for the next call. Validate the output JSON against the schema before persisting it. If chain_intact is false, quarantine the record and trigger an alert for manual investigation. For high-risk domains, require a second verification step where a separate process recomputes the hash chain independently and compares it against the stored records. Never skip the hash chain validation on read-back: an intact chain is the only proof that no record has been inserted, deleted, or modified.

The Tool Call Chain of Custody prompt is not a standalone utility; it is a critical component of a forensic logging pipeline. It should be invoked synchronously as a post-processing step immediately after every tool call completes, before the tool result is passed back to the agent's main reasoning loop. The implementation must treat this prompt's output as an immutable audit record. This means the application layer should append the generated JSON record to an append-only log, compute a content hash, and store that hash in a separate integrity registry to detect any post-hoc tampering. The prompt itself is responsible for generating the sequential hash that links the current record to the previous one, but the application must supply the correct [PREVIOUS_RECORD_HASH] from the trusted log, not from the agent's potentially corrupted context window.

The integration requires a strict validation layer before the record is committed. After the model returns the chain-of-custody JSON, the application must validate: (1) the record_hash field is present and matches a server-side recomputed hash of the record's content, (2) the previous_record_hash matches the last committed hash in the log, (3) the actor_identity and tool_name fields are non-empty and match the current session's authenticated principal and the tool that was actually invoked, and (4) the timestamp is within an acceptable clock-skew threshold of the server's wall clock. If any validation fails, the record must be rejected, the failure logged as a security event, and the agent's action should be halted or escalated to a human reviewer. A retry loop with a maximum of two attempts is acceptable for transient model formatting errors, but hash chain breaks must never be silently repaired.

For production deployment, use a deterministic, low-temperature model configuration (e.g., temperature=0) to maximize structural reliability. Store the raw model response alongside the validated record for future auditability. The sequential hash chain is only as strong as its weakest link; a single missing or corrupted record breaks the entire chain. Therefore, implement a periodic background job that walks the full log, recomputes all hashes, and alerts on any integrity failure. Finally, never allow the agent to see or manipulate the raw chain-of-custody log directly—it should only receive a confirmation that the record was committed successfully, preventing an attacker from using prompt injection to rewrite forensic history.