Capability

What authorizes a supervised session to do something its hooks would otherwise refuse? A capability: a bounded, session-bound grant record that the session's runtime holds. Tama never issues or extends one; it can withdraw one at the operator's word (see Withdrawing it below).

#What it is

The optional capability object inside a session record (ai.wisent.tama.session-control.v2), decoded by the desktop as SessionCapability:

A grant without actions means every action of that tool — the Session screen renders it as every action in the TOOL/ACTIONS table.

#Who requests it

The session, from inside itself. In an OMP session the bundled adapter (~/.shared-hooks/omp-shared-hooks.js) exposes tama_request_session_capability, described in its own tool text as authorizing "exact tool/action grants for one invocation, a stated expiration, or the current OMP session". The request is part of the hook runtime's control plane, not of Tama: the supervisor and its policy decide whether a grant is issued, and the resulting capability appears in the next session record Tama polls.

#Issued by the operator's ruling

The operator can issue a capability to one session he names by a ruling, with no window and no ask: oko rulings record --session S --subject capability:<tool>[:<action>]@session:<ID> --by … (for example capability:tama:hook-edit@session:<ID>). Tama's core reads Oko's ruling register (OKO_RULING_REGISTER, else ~/Library/Application Support/Oko/rulings.json) for every dispatch and passes each grant a standing ruling issues to the dispatch's session to its hooks, beside the grant the session recorded, each carrying the ruling's id as its record; a command run outside the runner (tama hooks release) finds the same grant for the session it runs in. The capability ends when the ruling stops standing (oko rulings supersede, oko rulings unbind): the register is read again for every dispatch. A register that cannot be read issues nothing and every refusal of that dispatch says so with its cause.

#Who observes it

• The Session screen shows the capability of the selected session — Lifetime, Expires at, Remaining uses, Issued by, Schema version, Nonce, Release, Catalog checksum — with warning tones on identity mismatch, and the grants table below (desktop/session). A session without a capability shows an explicit no-capability message rather than an empty table.
• tama sessions --json includes the capability in each session's record (cli).
• The operator's consent is to the work, not to one hook release. When the session's own runtime loads another release — an install, tama_reload_hook_runtime, or the release a resumed session finds installed — it binds the grant the session holds to the release and catalog it now runs, with its grants, lifetime, expiry and remaining uses unchanged. A grant ends at its expiry, after its single use, at tama sessions capability revoke or under emergency disable, never because a newer release was installed.
• A grant whose control key, catalog checksum or release id does not match the policy the hook runtime has loaded is not passed to any hook, and every refusal the runtime gives while it is held says so: The session's recorded capability was not passed to the hooks: its <session control key|catalog checksum|release id> does not match the policy this runtime has loaded, so it was recorded against another policy generation. Record the grant again with tama_request_session_capability. A refusal therefore never reads as missing consent while a recorded grant was dropped.

#Withdrawing it

When the operator takes back a consent, the grant is withdrawn at once, not at its expiry:

tama sessions capability show --session <SESSION_ID> --agent omp|claude|codex [--json]
tama sessions capability revoke --session <SESSION_ID> --agent omp|claude|codex [--json]

show prints the capability the session's override holds now, as the build gate reads it ("capability": null when none). The harness is named with --agent, never assumed: the same id under another harness names another control file, and a command without it is refused with name the harness that runs the session with --agent. revoke withdraws the grant:

It sets capability to null in that session's <controlKey>.override.json and keeps every other field. The build gate reads that file on every call, so the next build is refused; the session's runtime adopts the change from the session-control directory's change event, and tama_hook_runtime_status then reports "capability": null. The answer says which case it found: revoked (with the withdrawn grant), none-held (the session holds no capability), or no-override (nothing was ever recorded for that session). A missing --session is a usage error, exit 2.

#Where it lives

Only inside the supervisor-owned session record under ~/Library/Application Support/Tama/session-control/. It disappears with the session; nothing durable under Tama's state directory records grants, and Tama's own state never holds a credential (what-is-tama).

#Not to be confused with

• A session-scoped enable. Enabling changes which hooks run (session-enable); a capability is an allowance the running hooks consult. The Session screen mutates the former and only displays the latter.
• A Wisent role. owner/admin/member authorize the operator to use Tama's mutating screens (desktop); a capability authorizes the agent session under policy. Different subjects, different issuers, different lifetimes.
• A justification. Justification-gated hooks demand a recorded human reason in a local registry file (hook-model); a capability is a machine-validated grant with nonce, expiry, and use budget. Both are evidence, but only the capability is bound to a control key.