# oap session

> oap session: Inspect AgentSession resources. Every subcommand, flag, and example, generated from the CLI.

Source: https://openap.org/docs/oap-session

Inspect AgentSession resources

## `oap session approve <session> [<requestID>]`

Publish an approval decision envelope to NATS as if the named
approver had clicked Approve (or --deny) in the channel. Drives any
registered yes/no approval on the session, including plan approvals
and private reminder consent. Useful for end-to-end testing without a Slack
workspace.

The decision still flows through channelsd's normal pipeline:
  - approver canonical-id is derived from --approver-email
  - SpiceDB LookupSubjectIncludes validates the approver against
    the request's ApproverSubject set
  - on approve: SpiceDB grant tuple is written; runner re-Checks
    against the grant and proceeds
  - on deny / not_authorized: runner sees the denied decision

requestID may be omitted when the session has exactly one pending
approval (of any kind); the command picks that one and prints its
kind. If multiple approvals are pending, requestID is required (the
show output above lists each one with its kind).

Flags:

```text
--approver-email string  Email of the approver — must match the SpiceDB approver subject. When omitted, the CLI's cached/logged-in identity is used. Pass an explicit email as an unverified override for scripting (use `oap identity canonical-id <email>` to preview the canonical form).
--deny                   Publish a deny decision instead of approve
--force                  Publish even if --approver-email is not in the request's required approver set (skips the client-side pre-check; channelsd's server-side check still applies)
--timeout duration       How long to wait for the Applied envelope when --wait is true (default "30s")
--wait                   Subscribe to the outbound Applied envelope and surface the channelsd-side outcome before returning (default "true")
```

## `oap session capabilities <session>`

Show every permission class this AgentSession's tools can reach.

Each row is a handle and the severity of reaching it:

    readonly   perm:read:github_repo
    readwrite  perm:write:tracker_issue
    external   tool:apply_workspace

The severity is the MAX across every tool reaching that handle — a class one
tool reads and another writes is a write class, because the reach is what
matters, not the mildest route to it.

This is a REPORT, not a grant. It says what the tools could reach if authorized;
whether any particular call is allowed is decided at dispatch by the per-tool
check, the plan gate, and the approval flow. A session may hold far less than
this list.

The surface is published by the runner at session start, so a session that has
not started yet — or one whose runner predates this field — shows nothing.

Flags:

```text
--tools  also show which tools reach each handle (the answer to "why can it do this?")
```

## `oap session capture <session>`

Read a finished session's durable records and write a steelthread bundle:
a transcript, the fixture manifests to boot it, the SpiceDB relationships its
authorization depended on, and a golden authorization trace.

Mechanical throughout — no model is invoked, and every emitted field is derived
from a record or left empty. Exits non-zero when the capture cannot be made
faithfully, rather than writing a bundle that would replay differently than it
recorded.

Every byte that would be written is scanned before anything is: once against
the live credential values the referenced Secrets hold, and once for anything
SHAPED like a credential — a private key, a JWT, a provider token, a kubeconfig
client key. A hit refuses the capture, and no flag turns that off.

--redact removes identifiers a scan cannot recognize and a heuristic must not
guess at: a customer, a partner, an internal hostname. Replacements run over the
final bytes BEFORE the scans, so a redaction can remove a secret but can never
suppress a finding about one.

Write the original ALONE (--redact acme-corp) and a stand-in is generated for
you: the same byte length, derived from the original so re-capturing the session
produces the same token, unique across the rules, and spelled so a reader of the
committed fixture can see it is a placeholder.

Name your own (--redact acme-corp=COMPANY-A) and it must be the SAME BYTE LENGTH
as what it replaces. That is enforced, not advised. The bundle records values
DERIVED from the redacted text — an artifact's size, a content length — which
the replay recomputes from the redacted bytes; a shorter token moved one real
capture's artifact size from 5291 to 5276 and the replay diverged at the
artifact, many turns from the rule that caused it.

Give it the same SHAPE too — same case, same character set. A redacted value
still goes through whatever validated it the first time, and an upper-case token
standing in for a lowercase slug makes the replayed call fail its own
constraint. A generated stand-in is lowercase alphanumeric for that reason.

--elide-skill is the structural counterpart for a third-party skill repo, which
a textual rule cannot rewrite: the authority appears in a SkillSource's
repoURL, in each Skill's canonicalName and provenance, in the object names, and
in the controller owner-ref that binds them — and desynchronising any one of
those fails the skill's provenance gate. This moves them together and drops the
skill content that came from that repo.

It REFUSES unless every AgentClass link to the elided source targets the
sandbox. A sandbox-targeted skill is staged to disk and reaches neither the
system prompt nor load_skill, so the run depended only on its existence; an
agent-targeted one's description IS part of the recorded prompt, and emptying
it would replay a different prompt with nothing to notice.

The stand-in authority is held to the SAME BYTE LENGTH as the one it replaces,
exactly as --redact is and for the same reason: the rewrite puts that string
into every canonical name, every repoURL and every skill ref the fixture emits,
and a length change desynchronises any recorded value derived from a byte count.
Write the authority ALONE (--elide-skill github.com/someorg/somerepo) and a
same-length one is generated — counting an exact byte total out of a plausible
repo locator by hand is how an operator ends up picking a shorter one.

The skill CONTENT it drops is deliberately not padded back to its original size.
Nothing derives a count from it: a sandbox-targeted skill's body and description
reach neither the prompt nor load_skill, which is the same fact the target
refusal above rests on.

Flags:

```text
--description string       Bundle description
--elide-skill stringArray  Rewrite a skill repo authority to a stand-in and drop that source's skill content, as old=new (github.com/someorg/somerepo=github.com/exampleorg/examplerepo, and the replacement must be the same byte length), or as the authority alone to have a same-length one generated. Refused for any skill the AgentClass does not target at the sandbox. Repeatable
--name string              Bundle name (default: the session name)
--overwrite                Replace an existing bundle in --output (clears the directory first)
--redact stringArray       Replace every occurrence of a string in the emitted bytes, as old=new (the replacement must be the same byte length), or as the original alone to have a same-length stand-in generated. Repeatable
--redact-from string       File of redactions, one per line in either --redact form; # comments and blank lines are ignored
-o, --output string        Directory to write the bundle into (required)
```

## `oap session delete <name>`

Delete an AgentSession

## `oap session grant <session> <subject>`

Grant an additional participant on the named AgentSession.

&lt;subject&gt; may be either:
  * A subject-set expression: "&lt;type&gt;:&lt;id&gt;#&lt;relation&gt;" (e.g. "group:engineering#member")
  * A direct user reference: "user:&lt;canonicalID&gt;" (use 'oap identity canonical-id &lt;email&gt;' to derive)

Bypasses the permission_request flow — useful for programmatic provisioning.

## `oap session hold <session>`

Creates a SessionHold that freezes the named AgentSession: the runner
stops accepting new turns and a release card is published for a human to
review the session's history and either release it or leave it held.

--reason is required — it is platform-authored text shown on that card, and a
hold with no reason gives the reviewer nothing to act on.

There is no CLI release: release is a human decision on the card, gated to the
session's owner.

Flags:

```text
--reason string  Why this session is being held (required; shown on the release card)
```

## `oap session logs <name>`

Print every memory turn (system / user / assistant / tool) recorded
for the given AgentSession. By default, the command prints the full
history and exits — pass --follow to keep streaming new turns until the
session reaches a terminal phase (or Ctrl-C).

Flags:

```text
--timeout duration  Client-side cap when --follow is set (default "30m0s")
-f, --follow        Keep streaming until the session is terminal or canceled
```

## `oap session operations <name>`

Reconstructs the audit trail for an AgentSession by grouping its
ToolCalls under the operation_id label they were stamped with at dispatch
time. When a memory token is available, also fetches the session memory
to recover the original new_operation description for each operation.

## `oap session participants <session>`

List all users that currently have interact permission on the named AgentSession.

Calls SpiceDB's LookupSubjects API for agentsession#interact. Requires
SPICEDB_ENDPOINT and SPICEDB_TOKEN to be set.

## `oap session revoke <session> <subject>`

Revoke a participant from the named AgentSession.

&lt;subject&gt; may be either:
  * A subject-set expression: "&lt;type&gt;:&lt;id&gt;#&lt;relation&gt;" (e.g. "group:engineering#member")
  * A direct user reference: "user:&lt;canonicalID&gt;" (use 'oap identity canonical-id &lt;email&gt;' to derive)

Bypasses the permission_request flow — useful for programmatic provisioning.

## `oap session revoke-slot <session> <resourceType>:<id>#<permission>`

Remove a single slot grant, so the session can no longer reach that instance.

The next authorization check denies — a slot grant is a SpiceDB tuple, and its
removal is visible immediately to any later check. Work already dispatched is
not clawed back; the revocation applies from the next call onward.

Standing is symmetric with APPROVAL, plus platform admin: whoever could have
granted the instance can take it back. Pass --as to name the canonical identity
the check runs against; without it the command refuses rather than acting
unattributed.

Use 'oap session slots &lt;session&gt;' to see what is held. For a value slot the id is
the hash the tool computes, which is what this command expects.

Flags:

```text
--as string  canonical identity the revoke-standing check runs against (required)
```

## `oap session show <name>`

Show status of an AgentSession

## `oap session slots <session>`

List every instance this AgentSession currently holds through a slot grant.

Each row is "&lt;resourceType&gt;:&lt;id&gt;#&lt;permission&gt;" — the object, and the permission
that grant confers. The permission is part of the identity, not decoration:
grants are per-permission, so a read-scoped grant and a write-scoped grant on the
same instance are different objects. For a
VALUE slot (a URL, a path) the id is the hash the tool's own permission check
computes, not the original value — the value goes to the tool, SpiceDB only ever
sees the hash. That is by design, and it is why this listing exists: without it
the held set is not discoverable at all.

Grants also expire on their own (bounded by the session's wall-clock lifetime
cap), so an empty list may mean "expired" rather than "never granted".

## `oap session un-deny <session> <subject>`

Lift a Deny on the named AgentSession.

&lt;subject&gt; is either a direct user reference — "user:&lt;canonicalID&gt;", from
'oap identity canonical-id &lt;email&gt;' — or a subject set such as
"group:eng#member". Both are valid: the blocklist accepts every subject type
owner and participant do, because a grant that can be made to a group must be
revocable from that same group.

Denying subtracts from every permission the session grants — interact, approve,
fork, and manage_scope — so lifting it restores whatever standing the subject
had before. It does NOT grant standing they never had.
