# Record a conversation

One role's conversations are recorded with secrets masked, and you have read a recorded prompt back.

- Who: Admin
- Where: Console or strazactl, and the agent's machine

In short: Recording is a policy decision: a policy set that matches a role and carries a `capture` block records that role's prompts and replies. The agent and the person are told at session start that recording is on. In `redact` mode, credential shapes are masked before anything leaves the machine.


Recording is a policy decision about whose conversations are kept. A policy set that matches a role and carries a `capture` block turns recording on for that role's sessions: the prompts as they are submitted, and each reply when its turn ends. The agent is told at session start that recording is on, and the person sees the same line in the harness, so nobody is recorded without knowing it. In `redact` mode, credential shapes are masked before anything leaves the machine, and when two sets disagree, redact wins.

## Before you start

- The `local-tools` allow rule from [Your first deny](https://docs.straza.ai/guides/write-policy/first-deny/index.md) live for your role.
- An administrator's console sign-in, or an admin API token for `strazactl` in `STRAZA_API_TOKEN` minted in the console as [Mint an admin API token](https://docs.straza.ai/guides/console/settings/index.md#mint-an-admin-api-token) shows.
- An enrolled machine held by a user of the role, here `dana`.

## Turn recording on

In the console:

Recording is a property of a policy set, never a wizard outcome, so open a live set that matches the role:

Click path in the console: "Policies" › "local-tools-guardrails" › "Change" › "Secrets masked" › "Add to unpublished changes" › "Save and publish" › "Publish"

![The Change recording sheet on local-tools-guardrails, with Secrets masked picked](https://docs.straza.ai/shots/policy-recording-dark.png)

The **Change recording** sheet with **Secrets masked** picked.

**Change** sits under the fact Recording on the set's page. The sheet `Change recording` offers `No recording`, `Word for word` and `Secrets masked`. Once published, the set's row on Policies carries the mark `REC`.

With the CLI:

Save this as `session-recording.yaml`. A policy set needs at least one rule, so the capture block sits beside the `local-tools` allow rule.

```yaml
apiVersion: straza.dev/v1beta1
kind: PolicySet
metadata:
  name: session-recording
  description: Record the prompts and replies of every local-tools session, with credentials masked
spec:
  match:
    roles: [local-tools]
  capture:
    conversations: true
    mode: redact
  rules:
    - id: local-tools
      # A policy set needs at least one rule, so the capture block sits
      # beside the local-tools allow rule.
      events: [tool.pre]
      tools: [shell.exec, file.read, file.write, file.edit]
      effect: allow
```

Terminal, administration:

```sh
strazactl policy apply -f session-recording.yaml
strazactl policy activate session-recording
```

```text
applied session-recording (Off, 01a0e997-1b2e-71ff-af39-06dc4238e28e)
published session-recording, it is live now; new snapshot 4adaae7033b474860dce4538a502280e72a95d0b67375de95d3a307807e05cab
```

`conversations: true` turns recording on, and `mode: redact` masks recognizable credential shapes: AWS access key ids, GitHub tokens, bearer values, complete PEM blocks and Straza tokens. The battery is deliberately narrow, because a false positive destroys the text it scrubs. A `mode` without `conversations: true` is rejected as inert.

## Submit a prompt

CLI only: The session runs on dana's enrolled machine.

The next session start carries the recording notice in both voices:

dana's machine, client:

```sh
printf %s '{"hook_event_name":"SessionStart","session_id":"a7d5f2b4-6ea2-4b8b-9f30-5c1e4a6b8d07","cwd":"/home/dana/work","source":"startup"}' | straza hook --harness claude-code
```

```text
{"hookSpecificOutput":{"additionalContext":"Straza governs this session as \"dana\". Every tool call is checked against policy and recorded in the audit log. When a call is denied, tell the user what the reason says, then do what it says next: wait for a person's approval, change the call, or try once more later. A denial that says none of these is a policy decision, and the same call will be denied again. Do not try to reach the denied result another way. By policy, the prompts and responses of this session are recorded with secrets masked in the audit log.","hookEventName":"SessionStart"},"systemMessage":"🛡 Straza governance active: dana (local-tools) @ http://localhost:8420 · policy 4adaae7033b4 · attestation advisory · conversations recorded with secrets masked"}
```

The context for the agent and the one-line `systemMessage` for the person both end with the notice. Under `mode: verbatim` both say `word for word` in place of `with secrets masked`.

Claude Code sends the prompt text in its `UserPromptSubmit` event. The hook hands it to `straza service`, which hashes the full original, masks it, caps it at 64 KiB and spools it to the audit pipeline. Because the event is observational, the hook answers with silence and exit code 0.

dana's machine, client:

```sh
printf %s '{"hook_event_name":"UserPromptSubmit","session_id":"a7d5f2b4-6ea2-4b8b-9f30-5c1e4a6b8d07","cwd":"/home/dana/work","prompt":"Deploy the billing service to staging. Use the key AKIAIOSFODNN7EXAMPLE for the S3 bucket."}' | straza hook --harness claude-code; echo "exit $?"
```

You should see: `exit 0`

Once the prompt is spooled, the service starts an upload at once, and it also uploads every 15 seconds, so the hook exits without waiting. Replies are recorded differently: when a turn ends, the hook reads what the harness appended to its own transcript file since the previous read and hands that text to the service.

## Read it back

In the console:

Click path in the console: "Transcripts"

![The Transcripts page with dana's recorded session](https://docs.straza.ai/shots/transcripts-dark.png)

Transcripts with one recorded session of dana's, the search box and the **Match** picker.

The screen has one row per recorded session, newest activity first, and a row opens the whole conversation. Sessions offers the same through a session's **Open transcript**. The search box, `Search recorded prompts and replies`, finds text across sessions. Its Match picker offers `contains text` and `exact value`. An exact value is hashed in your browser, so a secret you hunt for never leaves your machine.

With the CLI:

`straza status` on the machine names the Straza session id. The transcript shows the masked prompt, the mode it was recorded under, and a truncation marker with the full-content hash when the cap applied.

Terminal, administration:

```sh
strazactl sessions transcript 01a0e997-1d3f-7542-b42f-c6b6eba5c031
```

```text
session 01a0e997-1d3f-7542-b42f-c6b6eba5c031: dana, 1 turns

[19:56:29] prompt (redact)
Deploy the billing service to staging. Use the key [REDACTED] for the S3 bucket.
```

Across sessions, search by substring, and add `--user` when you know the user. The `--value` form hashes a secret locally and matches turns whose whole content equals it.

Terminal, administration:

```sh
strazactl transcripts search billing --user dana
```

```table
TIME                 USER  SESSION                               KIND    CONTENT
2026-09-28 19:56:29  dana  01a0e997-1d3f-7542-b42f-c6b6eba5c031  prompt  Deploy the billing service to staging. Use the key [REDACTED] for the S3 bucket.
```

An exact-value search finds a pasted token on its own line, and under redact mode it finds nothing, because the stored text no longer holds the value.

The audit log holds the fact of the recording without repeating the text: the byte count, the hash of the full original, the mode and the session.

In the console:

Click path in the console: "Audit" › "Lens" › "recording"

![The Audit page under the lens recording, with the prompt record that keeps size and hash only](https://docs.straza.ai/shots/audit-recording-dark.png)

The `recording` lens, where a prompt record keeps its size, its mode and a hash, never the text.

With the CLI:

Terminal, administration:

```sh
strazactl audit tail --user dana --limit 3
```

```text
#247 [dana] {"data":{"contentBytes":80,"contentHash":"sha256:a6837a1d815a71f1dfcc09d7451b76bbe03ca52724294c08177b53ca70e3ef1c","mode":"redact","session":"01a0e997-1d3f-7542-b42f-c6b6eba5c031","truncated":false},"type":"straza.audit.prompt"}
```

This listing is trimmed to the prompt record and to the fields that matter here.

## Retention and where the text lives

Recorded turns are purged after `governance.captureRetention`, 30 days by default. By default the text sits inline in the relational store. The enterprise profile can send bodies to an S3-compatible bucket with `capture.bodyStore.type: s3`, where the bucket's lifecycle rule becomes the retention and reads stay transparent to the console and the CLI. On a standalone host the inline store is the only option. Both settings live in the strazad config file, and the line under the Transcripts title reads them back.

## Undo

Turning recording off takes effect for the role at its next session start, because recording is off unless an active matching set says otherwise. In the console, pick `No recording` in the same Change sheet and publish, or turn the set off with **More** and **Turn off**. In a terminal, `strazactl policy deactivate session-recording` turns the set off. Turns already stored stay until retention removes them.

Two limits matter before you rely on redact for compliance. The battery masks shapes it recognizes and nothing else, so a password pasted as plain words is stored as typed. Redaction happens on the agent's machine before spooling, which is what keeps the value off the wire, so an unmanaged install that a user can edit is advisory here as everywhere else.


Walked on v1.1.0 on 2026-09-28. Linux, against the enterprise demo stack under the enterprise profile, with strazactl logged in as an administrator and the hook events fed to straza hook by hand in a Linux container enrolled as dana. Console screenshots show strazad v1.0.0-1753-ga27c516c, standalone.

