Tama documentation

Policy you can inspect,
operate, and recover.

Everything Tama owns: core concepts, every desktop screen, CLI and configuration contracts, release integrity, exact failures, and end-to-end walkthroughs.

Start with the quick start →Open the runbook

Start here

3 topics

What is Tama

What is Tama, and what is the mental model for reading everything else in these docs? Tama is the local control surface for coding-agent policy hooks on one Mac: a sealed catalog of approved hooks, a per-user runtime that enforces them in live agent sessions, and one desktop application that can prove which policy is loaded and recover when a hook blocks necessary work. The whole product is three moving parts — a release that declares, a runtime that enforces, and an operator surface that verifies and overrides.

Quick start

How do you go from nothing to one supervised agent session whose policy state Tama can prove? This page is the one happy path: verify an exact release, open the app, install local enforcement, and watch one session report matching identities. Full prerequisites, every failure, reset, and uninstall live in onboarding.

Onboarding

A new Wisent developer verifies and opens an exact Tama release, signs in, inspects the bundled policy without changing the machine, explicitly installs local enforcement, and sees one supervised agent session reported as kernel-gated with matching hook release identity.

Concepts

8 topics

Hook

What is the atom of Tama policy? A hook: one approved command bound to one or more agent events, with a human record of what it does, why it exists, and what it touches. Hooks are approved and shipped as a set — one hook release — never individually.

Hook release

What exactly is the unit of hook-policy deployment on a machine? A hook release: an immutable, content-addressed directory tree carrying the registry, every approved hook source, the sealed Rust backend, and a manifest whose releaseId is the SHA-256 digest of the tree itself. Nothing smaller deploys — no single hook, no patch — and nothing mutates in place.

Registry

Where is the single declaration of what runs, when, and why? In shared-hooks/registry.json at the release root — one JSON document that both the runtime executes from and the human audits from. Everything the desktop shows about hooks derives from it.

Seal and integrity

What makes a Tama hook release tamper-evident, and which checks actually stand between a modified tree and a running session? One digest definition, computed in one place, enforced at three moments.

Posture

What single answer does Tama give to "is this machine enforcing the policy it claims to enforce"? Posture: the joined comparison of three release identities plus the live enforcement signals, ordered by severity. It is a derived judgment, not a stored state — nothing on disk says "posture"; every element of it is readable independently.

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).

Session-scoped enable

How does Tama change what runs in a live agent session — and why can it only ever make policy stronger there? Through one narrow mutation: enable a hook, or every hook, in exactly one session, applied not by Tama but by that session's own supervisor. There is no per-session disable, by contract (core-contracts).

Emergency disable

When a hook blocks work that genuinely must proceed, what is the recovery — and what does it cost? One confirmed, operator-owned action that bypasses every Tama-managed dispatcher on the machine, records exactly what it moved, and stays visible until a verified re-enable restores everything. It is deliberately the only way to weaken policy: sessions can enable, only operators can disable, and only globally (enforcement-control).

Desktop app

14 topics

Desktop application

The SwiftUI app is the canonical human interface: one window, one sidebar of destinations grouped by the decision the operator came to make, one screen at a time. Authorization removes destinations instead of rewriting them — a signed-out or under-privileged operator sees fewer rows, never dead ones.

Setup and the first-use journey

How does a fresh install become a machine whose setup Tama calls complete? There is no separate setup gate: since the change titled Keep Tama navigation available during setup, an authorized operator gets the full window immediately, and guided first use runs alongside as a quiet journey. The end-to-end operator path is quick-start; every prerequisite and failure is in onboarding.

Posture screen

The headline screen: is this machine enforcing the policy it claims, and what was the last thing policy refused? Posture joins the three release identities with the live enforcement signals and hosts the machine's most destructive action. The underlying judgment is concepts/posture.

Hooks screen

The approved catalog and the per-hook decision that goes with it: what a policy does, why it exists, which events it gates, and whether the live session in front of you has it enabled. Three zones — facets, table, inspector. The catalog itself is read-only here; the sealed registry model is hook-model.

Session screen

What is one supervised agent session actually allowed to do right now? The capability document, the tool grants, the loaded release, the liveness contract, and every recent decision — for the one session selected in the rail. This is also the screen for session-scoped policy enabling and OMP adapter reload; reloading changes neither policy selection nor process identity (concepts/session-enable).

Violations screen

Findings in the repository under repair, and the one irreversible verb. Scan is read-only and replays the release's real pre-write hook; Repair hands the working tree to one headless external agent behind a confirmed dialog and trusts only the final rescan. The engine is the sealed CLI's violations find / violations clean (cli), run as the streamed jobs tama request violations/scan and tama request violations/clean, one process each; Stop ends the job's whole process tree.

Justifications screen

The Justifications screen reads recorded file reasons, records the operator's test approvals and provides CUA consent management. Every control runs tama request, one process per operation, with the same validation as the CLI.

Coverage screen

Which runtime carries which hook, and whether that runtime's own configuration really installs it. The screen answers "is Codex actually covered on this machine" without a terminal, and it separates the two halves of that question: the registry's declared mappings, and how many of them the provider's config on this machine installs. It is explicit that neither half is live execution evidence — each provider's own sentence, captured from the sealed release, is Registry-declared mappings; not live execution evidence.

Install plan screen

Where an install would write, scope by scope, and the MCP snippet that goes with it — so an operator approving a privileged install can see which files it would touch first. The plan is read-only: the screen states target paths and performs none of the changes. The command behind it is the sealed CLI's install plan (cli), run as tama request install/plan with an empty body.

Settings screen

The local policy store, installation, and build behind Tama: import an existing inactive bundle, install the runtime, register the privileged backend, and — the screen's one destructive owner — deactivate everything. Import and activation remain separate operations.

Copies screen

Every second full checkout under the roots you name, and the one verb that deletes them. The engine is the sealed CLI's copies group (cli/copies), run as tama request copies/list and tama request copies/remove, so the screen and the terminal cannot disagree about what a pass would do.

Reviews

The Reviews destination in the Repair group inspects retained commit reviews: what the model reviewer of review-commit read and answered before a commit was created. A push retains nothing to inspect; review-push reads the attestation each commit carries, shown under Install → Carried attestations. The screen has the same local control authorization boundary as the other Repair screens. It does not run a model, retry a commit or change credentials.

Learned screen

Tama shows proposals for contested hooks, drafted rules, named causes and unexplained operator corrections. The screen reads the sealed CLI's tama rules digest through tama request rules/digest; it does not install policy.

Commit standing

Policy → Commit standing shows what each agent session's commits have cost it. A session earns a point for every commit whose staged files are all in their formatter's form (rustfmt's for Rust, the one the repository declares in .tama/formatters.json for any other extension) and loses one for every commit with a file out of that form; the commit is made either way. A session whose standing falls below zero is shown as blocked: block-negative-commit-standing refuses every tool call it makes until a charge is taken back.

Reference

45 topics

Architecture

What does Tama own, what does it deliberately not own, and how does a policy decision travel from a sealed release to a refused tool call? This page is the structural map; per-noun depth lives in concepts/ and the operational contracts in core-contracts.

Core contracts

Initial state: any app launch, including no account or installed runtime. Input: signed app resources and an explicit choice to inspect. Success: decoded catalog, validation result, hook count, checksum, and build identity are visible without starting session monitoring. Failure: the UI reports an incomplete/corrupt bundle and does not mutate local policy.

CLI

Tama Desktop bundles a sealed native Rust CLI at Tama.app/Contents/Resources/hooks-release/bin/tama. Its public usage starts with tama <command>. This index links every public top-level command and command leaf; hidden runner and bridge entrypoints are intentionally not part of the public surface.

Configuration

Tama has no required environment variables and no free-form settings file for a supported installation: setup choices are explicit actions in the app, and everything durable lives in known files with known schemas. This page maps that surface — where state lives, which environment variables the bundled scripts and runtime honor, and the few user-defaults keys the app itself keeps. Build- and release-time variables (signing identities, provisioning profiles, channels) are maintainer-only and tabled in operations.

Enforcement control

Tama has three machine enforcement states, and their ownership is explicit. The normal baseline runs every registered hook. An operator can narrow that baseline to a durable machine-wide selection, or use the confirmed emergency switch to bypass it completely. A live session can only add hooks to the machine baseline; it can never remove one. There is no per-session disable (core-contracts).

Common hook runtime and harness adapters

The enforcement states live in enforcement control; hook execution and harness translation are described here. An OMP write to xd://lsp is a tool-device request, not repository prose. Documented read-only actions—status, capabilities, diagnostics, definition, references, hover, symbols, type definition and implementation—use lookup admission with the existing remote-access and audit protections. The original outer request remains in evidence; pre-event, post-event and evidence routing use the same normalized identity. Malformed JSON or a missing string action refuses with its protocol cause. Rename, rename-file, applying code actions, unknown actions and raw requests do not receive this read-only classification.

Cancellation, judge requests and hook supervision

How a dispatch the common hook runtime runs is cancelled, how a judge request shares its adapter with other hooks and waits only while Brama serves, and how each hook's processes are owned and ended.

Completion policy and work registers

Role preflight, actionable work and the distinction between a source repair and a qualified result.

Conduct gates

The gates that keep a session's own conduct tied to its work: no cycle of gates that leaves no step, every call serving a claimed item, purgatory, reports that are not the work, repeated looks, operator messages kept as records, and the operator's stop order. Completion enforcement and the work registers are on Completion policy and work registers.

Endings a report cannot replace

Part of enforcement control, completion enforcement.

A supervisor's negative report needs its repair

Part of enforcement control, completion enforcement.

How the build gate decides a build

Part of enforcement control, completion enforcement. The policy the gate applies — a build, compile or test waits until every open item carries a repair — is on the completion policy and work registers page; this page says who decides it and what the gate answers.

Hook model

What exactly is a hook, and where is it declared? A hook is one approved policy command bound to one or more agent events, described by a registry that ships sealed inside every release. This page is the registry model; sealing and installation are in hook-releases, and the runtime controls are in enforcement-control.

Numeric values and standard operations

block-numeric-literals checks numeric choices against the operator's recorded instruction. Its declaration format is numeric-provenance.json with entries {"value": n, "user_said": "…"}. A write is judged by every literal the file holds as the write leaves it, the ones it already held included: a number is not approved by having been written before, so an edit of a file that holds an unsourced number is refused for it, whoever wrote it, until the number carries a source or is removed. A hashline edit is read as the file its section leaves behind (replace, insert and cut replayed against the file on disk), so text added inside a string or comment — a shell program held in a Rust raw string, with its $1 and 2>/dev/null — is read as that string, and a number added to the code around it is still refused; a section with an operation that is not replayed (a block, a register paste) is read from its added lines alone. In a data file (JSON, a Package.resolved, a manifest) a quoted value shaped as an identifier is not a number: a dotted release version such as "0.7.56" or "1.2.3-beta.1", and a hexadecimal revision or digest holding a letter such as a git commit. So a version bump and a dependency pin pass, while a quantity beside them ("retries": 7) and a quoted decimal ("port": "8792") are still refused by name. A quoted value that holds whitespace is prose, not a quantity: a documentation page's sentence ("An approval_id is at most 64 characters") or a description passes whatever figures it quotes, while a bare value and a quoted single word ("retries": "7") are still read. In a Cargo.toml, the quoted text of every dependency table ([dependencies], [dev-dependencies], [build-dependencies], [workspace.dependencies], [target.….dependencies]) is a requirement on a release the registry publishes (tree-sitter = "0.25"), so it passes; a number in any other table of the manifest (opt-level = 3), and a table of that name in any other file, is still read. The manifest's edition, rust-version and license values (edition = "2021", rust-version = "1.80", license = "BSD-3-Clause") are names Rust and the SPDX list publish, so they pass in [package] and [workspace.package]; the same keys in any other file are still read. In a package.json, read as JSON, the package's own version and license ("Apache-2.0"), and the package names and release ranges of its dependencies, devDependencies, peerDependencies, optionalDependencies and engines ("node": ">=20", "fs-ext": "2.1.1", a github: pin to a commit) are names the registry, Node and SPDX publish, so they pass; every other number in it ("config": { "port": 8130 }) and the same fields in any other file are still read. A package.json that is not JSON is refused naming the cause.

Identity provenance and incremental checking

How Tama sources newly introduced identities without rereading unchanged prose and transcript bodies.

Asking a model, when shape cannot decide

How a gate asks a model for a judgement its input's structure cannot give, and what it does when no model answers.

Adaptive enforcement

Tama observes hook outcomes, learns only from structurally complete runs and causally identified owner corrections, and may automatically weaken only an etiquette hook from enforce to warn. It never disables a hook and never edits hook source.

Hook management

Tama stores hook source and structured configuration, exposes the CLI and MCP catalogue, and carries the runtime paths that enforce approved policy. The repository is never runtime state: logs, transcripts, credentials, shell profiles, local settings, caches, and machine-specific state stay outside it.

What counts as changing a hook

How the hook-configuration guard reads a shell payload, and how a hook source the registry recorded wrongly is repaired.

Why a gate decided what it decided

How to read what a hook read and decided, which program a provider runs, and which checkout a tama hooks command reads.

Warming the hook binaries

A hook binary that has never been executed still owes macOS its first-run work: the system assesses the executable's signature before it runs, that assessment reaches Apple over the network, and XProtect scans the image. The first run of a freshly installed hook binary can take minutes, while every run after it takes a few milliseconds. An engine that killed a hook at a fixed number of seconds would therefore refuse a finished turn on a cold cache with a timeout — a refusal nobody wrote.

One-off repairs: block-one-off-repairs

A gate on pre_tool_use:bash (tama hook block-one-off-repairs) that refuses repairs made by hand against live machine state, and builds while the build hold stands, and names, in each refusal, the product command that owns the outcome. Every refusal starts BLOCKED: one-off repair by hand., appears as a {"decision":"block","reason":"…"} document on stdout, and repeats its reason on stderr. The dispatcher ends normally after that decision; a nonzero exit without a decision is a hook failure, not a policy refusal. The harness prevents the proposed command from running. An ordinary allowed command prints nothing; an admitted build may report consumption of its recorded capability.

Work outside the task

block-off-task-work refuses a change to a repository the session never said the operator's current instruction touches. It runs on the tools that change or publish a file — write, edit, refactor, apply_patch, and a git commit or git push in bash. Reads are never refused.

Build and restart registry: block-unregistered-build-or-restart

A gate on pre_tool_use:bash (tama hook block-unregistered-build-or-restart) that refuses a build without an unused, unexpired entry recording the agent's statement that the whole task is finished. Each accepted build consumes its entry, so the next build needs a new statement and intent. A restart still needs an open entry but no task statement. Refusals start BLOCKED: unregistered build: or BLOCKED: unregistered restart:, go to stderr and exit 2 before the command runs. The registry is ~/.shared-hooks/build_restart_registry.json; tama build and Tama Desktop share its writer.

Git authorship: block-git-authorship

A gate on shell, eval and process-start calls (tama hook block-git-authorship) that refuses every way of asking git who wrote something. Every agent in this workshop commits through the operator's git identity, so an author line, a blame line, a shortlog or a mailmap names him whatever an agent did; who decided something is answered by the transcripts (oko tasks --session <id> --full, oko tasks rules --session <id>). The refusal carries a reason: line naming which way the command asked.

Keychain prompts: block-keychain-prompt-commands

A gate on shell calls (tama hook block-keychain-prompt-commands) that refuses a command which can raise a macOS Keychain or interactive sign-in prompt. The prompt is native UI the agent cannot answer, so the session stands still until a person clicks it. The refusal names the non-interactive route: already-approved environment variables, an explicit connection string, service-role API calls, or a checked-in migration that invokes no keychain-backed CLI.

Oko and Weles: block-oko-trajectory-edits

A gate on writes, patches and shell commands (tama hook block-oko-trajectory-edits) that keeps Weles-owned automation out of Oko's checkout. Oko may consume Slack tokens and Slack's Web API and read what Weles reports; Weles owns every trajectory and every login or install automation, and a browser is only ever driven there.

Shell commands: pre-bash and block-inline-execution

Two gates read every shell command an agent runs. tama hook block-inline-execution refuses a program written inline instead of in a checked-in file; tama hook pre-bash refuses throwaway work and commands that cross a product boundary. Neither decides by a list of program names: an interpreter, wrapper or cloud CLI nobody listed walked past every list that did.

External source: block-external-source-edits

A gate on writes, patches and shell commands (tama hook block-external-source-edits) that refuses a change to source someone else owns: installed dependency source (node_modules, site-packages, Cargo's registry and similar) and a checkout any of whose remotes, whatever it is called, is a fork of, or a repository owned by, an account other than the one signed in to GitHub. The remotes are read from the checkout's own configuration (git config --get-regexp '^remote\..*\.url$'), so renaming a remote does not change what the checkout is. A remote that is not a GitHub repository is refused as unsupported ownership provenance <remote>=<url>, and a configuration git cannot read as reading remotes at <checkout> failed: <git's error>. The refusal says what the path resolves to and to use documented configuration, APIs or a separately owned extension instead.

Writes are judged by the whole file they leave

Every gate on a write, an edit, a patch or a notebook edit judges the file as the write leaves it, not the text the write carries. Tama rebuilds that file once, through the replay in check_numeric_literals_payload::path_texts, and hands each gate the whole result:

Temporary paths and scratch heaps: block-temporary-path-operations

A gate on reads, edits, writes, notebook changes and saves (tama hook block-temporary-path-operations) that refuses a target in a temporary directory: /tmp, /var/tmp, /var/folders and their /private spellings, $TMPDIR and any path with a component spelled tmp. Each target is judged as written, made absolute against the directory the hook runs in, and with symlinks resolved, so either spelling of a symlinked temporary directory is caught. A target is found in every field a harness names it in: a path field under any of its spellings, a patch's file header, a list of edits, and a target list of bare paths (files: ["<path>"]). The refusal is BLOCKED: Temporary-path Read/Edit/Write/Save operations are not allowed: <targets>.

Credential stores are never copied: block-credential-copies

A gate on the shell and on the tools that write files (tama hook block-credential-copies) that refuses a command, or a source file a write leaves, that copies a harness's credential store. An OAuth refresh token is spent when it is used: a process that refreshes an account from a copy of the store voids the token the original holds, and every account the copy carried stops signing in wherever the original is used. A test that ran a harness on a copied store signs its operator out of all his accounts each time it runs.

Artifact inspection: check-artifact-inspection

A trajectory may run again only once the session has looked at what its last run left behind. tama hook check-artifact-inspection <label> <command> <transcript> answers that question for pre-bash's trajectory counter: a first run needs WELES_FIRST_RUN=1 or written notes, and a later run needs evidence that an artifact of the label was opened since.

What the operator already knows

block-known-to-operator is a Stop gate that refuses a final message telling the operator what he already knows: what this session already told him, or what he himself decided — a refusal from his own hooks, a limit he set, a rule he stated — handed back to him as a blocker, a limitation, a reason the work stopped, or as news.

Cloud instances need the operator's consent

block-cloud-instances refuses a shell command that runs a cloud provider's command line until the operator has directly consented to operations on cloud instances. It runs before every shell call; reads of files, edits and other tools are never touched.

No fallbacks

block-fallbacks is a write gate that refuses code which answers a missing or failed value with one nobody stated, or drops the error that says why it failed. A fallback hides the failure from whoever could fix it and turns into a decision nobody made; the rule is that a missing value is an error naming what is missing, where it was looked for and why it matters, carrying the cause it was given.

Incident references

The write gate (pre-write-edit) refuses a write that puts a pointer into the internal defect register or transcript store into product code or a public page. Such a pointer tells a reader nothing they can follow, and on a product's site it publishes the operator's internal history. Why a line or a page exists is said in the product's own terms; the incident stays in Oko.

Hook releases

How does an approved hook tree become the runtime a session loads, and how does Tama know nobody changed it in between? Through one identity: a hook release is a directory whose name and manifest are the SHA-256 digest of its own contents, checked when it is sealed, checked before it is installed, and checked again after it lands. Hook policy evolves separately from the desktop app, so the two have separate identities — the product version policy is in releases.

Integration contracts

Integrations extend Tama's local policy-control core. They do not own product state, and an unavailable optional integration must not prevent catalog inspection or emergency recovery.

Tama operational model

No log, cache, or UI snapshot is authoritative policy state. Hook catalog checksum and release ID are the evidence used to compare the signed bundle, installed release, and live runtime.

Release and versioning

Tama uses Semantic Versioning. The version of a distributable desktop release is CFBundleShortVersionString in App/Info.plist, the version source .wisent-release.json declares; stado release submit --version must name that exact version, and Stado refuses any other. The build stamps it on the app, the Network Extension, the update feed and the release evidence. Builds outside a Stado release keep their source metadata but are never supported or published.

Runbook

Something refused — which sentence are you holding, what does it mean, and what do you check next? Every heading below is an exact string from this repository's sources or a state you can reproduce; each entry says where the sentence comes from, what it is really telling you, and the first read-only command to run. Attribution tooling is in scripts; the executed evidence for the integrity entries is in the two walkthroughs.

Runbook: repository copies

The refusals of the block-repository-copies hook and of tama worktrees remove, each with where it comes from, what it means and what to do next. The rest of the refusal sentences are in the runbook.

Scripts reference

Every executable under Scripts/, with its arguments, environment, output, and exit behavior, and the tama hooks commands those scripts run. Two of them ship inside the app bundle and run on operator machines (emergency_disable_hooks and the sealed release with its own bin/tama); the rest are maintainer tools that run only in a checkout. The sealed CLI itself is documented in cli; the integrity model these commands implement is concepts/seal.

Testing and qualification contract

Qualification belongs to an exact source revision and the product built from it. Retain the command, exit status, report, supported screenshots or recordings, and the persisted or external state the run observed. A source test pass is not proof of a signed app, an installed hook release, a live provider session or the desktop. Missing dependencies and refused runs remain blocked.

CLI reference

53 topics

tama help

Prints the sealed public top-level command summary.

tama list

Lists every hook in the sealed catalog, either as a compact tab-separated inventory or as the complete catalog JSON document.

tama show

Looks up one hook by its exact catalog id and reports its source, command, description, rationale, and event bindings.

tama validate

Validates the sealed hook catalog, its source archive, justification metadata, secrets posture, and material runtime-install drift.

tama install plan

Shows the archive root and the target paths for every enforcement level without installing anything.

tama install

Installs Tama-managed user-global Git dispatchers for pre-commit, commit-msg, pre-push and reference-transaction, preserving each pre-existing unmanaged hook once as .before-tama.

tama uninstall

The reverse of tama install: removes the Tama-managed pre-commit, commit-msg, pre-push and reference-transaction dispatchers and restores the hook each displaced from .before-tama. A hook Tama did not write is left alone.

tama stage

Stage a session's recorded text edits without taking other changes merely because they share a file. Tama reads completed tool receipts, reconstructs their deltas and lets Git merge those deltas into a private index. It publishes that index atomically only when every selected transition succeeds. It does not edit working files, create a commit, compile source or install a product.

tama onboarding

The first-use walkthrough on the command line, and the inactive policy bundle it may adopt on the way in. The screens, the outcome they lead to and what first success means are on the Onboarding page; this page is the command.

tama mcp config

Prints the MCP client configuration fragment for Tama's native MCP server.

tama violations find

Replays the shared content and file-size hooks, reporting the first violation per file and one finding per crowded folder without modifying the repositories. The CLI, repair command and MCP tool use the same scanner.

tama violations declare-root

Declares a repository root to the audit when every file it holds is fixed there by somebody else's tooling, and refuses while anything movable is still in it.

tama vocabulary report

Lists every keyword list still written into a repository's code or data files, grouped by the words themselves, so every copy of one list is removed in the same change.

tama violations clean

Scans target repositories, asks Brama for one patch per repository per round, applies it with git apply, rejects rule-gaming, and re-scans until clean or the round limit is reached.

tama model-provider

Chooses the model service Tama's model calls ask — the objective reviewer, the stop review, frustration drafting and adaptive disputes — and checks whether it accepts this machine. Brama is the default; a machine without Brama declares any OpenAI-compatible chat-completions service instead, or declares that it has no model at all.

tama doctor

Diagnoses access to the configured model service from this machine without changing its provider, credentials or fleet declaration.

tama justify

Records, reads and retires the justifications the write guards require, so a registry that a hook demands is written by a command instead of by hand.

tama tests

Records the operator's approval of test code. block-unapproved-tests refuses every write of test code outside an approval, so a test exists only where the operator asked for it.

tama sessions

Reports every recorded live agent session and the hook state projected into its session-control record.

tama build

Writes and reads ~/.shared-hooks/build_restart_registry.json. A build needs the agent's written whole-task completion statement and one unused entry; the block-unregistered-build-or-restart gate consumes that entry for one attempt. Restarts retain their ordinary open entry. The CLI and Tama Desktop use the same registry operations.

tama enforcement status

Reads the durable machine-wide hook selection and the emergency switch that can temporarily bypass it.

tama enforcement only

Replaces the machine-wide baseline with an operator-owned selection of installed hook ids.

tama enforcement add and tama enforcement remove

Turn hooks on or off in the machine-wide selection while keeping every other hook it holds.

tama enforcement preflight

Asks one installed hook whether it can work on this machine, and prints the whole exchange.

tama enforcement all

Restores the all-hooks machine baseline without changing the separate emergency switch.

tama provider config

Prints the hook block an install writes into a provider's configuration: the wiring that makes an event of Claude Code, Codex or another coding-agent harness reach the installed runtime.

tama request

Answers one Tama Desktop request and exits: the JSON body on stdin, NDJSON events on stdout. Tama Desktop runs one tama request process per operation, so no Tama process stays running between two operations and no port is opened.

tama assignment show

Prints one session's newest operator instruction verbatim together with Oko's current task ledger, then records that both were read. A question about the task is not itself a replacement task, and a session summary is not a source of task state.

tama adaptive

Opens the public adaptive-layer doctor command group for inspecting state, detecting drift, drafting repairs and applying them.

tama adaptive status

Reports adaptive autonomy policy, per-hook effective state, source identity, and telemetry transport status.

tama adaptive drift

Compares the SHA-256 content of every mapped live hook script with its source in the Tama archive.

tama adaptive queue

Lists repair proposals recorded in closed adaptive telemetry segments.

tama adaptive repair

Drafts or accepts a candidate hook script, validates it against the hook's evidence corpus, and stages a repair proposal without changing the live hook.

tama adaptive apply

Applies one previously validated adaptive repair proposal to the live hook and, when mapped, its archived source.

tama worktrees

Opens the command group that reports and removes the linked git worktrees under roots you name, because a linked worktree is a second checkout of a repository you already have.

tama worktrees list

Reports every linked git worktree under the roots you name, with its branch, head, dirty, locked and prunable state, and mutates nothing.

tama worktrees remove

Removes every linked git worktree under the roots you name, previewing the whole pass unless --apply is given, and refusing the entire pass before deleting anything when a selected worktree is dirty or locked.

tama copies

Opens the command group that reports and removes the second full checkouts under roots you name, because a repository copy is a checkout of a repository you already have that git knows nothing about.

tama copies list

Reports dependency checkouts, bare Git caches and other second repository copies under the roots you name, with their canonical checkout, apparent size and removal refusals. It mutates nothing.

tama copies remove

Removes every repository copy under the roots you name, previewing the whole pass unless --apply is given, and refusing the entire pass before deleting anything when a selected copy carries work that exists nowhere else.

tama contributions

Reports to Wisent's contribution ledger, in compute.wisent.com, the commits that reached a repository's remote with a standing attestation, so the people who write accepted code are credited for it.

tama rules

Reads proposed policy repairs, drafted rules, and unresolved corrections from Oko. It groups evidence across agent sessions without silently installing a hook.

tama policy

Imports, lists and removes retained inactive policy bundles: hook policy trees validated and kept beside the runtime without being installed or enabled. Nothing here changes which hooks a machine runs; tama enforcement decides that.

tama hooks

The halves of adding, changing or keeping a hook, each behind one verb. declare writes the repository documents — the catalogue entry, the registry binding, the reconciled sources and the seal; undeclare is its reverse. release builds the native hooks from published main, installs the ones that changed, and stages, seals and installs the live release this machine runs. warm runs each installed binary once so the operating system's first-execution assessment is paid outside a live event. The packaging verbs — stage, seal, source-identity, install-release, integrity, digest — are the release build's and the installer's own steps, exposed so a person can run and verify each one.

tama task scope

Declares, shows or clears which registered work one session is serving — a defect in Oko's register or a task in its task register — and which repositories that work touches. The block-off-task-work gate checks every write against this declaration: a call that changes a repository outside it is refused with the declaration to make.

tama reviews

Inspect the results retained by Tama's model review of a commit before it is created (tama hook review-commit) without repeating it, calling a model or changing provider credentials. A push is not reviewed by a model and retains nothing: review-push reads the attestation each commit carries (tama attestation). The Reviews screen reads the same records.

tama hook commit-lock

Git keeps one message file per repository (COMMIT_EDITMSG), whichever index a commit is made from, a private GIT_INDEX_FILE included. It writes the message after the pre-commit hook and reads it back after commit-msg. Two commits running at once in one checkout therefore each record whichever message was written last: one commit can land with the other's message over its own staged files, after each review passed the pair it was shown. The managed Git dispatchers allow one commit at a time per checkout.

tama reviews harsh

A commit is made only on rounds of harsh review by a reviewer that is not its author. The author's own attack lines in the commit attestation are one pass he writes himself; they can say an attack failed while he knows the defect, and nothing repeats them. So tama hook review-commit, which Git's commit-msg hook runs for every commit of every session, reads the rounds recorded for the commit being made and refuses it until a round by someone other than the author, over the exact staged tree and message, found nothing.

tama standing

Every agent session's commit standing. The commit review makes every commit a session asks for, whatever the form of its files, and scores the session for it: a commit whose staged files are all in their formatter's form earns one point, and a commit that stages a file out of that form costs one point and names the files. A Rust file is judged by rustfmt; any other file by the formatter the committed tree declares for its extension in .tama/formatters.json, such as [{"extension": "swift", "argv": ["xcrun", "swift-format", "format", "--configuration", ".swift-format"]}], run in the tree written out into the checkout's ignored build directory with the file's path appended and its formatted text read from standard output. A tree without that file declares no formatter and its other files are not judged; a declaration that cannot be read or parsed, an entry with an empty argv, or a formatter that fails is reported with its cause and scores nothing. A session's standing is the points it earned less the points it lost; below zero it has committed more unformatted work than formatted, and block-negative-commit-standing refuses every tool call it makes until the operator takes a charge back.

tama format fold

Folds the formatters' form into the unpublished commits that wrote each file: rustfmt's for Rust files, and for any other file the form of the formatter the commit's own tree declares for its extension in .tama/formatters.json (see tama standing). The push gate (check-rust-format) refuses a push whose commits carry Rust files rustfmt would write differently, a repository's own format gate refuses its other files, the commit review charges the session that commits a file out of its formatter's form, and it refuses a commit that only reformats, so the formatting belongs inside the commits that wrote those files. tama format fold puts it there.

tama attestation

An agent's own attestation, read without any model. A commit carries its attestation in its own message: every claim of the commit standard, word for word. review-push reads every commit a push adds and refuses the push at the first commit whose message lacks a claim, naming the commit and each missing claim. When every ref passes, each pushed commit is recorded in Oko's claim register as a push claim on <repository>@<commit> (the checkout's folder name) carrying review-push's structural verdict, which holds: oko claims list --subject <repository>@<commit> and Oko Desktop's Claims section show it, and Tama keeps no review record of its own. A claim that cannot be recorded is said on stderr (review-push: commit <sha> is not recorded as a claim: <cause>) and does not change the push's verdict; a machine without Oko says this machine has no Oko, so the pushed commits are not recorded as claims. An answer that ends a turn carries the claims each turn-end stop hook declares (check-stop-asking, block-false-blockers, block-stop-on-own-work), and those hooks refuse an answer that lacks one in the same way. Nothing is asked to judge either: no model, no key, no Brama, so a push and a turn end are judged the same on a machine with nothing but Git and Tama. A session's attestation that its task is finished is different: it is recorded, and on a machine that declared no model (tama model-provider set --none) the stop gates that would otherwise ask a model read it instead.

tama commands judge

The review a write that declares a new command waits for. block-one-off-commands reads every command a written file declares — by the language's structure, whoever declared it — and decides the write from the verdicts already kept for that file path, command name and declaration. A command without a kept verdict is never let through: the hook publishes a review request and refuses the write at once, naming tama commands judge <request>. No judge runs inside the hook. This command is that review, run in the foreground: it asks the judge whether each command is a general primitive or a one-off workflow, keeps the verdicts and prints them, and the same write is afterwards decided by them alone.

tama judgement ask

The model call a gate on a shell command does not make inside its hook. block-one-off-repairs, block-background-execution, block-external-source-edits, block-inline-execution, block-keychain-prompt-commands, block-local-model-training, pre-bash and block-device-level-tests-without-consent judge a command by asking a model through Oko (oko gateway object), and a model call takes longer than a harness waits for a hook: a gate that waited was abandoned and decided nothing, and while Brama or Skarbiec stood unreachable every shell of every session waited with it. So the gate decides a command from the answer already kept for that exact question, and a command not yet judged is refused, never let through, with the request that asks it named.

Walkthroughs

3 topics

Walkthrough: inspect runtime status

What is installed, and what would an install or an emergency re-enable hit? Two read-only answers: the sessions the runtime is supervising right now, and the integrity of every installed release tree — the second integrity gate an install passes through. The integrity commands run tama hooks integrity against a scratch home holding a copy of a sealed release, so nothing operator-owned is touched. Outputs are pasted verbatim with scratch directories abbreviated to $H. The desktop shows the same facts on Posture and Session.

Walkthrough: verify a hook release seal

Can you prove, byte for byte, that a hook release is exactly what was sealed — and when it is not, name the file that changed? This walkthrough does both, read-only, against a real sealed release: the one installed on this machine under ~/Library/Application Support/Tama/hooks-runtime/releases/. Every command below was executed with tama hooks integrity; outputs are shown as the command prints them, with that release directory abbreviated to $R and the identifiers of one machine's release written as placeholders: <release id> for the sealed digest, <drifted digest> for a digest that differs from it, <commit> for the source revision and <sealed at> for the seal's time. The identity model is concepts/seal; the command is in scripts.

Examples

Runnable, commented shell scripts, one bounded CLI outcome each. Every script states whether it reads or mutates before its first command; mutation scripts require explicit environment inputs before they act. The command surface is documented in docs/cli.md; the two integrity scripts are executed end-to-end with pasted output in the walkthroughs.

Project

2 topics

Security policy

Report vulnerabilities through the private GitHub Security Advisory channel for wisent-ai/tama-desktop.

Changelog

All user-visible changes follow the categories required by releases. A published section maps to the Stado release of the same version.