Subagents can execute commands without any audit, making session recording essential to avoid blind spots.
A subagent is any non-human client that talks to your infrastructure – CI runners, automation bots, background workers, or AI-driven assistants. In many organizations the subagent connects directly to a database, a Kubernetes cluster, or an SSH host using a static credential that was baked into a container image or stored in a secret manager. The credential grants the subagent the same privileges as a human operator, but the connection bypasses the normal logging and approval workflows that protect interactive sessions.
Because the subagent’s traffic travels straight to the target, you lose visibility at three critical points:
- There is no record of which commands were run, when they ran, or which identity initiated them.
- Sensitive response data – passwords, tokens, personally identifiable information – can be streamed back to a log collector that is not protected by masking.
- Any unexpected escalation, such as a subagent invoking a shell or spawning a child process, goes unchecked until damage is already done.
When you are trying to meet audit requirements, investigate a breach, or simply understand the behavior of your automation, the lack of a reliable audit trail is a showstopper. The first step is to recognize what you need to watch for:
Why session recording matters
Identify any connection that is created by a service account, a CI pipeline, or an AI assistant. Verify whether the connection is:
- Authenticated only by a static secret that never rotates.
- Allowed to run arbitrary commands or queries without an explicit approval step.
- Sending response payloads that contain fields marked as sensitive in your data model.
If the answer is yes to any of these items, you are operating without session recording. That gap means you cannot reconstruct the exact sequence of actions, cannot prove who or what performed them, and cannot redact sensitive data after the fact.
What to watch for
The only reliable way to capture a complete, reliable audit trail is to place a gate in the data path – a layer that sits between the subagent and the target resource and inspects every protocol exchange. The gate must be able to forward traffic transparently while applying policy controls such as command blocking, inline masking, and just-in-time approval.
hoop.dev provides exactly that gate. It runs a lightweight agent inside your network and proxies every layer 7 connection – whether it is a PostgreSQL query, a kubectl exec, or an SSH command. Because the gateway is the sole conduit for traffic, it can record each interaction in real time. The recorded session includes the full request, the response (with optional masking of sensitive fields), and metadata about the initiating identity.
With hoop.dev in place, session recording becomes an enforcement outcome rather than an after-the-fact add-on. The gateway stores the replayable logs in a location you control, making them available for forensic analysis, compliance reporting, or simple troubleshooting. The recordings are immutable for the duration of your retention policy, and they can be replayed in a safe viewer that respects any masking rules you have defined.
Because hoop.dev is open-source and MIT-licensed, you can self-host the gateway and integrate it with any OIDC or SAML identity provider you already use. The same identity token that grants a user access to the UI also drives the policy decisions for a subagent, ensuring that the principle of least privilege is enforced at the point of connection.
To get started, follow the quick-start guide that walks you through deploying the gateway with Docker Compose, registering a subagent connection, and enabling session recording for that target. The documentation also explains how to configure masking rules for fields such as password or api_key, and how to set up retention periods that align with your audit schedule.
For step-by-step instructions, see the Getting Started guide. For deeper insight into how hoop.dev handles masking, approvals, and replay, see the learning center.
FAQ
Do I need to modify my subagent code?
No. hoop.dev works at the protocol layer, so the subagent continues to use its native client (psql, kubectl, ssh, etc.). The only change is the endpoint address – it points to the gateway instead of the target directly.
How long are recordings kept?
The retention period is configurable in the gateway’s policy store. You can align it with regulatory requirements or internal data-retention guidelines.
Can I replay a session without exposing sensitive data?
Yes. When you enable inline masking, the gateway stores the masked version of the response. The replay UI respects those masks, so you can review the command flow without revealing secrets.
Ready to see the code in action? Explore the source on GitHub.
