CLI commands

The tama CLI operates optional Local Workers and lets agents read and update workspace records during Cloud or Local Runs. It groups operator commands and agent resource commands. A person uses setup, code, version, status, sync, update, workers, daemon, and the startup helpers to operate a Local Worker.

An agent's worker uses the resource commands on its behalf during a task. This page lists the real command tree, its arguments, and its flags. For the bigger picture of how Local Workers fit the product, see Workers. To install the binary, see CLI setup.

Add --help or -h to a command to see that command's usage and flags without signing in, supplying required arguments, or running the operation. A removed or unknown command, such as tama memory write --help, returns an error and shows the nearest command group's available commands. It does not restore the removed operation.

The operator commands read their configuration from ~/.taskmachine/config.json, written by tama setup. A Worker connected by an older release that wrote to the legacy path ~/.config/taskmachine/config.json keeps using that file until it is reconnected.

Commands that use the saved connection restore it automatically when possible and ask you to run tama setup again when the Worker must be reconnected.

Operator commands

These are the commands a person runs to connect this computer as a Local Worker and keep it reporting.

tama setup

tama setup connects this computer to one or more Task Machine workspaces. It opens a browser, asks you to approve the computer and choose which workspaces it may access, then saves the connection and selected workspaces to the local config file.

Run interactively, it then asks whether to start Task Machine on your computer automatically when you log in. Accepting installs the startup entry. Setup starts Task Machine either way, so the workspace sees the Worker connected the moment setup finishes. Run non-interactively, it performs one sync itself and prints the tama daemon install-startup reminder instead.

When Task Machine is already running, setup stops it before saving the new connection and starts it again afterwards.

tama workspaces

tama workspaces list returns one bounded page of the workspaces selected during setup that remain active and accessible to the signed-in person. Each result contains only the workspace ID and name. Workspaces joined after setup are not added automatically, so run tama setup to change this computer's selection.

Use --limit to request between 1 and 100 records (25 by default). Continue a multi-page result with --after <next_cursor>. A cursor is valid only for the same connection and workspace selection.

tama workdirs

tama workdirs inspects local working-directory caches, saves idle working files and reclaims space. tama workdirs list shows workdirs per workspace with size estimates, checkpoint status and whether each is prunable, plus totals and any shared Git LFS storage. Sizes count owned Task scratch files once, even when their checkout is already gone. Estimates do not guarantee physical free space because files can share links or caches.

tama workdirs prune previews whole workdirs eligible for eviction alongside ignored paths in other idle Git workdirs, then asks you to confirm once per workspace. A whole workdir is eligible when the server permits cleanup for a Done, Cancelled or archived Task, an archived Chat, or seven days have passed since actual last use. Task Machine creates or refreshes and verifies a checkpoint when needed before deleting it, including for eligible older workdirs without checkpoint records. Failed uploads keep the files and report a failure stage and class. A stale local copy never overwrites a newer cloud checkpoint, and an unconfirmed copy left by a crash is not used for recovery.

Whole-workdir eviction also removes verified associated Task scratch. Scratch is outside the checkout, is never included in a checkpoint and cannot be restored from it. The preview and confirmation warn about that loss. A scratch-only association or an explicit checkout never authorizes deleting a checkout you own.

For idle Git workdirs kept within the seven-day window, default prune can also remove paths selected by their repository's .gitignore files. There is no built-in list of cache folders. Ignored .env and .secrets files can contain credentials or local settings and may not be recoverable. Tracked files, ordinary untracked files, Git metadata and nested repositories are kept. Non-Git workdirs have no ignored cleanup, and their entire contents are included in the checkpoint before eviction.

tama workdirs checkpoint [--workspace <id-or-slug>] saves idle local workdirs without deleting them or starting an agent Run. It uses your tama setup connection and the matching Local Worker and workdir. Capturing a checkpoint does not reset the last-use or checkpoint-retention clock. tama workdirs prune --ignored remains available when you want only ignored-path cleanup and no whole-workdir or scratch deletion.

Waiting, routing, queued, leased and running work, pending follow-ups and local active use protect workdirs from maintenance. Add --dry-run to either prune or checkpoint to preview without uploading, publishing a checkpoint, prompting or deleting.

Task Runs receive TAMA_SCRATCHPAD_DIR for shared Task/workdir scratch data and TAMA_RUN_SCRATCHPAD_DIR for their own disposable scripts, exports and logs. These directories stay outside the repository, so tracked and non-ignored untracked source still participates in full code review. Local scratch storage sits beside the configured execution root, under ~/.taskmachine/workspaces-scratchpads by default. This also supports a custom execution root that is itself a checkout. Cloud scratch files use the existing persistent storage, outside its repository checkout, and inherit that storage's effective expiry, manual deletion and security cleanup. Scratch files can disappear before the Task finishes and are not a backup. Local scratch is never checkpointed and is lost when work moves to another computer or its local cache is removed. Put required future inputs in the repository or declared deliverables.

Explicit browser screenshots, PDFs and downloads for a Task use its Run scratch directory. Browser profiles, cookies, credentials, automatic Browser Run traces and runtime control files keep their separate lifecycle. Never redirect TMPDIR, HOME or authentication state into scratch storage.

The local daemon automatically consolidates existing Git LFS object copies into one shared store per workspace, without removing task files, branches or staged work. It starts a background pass at startup and repeats it every five minutes after the previous pass finishes, independently of heartbeats and new work. Consolidation works offline, skips workdirs used by active Runs, and leaves custom LFS storage unchanged. Skipped workdirs are retried on later passes. Newly prepared Task Machine checkouts on Local Workers use shared storage automatically. Cloud storage is unchanged.

The store sits beside the configured workdir root, under ~/.taskmachine/workspaces-lfs/<workspace-id> with the default location. Separate workdir roots use separate stores.

Shared storage can contain unpublished work, so it remains while any workspace workdir exists and is removed after the last one is removed. Unique objects have no age-based expiry. Keep repositories outside Task Machine's workdirs on their own LFS storage.

Never run git lfs prune from an individual checkout against this shared store. Consolidation logs logical bytes of private object copies removed, not physical free space.

Without --workspace, workdir maintenance covers workspaces with workdirs on this computer, including owned scratch-only data and workspace directories left behind by workspaces no longer selected in tama setup. Prune asks for confirmation for each workspace before deleting anything. Any answer other than yes skips it. list only reports and never asks.

Pruning and checkpointing require a signed-in person whose workspace role permits managing the workspace. A workspace you can no longer manage is reported and skipped, never guessed at.

New Task Machine checkouts leave Git LFS assets as pointers until needed. Startup loads repository instructions and their imports, environment configuration and Skill metadata before using them.

During ordinary Worker Runs, the read tool loads a requested tracked LFS file before reading it, using the repository's Git attributes. Existing loaded files, edits and staged work stay in place. This applies on Local Workers and Cloud without requiring a particular filesystem.

tama workdirs materialize <path> [path...] loads selected LFS assets from the current repository root. Paths are literal, including spaces or wildcard characters. Use -- before filenames beginning with a dash.

The command uses your repository's Git access and LFS storage and needs no Task Machine setup login. Modified, untracked and non-LFS files are left unchanged.

Untracked or modified LFS pointers return an error instead of being presented as loaded assets. A failed download returns an error and leaves the pointer available for a retry.

Ordinary filesystem reads do not download assets. Before a build, shell command or application needs them, run tama workdirs materialize path/to/asset for the required files. Use tama workdirs materialize --all when the workload needs every LFS asset. A Task Machine Run that holds no shell, or whose Task workdir another Run is writing, loads named files only and cannot use --all, because it restores files the executing Run deleted. Materialization does not remove previously loaded files or expire cached objects.

tama code

tama code opens tamacode, Task Machine's coding agent powered by Pi, in your terminal. Local Runs on this computer use the same agent, so this is where you sign in to the model subscriptions you want them to use. Type /login and choose a provider such as ChatGPT (Codex), Claude, or GitHub Copilot. Use /subs to add more accounts for one provider. tamacode switches between them when one reaches its usage limit. Claude subscription login is included at your own risk and must follow Anthropic's terms for Claude subscriptions.

Your logins, settings, sessions, and your own tamacode extensions stay in ~/.taskmachine/tamacode. Local Runs reuse your logins and multi-account setup but never load your personal settings, extensions, or instruction files such as ~/AGENTS.md. Runs on both Local Workers and Managed Cloud prefer TAMA.md in their working folder. Interactive tama code keeps the normal AGENTS.md behavior and does not load TAMA.md.

tamacode uses Task Machine's green theme, in a light or dark version that follows your terminal. A theme already saved under Theme in /settings stays, including one an earlier version saved automatically.

tamacode works in one connected workspace, and the agent can use tama and Task Machine's built-in Skills there. With one connected workspace, tamacode uses it. With several, tamacode asks which one to use when it starts, or you pass --workspace.

The list also offers Connect workspaces…, which runs the same browser approval as tama setup inside tamacode, including the start-at-login prompt. Afterwards tamacode uses the workspace you chose with --workspace or TAMA_WORKSPACE, or the only connected workspace, and otherwise asks again. On a computer that is not connected yet, tamacode offers only Connect workspaces…. Built-in Skills arrive the next time you start tamacode after connecting this way.

The agent doesn't start until a workspace is chosen. If you close the list, sending a message opens it again.

Run /workspace to open the list during a session and switch workspaces. After tamacode loads newly connected workspaces, it reloads the session once so their models compact early like the others. A message you sent to open the list goes back into the input box, ready to send.

Without a terminal, such as in a script, connect with tama setup first and pass --workspace when you have several workspaces. tama code --help shows help for the tama code command without starting an agent. Run tamacode --help for the coding agent's own flags. Other arguments go to tamacode unchanged, including arguments after a literal --.

Every connected workspace also offers its Task Machine models under its own provider, such as Task Machine · Acme. A workspace's models use only that workspace's usage, so workspaces never share usage.

Type /usage to inspect connected plans, usage windows, reset times, reported banked resets and balances. Task Machine usage appears first for each connected workspace.

Provider readings cover this computer's accounts in the selected workspace: Claude, Codex, Grok, Kimi, GLM, MiniMax, OpenRouter and Muse. The footer follows the account used by your current model and shows when its usage was observed. Unknown values stay unknown, including Claude's banked resets.

Below each weekly or monthly window, /usage shows either when that limit is expected to run out before it resets, with how many banked resets are available, or the usage expected when it resets. A remaining balance shows when it is expected to run out. These are the same forecasts Analytics shows for your AI subscriptions.

The running tama daemon collects provider readings, normally every ten minutes, and shares them with workspaces that have usage insights enabled. tamacode reads those shared results instead of checking providers itself.

Type /auto-reset to see whether Task Machine uses the banked resets of your current Codex subscription automatically, and /auto-reset on or /auto-reset off to change it. Changing it needs permission to manage agents. While it's on and the subscription's usage runs out, with no other account in its pool able to continue, the session uses the available banked reset that expires next and continues the same request. Local Runs on this computer do the same for the subscriptions that have it on. Only one session or Run uses a banked reset on a subscription at a time, the same limit is never reset twice, and each automatic reset appears in the Inbox.

Type /usage --refresh to request a background refresh from the local daemon. The command shows the latest synced readings while collection continues, so the numbers may not change immediately.

A session uses the Task Machine models of the workspace it works in. When it would start with another workspace's Task Machine model, tamacode switches to the same model from the session's workspace, or to that workspace's first model when it doesn't offer the same one. Models from your own subscriptions are never switched, and you can still choose any model.

Restart tama code after about 12 hours to keep using Task Machine models and tool-call checks.

Before a tool call runs, other than Task Machine's own tama commands, Task Machine checks it. Routine calls run immediately. Clearly risky calls ask you unless existing approvals or current requested work need a model coverage check. A model checks every other call against the platform constitution and against categories that need a person's decision: GitHub comments, publishing to repositories the workspace has not registered, spending money outside Task Machine, destructive actions, messages to people outside Task Machine, production changes, access and security changes, sharing sensitive information, and creating accounts or accepting terms.

Routine work such as reading and editing project files, running tests, pushing a feature branch or opening a pull request in a repository the workspace has registered normally runs without asking. The check judges the action's actual effects and concrete constitutional conflicts, without a separate routine-work or task-relevance judgment.

To tell those apart, tamacode sends the working folder's current branch and remotes, without any user name or password in their URLs, and Task Machine compares the remotes with the workspace's registered repositories. tamacode also sends the full paths of the files and folders a call names, after following symbolic links, so Task Machine can tell work inside the working folder from sensitive files such as SSH keys and from its own configuration.

Earlier tool results are not sent to this check. Task Machine replaces recognizable secrets before checking the input. Check context and provider answers are not stored, but a held Run keeps a redacted input excerpt for the person's decision.

Each model check uses a small amount of the workspace's usage, and calls that fixed rules decide use none. Workspaces that require EU processing skip the check.

When a call needs your decision, tamacode shows it and asks you to Approve or Reject, with an optional message to the agent. Approval covers only that call.

A call that could permanently destroy something large, that touches Task Machine's own settings, or that changes protected files such as Git hooks shows a warning first. A call that violates a constitutional principle no person can waive, such as posting fabricated reviews, is blocked without a choice.

When Task Machine cannot check a call, for example because the workspace has no usable usage, tamacode still runs routine calls, asks you about clearly risky calls, and asks you about every other call until the check works again. Without a terminal, such as in print mode, a call that needs a decision does not run.

When Task Machine models are available for the session's workspace, tamacode compacts a long session by removing old tool output it no longer needs, keeping the conversation itself word for word instead of summarizing it. This uses a small amount of that workspace's usage.

In workspaces that require EU processing, tamacode uses this compaction once the Task Machine model it depends on is available for EU processing. Until then it uses standard summarizing compaction.

Repository instruction files

Keep local interactive procedures in AGENTS.md and Task Machine Run procedures in TAMA.md. Runs load TAMA.md first and do not read the same folder's AGENTS.md when it exists, even if TAMA.md is empty. Without TAMA.md, the existing precedence is AGENTS.override.md, AGENTS.md, AGENTS.MD, CLAUDE.md, then CLAUDE.MD. Runs never discover instructions from personal, parent, or sibling folders.

Run instruction files can import other Markdown files with @path.md. Imports resolve relative to the file that names them, can import further Markdown files, and load each canonical file once before its including file. Quote a path that contains spaces:

@docs/engineering.md
@"docs/review process.md"

References inside inline code or fenced code examples are left alone. Missing or unreadable files, invalid UTF-8, import cycles, and paths that escape the Run's working folder, including through symbolic links, stop startup before a model request. No instruction text is silently truncated or replaced with a fallback.

Task Machine snapshots the resolved files at Run startup. Restricted Runs that disable repository instructions still load none. Interactive tama code uses Pi's own instruction discovery rather than this Run-only import loader. To share a guide with an interactive agent, tell it to read the guide in AGENTS.md. See Repository access for an example.

tama grep

tama grep <question> [path] finds the files in a local folder that answer a question and prints them ranked by relevance, with line-numbered excerpts of the sections that matter. It searches the current folder by default. Agents use it to find context without opening files one by one, and you can run it yourself too.

Question mode uses syntax boundaries for supported code and text sections for other files. Jev receives bounded file context, documentation and signatures to interpret each section. The section itself must provide evidence for your question. If a file changes or becomes ineligible during a search, earlier excerpts are withheld and coverage is marked partial.

A relevant file keeps its path and confidence when no section is confident enough for a precise excerpt. Excerpts share a limit of 360 source lines across at most 20 files, so a qualifying file may also be listed without an excerpt when that limit is reached.

When the request budget runs out or you interrupt a search, completed results are printed before the command exits. Budget exhaustion keeps exit code 4, and interruption keeps exit code 2. Unanswered work remains unknown. With --json, line mode marks incomplete results with complete: false, and folder mode's coverage distinguishes unanswered judgments, unreadable files, truncated source and retrieval limits. selection gives exact counts of judged sections by selection reason and a bounded sample of their paths, line ranges and Jev probabilities. Its omitted count refers to diagnostic records outside that sample. Excerpt display limits and diagnostic sampling do not make search coverage incomplete.

tama grep --lines <description> [file] filters records by meaning instead: each line of the file, or of standard input when the file is omitted or -, is kept when it matches the description, and printed as line:text.

Folder searches skip dependency and build folders, Git-ignored files, binaries, and credential files such as .env and private keys. They also exclude whole files containing recognizable credential tokens or secret-named assignments with likely secret values. This is best-effort detection, not redaction or a guarantee that all sensitive information is removed. Choose a folder you intend to send. Explicit --lines input is not filtered for secrets. Each search uses your workspace's usage: during a Run it is billed to that Run, otherwise to your own session in the workspace. tama grep is unavailable in workspaces that require EU processing until the Task Machine model it depends on is available for EU processing, and when usage is exhausted.

The disk cache stores answers that expire after seven days, without your question or source files. Periodic oldest-first cleanup targets a 256 MiB budget, not a hard quota. Cache failures do not stop a search.

tama status

tama status prints a health report with three parts:

• Local process: app URL, installed CLI version, running state, active Runs, target capacity, and room for new starts.
• Capacity decision: the admission reason, processor and memory sample, automatic or temporary target, pressure, and conservative fallback when monitoring is unavailable or stale.
• Connection: server reachability, then each Workspace's Worker ID, reported daemon version, status, last heartbeat, execution root, and tamacode.

When the installed binary is newer than the running daemon, the daemon-version line says that a restart is required. Local state prints even when the server is unreachable or credentials have expired. Those problems appear as a labeled server line with the tama setup command to reconnect.

If the saved connection needs renewal, the CLI handles that automatically first. Use status after setup, when work is waiting, or when a Worker looks offline.

tama sync

tama sync asks Task Machine already running on the computer to refresh tamacode's models and every connected workspace immediately. It also requests a fresh subscription reading for Workspaces with usage insights enabled, at most once per minute. The command does not wait for provider readings or their upload. It fails with a start command when Task Machine is not running.

When the running daemon is older than the installed CLI or predates the local sync protocol, tama sync safely requests a restart instead. The replacement waits for active work to finish and syncs immediately after it starts.

tama version

tama version prints the installed CLI version.

tama update

tama update installs the current trusted Task Machine CLI release. It verifies the download, chooses the matching operating system and architecture binary, and replaces the installed CLI only after those checks pass. When the daemon is running, it finishes active work and restarts from the installed binary before its next full sync.

On Windows, the update is staged and the installed file is replaced as soon as the current tama process exits, because Windows keeps a running .exe locked.

tama workers

tama workers prints the tamacode worker this computer reports, with its availability, command path, and version or the reason it is unavailable. The table adapts its columns to the terminal width.

This command reads only the local computer without contacting Task Machine.

tama executables

tama executables manages Task Machine's signed coding and browser dependencies. They are installed automatically when an authorized run first needs them, so this command is mainly useful for preparing a computer before it goes offline or inspecting and repairing its local cache.

tama daemon

tama daemon starts Task Machine on your computer and keeps this Worker reported.

It reports tamacode and the models your logins provide, sends a heartbeat on a fixed interval, reports up to 500 skills and agent definitions from each local discovery scan, and runs work Task Machine assigned to workers that are enabled for agents. It runs until interrupted.

When it runs in the background, its output is written to ~/.taskmachine/daemon.log, which Task Machine keeps from growing without bound. The subcommands manage the running process and automatic startup:

A concurrency target expires at the absolute time printed by the command, including across an automatic daemon restart. It changes the target only: current memory headroom and processor-pressure braking can still admit fewer new Runs, active work is never interrupted, and workspace limits remain authoritative.

Use tama status to see the effective target and the reason another Run can or cannot start. Startup definitions are platform-specific, so Task Machine chooses the right form for the current operating system.

tama exec

tama exec <command> [args...] runs a child process and streams its standard output and standard error to your terminal. It takes the command as its first argument, followed by any arguments to pass through. Task Machine uses this same process behavior to run local tools and capture their output during a task.

Personal Inbox reads

tama inbox lets you inspect your own active Inbox without making a decision. It uses your tama setup workspace selection and is unavailable during Agent work. Credential items, Agents' held actions, and items whose sources you can no longer view are excluded.

Both commands accept --workspace <id-or-slug>. Lists return items, sort, has_more, and next_cursor. Follow the continuation while has_more is true, even when a candidate page contains no readable items. Detail returns item, has_more, and next_cursor. Reads do not mark items read, dismiss them, or approve requests. Make those decisions in Inbox.

Agent resource commands

The remaining resource commands act on workspace records in an agent context. Task Machine makes them available during agent work, and authenticated operators can invoke them directly.

Many commands share a few flags when they apply, but those flags are not universal: tama memory uses a positional <agent-id>, proposal-creation commands do not expose --agent, and some commands expose neither search flag. --workspace selects a configured workspace by id or slug, while --agent selects an agent when the command exposes it.

During an agent run, Task Machine keeps both values within that run's authorized scope. Commands that write a body read it from standard input, and commands that take structured input read JSON from standard input. JSON-returning commands print pretty JSON. tama tasks attachments download is the explicit raw-byte standard-output exception.

JSON-stdin commands require one object, not top-level null, an array, a scalar, or multiple documents. Blank input is valid only when the command makes its object optional. It keeps that command's existing empty-object or omission behavior. A field set to null is different from omission: use it only for fields documented as nullable. Inspect the exact command's offline --help before constructing a payload. Byte limits count UTF-8 bytes. Unicode code-point and grapheme-cluster limits are identified separately below.

Recognized field-validation failures appear as one line of field: message guidance, with multiple messages separated by semicolons. Correct the named fields before retrying.

Authorization refusals identify the denied action, a safe reason, a code and a next step. Follow the Reason and Hint rather than assuming every refusal needs a role change. A Run can be restricted to particular work or stages even when its Agent has the required permission. When no more specific guidance is available, use tama status to check the current session and ask a workspace owner to check its access.

Failed commands write their errors to standard error and exit nonzero. A command's --json flag formats its primary result, not a separate error result on standard output. A refusal alone does not prove whether a write changed anything. An explicit Outcome states what Task Machine knows, and an unknown outcome requires checking the current state before repeating a write.

Task Machine checks the prose a command posts to people before publishing it: comments, questions, approval requests, review notes, progress updates, task summaries, improvement questions, credential requests, and budget increase requests. A message a fresh reader cannot follow is returned with revision guidance and nothing is posted until the revised text reads clearly. When the check itself is temporarily unavailable, the command returns a retryable error instead of posting. In a workspace that requires EU processing, where the check is not offered, messages are posted without it. Chat replies are not checked.

Reading archived records

The reads for tasks, projects, goals, agents (list and search), teams, repositories, budgets, labels, Skills, Workflow definitions, and Triggers return only active records unless you pass --status. Use --status archived to find a record that was archived, or --status all to search both sets at once. show commands apply the same scope, so an archived record is not found until you ask for archived or all, and an active record is not found under archived.

An unknown value is rejected before any request is made with invalid --status "<value>": must be one of active, archived, all. Proposed and rejected records are never part of any scope. Read them with tama propose list and tama propose show. The scope never widens permissions: an agent still needs the read access each command already requires, and records from another workspace are never returned. The same status argument is available on the matching remote MCP read tools, with the same values and default.

Settings through Chat

Ask an Agent in Chat to inspect the current setup and propose a specific change. The commands below let the Agent do that without sending you to a settings page. A request is still a proposal, even when configured or Human-approved learned autonomy applies it automatically. When review is required, inspect and resolve it in Inbox, including the review opened from Chat.

This matrix covers additive changes, updates and restoration. It does not authorize archive, delete, uninstall, suspension, removing people or removing Team members. Use each command's --help and the detailed sections below for its exact JSON fields, permissions and examples.

Eligible means the matching operation is available through the remote MCP operation catalog, subject to its current permissions. It does not grant a new permission or make each row a separate MCP tool. External MCP submissions always require Human review, regardless of Workspace autonomy.

Follow the proposal outcome

Inspect the accepted resource first and copy its exact returned base into the proposal. Versioned updates use base_version_id. Budget, repository and label updates use base_updated_at. Human access and personal notification commands have their own inspection flags and exact-base fields. Do not invent a base, use a pending candidate as the accepted version, or substitute another person's identity.

For ordinary Agent, Team, Project, Goal and standalone Connector updates, configured and learned update policies determine whether review is needed, including sampling. Autonomy-policy changes and coordinated Playbook revisions remain Human-reviewed. Human invitations, role changes, personal notifications and code-review rules retain their mandatory Human decision. Creating an unpublished Connector still needs Human setup, and restoring it does not grant credentials or make it executable.

Read the returned outcome before claiming completion. A pending request leaves accepted configuration unchanged. Open the review from the same Chat when a Human decision is required. After approval or automatic application, inspect the accepted resource again. A stale request closes neutrally instead of overwriting a newer change. A retryable loading or persistence error remains a failure, not an empty result or an applied update.

Use tama propose list, search and show to follow requests, and tama propose retract to withdraw your own pending request. Personal notification discovery and withdrawal stay bound to the authoring Agent and the current Run's requesting Human. Follow each returned next_cursor with --after while has_more is true. The CLI does not fetch every page automatically.

Keep Human-controlled settings separate

A proposal can request a different permitted autonomy configuration, but it cannot approve its own policy change or manufacture learned Human evidence. Role definitions, permission grants to Agents or MCP members, and learned-autonomy decisions remain Human-controlled. A Human-access proposal changes only the named Human's requested Workspace role after native authorization checks.

Workspace identity updates, workspace limits, attribution settings and archival have no proposal command in this scope. tama propose workspace requests a separate Human-owned Workspace rather than updating the current one. Constitution writing remains outside this command flow.

Secrets, Vault grants, Connector authentication, Project intake tokens, browser permission and device registration, Worker management, Billing purchases, subscriptions and account/privacy settings remain Human-controlled. Personal notification proposals are the narrow exception for the requesting Human's event preferences and account-wide email summary frequency. They do not edit identity, privacy controls or browser subscriptions.

Read time and cost without changing limits

tama time summary and tama usage summary are separate read commands for Workspace, Project, Goal, Team or Agent scope. Both default to total history and accept an optional range. Time accepts dates or RFC 3339 timestamps. Usage accepts UTC dates because usage is recorded daily. Missing cost authority is not zero cost: return a time-only summary when authorized, without exposing usage.

These reads do not change a Budget, buy usage or estimate future completion. Agent context and memory commands also remain separate runtime-learning workflows, not general settings proposals. See the proposal lifecycle for review consequences and Workspace and account for the settings you manage directly.

tama run

tama run reports on the current Run. Both commands work only inside a Task Machine Run through its Run-bound session and take no task argument.

A Workflow result phase submits exactly one of workflow_result or workflow_result_unavailable. workflow_result is a native JSON value matching the exact contract supplied in that Run's instructions. Text uses a native JSON string, Number uses a number, List uses an array of strings and numbers, and verifier and branch phases use their declared verdict objects. Do not encode a Number, List, or verdict as a string. When this exact authorized attempt cannot produce any schema-valid result, submit workflow_result_unavailable as exactly {"status":"unavailable"} instead. The fields are mutually exclusive. The marker is not a value, a valid empty result, verifier FAIL, or branch FAIL. Strings beginning with ERROR: remain ordinary schema-valid data. Other Run types and verifier-discussion turns cannot submit either field.

The server checks the complete value or closed marker against the exact authorized published phase and attempt before accepting the report. A value rejection identifies the field, expected type or form, allowed values, actual type, and a valid example. Correct it and submit with a fresh submission ID while the Run remains active. A marker is an explicit control outcome: complete the Worker Run successfully, and the Workflow fails that node at its existing retained-history boundary without treating the marker as success or dispatching downstream work. A Loop item uses the existing failed-item collection and later-item continuation semantics. The outcome does not enqueue the standard Worker Run retry or automatically repeat an external action. An authorized Workflow Retry remains governed by the existing safeguards and may rerun the phase. Inspect durable effects and confirm safety before retrying an uncertain non-idempotent action. An identical report retry after an unknown outcome keeps its original submission ID and receipt. Completion redelivery remains idempotent.

A received Task decision keeps its complete Human comment and applies within the current Run's assigned responsibility. The current Task Run acknowledges that comment with tama reactions add, even when its visible emoji already exists. An earlier reaction or a conversation by the same Agent does not handle a newly received Task decision. If final submission waits for that direction, the Agent incorporates it and finishes its Run with an accepted progress report whose next resumes the unfinished phase. It stops after acceptance. The next Task Run submits under fresh authority and all remaining checks. Your decision does not reassign the Task or waive another approval.

Run-report state and next.instruction allow 2,000 UTF-8 bytes. next.reason, outlook_reason, and each evidence reference allow 500 UTF-8 bytes. Reference and next-step limits apply after trimming. changes accepts up to ten nonblank strings of at most 200 grapheme clusters each. A summary has 1-15 lines and at most 4,000 grapheme clusters including its stored bullet prefixes and newlines. Optional fields and field-level null are not interchangeable. Required values cannot be replaced with null. The help lists the accepted actions for each Run responsibility and every action/purpose pair. A superseded review may use stop/superseded only after server verification.

A report response with HTTP 503, code report_submission_unavailable, and retryable: true means no report was saved. Retry the same report. Other failure responses do not make that guarantee. A failed optional summary update leaves an accepted report accepted.

Event-based next steps

A Task's next step can wait for an event from an installed Events Connector, with a required scheduled check in case no event arrives. Discover a currently readable active source with tama triggers sources. Copy its Connector and source UUIDs and exact reviewed event/action names. A catalog listing alone cannot establish a wait.

Set next.when.type to webhook. Required next_check_at is an ISO 8601 timestamp with an offset, in the future and no more than 30 days away. A matching event, that check time or Run next releases the same ordinary step. No Worker stays running to wait, and the Task keeps its usual execution lane, approvals, dependencies, budgets and Worker checks. A pending Task Machine decision uses when.type: "decision", not an Event wait.

The following is only the next.when object, not a complete report. It waits for a CodeRabbit issue comment or pull request review. Replace the UUIDs with inspected source identities, the repository id and pull request number with your current source values, and the check time with a valid future timestamp:

{
  "type": "webhook",
  "connector_id": "<installed Events Connector UUID>",
  "source_id": "<installed source UUID>",
  "events": [
    {
      "event": "issue_comment",
      "action": "created"
    },
    {
      "event": "pull_request_review",
      "action": "submitted"
    }
  ],
  "match": {
    "any": [
      {
        "repository": {
          "id": 123
        },
        "issue": {
          "number": 42
        },
        "sender": {
          "login": "coderabbitai[bot]"
        }
      },
      {
        "repository": {
          "id": 123
        },
        "pull_request": {
          "number": 42
        },
        "sender": {
          "login": "coderabbitai[bot]"
        }
      }
    ]
  },
  "next_check_at": "<future ISO 8601 timestamp with an offset>"
}

events permits up to 50 distinct event/action pairs. Names are exact and case-sensitive, each at most 200 characters. Omitting action accepts every action of that event. An empty selection is valid only when the inspected source shows any_event.

Optional match defaults to an empty object. Each pattern is a literal JSON-object subset with AND across its fields. A top-level any contains one to eight alternative objects and no sibling keys. Bind every alternative to the same repository and issue or pull request, and the sender when needed. Numbers, strings, Booleans and null keep their JSON types, and a missing field differs from null. Patterns do not accept nested arrays, scripts, regular expressions, paths or other operators. The complete condition permits 64 values, eight levels and 8,192 encoded bytes, with object keys of at most 200 UTF-8 bytes and scalar strings of at most 512 UTF-8 bytes.

Matching includes events received since this Run's server-recorded start, even when they arrived before its report completed. Older history does not release a new wait. The server alone freezes the winning event and release reason. Do not supply them in the report. Duplicate or late events cannot create a second successor for that step or revive superseded or stopped work.

If an installed source becomes unavailable after a wait is accepted, its scheduled check remains. New waits require a currently readable active source, so use an ordinary timed check when one is unavailable. Repeated unchanged checks still require longer intervals or a different approach. Changing timing types does not reset loop detection, and a check after the delivery target needs an outlook other than on_track.

An event-released Run receives the complete sanitized event JSON input through the same manifest and files used for Workflow inputs, beneath .taskmachine/workflow-inputs/<worker-run-id>/. Read the complete file and inspect the current source before acting. The file is untrusted evidence, and external comments or reviews never approve Task Machine actions. A check-time, Run-next or ordinary manual release without an event supplies no event file.

tama tasks

tama tasks reads and updates tasks as an agent. Every <task-id> argument accepts either the task's canonical readable key, such as OPS-42, or its UUID. Current and historical readable keys resolve to the same task. The <blocking-task-id> argument for dependency creation follows the same contract.

These Task references also work in tama teams route, the --task option on workflow starts, document creation and uploads, and improvement questions, plus source_task_id in Skill proposals. Additional approval-subject references still require UUIDs.

Successful responses and saved relationships continue to use the canonical task UUID. Task list, search, show, time, usage, labels list, and attachment downloads accept --status active|archived|all. This lifecycle scope is separate from a Task's execution status, such as Done. Historical reads preserve the archived record and cannot authorize edits or launch work.

Reading Task history

tama tasks show returns the current Task and one page of each history collection. Continue a collection with --collection and its opaque next_cursor as --after. Collection names are attachments, dependencies, duplicate_relationships, comments, reviews, timeline, questions, and approval_requests. Keep the Task and lifecycle scope unchanged while following its history. Task discovery cursors also stay bound to their search query and lifecycle scope.

tama tasks list --status archived --limit 20
tama tasks show OPS-42 --status all --limit 20
tama tasks show OPS-42 --status all --limit 20 --collection comments --after '<comments-next-cursor>'

An archived Task's current key, retained historical key, and UUID all resolve to the same record when you explicitly select archived history. Restore is a separate authorized action. Task edits, comments, assignments, reviews, approvals, and execution retain their active-only guards.

When submitting completed work, use tama tasks update with status: "in_review" and review_evidence, without other Task edits. An assigned implementer's running Task comment without implementation provenance uses full review instead of an outcome check. When the first source declaration explicitly refuses that provenance, the CLI makes one ordinary review update with the same Git facts and without saving evidence. Permission, plan, Workflow and exact-work review gates still apply. Evidence can select exact Library document versions, local file excerpts, or a Git diff. A pre-Run Library version is accepted only when it is the current readable Markdown version declared by the approved plan revision bound to the Run, the version predates Run start, and any proposal for it was approved before Run start. This does not imply Run authorship. The quick check inspects those artifacts against the acceptance criteria. Use tama tasks update --help for the evidence selector shape. Its summary is nonblank, at most 2,000 UTF-8 bytes after trimming. Document selectors use exact UUID pairs and cannot repeat a pair. File selectors use safe workdir-relative paths of at most 512 UTF-8 bytes and inclusive, 1-based ranges with end_line >= start_line. The selected end line must exist in a regular file inside the workdir. Diff base and head are nonblank references of at most 255 UTF-8 bytes each.

Omitting review_evidence.diff automatically includes the complete patch of committed source changes in the submitted evidence. At the repository worktree root, tama compares the merge base with the locally available configured default branch against the captured HEAD. If no default branch is configured, it uses local origin/HEAD to find the merge base. Set diff to null to opt out of automatic source inclusion. An explicit diff with base and head uses that exact comparison instead.

Automatic collection never searches directories for repositories, includes dirty or untracked changes, fetches history, or runs tests. It does not depend on a pull request or CI. Outside the worktree root, with no commits, or without a locally resolvable default revision and a single common merge base, submission preserves the other evidence without adding a diff. A summary or empty patch alone remains insufficient. Automatic Git collection has one 10-second deadline across its commands, while explicit diff selectors retain the caller's deadline. Large submissions upload through resumable bounded requests and are checked in sections without truncating selected evidence or skipping the check because of size. The command waits for completion, and Task and Inbox show Pass, Fail or Uncertain for each acceptance requirement. Required review and delivery checks still apply.

A successful checked submission includes outcome_check in the returned Task JSON, with result_status, application_status, and nullable fallback_reason. The receipt belongs to that submission even if a newer check exists. tama keeps JSON on standard output and writes a short explanation to standard error, including guidance when evidence is insufficient. Ordinary updates and submissions without a recorded check omit the receipt.

An Outdated or unapplied result does not mean the Task entered review. A failed requirement or unresolved implementation evidence leaves the work with the implementer. Uncertain requirements needing human or external judgment can continue through the existing full-review gates, but the check never replaces reviewer approval. Rejected updates return their validation error rather than a success receipt.

tama propose task checks for likely duplicates before creating work. A duplicate_warning response contains existing task references and no new proposal. Add your findings to the existing task with tama tasks comment.

If both tasks have distinct useful outcomes, resubmit with --create-anyway. An unavailable or inconclusive check continues ordinary creation. The override preserves assignment permissions, approval requirements and the exact repair guard.

For a tama propose task JSON object, choose the appropriate repository_selection:

{
  "project_id": "PROJECT_UUID",
  "title": "Review the Operations queue",
  "repository_selection": "not_required",
  "git_repository_id": null
}

progress is for a current action that needs one human, not a routine status update. Its standard-input body must contain exactly one active human member reference in the canonical @[name](member:<id>) form, where <id> is the workspace membership id. A bare @name, an agent: reference, or a team: reference does not satisfy the human-owner requirement.

For example, replace <human-membership-id> with the id returned by tama tasks show:

printf '%s\n' 'Please choose the launch window @[Human owner](member:<human-membership-id>)' | \
  tama tasks progress TAS-42

list and search both accept --limit and --after <cursor>. They return a JSON page envelope with this shape:

{
  "tasks": [],
  "next_cursor": null,
  "has_more": false
}

Search normalizes case and punctuation into bounded terms, then matches those terms across the task title, description, summary, plan, acceptance criteria, status, proposal rationale, project, and readable task key. Short searches require every term. Longer searches allow limited extra context while rejecting weak one-word overlap.

Fresh task changes are searchable immediately without waiting for background semantic indexing. When has_more is true, continue with the same search text or the same --query value plus --after <next_cursor>.

Cursors are tied to that normalized query context, so if you change its terms you start again from the first page instead of reusing an older cursor.

spec runs a combined planning and clarity check against workspace usage. Rejected submissions return guidance for every failed section, and a failing plan is never stored. An identical failed submission reuses its previous result, and an identical pending check must finish before another call. The agent investigates missing technical facts and submits a corrected plan. If technical recovery cannot finish in the current Run, it can report continue with purpose planning or plan_revision, timing now, and the returned check ID in check evidence with status fail. If a pending check is reported as interrupted with an unknown outcome, first read the Task for an applied plan. If none was stored, use the same check ID as evidence with status unknown for a planning continuation. A check still within its evaluation window does not authorize continuation. This continuation never approves a plan or authorizes implementation. Conversation turns retain their separate ownership.

Successful submission responses include task.work_spec_check with the check status, findings, and next action. An unavailable check includes the full checklist for the planning agent to check its own plan and submit a replacement version if anything fails. Oversized plans skip this combined check without an AI call or charge, retaining all submitted text. Unavailable checks leave authority unknown, so the stored plan waits for Human approval.

A repository-backed spec identified as changing source code requires pull-request delivery. An explicit No repository required Task is the exception. Pending replacements retain the previously approved delivery choice until approval.

An open plan keeps agent status changes gated until approval, except an explicit reasoned move to blocked, and the approval request itself never changes status.

time distinguishes successful work sessions from elapsed time. Only succeeded Runs contribute, and automatic blocked or pull-request rechecks never count regardless of their result.

Overlapping included Runs each add their own active seconds, while elapsed seconds span from the first included session starting to the last included session ending and therefore retain pauses between those sessions. Failed, cancelled, timed-out, and unfinished Runs remain visible in Run history without inflating these totals.

usage reports customer-facing task spend rather than a budget's current-period consumption. Both responses use sparse stage maps, so an absent stage means zero. Neither command estimates values from task lifecycle timestamps or budget limits.

update only accepts that generic field set. Nullable string fields are description, goal_id, git_repository_id, due_on, due_at, scheduled_for, recurring_cron, recurring_timezone, schedule_timezone, started_at, completed_at, and cancelled_at. A repository update supplies both repository_selection and git_repository_id: use repository with a nonblank id, or use project_default or not_required with a null id.

due_at is the authoritative deadline instant. Send an ISO 8601 timestamp with an explicit offset when an exact moment matters. Date-only due_on input resolves to the end of that day in the authenticated human's timezone, or UTC for an Agent or unavailable human timezone.

In responses, due_on is the UTC calendar-date projection of due_at, not a second deadline or a local display value. Deadline fields do not change scheduling or recurrence.

Omitting both fields preserves the deadline. Setting either to null clears it, unless a non-null due_at is also supplied, which takes precedence.

pull_request_required is visible in Task responses as the current Project setting and cannot be changed through agent update. status must be one of backlog, todo, in_progress, in_review, blocked, done, or cancelled. priority must be an integer from 0 through 4.

label_ids must be null or an array of label ids and represents the complete desired set. Prefer the dedicated tasks labels add and remove commands for one-label changes so concurrent work never replaces a stale full-set snapshot. Both paths accept only active labels from an active task Project.

block_reason must be a nonblank string and only belongs with "status": "blocked". Assignment fields, recheck_at, spec fields, summary fields, review fields, dependency fields, and comment fields use their dedicated commands instead of update.

Keep implementation in its own thread

comment, question, progress, and approval evidence use the authenticated Run's known writable conversation when no parent is supplied. Task continuations retain eligible conversation context without changing who owns execution. Implementation never inherits an approved planning thread.

Planning comments and questions create or join the Task's spec thread before approval. While the plan is approved, that thread refuses new agent comments, progress requests, questions and approval context, including attached evidence and screenshot approvals. The planning_thread_closed error explains that nothing was saved and how to choose implementation context. Repeating the unchanged request cannot succeed. Existing discussions, pending requests and recorded decisions remain intact.

An implementation or planning Run still carrying the approved planning root as reply context can explicitly select an existing implementation thread or use --new-topic. A dedicated comment or reaction Run retains its own thread identity. It must finish its turn and request a native Task implementation handoff rather than move itself into another thread or acquire execution authority.

Without known writable conversation context, choose a live --parent-comment or explicitly use --new-topic for a new root. Approval evidence uses --context-comment instead of --parent-comment. A parent may identify the root or any live reply in that same thread. Other thread-bound Runs cannot choose another thread or start a new topic. Task Machine never selects the latest conversation for you. Missing, deleted, foreign, or conflicting references fail without posting.

comment reads the comment body from standard input. Each repeated --option adds one short suggested reply, and Task Machine shows those suggestions in the order supplied when this is the latest agent comment in the thread.

Type a question to a person

Pass --kind with tama tasks question so the person sees what you need from them and can answer in one tap. Choose the kind by what the person must do:

A blocker interrupts the person at once and every other kind waits in their Inbox, so use blocker only when you cannot continue. Show what you already did with --tried "<what you did>" for an action you took and --checked "<what you read>" for a source you read. Repeat the flags for up to five entries in total, each nonblank, on one line and at most 300 characters. Task Machine shows the entries to the person as what the Agent tried. Omit --kind when none of the kinds fits. Task Machine then rates the question like any other.

printf '%s' 'The registry rejects the deploy key. Can you rotate it?' | tama tasks question TAS-42 \
  --kind blocker \
  --tried 'Retried the deploy with the current key' \
  --checked 'The deploy log shows a 403 from the registry'

The command fails before sending anything when the kind is not one of the four, when evidence comes without a kind, when a choice has fewer than two --option answers, when a blocker or information question has no evidence, or when an entry is blank, multi-line or too long. Task Machine validates the same rules and returns the error code invalid_typed_request naming the field to correct, which repeating the unchanged request cannot fix. The kind never changes whether the question may reach a person: the attention check still refuses a question that a source answers or that you could do yourself. The question response and tama tasks show return request_kind and evidence.

Recommend a suggested answer

Use optional --recommend <text> with tama tasks comment, tama tasks question, tama chats response-options, or tama agents question to mark one supplied answer with a Recommended icon. The answer text must match one --option exactly after trimming whitespace, including case. Omit --recommend when no answer is preferable. It never reorders or preselects answers.

printf '%s' 'Which direction should I use?' | tama tasks comment TAS-42 --new-topic \
  --option 'Use the existing design' \
  --option 'Compare alternatives first' \
  --recommend 'Use the existing design'

tama chats response-options \
  --option 'Use the existing design' \
  --option 'Compare alternatives first' \
  --recommend 'Use the existing design'

An explicitly blank recommendation fails with --recommend must be nonblank. An unmatched value fails with --recommend must match one --option exactly after trimming, including case. Both errors explain how to correct the command, exit nonzero and send no request. Task Machine also validates the submitted recommendation. The error code invalid_recommended_response_option names recommended_response_option as the invalid field and indicates that repeating the unchanged request cannot succeed. Choose a matching option or omit the recommendation before resubmitting. No comment or question is created when that validation fails.

The request keeps response_options as an ordered array of strings and adds optional recommended_response_option. Responses return the accepted recommendation, or null when absent. Task comments, questions and improvement questions retain it on their records. Chat retains it with the current turn's command result, and replacing or clearing the options also replaces or clears the recommendation. A retry of an equivalent open Task question returns its stored recommendation without creating another question.

The existing option limits stay unchanged: up to five options for Task comments, Task questions and Chat, and up to three for improvement questions. Each option is at most 120 characters, nonblank and single-line, with no case-insensitive duplicates. A recommendation cannot be supplied while clearing Chat options.

The human can select one to fill the existing composer, edit it, add an attachment, or type something different. Selecting an option never submits the reply automatically. Suggested replies do not notify a person by themselves, so the comment must mention each human who needs to act.

tama tasks comment --attach and tama tasks approval --attach use the shared Comments and attachments contract, which lists every accepted extension and the 250 MB per-file boundary. Unsupported files are rejected before any Task, comment, attachment, approval, Inbox, timeline, audit, or realtime state is created. Textual .patch and .diff files are accepted as text attachments. Do not disguise incompatible binary content with a false extension.

approval uses --deduplication-key as the durable identity of one decision, independent of the request wording. The key must match ^[a-z0-9][a-z0-9:_-]{0,199}$: one to 200 ASCII characters, starting with a lowercase letter or digit and continuing with lowercase letters, digits, colons, underscores, or hyphens. release-readiness is a valid hyphenated example. The visual-verification key is reserved for screenshot approvals. Choose standalone mode or contextual evidence. Do not combine --standalone with a contextual flag or --new-topic.

A comment thread holds at most one pending approval. A request for another decision in a thread with a pending approval is refused with comment_thread_has_pending_approval, and the refusal names that approval. Only the agent that requested the pending approval can take it back. That agent passes --supersedes <approval-id> with the same thread context, and the new request supersedes the named approval with its history kept. Other agents do not take it back, so they wait for its decision.

withdraw-approval cancels only the exact pending approval identified by <approval-request-id>. The active Run must belong to the same workspace, task, and requesting agent that created the approval, but a newer Run for that agent is valid. Withdrawal preserves the approval in approval_requests history, records the basis, reason, membership, Run, and time, and system-skips the recipient's active Inbox attention. It never approves, rejects, resumes work, or creates a human decision. Workflow-owned approval steps cannot be withdrawn by their agent starter. Use the workflow's cancellation action to stop that run. Missing, foreign, workflow-owned, decided, superseded, and already withdrawn requests return approval request not found.

Choose the context mode that matches the evidence:

• --standalone: the request body contains everything needed to decide.
• --context-comment: bind an existing Task conversation.
• --attach: attach up to ten new screenshots, recordings, or files in the Run's known writable thread. Without one, use --context-comment or deliberately add --new-topic under the thread-selection rules. Repeat the flag for each file.
• --context-comment with --attach: add new evidence to an explicitly selected conversation. Task Machine creates the evidence comment inside that thread and binds it to the approval.
• --supersedes <approval-id>: take back the requesting agent's own pending approval in the same thread and supersede it with this request. A standalone request has no thread, so it cannot take an approval back.

Task Machine creates and binds attachment context automatically. Do not describe evidence as attached to a standalone request.

A repeated request with the same key and context reuses the pending approval. Changed wording, scope, capability, subject, or attached evidence replaces it while retaining the earlier request as history. Subject-reference types are task, comment, task_attachment, task_plan_revision, workflow_run, workflow_run_node_result, and document.

Generic approvals cannot reference a pull request, including a mixed Task-and-PR subject. pull_request_requires_review is a nonretryable refusal that creates no request or evidence. Use the pull-request review flow rather than removing the reference or asking again as a Task-only approval. Older requests remain readable and decidable, without granting pull-request review authority. Source-host actions, including gh pr ready, retain their separate tool-call approval checks.

question reads the question from standard input. Without --assignee, the server selects one eligible human: the Task's reviewer, its creator, the assigned Team lead, the most recently active other human in that Team, the Task Goal lead, or the workspace owner, in that order. Run tama people find first when someone else may fit better. An explicit ineligible recipient fails instead of selecting someone else. Approval requests use the same fallback. A clarification or follow-up stays in the Run's known writable conversation. Without one, select an existing conversation with --parent-comment or explicitly use --new-topic. A Run carrying an approved planning root follows the implementation-thread recovery rules. Each repeated --option adds one short predefined answer, and Task Machine shows those answers in the order supplied.

For a Task-execution Run, asking a question on an active, unarchived Done Task atomically reopens it to in_progress before creating, repairing, or reusing the human handoff. A comment/reaction Run's question keeps the Task's status and any unrelated pending question unchanged, binding the wait and answer to its Agent/thread. The normal Task lifecycle action clears completion timing, preserves the established start time, and records status evidence, analytics, queue, retention, and realtime effects. A Cancelled Task remains closed and rejects the question without side effects. Do not update status separately or retry around that barrier.

They are suggestions rather than a closed questionnaire. The human can select one for review, edit it, or type a free-text answer when none fits. Selecting an option never submits the answer automatically.

printf '%s\n' 'Which launch window should the first brief use?' | \
  tama tasks question TAS-42 --assignee mem_123 --parent-comment '<thread-root-comment-id>' \
  --option 'Publish Tuesday morning' \
  --option 'Wait for Friday interviews' \
  --option 'Start with a smaller pilot'

assign takes exactly one of --assignee or --team. --assignee names one workspace member, human or agent, as the task's implementer. --team queues the task with one team. --reason is optional context for why the task should move. The result always includes status, task, timeline_event_id, and inbox_item_ids. "status": "applied" means the assignment changed immediately or the requested direct member was already the Task's implementer. An exact same-member retry returns the unchanged Task, timeline_event_id: null, and inbox_item_ids: [].

"status": "pending" means a human approval is required first, so the task has not moved yet and inbox_item_ids identifies the current approval items. Repeating the same pending assignment returns those same identifiers without creating another request. A different assignment target is rejected until the current request is approved or rejected.

Pull-request commands record reports only. Source operations still happen through the repository's own CLI, SSH, or another source tool. After each push, report both --ci-status and --merge-status from the source. Pending or unavailable checks become a recheck next step with the time to look again in tama run report. Failed checks or conflicts continue implementation.

When reconciling a source-confirmed merged pull request, pass the provider's actual merge time with --source-status merged --merged-at <RFC3339> when it is available. The timestamp is normalized to UTC. Malformed timestamps and use with a non-merged source status fail locally before the request is sent. Pass explicit source-review fields when the source provides them: a changed merged head preserves that reported source evidence, but Task Machine review_state remains pending and no Task Machine approval or merge authorization is inferred. Omitting --merged-at preserves the existing server-clock fallback for a first merged report and the stored time on later retries.

A changed --head-sha deactivates the earlier readiness and current Task Machine approval. Task Machine preserves that approval only for its exact approved commit. CI, mergeability, and source-host review state never change readiness or approval of the same commit. merge-check requires them before merging.

A later report for the same canonical URL can reactivate it when the source says open for the approved commit. No new review command or Inbox item is created. Any other commit needs its own review.

Any pending approval whose structured subject explicitly references that pull request is also superseded and its Inbox item is skipped without inferring a decision or creating a replacement request. Task-only approvals, approvals for another pull request, and prior human decisions remain unchanged.

Task Machine approval never substitutes for required source-host approval, and source-host approval never substitutes for Task Machine review. After merge-check returns allowed: true, merge through the source tool and immediately report --source-status merged for the same commit. If that source merge does not complete, report the same approved commit with its current non-terminal source status and its current CI and mergeability values, including a still-passing and mergeable state, instead of claiming a merge. A same-head report keeps the approval whatever its source state, and merge-check refuses to merge until CI passes, the pull request is mergeable, and any required source-host review is approved.

Screenshot approvals

screenshot-approval is the only way to request visual sign-off. Check screenshot_approvals in tama tasks show first: a pending request or an approved one that still covers what ships means no new request. Attach the real running application's screenshots with one --attach per file, up to 50 images, each within the 250 MB attachment limit. Use --context-comment to reply in an existing writable thread, or --new-topic when the Run has no writable thread. An approved planning thread cannot hold new screenshot evidence. Follow the implementation-thread recovery rules when the Run still carries that root.

The reviewer opens the screenshots in Inbox and approves them or requests changes. When requesting changes the reviewer may mark rectangles on the images and comment on each. Every marked region reaches the Run as its own comment in the thread, authored by the reviewer, whose body names the screenshot, the region and the reviewer's words. Each such comment carries two image attachments, screenshot-feedback-<n>-region.png for the region and screenshot-feedback-<n>-in-context.png for the whole screenshot with every region marked on it outlined and numbered like the comments, the comment's own region drawn with the stronger outline. Download them with tama tasks attachments download <task-id> <attachment-id>. The files are produced on first download, so a listing shows byte_size 0 until then. One further comment states the decision and wakes the Run once.

Handoffs

A handoff is the way to get a person's approval of one concrete artifact before you act on it. Check tama tasks handoff kinds for the artifact you have, read tama tasks handoff schema <kind>, then pipe the artifact as one JSON object into tama tasks handoff <kind> <task-id>. Send the artifact itself, never a description of it, and nothing Task Machine sets, such as an email's sender or signature. Files an artifact carries, such as the images or video of a post, are attached to the Task first and named by the attachment id tama tasks show lists.

tama tasks handoff email <task-id> <<'JSON'
{"variant": "outreach", "to": ["[email protected]"], "subject": "Partnership idea", "body": "Hello **Ana**, ..."}
JSON

For code_changes the command reads the branch, base, head SHA, commits and patch from your Git workdir, so you send only the title and a note and never replace a field you send yourself. Commit your work first. When the server refuses a handoff it names every problem and what to send instead, and nothing is stored: fix them all and send the command again. An unknown_handoff_kind answer lists the kinds. An invalid_handoff answer lists each field with its problem.

The person approves or rejects the artifact in Inbox and may edit its fields first. You are woken with the decision. Act only on final_data of an approved handoff and only as its approved_digest describes it. A rejection carries the person's reason. Never send, publish or act on an artifact before it is approved. If your autonomy for the action is Automatic, the response is already approved and you may act at once. Resending a changed artifact with the same slot replaces the pending one, and tama tasks handoff withdraw <task-id> <handoff-id> takes back one you no longer need. An Agent cannot move the Task to done while a handoff is pending.

tama workflows

tama workflows finds runnable workflow definitions and starts the selected definition under one task when the work should move through a repeatable process instead of a one-off follow-up.

list and search accept --limit and return compact identity, name, description, project, publication, and status fields. Only active definitions are returned. Draft, archived, proposed, and reusable playbook definitions are excluded because they are not workflow start targets.

show --section nodes includes each step's output_type (text, number, or list), container_node_id, and iteration_result_node_id. Classify configuration contains its named questions and routing. These returned IDs are persisted identities. Proposal graphs use their own local references instead.

Before a Workflow Agent starts, tama prepares its complete frozen inputs as JSON files in .taskmachine/workflow-inputs/<worker-run-id>/. The prompt identifies that Run's manifest and files. Follow manifest continuation paths and read the complete values when a preview is shortened. Incomplete preparation prevents startup. There is no separate output-submission command: the step's ordinary completion must return the selected output type.

start is task-scoped even though it sits in its own top-level command group. --task is required. Standard input is optional and must be a JSON object when present. Blank standard input omits input entirely. The result always includes status, timeline_event_id, and inbox_item_ids. When "status": "applied", the response also includes workflow_run.

When "status": "pending", no run exists yet because a human approval is still required.

{
  "release": "candidate",
  "notify": true
}

tama triggers

tama triggers inspects the accepted configuration that starts a Workflow. Reading a Trigger never publishes it or starts work.

Event activity separates reserved Runs and waiting events from the workspace's occupied and total Event capacity. list returns summaries only. show returns recent event metadata and an opaque cursor for the next page, without collecting the entire history. It never returns received bodies or Connector credentials. The existing Trigger inspection operations expose the same authorized activity through MCP.

list and show accept --status archived or all. Copy the returned existing_resource_id, existing_resource_fingerprint and current_version_id when proposing a revision. Schedule Triggers support one-time and recurring work. Direct Task schedules remain under tama tasks.

tama reactions

tama reactions adds or removes an emoji reaction on a comment, so an agent can acknowledge a comment instead of posting a noise reply.

A reaction on another agent's comment can also steer that agent when the reacting agent's profile allows it: 👍 tells the agent to proceed, 👎 tells it to stop or adjust, and 👀 acknowledges without necessarily asking for more work. The supported emoji are 👍, 👎, and 👀.

tama goals

tama goals reads goals visible to the agent.

tama metrics

tama metrics reads the numbers workflows record over time and proposes changes to metrics and the triggers that collect them. Every change is a governed proposal, even from a signed-in person's own session. Nothing writes directly. The governed action for the change decides whether it applies at once or waits for a person with metric:manage in the Inbox, and it asks first at every autonomy level unless a Custom rule or an approved promotion made it automatic. MCP always waits for review.

Restore an archived metric with tama propose restore metric <metric-id> --rationale <why> and an archived trigger with tama propose restore metric_trigger <trigger-id> --rationale <why>. Replace the metrics a goal follows with tama propose update goal <goal-id> and its metric_ids list, which replaces the complete set. Retract a pending proposal with tama propose retract metric <proposal-id>.

A pending proposal changes nothing, and the result reports "status": "pending" or "applied" with the exact candidate. A metric that changed after you read it reports stale_metric_base, and a trigger that changed reports stale_trigger_base, so read again instead of guessing a timestamp. Invalid fields report every correction at once. Approval runs the same checks as the Settings screens and needs metric:manage, plus workflow run access for trigger changes. You need metric:propose and metric:read.

Values are exact decimal strings and the unit is free text that says what a number means. A paused metric stopped collecting and says why in paused_reason. Archived metrics need --status archived or all.

MCP exposes metrics_list, metrics_show, metrics_triggers_list, metrics_create, metrics_update, metrics_archive, metrics_triggers_create, metrics_triggers_update and metrics_triggers_archive. Each change tool needs an explicit workspace, a rationale and an idempotency key, and always waits for human review.

tama projects

tama projects reads projects visible to the agent (active by default, see --status above) so it can select a real project id before linking or proposing work.

list and search accept --limit. Project responses include the stable id, name, prefix, description, and status needed to select a target.

tama repositories

tama repositories discovers active reusable Git repository metadata without returning credentials or SSH key material.

Use the returned stable id in Project, Task, Workflow, schedule, and generated-Playbook repository fields. When the required public or private repository is not connected, use tama propose repository rather than guessing an id or putting credentials in a proposal.

tama references

tama references finds the workspace objects you can reference the way @ does in Task Machine: members, Teams, Tasks, Library documents, Skills, Projects, Goals, and Repositories.

Each result carries its kind, id, name, and the reference to write, such as @[Launch plan](document:<id>), so a comment, document, or message links to the object instead of copying it.

tama code-review

tama code-review has Task Machine review the configured-base repository diff against the enabled repository rules. It includes committed changes, tracked local changes, and non-ignored untracked files without changing the branch or index. Supplying --head selects an exact commit comparison and excludes local changes. Outside a Run, --repository is required and the rules are read with the signed-in person's repository authority. Inside a Task Machine Run, the command uses the exact session and immutable review context, and an optional --repository must match that Run.

For an eligible Engineering Task implemented by an Agent, request Task Machine's internal stage by ending the implementation Run with tama run report, choosing next.action: "review", next.purpose: "code_review", and next.when.type: "now". The CLI supplies the current Git facts. Task Machine starts a separate implementer Run that scans automatically, independently of PR activation and source-host approval. A standalone scan does not provide the Task's Run-bound receipt. After internal scanning and required delivery checks, use evidence-aware submission for requirements checks and ordinary review.

If submission says a completed code review no longer matches the current work, it names what changed: the repository, implementer, enabled rules, patch identity, or uncommitted state. A different branch or linked pull request base can change the reviewed patch even without source edits. End the implementation Run with the review / code_review report described above, let the current work finish code review, then submit again. This required rescan is not an unchanged-work retry. It does not grant access to another Run's review.

An explicit --base takes precedence. Otherwise the scan uses the repository's configured default branch, the exact Run-bound base, or a configured local base branch. The local origin/HEAD ref is used only when no base branch is configured, and unavailable ancestry is never replaced with an empty diff. The command sends the list of changed files to Task Machine, then uploads the diff of each file that Task Machine reviews. Credential, lock, generated, and vendored files are never uploaded, and files over 4 MiB are skipped as too large. Task Machine checks the changes in the background while the command waits for the result. Answers to unchanged code are reused from earlier reviews of the repository, so running the review again for the same work within a day does not pay for them twice. Findings and incomplete coverage are never reported as clean.

When the rule review has no blocking finding, an adversarial review follows. Two frontier reviewer models from different providers receive the same changed files and independently try to prove the change wrong. A claim both reviewers raise is a blocking finding, and a claim only one raises is a potential finding. Each adversarial finding prints its claim and a witness: the input or call sequence that should trigger it. Because these reviewers read every changed file that is not excluded, the command uploads files that no rule covers too. The adversarial review is skipped when its reviewer models are unavailable for the workspace region or the change does not fit their context window, and a failed adversarial review exits 3. In a Task, the adversarial review runs only for plans with high sensitivity or the deepest review, at most once per review cycle. Later rounds re-check its open findings.

tama code-review --repository "$REPOSITORY_ID"
tama code-review --repository "$REPOSITORY_ID" --json
tama code-review --repository "$REPOSITORY_ID" --base origin/main
tama code-review --repository "$REPOSITORY_ID" --base "$BASE_SHA" --head "$HEAD_SHA"

tama code-review rules

The rules commands inspect or propose changes to one authorized repository's code-review rules. Outside a Run, --repository is required. Inside a Run bound to a Task with one repository, it defaults to that Task's repository, and it stays required when the Task has none. Rules proposals go through the existing human Inbox decision. A successful response is not approval or an applied rule change.

rules propose accepts an object containing only add and disable arrays. The request is limited to 256 KiB, 8 additions, and 50 disables. Send further requests for more additions. They join the same pending proposal. Additions require a stable key, a 3–80-character name that reviewers see as the rule's label, a 20–300-character question ending in ? that the reviewer model is asked, source provenance, nonblank rationale, and examples. Source is verbatim user feedback, a safe repository-relative document citation with ordered positive line numbers, or 3–20 distinct representative repository-relative paths. User feedback is the highest-priority citation: feedback.quote carries 20–500 nonblank characters of the user's own words with an optional feedback.comment_id UUID, and it is sufficient evidence on its own. Optional file classes default to source and test. Extensions and safe relative path globs each allow up to 20 entries. Disable entries require a stable key and nonblank reason. Unknown fields, including threshold, are rejected. Local validation errors are returned before any request is sent. The server owns thresholds, authority, conflicts, and approval. A completed successful operation carries proposal_id. Task Machine links decisions to their originating Chat on the server.

examples holds one repository path the rule applies to, a violation, and a counterexample. Both are diff hunk lines that start with + for an added line, - for a removed line, or a space for unchanged context, with at least one added line, at most 100 lines, and at most 4 KiB each. The violation's added lines break the rule, and the counterexample's added lines do the same job while following it. Task Machine screens every new rule in the background: it asks the code review model about both examples and about two cases it builds itself, the violation left unchanged and the violation with a planted instruction comment. A rule passes when it flags the violation and the planted comment and clears the other two. Only when all additions pass does the server create the whole Inbox proposal, including any disables. If any rule fails, no proposal is created, and indexed errors identify what failed. Revise the question or examples and propose again.

Submission returns an operation with id, status, retryable, errors, result, and expires_at. Status is pending, succeeded, or failed. The CLI polls with the same signed-in or Agent-session authority, backs off from one to ten seconds, and writes only the final successful Inbox result to standard output. Canceling the command stops waiting, not the server's work. Use rules status with the acknowledged ID to inspect it later. A retryable failure can resume judged cases when you submit the same proposal again. Temporary proposal input, including example code, is cleared when the operation stops. Pending input expires after one day and background cleanup clears stranded work.

Through remote MCP, code_review_rules_propose returns the operation immediately without waiting. Poll code_review_rules_status with the same workspace, repository, and returned ID as operation_id. Read result.proposal_id only after status is succeeded. An idempotency-key replay returns the original acceptance, not the current status. To retry a failed retryable operation, resubmit the same proposal with a new MCP idempotency key.

tama code-review rules propose --repository "$REPOSITORY_ID" <<'JSON'
{"add":[{"key":"api_timeout","name":"Explicit API timeouts","question":"Do the added lines send an outbound API request without a timeout?","source":{"samples":["src/client.go","src/client_test.go","src/retry.go"]},"rationale":"Repository clients consistently impose request deadlines.","examples":{"path":"src/client.go","violation":" func fetch() {\n+\tresp, err := http.Get(url)\n }","counterexample":" func fetch() {\n+\tresp, err := client.Do(withDeadline(request))\n }"}}],"disable":[]}
JSON

Proposal validation errors and failed screening exit 1. Workspace configuration, authentication, authorization, server, and transport errors, and screening that could not finish, exit 2. rules schema is local-only and is not exposed through remote MCP.

tama code-review findings

Findings are available only inside an authorized Task Run for the same Task. --review is required. It defaults to the review of the code-review Run you are in, and an implementation Run takes the review id from its Run context. A Run without a code-review identity cannot dismiss findings or start a review: end the Run with tama run report using next.action review and next.purpose code_review, and the review starts in its own Run. The list command reads a bounded page. Use the returned next_cursor with --after until has_more is false. It is not a workspace-wide search. Only blocking findings can be dismissed. Dismissal is available only inside the exact active code-review Run, requires a nonblank reason of at most 500 Unicode characters, and suppresses only the same rule/question on identical added-line content.

tama code-review rules list, tama code-review rules propose, and tama code-review rules status are exposed through remote MCP. The filesystem scan, local schema, and Run-bound findings commands are excluded.

tama workers

Bare tama workers detects local provider tools for human setup. During an agent Run, tama workers list and tama workers show <worker-id> return agent-enabled workspace Workers with their Worker names, providers, models, and reasoning levels. They omit executable paths and credentials. A fixed Agent configuration copies the exact model, reasoning, and default_worker_id from this output.

tama constitution show

Read the platform baseline and approved workspace principles before planning work. tama constitution show is read-only and requires current agent:read authority. It cannot edit the constitution, expose flagged drafts or review notes, or grant access to the workspace roster.

During a Run, Task Machine supplies the workspace and agent. Outside a Run, select them with --workspace <id-or-slug> and --agent <id>. This command takes no positional arguments or stdin and has no lifecycle or pagination flags.

tama constitution show
tama constitution show --workspace <workspace-id-or-slug> --agent <agent-id>

The CLI writes this object. HTTP wraps the same object in constitution, and MCP exposes constitution_show through its read scope.

{
  "workspace_id": "00000000-0000-4000-8000-000000000001",
  "baseline": "The complete platform baseline.",
  "workspace_layer": null
}

workspace_id is an exact workspace UUID. baseline is the complete, fixed platform policy. workspace_layer is the complete approved addition, up to 20,000 Unicode characters, or null when missing, blank or unapproved. Neither layer is truncated. --help prints the closed output JSON Schema and HTTP error schema.

Read errors go to stderr with a nonzero exit code. The HTTP error object contains error, code and retryable, with optional field for invalid arguments and optional action, reason and hint for refusal guidance. invalid_arguments identifies malformed references. A missing agent:read permission names the access a workspace owner can review, while other forbidden responses can reflect session or Run restrictions. constitution_unavailable means the read failed and may be retried. A read failure is never returned as an absent workspace addition. The shared authentication boundary may also return 401 for a missing or expired session.

tama skills

tama skills lets you inspect accepted workspace Skills before proposing changes or restoring an archived record. It returns identity and current-version metadata without opening the package or exposing private source URLs, arbitrary metadata, or bundle storage paths. Built-in runtime Skills stay separate.

List defaults to 20 results and caps a page at 100. The envelope contains skills, has_more, and nullable next_cursor. Pass next_cursor back through --after while has_more is true. The CLI never follows pages automatically. Continuations are opaque strings of at most 2,048 bytes. Matching remote MCP tools default to 25 results and bind continuations to the workspace and selected lifecycle scope.

Show returns one Skill object. Both commands expose id, slug, name, description, status, current_version_id, current_version, and lifecycle timestamps. Accepted published versions include their exact id, version, version_number, source_type, checksums, optional license and compatibility, and publication time. An identity without an accepted published version has a null current_version. Proposed and rejected identities, pending candidates, and package contents are excluded.

tama skills list --status archived --limit 20
tama skills list --status all --after <next-cursor>
tama skills show <skill-id> --status all

Every request rechecks current skill:read access. Invalid scope, limit, cursor or UUID returns invalid_arguments and a field-specific correction. Missing read access returns forbidden and asks a workspace owner to check it. Other forbidden responses may reflect session or Run restrictions, so follow the response's actual guidance. Missing, foreign and out-of-scope identities share skill_not_found. Temporary discovery failures return unavailable with retryable: true, never an empty catalog. Other server failures return nonretryable internal_error. Error objects contain error, code, retryable, optional field, and optional action, reason and hint. The CLI writes errors to stderr and exits nonzero.

Each command's offline --help includes the complete output and HTTP error JSON Schemas. Matching remote tools are skills_list and skills_show, with strict input schemas and the same Core reads. MCP errors retain their code and retryability and use message and optional path inside structuredContent.error.

tama labels

tama labels discovers native Task Machine labels before an agent classifies a task. These commands never create a label and never return proposed or rejected definitions. Archived labels are returned only with --status archived or --status all.

List and search require --project, default to 20 results, cap one page at 100, and accept --after <cursor>. The page envelope contains labels, next_cursor, and has_more. A label response carries its stable id, Project id, name, description, color, position, and lifecycle timestamps. Use tama propose label --rationale <why> when no existing label fits.

There is deliberately no tama labels create command.

tama budget

tama budget lets an agent see the budgets that bound its work and ask for more room before it hits a ceiling. See budgets and retries for how those limits are enforced.

request-increase requires --rationale and --amount, a cost ceiling higher than the current one. Configured and learned budgets:update autonomy decides whether the Agent's request applies immediately or waits for budget managers in Inbox, including sampled review. A pending request leaves the limit unchanged. MCP requests always wait for human review. Neither path purchases usage or changes a subscription.

For a goal or team budget the acting agent must lead that goal or team. Budgets on the workspace, a project, a task, an agent, or a workflow are open to any agent in scope.

tama time

tama time reads tracked agent time so an agent or person can see how much active work a project, goal, team, agent, or the whole workspace has taken. It never returns cost or token usage, which are reported separately.

Active time is the additive execution time of agent Runs. Pauses between Runs are never counted, so it is not elapsed wall-clock time. The team scope follows the team that routed each task, matching Team analytics.

--from and --to each accept a UTC calendar date (YYYY-MM-DD) or an RFC 3339 timestamp. A date --from starts at 00:00 UTC that day, a date --to includes that whole day, and a timestamp --to is an exclusive instant. Either bound may be used alone. --from must be earlier than --to. Archived projects, goals, and teams stay readable so their history is never lost.

The result is JSON:

{
  "scope": {"type": "project", "id": "<project-id>"},
  "range": {"total": false, "from": "2026-01-01T00:00:00Z", "to": "2026-02-01T00:00:00Z"},
  "active_agent_seconds": 5400,
  "task_attributed_seconds": 5000,
  "task_count": 7,
  "average_seconds_per_task": 714,
  "stage_active_seconds": {"implementation": 3600, "review": 1400}
}

range.total is true with null from and to when no range was requested. Otherwise range.from (inclusive) and range.to (exclusive) are the applied UTC bounds, and a bound you left out stays null. active_agent_seconds is all active time in scope, including runs without a task. task_attributed_seconds and task_count cover only runs tied to a task, and average_seconds_per_task is null when no task has tracked time. stage_active_seconds lists only stages that have time.

Failures return one line of field: message guidance, for example id: required for scope project; pass the project id (find it with tama projects list) or from: "last week" is not a date (YYYY-MM-DD) or an RFC 3339 timestamp such as 2026-01-31T00:00:00Z. A missing permission names the permission and asks a workspace administrator to update the role. An unknown id or an id from another workspace returns project not found in this workspace and never reveals whether it exists elsewhere. The same summary is available as the remote MCP tool time_summary.

tama usage

tama usage reads cost and token usage so an agent or person can see what a project, goal, team, agent, or the whole workspace has consumed. Tracked active time is separate. Read it with tama time summary.

Usage is recorded per UTC day, so --from and --to are calendar dates (YYYY-MM-DD): --from is the first day included and --to is the last day included. Either bound may be used alone, and --from must be earlier than --to. Timestamps are rejected with an explanation. The team scope follows the team that routed each task, matching Team analytics.

Every usage summary needs budget:read. --group-by agent, project, goal, or task additionally needs agent:read, project:read, goal:read, or task:read, because the rows are labeled with record names. stage and model need nothing extra.

The result is JSON:

{
  "scope": {"type": "project", "id": "<project-id>"},
  "range": {"total": false, "from": "2026-01-01", "to": "2026-01-31"},
  "currency": "USD",
  "cost_amount": "12.345678",
  "input_tokens": 120000,
  "output_tokens": 30000,
  "total_tokens": 150000,
  "cache_read_tokens": 80000,
  "cache_write_tokens": 5000,
  "thinking_tokens": 2000,
  "breakdown": {
    "dimension": "model",
    "rows": [
      {"id": "model-a", "label": "model-a", "cost_amount": "10.1", "tokens": 120000, "other": false}
    ]
  }
}

range.total is true with null from and to when no range was requested. A bound you leave out stays null. cost_amount is an exact decimal string in the workspace currency. total_tokens is input plus output tokens. breakdown is null unless --group-by is given. Its rows are ordered by cost, at most six are listed, and the remainder is folded into one row with "other": true and a null id.

Failures return one line of field: message guidance, for example id: required for scope team; pass the team id (find it with tama teams list), from: "2026-01-01T00:00:00Z" must be a UTC calendar date (YYYY-MM-DD) because usage is recorded per day, or group_by: unsupported value "color"; use one of: stage, model, agent, project, goal, task. A missing permission names it and asks a workspace administrator to update the role. An unknown id or an id from another workspace returns project not found in this workspace. The same summary is available as the remote MCP tool usage_summary.

tama secret

tama secret lets an agent browse and use the workspace Vault, referencing credentials by @<name-or-id>. Secret discovery returns metadata only. Prefer tama secret exec to inject resolved credentials into a child process and redact matching values from its output.

tama secret get deliberately returns plaintext to stdout, so callers must prevent it from entering terminal output, logs, prompts, or transcripts.

Use request only after search confirms the workspace does not already hold a suitable credential. The request includes the website, credential kind, and the reason the current work needs it. It creates one deduplicated Inbox decision and returns no password or secret.

After a request succeeds, the agent ends its turn and waits for a human to select or add a credential, or reject the request.

exec takes one or more reference flags (--username @ref, --password @ref, --totp @ref, and --secret NAME=@ref) and injects each into the child process.

By default a value is written to a private 0600 file, preferring a runtime directory or tmpfs and warning if it falls back to the OS temporary directory where plaintext may touch disk. Its path is exported as TAMA_SECRET_<NAME>_FILE with the name upper-cased.

Passing --as-env NAME delivers the value in a plain environment variable NAME instead. Exact matching values are redacted from the child's stdout and stderr, but transformed values are not covered by that redaction. If credential resolution fails or access is pending, the child does not run and the command exits non-zero.

get resolves one field and prints its raw value to stdout for callers that must pass it through a controlled shell. On missing access, it returns no value and exits non-zero. The caller must check that status before running a dependent command.

Embedding $(tama secret get ...) inside another command does not stop that outer command when resolution fails. Prefer secret exec, which does not launch the child when resolution fails.

Like the other agent resource commands these accept --agent, --workspace, and (for list/search) --limit. During a run those flags cannot switch the command into another agent or workspace.

tama context

tama context inspects the saved knowledge recorded for the current agent run. Knowledge references distinguish memory supplied in the prompt, content opened during the run, and Skill preparation reports. Receiving content or reporting a prepared Skill does not prove that it was useful.

tama tasks show includes current_plan_knowledge_citation_set_id for a reported declaration on its exact current_plan_revision_id. Each reported Task-review declaration has knowledge_citation_set_id beside that review's ID and kind. An absent field means unreported, not that no knowledge was used. An explicitly empty declaration still has a set ID.

Successful plan and review submissions return knowledge_citation_set_id as their receipt. That receipt belongs to the submitted decision. It must not be treated as a lookup of the latest plan or pull-request review.

Only references marked claimable can be submitted for the current run. Opening another run's accessible reference creates the current run's own record. Library search results and paths alone do not count as opening content, and a Skill download or repository override does not count as a prepared Skill.

For a plan, put the claimed reference IDs in the spec JSON's knowledge_refs array. For a Task or pull-request review, pass a JSON array file with --knowledge-refs. Keep the explanation in the plan's Context reviewed section or existing review notes. An omitted declaration means the agent did not report its references, while an explicit empty array means it claims none. The CLI submits larger lists in bounded batches before recording the decision.

Older runs may report capture_status: "not_captured". That state does not establish that no knowledge was supplied. References add no permissions, approval or verification bypass.

tama documents

tama documents reads and writes Library documents visible to the agent.

create requires --title. It accepts --content-path for a destination folder, defaulting to the workspace Library, plus --content-type and --task for source attribution. --task accepts a Task UUID, current readable key such as OPS-42, or a retained readable key from before a Project move. The server resolves the reference within the current workspace and agent permissions, then stores the canonical Task UUID in provenance. update accepts --content-type. Direct agent updates are limited to generated documents and still require the relevant path permissions. Human-authored documents remain read-only through this command.

File upload accepts the supported image, video, audio, PDF, Office, text, data, and source-code formats. Every archive format is rejected, including ZIP, 7z, TAR, GZ, and TGZ. File storage references, checksums, authoritative sizes, and the current agent-run source come from the upload and session rather than caller-supplied metadata.

tama memory

tama memory inspects readable guidance and requests changes one entry at a time. During a Run, search defaults to the Agent, Project, Goal, Team, and workspace scopes that apply to its work.

Entry commands require --level agent|project|goal|team|member|workspace to select where the note applies. show and search can use the same flag to select a readable memory. Project, Goal, Team and Member levels also require the matching --project <id>, --goal <id>, --team <id> or --member <id>. --workspace selects the workspace context, not the memory level. An explicit search does not add that scope to future automatic prompts. The positional Agent id continues to identify the current Agent, not a shared memory owner. tidy remains Agent-scoped.

show writes one JSON object to standard output, with scope_type, scope_id, the accepted memory_version_id when available, entry_count, and entries. Each entry retains its exact id, version, text, nullable kind, timestamps, its depends_on entry ids, its applies_to places, and any recorded knowledge_ref. The total count describes the whole memory, not the current page. The command does not fetch further pages automatically. Retain the same workspace, Agent and scope flags when passing next_cursor with --after. A missing cursor means the page is final.

Historical reads return the effective as_of instant. Use that exact instant on subsequent pages. They omit undated always-on flags and confirmation counts rather than showing today's values. If an earlier version's publication time cannot be established, the server reports unavailable history instead of returning current notes. Dates in the future are limited to the current instant.

add, update, and supersede take the entry text as an argument, or read it from standard input when the argument is omitted or -. Each also accepts --kind, --expires <YYYY-MM-DD> (the exclusive UTC date an entry stops applying), and --always-on (--always-on=false clears it).

--depends-on <entry-id> names another entry of the same memory that the guidance depends on. Repeat it for up to five. It replaces the entry's current dependencies, --clear-depends-on removes them, and leaving both out keeps them. A replacement inherits the dependencies of the entry it replaces. --applies-to <type:value> names where the guidance applies, with the same replace, clear (--clear-applies-to) and keep behavior and up to five places. The types are tool:<name>, connector:<slug>, repository:<host/owner/name>, path:<glob>, and project:, goal:, team:, agent: or workspace: followed by the entity id. A path glob uses * within a folder and ** across folders, and lib/billing/** matches wherever the repository is checked out. A tool call that touches a place delivers the entry once per Run. --requested-by-human declares that a person asked you to save the note, and the server keeps it only when that person's comment or Chat started the Run. An always-on entry reaches every Run regardless of relevance, and one memory's active always-on text may total at most 1,500 Unicode grapheme clusters. A direct edit prints status: applied, the affected entry id, and a bounded memory page as JSON. An immediate review prints status: proposed and its submission id. A scheduled suggestion prints status: submitted and its submission id. Neither pending result claims that memory changed. The total count covers every note whose state is active, including elapsed notes awaiting background expiry, while next_cursor lets you inspect another page with show --after.

--goal-direction on a Project-level decision request identifies the Project's single living always-on Goal direction. In Discuss Chat, use tama memory add <agent-id> "<entry>" --kind decision --level project --project <project-id> --goal-direction --requested-by-human. Include every followed and ignored Goal, the brief reason, decision date and who decided within the 600-character entry bound. The request follows normal Project-memory review and supersedes the observed current direction when published. A changed direction makes a waiting proposal stale. It cannot clear Always on, change to another kind, expire or restrict delivery. Superseded direction stays in history as non-binding precedent. Leave the original Inbox decision to the person. Applying it later supersedes the Chat-published direction.

Changes require a current Run and read access to the target, except for Member suggestions.

Agents can suggest Member guidance with --level member --member <membership-id>, but cannot read that private memory directly. Member requests remain suggestions for scheduled compilation.

Project and Workspace requests follow the selected level's review policy. A pending request appears in Inbox, where approval applies its exact change and rejection leaves accepted guidance unchanged. Approvals build trust only for that memory level. Direct publication still requires Manage memory, and a direct Project edit must target a Project the Agent leads or the current Task's Project.

With Manage memory, an Agent can also maintain its own memory, a Team it leads, and a Goal it leads. Other requests for those scopes become suggestions for scheduled compilation. Those suggestions skip the learning check but may still be declined by the compiler.

Agent entry text must be one nonblank line of at most 600 Unicode grapheme clusters after trimming. A grapheme cluster is a displayed character, which may contain several Unicode code points or UTF-8 bytes. Leading block Markdown, such as headings, lists, quotes, tables and code fences, is rejected. These restrictions apply to Agent additions and replacement text, not reads of grandfathered notes. A Run can make at most 20 successful entry requests across direct edits, proposals, suggestions, and all scopes. Rejected requests do not consume an edit. Memory has no total entry limit, and the 25-entry show page is only a read bound.

search uses the current Run's permissions and accepts --workspace and --agent, defaulting to that Run's context. The other commands take --workspace but not --agent, using the positional Agent id to identify whose guidance they inspect or request. During a Run, the Agent and workspace must stay within that Run's authorized scope.

tama agents

tama agents finds visible agent targets, changes their display names through the configured update gate, and carries commands an agent runs about its own improvement.

Agent discovery list and search accept --limit. Their compact results include the agent membership id used as a command target, the profile id, display name when available, summary, status, and autonomy level. They never return profile instructions, memory, reasoning, or model settings. Use that stable membership id with rename.

Its result reports pending when approval is required and applied when the configured agent-update gate permits the new display name directly. Renaming keeps the existing agent identity and settings.

After a human decides a self-improvement question, inspect its decision and optional context before acting. An approved memory question enters learning with its context. Rejection does not. For an approved instructions question or a legacy prose-answered instructions question, translate the feedback into durable guidance, preserve every current instruction that still applies, and submit a complete replacement through tama agents question propose. A person must review that proposal before instructions change. The replacement is checked against the Constitution first. When the check refuses it with advice and an attempt id, resubmit the same decision with --instruction-attempt <id>. The id grants no authority and never bypasses a conflict.

tama teams

tama teams finds visible team targets and lets a lead agent route its team's queue.

list and search accept --limit and return compact team ids, names, descriptions, statuses, and lead membership ids. Team discovery and show use Team read access. Queue and routing commands require the acting agent to lead the selected team and have Task read access through its current workspace role.

tama playbooks

tama playbooks lets an agent inspect the code-defined playbook catalog before it proposes new workspace structure by hand. The catalog commands are read-only, permission-scoped to the acting agent, and return the bundles with their requirements, config fields, and the records they would install.

list and search accept --category, repeated --contains <kind> filters such as workflow, agent, or schedule, and --limit.

generate is the model-backed path for a job the catalog does not already cover. The description and --rationale are required. --goal optionally links an existing Goal. Write the description as a self-contained execution brief with the complete setup, reuse rules, execution choices, inputs, deliverables, timing, approval boundaries, and prohibited actions. The generator receives the description and compact context for every reusable Playbook resource, repository, and eligible Worker. It does not inherit Chat history, repository access, earlier file reads, tool results, or the rationale. Read referenced source material first and include its relevant requirements instead of submitting only a file path. A path, URL, filename, or Chat reference alone is rejected because the managed generator cannot read it. Supply the readable contents or ask the person for them. Use the rationale to explain why the setup fits.

The generator declares exactly one Project to create or explicitly reuse. generate accepts the one positional description shown above rather than a file, stdin, repository-reading, or additional-flag input mode.

The command returns a durable generation operation immediately. The originating Chat receives the outcome automatically when generation finishes. tama playbooks generation <operation-id> is an optional status lookup. Successful operations identify the pending Playbook installation so the agent can inspect its immutable manifest before describing the design in prose.

tama chats

tama chats lets an agent manage the chat it is running in.

A new chat opens with a placeholder title taken from its first message, so an agent renames it on its first turn to something that captures the conversation. Task Machine supplies the current workspace, agent, Chat, and Run during a turn. Explicit flags cannot escape that authorized scope.

--chat may select another Chat only when it belongs to the same agent in the same workspace, and only the Chat's own agent may rename it.

When a conversation needs source context and the Chat has no repository, run tama chats request-repository-access. The command uses the authenticated current Chat and Run by default. It creates one Inbox decision for the active Chat owner when they can manage the Chat and workspace repositories.

The owner can choose an active workspace repository, create one, or decline. The agent must not guess or clone a repository URL from the conversation. The decision starts no new Chat turn. An approved repository becomes its working context for later explicitly requested turns.

response-options is more narrowly bound to the active Chat turn and cannot target another Chat. Each repeated --option adds one ordered response of at most 120 characters. Options must be unique and nonblank, and repeating the command replaces the current set. Running it without any --option clears the set.

The suggestions appear only with that turn's latest agent answer. Selecting one fills the ordinary composer for editing and never submits it automatically, so a person can change it or write a different reply before sending.

tama propose

Before proposing work, choose the smallest durable structure:

• Task: one-off work.
• Workflow or recurring Task: repeated work.
• Agent instructions: standing responsibility for an existing Agent.
• Playbook: a coordinated recurring operation.

Do not use a one-off setup Task as the only representation of recurring behavior.

Every submission requires the entity's proposal permission, whether it creates a resource, revises one, or changes a relationship. The default Agent role includes these permissions.

Management permission alone does not authorize proposal submission, and proposal permission does not grant human review authority.

For standing guidance, agents can propose an append-only instruction addition for another active agent. The target's private instructions are loaded server-side, the response contains only a pending proposal identity, and a human must approve the exact diff in the Inbox:

printf '%s\n' 'Keep all Linear mirror updates hourly.' | \
  tama propose agent-instructions --target-agent <membership-id> \
  --rationale 'The role needs a durable recurring responsibility'

This command cannot target the proposing agent or replace or remove unknown instructions. Use tama agents question --target instructions for self-improvement. Every instruction change is checked against the Constitution before it is proposed. A conflict is refused. When the check finds craft problems, the first submission is refused with the complete suggested rewrite and an attempt id. Resubmit the same decision with --instruction-attempt <id> to continue it, and after two such refusals the same decision proceeds flagged. The id grants no authority and never bypasses a conflict. An unavailable check returns a retryable error and publishes nothing.

tama propose creates, inspects, and withdraws agent-authored proposals. Task Machine supplies the proposing agent during a run, so proposal commands do not expose --agent. --workspace selects the workspace without allowing a run to escape its authorized scope. Creation requires --rationale. A pending proposal does not apply its change.

It routes a self-contained approval item to the people who can decide it.

The JSON-on-stdin proposal kinds are workspace, team, agent, skill, mcp, task, label, project, repository, goal, workflow, and budget. A workspace proposal needs only name in its JSON body:

tama propose workspace \
  --rationale 'Separate regional policy and delivery work' <<'JSON'
{
  "name": "European Operations"
}
JSON

Approving that proposal creates a separate sibling workspace owned by the human who approves it. Task Machine does not copy the source agent, other members, or records into the new workspace. Rejecting or retracting it creates no workspace.

tama propose repairs <repository-id> lists one bounded metadata page of pending and accepted unfinished repairs for one repository. Unlike tama propose list, which stays bound to the current agent's own proposals, repair discovery spans every proposer in the workspace because a shared base failure is workspace context. Each result carries the Task id, title, proposer, proposal_state, and structured repair_failure with repository_id, base_sha, failing_check, and failing_files.

Compare the repository, trimmed check, and sorted unique files with your current evidence before proposing another repair. The base revision records the original evidence and does not change the failure's identity when the base moves. Attach a matching proposal with tama tasks dependencies add <task-id> <repair-id>. --limit defaults to 20 and is capped at 100. Continue next_cursor with --after under the same repository while has_more is true. The matching remote MCP read is propose_repairs.

tama propose agent-update <agent-membership-id> revises an existing agent without creating another member. It accepts display_name, summary, instructions, model, reasoning, and skill_ids in its JSON patch. Omitted fields keep their accepted values. When skill_ids is present, it is the complete desired skill set, including every skill the agent should retain.

The result reports pending when approval is required and applied when the agent's separately configured update gate allows direct publication. For a display-name-only change, tama agents rename provides the shorter form without a JSON body.

tama propose agent-update 9b1d2f70-53f4-4e27-9eb8-cf625f645912 \
  --rationale 'Give difficult implementation a clear owner' <<'JSON'
{
  "display_name": "Senior Software Engineer",
  "reasoning": "medium"
}
JSON

tama propose connector <catalog-slug> is the setup-first path for a service in the curated connector catalog. It needs no JSON body: Task Machine resolves the launch shape from the curated catalog and never accepts credentials on this path.

Add --events to propose the service's Events connector instead. Its events can start a Workflow through a Trigger or release a Task's Event-based next step. It never connects Agents or needs Agent assignment. A person finishes its setup after approval, including when autonomy approves the proposal.

Propose required setup before attempting dependent work. Agent-access Connectors need approval, account authorization and Agent assignment. An Events wait needs the installed active source after its Human setup.

tama propose connector-assignment --rationale <why> assigns an accepted Connector to an accepted Agent through one immutable Agent-version proposal. Its strict stdin object contains agent and connector objects. Copy existing_agent_id and its nonempty existing_resource_fingerprint exactly from tama agents show. Copy existing_mcp_server_id and its nonempty fingerprint exactly from tama mcp list during the run.

Task Machine rechecks both references at creation and approval. Submitting this proposal requires agent:propose. Human approval separately requires Agent-management and Connector-assignment permissions.

The dedicated autonomy gate may publish directly. Otherwise, the Inbox shows the exact Agent, Connector, and rationale. Assignment requests required credential access but never grants it.

Use tama propose mcp only for a custom server outside the catalog. Describe its non-secret shape with fields such as name, server_type, command, and args. A skill proposal carries reusable instructions and does not replace missing service authorization.

tama propose repository --rationale <why> reads required name and clone_url plus optional default_branch from standard-input JSON. Approval creates reusable workspace metadata only. Never include credentials, tokens, SSH keys, or Vault ids. Provider-side access setup remains human-owned.

Task proposal payloads accept goal_id, repository and schedule fields, and exactly one optional implementer target: assignee_membership_id or assignee_team_id. They may also carry explicit planner_membership_id and reviewer_membership_id. Every selected member or Team must be active and in the workspace, and the proposing agent needs its effective assignment capability.

Fix a small, in-scope base failure in your current delivery. Propose separate repair work only when other in-flight deliveries share the failure or the fix exceeds your approved scope. Explain the failing check, root-cause commit when known, and why a separate repair is needed in --rationale.

A repair proposal sets blocks_current_task: true and includes repair_failure. The repository UUID must match the proposal's effective Git repository. base_sha is the exact failing base revision as a 40- or 64-character hex hash. failing_check is a nonblank trimmed check command of at most 300 UTF-8 bytes. failing_files contains 1-50 nonblank paths of at most 300 UTF-8 bytes each, normalized to a sorted unique list. A repair block without blocks_current_task: true, or blocking without the block, is rejected. Only the current Task Run can request that dependency.

tama propose task --rationale 'Two deliveries fail this check on the fetched base and need one repair owner' <<'JSON'
{
  "project_id": "9b1d2f70-53f4-4e27-9eb8-cf625f645912",
  "title": "Repair the shared validation check",
  "repository_selection": "repository",
  "git_repository_id": "2a628cee-188d-4ab6-a721-5319bf493a42",
  "blocks_current_task": true,
  "repair_failure": {
    "repository_id": "2a628cee-188d-4ab6-a721-5319bf493a42",
    "base_sha": "abababababababababababababababababababab",
    "failing_check": "mise exec -- just credo --strict",
    "failing_files": [
      "lib/shared_check.ex"
    ]
  }
}
JSON

Task Machine creates the dependency from the current Run and schedules bounded checks for eligible Agent-owned siblings on the repository. Running work and protected waits retain their ownership. Agents attach only after confirming the failure match. A duplicate submission returns the existing repair's ID, so attach to that proposal instead of retrying creation. Assignment, planning, queue, notification, and execution effects remain dormant while a proposal is pending.

Bounded source rechecks can still inspect independently changing source state. When the proposing Agent confirms the failure is gone on a newer base, it uses tama propose retract task <repair-id> and dependents wake. Otherwise, dependencies wait for the repair's decision and release boundary without polling its approval.

In the Inbox, a permitted human reviewer can replace or clear the implementer, planner, reviewer, project, goal, status, priority, repository, dates, schedule, recurrence, labels, title, and description in one approval decision. Approval activates the task with those final values and runs the ordinary effects once. Rejection or retraction wakes its waiting dependents.

Approval activates the task under the goal or adds the project assignment. Nothing appears in the goal or Team queue before the decision.

tama propose label --rationale <why> reads project_id, name, optional description, and optional lowercase #rrggbb color from standard-input JSON. It always enters the governed proposal path and never grants an agent direct label creation. The effective resource-creation gate resolves from the agent through the Project and workspace.

A gated result reports pending and creates a complete Project-manager Inbox decision. A permitted result reports applied. Use tama labels search first so a near-duplicate does not enter review.

tama propose label --rationale 'Billing needs one durable handoff signal' <<'JSON'
{
  "project_id": "2a628cee-188d-4ab6-a721-5319bf493a42",
  "name": "Ready for billing",
  "description": "Time entry is complete and ready to invoice"
}
JSON

A workflow proposal requires complete nodes, edges, and branch_conditions arrays so the execution graph is reviewable before approval. Step ref values are request-local and connect each edge or branch condition through its source and target. Applied proposals publish a runnable version immediately, while pending proposals publish that version when approved.

Steps may select output_type: "text", "number", or "list". Text is the default. Classify always returns Text, and Loop always returns a List. A body step's container names its Loop ref, and the Loop step's iteration_result names its Text- or Number-returning body result. Classify route targets also use local step refs. Loop requires exactly one incoming connection from a List-producing node, with no cross-body connections or nested loops.

The built-in taskmachine-propose skill contains the field, authorization, ordering, and topology contract. Its Classify entry points to taskmachine-workflows for guidance and tama propose workflow --help for the complete question and routing configuration.

Choose a Playbook proposal command for its source:

A generated Connector either names a catalog Connector slug with connector_slug or reuses an accepted workspace Connector with existing_mcp_server_id. Task Machine hydrates and validates it before creating the proposal. A generated goal may carry an exact due_on date in YYYY-MM-DD form. A generated bundle can also include metrics, each naming the declared Workflow whose steps end on exactly one Number, and metric_triggers, each a schedule with complete timing or an Event from a source listed by tama triggers sources. A person approves them together with the rest of the bundle. Bundle and generated-playbook approval installs the unit transactionally. Rejection or retraction creates no work-graph records.

tama propose chat

tama propose chat proposes starting a child chat from the current chat. It requires --target-agent, --title, and --rationale, and reads the opening prompt as plain text from standard input.

printf '%s' 'Review the disputed charges and summarize the evidence.' | \
  tama propose chat \
  --target-agent 9b1d2f70-53f4-4e27-9eb8-cf625f645912 \
  --title 'Billing evidence review' \
  --rationale 'The finance specialist should verify the disputed charges'

During a run, Task Machine supplies the source chat and source work record. Outside that context, pass matching current-turn records with --source-chat and --source-worker-run. The server verifies the source workspace, chat, run, proposer, and active target agent. Approval-gated opening prompts remain deferred until a source-chat manager approves them.

tama propose restore

tama propose restore <kind> <id> --rationale <why> proposes removing archival from one record while preserving its configuration and history. An unpublished Workflow returns to draft. An unpublished Connector returns to Setup required. Restoration does not publish, verify, or start them. The <kind> is agent, budget, connector, goal, metric, metric_trigger, project, repository, skill, task, team, trigger, or workflow. The <id> must be the archived record's UUID. For an Agent it is the Agent membership UUID. Workspaces cannot be restored this way.

No stdin is read. The rationale is required, nonblank, and at most 4,000 characters. tama propose restore --help includes complete JSON input, success, and error schemas for these positional arguments and the flag, not a JSON-stdin interface.

tama projects list --status archived
tama propose restore project 3f6b0a52-0d2e-4a43-a2b4-2d54cf1f5a10 \
  --rationale 'The Q3 migration resumes next sprint and needs its history'

Find archived ids with the read commands and --status archived (see Reading archived records): tama agents list, tama budget list, tama goals list, tama projects list, tama repositories list, tama skills list, tama tasks list, tama teams list, tama workflows definitions, and tama triggers list. Find archived Connector ids with tama mcp list --status archived.

The request is a governed action named after the kind, such as projects:restore, with Ask first / Automatic choices. Supervised and Balanced ask first. Autonomous asks first except for Tasks, which restore automatically. Full autonomy is automatic for every kind. Custom chooses per kind. Authenticated Task origins use the current Task's effective policy. Non-Task origins use Agent and Workspace policy. Do not send Task, actor, or origin fields. MCP always requires human review, and all modes retain sampled reviews.

A pending request appears in the Inbox of people who may decide that kind, with the target, rationale, current state, and approval consequence in the same decision. The result carries "status": "pending" or "applied", the proposal id, target_kind, and target_id. Retract your own pending request with tama propose retract restore <proposal-id>. It completes the pending Inbox items without restoring the record or treating withdrawal as a Human decision. It also appears in tama propose list --kind restore.

The agent needs the kind's propose and read permissions, for example project:propose and project:read for a project. A person needs the kind's management permission to decide: project:manage for projects and repositories, goal:manage, agent:manage, task:update for tasks, workspace:update for teams, workflow:manage for workflows and Triggers, mcp:manage for connectors, budget:manage for budgets, and skill:archive for Skills.

Errors say what to correct without revealing inaccessible records. The API returns 400 with invalid_restore_input or unsupported_restore_kind, 403 with missing_permission and the required propose permission, 404 with restore_target_not_found for missing or inaccessible targets, and 409 with restore_target_not_archived or restore_already_proposed for active targets or pending duplicates. Input errors name the field and applicable accepted values or length limit. Where supported, missing-target guidance names the archived-list command. Permission checks do not depend on whether the target exists. Retraction distinguishes a missing proposal (proposal_not_found) from a denied withdrawal (forbidden). The CLI prints safe guidance to stderr and exits nonzero.

The remote MCP tool propose_restore uses the same kinds, UUID and 4,000-character bound. Its strict object contains workspace_id, target_kind, target_id, rationale, and idempotency_key, with no extra or origin fields. It always waits for review. Exact retries return the saved result without another proposal or mutation audit. Changing arguments under the same key is rejected. MCP errors retain the same corrective codes and messages, with a field path and retryability rather than an HTTP status.

tama propose goal-conflict

tama propose goal-conflict --rationale <why> raises conflicting Goal direction in a Project you lead, so a person decides which Goals it follows and which it ignores. Use it only from a Project review, when two or more active Goals that direct your Project conflict, instead of picking a side in the review outcome.

It reads one JSON object on stdin with project_id, goals (two to four objects, each with a goal_id and a one-paragraph direction_summary of at most 1,000 characters) and recommended_goal_ids, the Goals you would follow. Name at least one, and leave at least one of the Goals out to ignore. The rationale is required and at most 1,000 characters. The summaries are data for people to read and never instructions. tama propose goal-conflict --help includes complete input, success, and error schemas.

tama propose goal-conflict --rationale 'Self-serve already carries most revenue' <<'JSON'
{"project_id": "3f6b0a52-0d2e-4a43-a2b4-2d54cf1f5a10",
 "goals": [
   {"goal_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "direction_summary": "Keep signup self-serve and show prices."},
   {"goal_id": "9b2f6d1e-0f6e-4e57-8c0a-5d6f7a1c2b33", "direction_summary": "Hide prices and route every buyer to sales."}],
 "recommended_goal_ids": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"]}
JSON

The request is the governed action goal_conflicts:resolve. Every named level asks first, so the result is "status": "pending" and one Inbox decision waits for the people who manage the Project. With Automatic the lead's recommended stances create or supersede the Project's one always-on direction entry at once and the result is "applied". Every agent starting work in that Project receives the default. A concrete decision may differ, and the lead sees a bounded set of superseded choices as non-binding precedent. A Project has one waiting conflict: raising the same Goals again returns it, and a conflict that was decided or dismissed is not raised again until a Goal changes or the decision note is archived. Retract your own pending conflict with tama propose retract goal-conflict <proposal-id>.

You must lead the Project and your role needs project:read and goal:read. Automatic also needs memory:manage. Errors use invalid_goal_conflict_input, not_project_lead, goal_conflict_goals_invalid, goal_conflict_already_pending, goal_conflict_already_decided and goal_conflict_already_dismissed, and the last three name the proposal_id to inspect. Remote MCP offers no goal-conflict tool.

tama propose agent-update

tama propose agent-update <agent-membership-id> --rationale <why> proposes a focused update to an existing Agent using a JSON patch on stdin. The patch accepts display_name, summary, instructions, model, reasoning, and skill_ids. Omitted fields preserve accepted values. A supplied skill_ids list replaces the complete Skill set. A changed instructions value follows the check described under tama propose agent-instructions, including --instruction-attempt.

tama propose connector-assignment

tama propose connector-assignment --rationale <why> reads exact nested Agent and Connector reuse references from stdin. It adds only that accepted Connector relationship to the immutable candidate Agent version. Pending, approved, rejected, retracted, and stale history uses the connector-assignment lifecycle kind in list, search, show, and retract.

tama propose update

tama propose update <kind> <resource-id> --rationale <why> proposes a change to an existing Agent, Connector, Team, Project, Goal, Workflow, Trigger, repository, or installed Playbook.

Versioned resource commands take the accepted base_version_id plus the settings to change, with Workflow updates requiring a complete replacement graph. Repository updates instead copy the inspected updated_at into base_updated_at. The command's --help output lists the complete schema for that resource.

For a Connector update, read current_version_id from tama mcp list inside the Run. Project and Goal list, search, and show commands also return current_version_id. Copy that value into base_version_id and use the resource's id as the update target. If the accepted version changes before you submit, read the resource again and review your changes against the new version.

Standalone Agent, Team, Project and Goal revisions use their independent agents:update, teams:update, projects:update and goals:update policies. Configured and Human-approved learned autonomy decide review or application, with periodic sampled reviews retained. A reviewed candidate returns proposal_state: "proposed" and status: "pending" without changing accepted configuration. Automatic publication returns proposal_state: "approved" and status: "applied", without a Human verdict or Inbox request. Actual autonomy-policy changes and coordinated Playbook revisions still need Human review. Team-member removal does not gain automatic execution. MCP updates always wait for Human review.

Submission requires agent:propose, team:propose, project:propose or goal:propose. Human review independently requires agent:manage, workspace:update, project:manage or goal:manage. Authenticated Task requests use the current Task's effective policy. Chat and other non-Task requests use Agent and Workspace policy. You cannot supply origin, Task or policy-scope overrides. If review has no eligible Human, no_agent_reviewers, no_team_reviewers, no_project_reviewers or no_goal_reviewers returns nonretryable guidance naming the capability to restore. No candidate or accepted change is committed. Retry after a Workspace administrator makes a reviewer available.

Standalone Connector updates require mcp:propose and follow configured and learned connectors:update autonomy, including periodic sampled review. Reviewed proposals leave accepted configuration unchanged. Automatically published proposals return proposal_state: "approved" without creating a human verdict or Inbox request. Credential, OAuth, provenance, and secret fields remain excluded. Coordinated Playbook components retain their shared review.

If no active human has mcp:manage, a reviewed submission fails with code: "no_connector_reviewers", retryable: false, and guidance to ask a Workspace administrator to grant that capability. No candidate, accepted configuration, or Inbox request is committed. Retry after an eligible reviewer is available.

A newer accepted version makes the proposal stale instead of overwriting the newer configuration.

Workflow and Trigger updates use workflow:propose. Human approval requires workflow:manage. If their update autonomy gate disables review, immediate publication also requires the proposing Agent's workflow:manage permission.

A Workflow update uses the stable workflow_id from tama workflows show as the positional <workflow-id>, not the inspected definition id. The inspected definition's id is both base_version_id and workflow.existing_resource_id, and its exact reuse fingerprint goes in workflow.existing_resource_fingerprint. Optional definition fields are top-level request fields, not members of the reuse reference. The request supplies complete replacement nodes, edges, and branch_conditions arrays.

Agent and Connector relationships use exact nested reuse references copied from tama agents show and tama mcp list. Raw relationship IDs are rejected.

Pending review leaves both the editable and runnable Workflow unchanged. Approval rechecks the base graph, permissions, and every reference before publishing the immutable candidate through the normal Workflow version path.

Trigger updates use the exact reference and current version returned by tama triggers show. Put that reference in trigger and the version in base_version_id. Supply only the description, overlap policy, typed schedule timing, or inspected owner (scope), Project and Goal references that should change.

Pending review leaves the Trigger unchanged. When switching between recurring and one-time work, explicitly clear the old timing inside schedule. This command does not change direct Task schedules.

A Playbook update uses its installation id and a components array. Each component names an Agent, Connector, Team, Project, or Goal, its accepted base version, and its changes. Task Machine creates the typed candidates under one Playbook review, so the Inbox shows one decision with every current-to-proposed change.

Approval publishes the complete set or none of it. Rejection and retraction leave every current resource unchanged.

Update proposals use the lifecycle kinds agent-update, connector-assignment, connector-update, team-update, project-update, goal-update, workflow-update, trigger-update, repository-update, and playbook-update in list, search, show, and retract.

tama propose update label

tama propose update label <label-id> --rationale <why> proposes partial metadata changes to an accepted Project label. Inspect tama labels show <label-id> and copy updated_at exactly, including fractional seconds and timezone. Omitted fields preserve accepted values. description: null or empty text clears the description. At least one effective change is required.

Input JSON Schema:

{
  "type": "object",
  "additionalProperties": false,
  "required": ["base_updated_at"],
  "minProperties": 2,
  "properties": {
    "base_updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "pattern": "\\S"
    },
    "color": {
      "type": "string",
      "pattern": "^#[0-9a-fA-F]{6}$"
    },
    "description": {
      "type": ["string", "null"],
      "maxLength": 1000000
    }
  }
}

tama propose reorder

Use tama propose reorder label for a non-destructive, one-place ordering proposal. This is not an archive, delete or full-order replacement command.

tama propose reorder label

tama propose reorder label <label-id> --rationale <why> proposes moving a label one place up or down in its Project. The server snapshots the immediate neighbor. It does not accept an absolute position, neighbor ID or label array. At either end of the order, that direction returns label_order_boundary without creating a request.

Input JSON Schema:

{
  "type": "object",
  "additionalProperties": false,
  "required": ["base_updated_at", "direction"],
  "properties": {
    "base_updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "direction": {
      "enum": ["up", "down"]
    }
  }
}

Both commands require one strict UTF-8 JSON object on stdin, at most 1,000,000 bytes. Unknown and duplicate fields are rejected. --rationale is separate from JSON, required, trimmed, and 1–4,000 characters. --workspace is optional. Neither command accepts proposer identity, origin, lifecycle fields or an approval decision. Submission needs project:read and label:propose. Human review needs project:manage. Configured and learned task_labels:update or task_labels:reorder autonomy determine approval. Pending requests leave accepted labels unchanged. Changed labels, order neighbors or Projects dismiss stale requests automatically.

Output JSON Schema:

{
  "type": "object",
  "additionalProperties": false,
  "required": ["proposal"],
  "properties": {
    "proposal": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "id",
        "kind",
        "proposal_state",
        "status",
        "label_id",
        "project_id",
        "base_updated_at"
      ],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "kind": {
          "enum": ["label-update", "label-reorder"]
        },
        "proposal_state": {
          "enum": ["proposed", "approved"]
        },
        "status": {
          "enum": ["pending", "applied"]
        },
        "label_id": {
          "type": "string",
          "format": "uuid"
        },
        "project_id": {
          "type": "string",
          "format": "uuid"
        },
        "base_updated_at": {
          "type": "string",
          "format": "date-time"
        },
        "direction": {
          "enum": ["up", "down"]
        },
        "neighbor_label_id": {
          "type": "string",
          "format": "uuid"
        }
      }
    }
  }
}

Task Machine links pending decisions to their originating Chat on the server. Exact retries from the same authenticated Run reuse the pending source. List, inspect and withdraw using label-update or label-reorder proposal kinds. MCP tools propose_update_label and propose_reorder_label use the same Core lifecycle, require taskmachine:write and an idempotency key, and audit normalized attempts. MCP submission grants no human management authority.

Error JSON Schema:

{
  "type": "object",
  "additionalProperties": false,
  "required": ["error", "code", "retryable"],
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "enum": [
        "invalid_label_change_input",
        "forbidden",
        "label_not_found",
        "stale_label_snapshot",
        "label_project_unavailable",
        "label_order_boundary",
        "no_label_changes",
        "no_label_reviewers",
        "label_name_conflict",
        "invalid_label_candidate",
        "unavailable",
        "internal_error"
      ]
    },
    "retryable": {
      "type": "boolean"
    },
    "action": {
      "type": "string"
    },
    "reason": {
      "type": "string"
    },
    "hint": {
      "type": "string"
    },
    "corrections": {
      "type": "array",
      "maxItems": 16,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string"
          },
          "field": {
            "enum": [
              "workspace_id",
              "label_id",
              "base_updated_at",
              "name",
              "color",
              "description",
              "direction",
              "proposal_rationale",
              "rationale",
              "changes",
              "idempotency_key"
            ]
          }
        }
      }
    }
  }
}

Errors exit nonzero and report safe corrections without echoing input. Fix every invalid field. For stale_label_snapshot, inspect the label again instead of guessing a timestamp. For label_order_boundary, choose the other direction or leave the order unchanged. no_label_changes requires an effective edit. label_name_conflict requires another available name. For forbidden, follow the returned Reason and Hint rather than assuming a missing permission. Only unavailable is retryable with unchanged input. internal_error is a server error that retrying won't fix: check the current state with tama propose list before resubmitting. Authentication may return an error-only envelope.

Example (copy the placeholder values from your authorized reads):

tama propose update label <label-id> --rationale 'Clarify this classification' <<'JSON'
{
  "base_updated_at": "<exact updated_at from labels show>",
  "name": "Ready to invoice",
  "description": null
}
JSON
tama propose reorder label <label-id> --rationale 'Keep frequently used labels near the top' <<'JSON'
{
  "base_updated_at": "<exact updated_at from labels show>",
  "direction": "up"
}
JSON

tama propose update skill

tama propose update skill <skill-id> --rationale <why> [--workspace <id-or-slug>] proposes a new immutable version of a workspace-authored Skill. Inspect tama skills show <skill-id> first and copy current_version.id as base_version_id. Stdin supplies the complete skill_md, including valid frontmatter, rather than a patch. Supporting scripts and references remain unchanged. Built-in and marketplace Skills cannot be edited through this command.

{
  "base_version_id": "<INSPECTED_SKILL_VERSION_UUID>",
  "skill_md": "---\nname: review-method\ndescription: Review a draft against its requirements\n---\n\nCheck each requirement against the draft.\n"
}

Stdin is one strict UTF-8 JSON object of at most 1,000,000 bytes. Both fields are required, and skill_md is a nonblank string of at most 100,000 characters. The required rationale is a nonblank reason of at most 4,000 characters supplied only through the flag. Unknown, duplicate, origin, lifecycle and destructive fields are rejected. Offline --help includes complete input, output and error JSON Schemas.

Submission requires skill:read and skill:propose. Configured and learned skills:update autonomy decides whether the candidate needs review, including sampled review. Approval and automatic publication independently require skill:publish_version. Pending review leaves the accepted package unchanged. A changed base dismisses the obsolete request without publishing its candidate.

tama propose invitation

tama propose invitation --rationale <why> requests a Human Workspace invitation. Every request needs an eligible Human's approval, even when the proposing Agent has Full autonomy. Pending requests grant no access and send no email. These proposals are excluded from remote MCP.

Inspect the selected role first with tama propose invitation --inspect-role <role-key-or-id>. This read-only mode returns one role's id, key, name, permissions and exact updated_at. Copy its id into role_id and its timestamp into base_role_updated_at. Inspection needs no rationale and does not read stdin or create a proposal.

Submission requires one strict UTF-8 JSON object of at most 1,000,000 bytes, with only email, role_id and base_role_updated_at. The email is nonblank and at most 320 characters. The role is an inspected UUID and the timestamp is RFC 3339, preserving fractional seconds. --rationale supplies a nonblank reason of 1 to 4,000 characters. Optional --workspace selects the Workspace.

tama propose invitation --inspect-role viewer
tama propose invitation --rationale 'Invite our collaborator with Viewer access' <<'JSON'
{
  "email": "[email protected]",
  "role_id": "00000000-0000-4000-8000-000000000001",
  "base_role_updated_at": "2025-01-01T00:00:00.000001Z"
}
JSON

Replace the example role and timestamp with the inspected values. Submission and inspection need member:propose. Human review uses the native member:invite capability. Owner-equivalent access requires the current Owner.

The receipt identifies the immutable proposal with id, kind, proposal_state, status, role_id and base_role_updated_at. Pending uses proposed and pending. Task Machine links the decision to its originating Chat on the server. Exact retries retain the frozen source and decision. Terminal retries omit pending attention. Receipts expose no invitation link, token, account data or email.

tama propose role-change

tama propose role-change --rationale <why> requests a new Workspace role for one active Human. Inspect that Human with --inspect-human <membership-id>, then inspect the selected role with --inspect-role <role-key-or-id>. Use one inspect flag at a time without --rationale. Neither read enumerates the Human roster or exposes account fields.

The Human projection returns membership_id, an email-free display_name, positive role_revision and the current role snapshot. Copy membership_id, role.id and role_revision into member_id, base_role_id and base_role_revision. Copy the selected role's id and exact updated_at into role_id and base_role_updated_at.

tama propose role-change --inspect-human 00000000-0000-4000-8000-000000000002
tama propose role-change --inspect-role viewer
tama propose role-change --rationale 'Use Viewer access for our collaborator' <<'JSON'
{
  "member_id": "00000000-0000-4000-8000-000000000002",
  "base_role_id": "00000000-0000-4000-8000-000000000003",
  "base_role_revision": 1,
  "role_id": "00000000-0000-4000-8000-000000000001",
  "base_role_updated_at": "2025-01-01T00:00:00.000001Z"
}
JSON

Replace every example identifier, timestamp and revision with inspected values. Role requests use the same input and rationale bounds as invitations. The receipt adds member_id, base_role_id and base_role_revision. Human review always requires current role:assign, with Owner-only protection for Owner-equivalent grants. Agents cannot approve the request or directly change access, and remote MCP cannot submit it.

Both commands reject unknown or duplicate fields, account identity, lifecycle changes, removals, suspensions, permission overrides and origin fields. Errors have a stable code, safe error guidance and retryable, with ordered field corrections for invalid input. invalid_human_access_input names each correction. stale_human_access_base requires fresh inspection. human_access_member_unavailable or human_access_role_unavailable requires an active authorized target. human_access_role_already_assigned means no change is needed. Missing member:propose access returns forbidden with that explanation. Other forbidden responses may reflect session or Run restrictions, so follow the returned guidance. no_human_access_reviewers names the native Human review capability an administrator must restore. Retry unchanged input only for retryable unavailable errors. internal_error is a server error that retrying won't fix: check the current state with tama propose list before resubmitting. Authentication failures may contain only error.

Use invitation or role-change with tama propose list, search, show and retract. Changed bases auto-dismiss every review copy without a Human verdict. Withdrawal neutrally clears only the author's pending request and cannot undo approved access. Each command's --help includes complete input, inspection, receipt and error JSON Schemas.

tama propose notification-preference

tama propose notification-preference --rationale <why> [--workspace <id-or-slug>] requests personal notification changes for the Human who requested the current conversation or Task. That same person must approve or reject inside Inbox or Chat, even when the Agent has Full autonomy. Other reviewers cannot decide their preferences, and remote MCP cannot submit these requests.

Run tama propose notification-preference --inspect first, without --rationale. This reads no stdin and creates no proposal or settings. It returns changes, containing all existing Boolean flags and the account-wide notification_summary_cadence, and the exact Workspace base_preference_updated_at timestamp. It exposes no Human identity, profile, browser permission or subscription data. Both inspection and submission require the current Agent's notification:propose capability.

Submission accepts one strict UTF-8 JSON object of at most 1,000,000 bytes. A nonempty changes object contains partial changes. Omitted fields remain unchanged. Event flag changes require the exact inspected base_preference_updated_at, preserving fractional seconds. A summary frequency change needs no base. The --rationale flag supplies a nonblank reason of 1 to 4,000 characters.

The supported event prefixes are subscription_reminder, assignment, task_update, mention, workflow_question, approval_request, delegation_request, worker_failure, rate_limit, budget_alert, usage_warning, usage_expiry, renewal_proposal, ai_subscription_running_out, ai_subscription_banked_reset_added, ai_subscription_banked_reset_expiring, ai_subscription_reset_early, ai_subscription_plan_fit and ai_subscription_automatic_reset. Each has _email_enabled and _push_enabled Boolean fields. member_change_email_enabled is email only, and morning_briefing_email_enabled includes this Workspace in the account-wide Morning briefing. Event flags apply to this Workspace. Browser event flags do not grant browser permission or register a device.

notification_summary_cadence is account-wide and takes none, hourly, twice_daily or daily. It sets how often that person's non-urgent notification emails arrive together in every Workspace. The Agent asks which frequency they want and proposes exactly their answer. The review shows it in its own section.

tama propose notification-preference --inspect
tama propose notification-preference --rationale 'Reduce assignment emails and mention alerts' <<'JSON'
{
  "changes": {
    "assignment_email_enabled": false,
    "mention_push_enabled": false
  },
  "base_preference_updated_at": "2025-01-01T00:00:00.000001Z"
}
JSON
tama propose notification-preference --rationale 'You asked for one summary email a day' <<'JSON'
{
  "changes": {
    "notification_summary_cadence": "daily"
  }
}
JSON

Replace the example base with the inspected value. Unknown and duplicate keys, Human IDs, browser subscriptions, timezone, origin and decision overrides are rejected. An Agent cannot choose a different person or work around approval with an account edit.

The response contains proposal with UUID id, kind: "notification-preference", proposal_state and status. Pending requests use proposed and pending. Task Machine links the decision to its originating Chat on the server. Frozen approved retries use approved and applied. Rejected and stale retries retain their verdict and omit pending attention. Receipts contain no personal values or rationale. The command's offline --help includes complete input, inspection, receipt and error JSON Schemas.

Errors include a stable code, safe error guidance and retryable, with ordered corrections for invalid fields. invalid_notification_preference_input names each field to correct. Missing notification:propose access returns forbidden with that explanation. Other forbidden responses may reflect session or Run restrictions, so follow the returned guidance. notification_requester_unavailable requires the affected Human to request the change in Chat or a Task. notification_preferences_unavailable asks them to open their Workspace notification settings. stale_notification_preference_base requires fresh inspection, and notification_preferences_unchanged means those flags are already selected. Retry unchanged input for unavailable. internal_error is a server error that retrying won't fix: check the current state with tama propose list before resubmitting. Authentication failures may contain only error.

Use kind notification-preference with tama propose list, search, show and retract. Personal results are limited to this Agent's requests for the current requesting Human, including in unfiltered discovery. List and search default to 20, cap at 100 and return next_cursor and has_more. Continue explicitly with --after. Cursors belong to the Human, Workspace and filters. invalid_cursor requires restarting from the first page. List supports --state proposed|active|rejected|withdrawn|all, with proposed as the default. withdrawn includes neutral stale dismissals, and all includes terminal history.

Readback contains the frozen Boolean changes and base_values with their bases, never another person's preferences. Native settings or authority changes auto-dismiss stale requests without a Human verdict. Withdrawal neutrally clears only a pending request and cannot reverse approved preferences. notification_preference_proposal_stale requires fresh inspection, notification_preferences_already_decided prevents reversing a verdict, and proposal_not_found keeps unavailable sources private.

tama propose team-member

tama propose team-member --rationale <why> proposes adding one active human or agent to an accepted Team as a regular member. Inspect tama teams show <team-id> and copy its exact current_version_id. Use the selected person's or agent's workspace membership UUID. The lead, existing members and roles, description, routing rules and workspace permissions remain unchanged. Removals, role changes and leadership edits are not accepted.

Stdin is one strict UTF-8 JSON object, at most 1,000,000 bytes. Duplicate keys, unknown fields, extra objects, lifecycle state and caller-supplied origin are rejected. --rationale is nonblank text of 1 to 4,000 characters. Optional --workspace selects the workspace. The authenticated session supplies the proposer and Run origin.

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "team_id",
    "base_version_id",
    "member_id"
  ],
  "properties": {
    "team_id": {
      "type": "string",
      "format": "uuid",
      "minLength": 36,
      "maxLength": 36
    },
    "base_version_id": {
      "type": "string",
      "format": "uuid",
      "minLength": 36,
      "maxLength": 36
    },
    "member_id": {
      "type": "string",
      "format": "uuid",
      "minLength": 36,
      "maxLength": 36
    }
  }
}

Replace these example UUIDs with inspected records:

printf '%s' '{"team_id":"00000000-0000-4000-8000-000000000001","base_version_id":"00000000-0000-4000-8000-000000000002","member_id":"00000000-0000-4000-8000-000000000003"}' | tama propose team-member --rationale "Add the launch contributor"

The receipt contains proposal with UUID fields id, team_id, base_version_id, candidate_version_id and member_id, plus kind: "team-member", proposal_state and status. Pending uses proposed and pending. Automatic publication uses approved and applied. Task Machine links pending decisions to their originating Chat on the server. Pending requests never change accepted composition. Exact pending retries reuse the source, sample and recipient attention.

Submission requires team:propose and team:read. Human decisions use workspace:update, matching existing Team management. Automatic publication keeps proposal authority and follows the resolved policy, matching Team creation. Configured and learned teams:update autonomy determine Agent approval requirements. Remote MCP submits the same candidate through taskmachine_mutate operation propose_team_member, with workspace_id, rationale, attributes and mandatory idempotency_key. MCP receives submission authority only and waits for human review. Continue a member-composition page with the Team read cursor when needed.

Use team-member with tama propose list, search, show and retract. Withdrawal leaves membership unchanged. A native Team or member change auto-dismisses obsolete review without a human verdict. The exact command's --help includes complete input, output and error JSON Schemas.

Server errors retain error, stable code, retryable and optional corrections containing field-safe messages. invalid_team_member_input reports all invalid fields. team_addition_stale means inspect the Team again. member_already_in_team means leave the Team unchanged or choose another member. team_unavailable and member_unavailable require eligible accepted records in this workspace. no_team_reviewers requires a workspace manager to check eligible reviewers. For forbidden, follow the returned guidance rather than assuming a missing permission. unavailable is retryable with the unchanged input. internal_error is a server error that retrying won't fix: check the current state with tama propose list before resubmitting. Authentication failures can be error-only. The CLI exits nonzero and prints safe guidance to stderr without echoing rejected input.

tama propose skill-assignment

tama propose skill-assignment --rationale <why> [--workspace <id-or-slug>] proposes adding one accepted Skill to an active Agent. Inspect the Skill with tama skills show and the Agent with tama agents show. Copy the Skill's current_version.id as skill_version_id and the Agent's current_version_id as base_agent_version_id.

{
  "skill_id": "<INSPECTED_SKILL_UUID>",
  "skill_version_id": "<INSPECTED_SKILL_VERSION_UUID>",
  "agent_membership_id": "<INSPECTED_AGENT_MEMBERSHIP_UUID>",
  "base_agent_version_id": "<INSPECTED_AGENT_VERSION_UUID>"
}

Every field is a required UUID. The same strict stdin and rationale bounds apply as Skill updates. The immutable candidate adds only this Skill, preserving existing Agent configuration and relationships. It cannot remove or replace assignments. Submission needs skill:read and skill:propose. Configured and learned skills:assign autonomy decides review, and publication independently requires agent:manage and skill:assign_agent. Pending review changes no accepted Agent version. Approval rechecks both inspected resources.

Both commands return proposal.id, canonical kind (skill-update or skill-assignment), proposal_state, status (pending or applied), skill_id, base_version_id and candidate_version_id. Base and candidate IDs describe Skill versions for updates and Agent versions for assignments. Assignment output also includes skill_version_id and agent_membership_id. Task Machine links pending decisions to their originating Chat on the server. Responses contain no Skill source, private package paths or storage handles. Use these same kinds with tama propose list, search, show and retract.

Errors exit nonzero with all safe correction guidance on stderr. invalid_skill_revision_input and invalid_skill_assignment_input include ordered corrections for known fields without reflecting submitted values. stale_skill_reference requires fresh inspection, skill_reference_unavailable means an authorized reference is unavailable, and skill_revision_not_editable identifies source-managed Skills. skill_already_assigned and no_skill_changes require an effective change. no_skill_reviewers requires a workspace manager to check eligible reviewers. For forbidden, follow the returned guidance rather than assuming a missing permission. Retry unavailable with unchanged input. internal_error is a server error that retrying won't fix: check the current state with tama propose list before resubmitting.

MCP exposes propose_update_skill and propose_skill_assignment with explicit workspace identity, rationale and an idempotency key. Skill updates supply the Skill UUID and a strict changes object. Assignments supply a strict attributes object. MCP always requires human review and receives no publication or assignment authority. Exact retries reuse the saved result, and changed input under the same key conflicts.

tama propose trigger

tama propose trigger --rationale <why> [--workspace <id-or-slug>] proposes a Trigger for an accepted Workflow. Set scope_type to workflow and copy the exact definition existing_resource_id and existing_resource_fingerprint from tama workflows show into scope. Optional project and goal objects use the same two fields from authorized inspection.

A Workflow's bound Project is authoritative. A projectless Workflow needs an active Project reference. An optional Goal must already belong to that execution Project. Missing, inaccessible or incompatible references return the same opaque error. Reinspect the authorized resources before retrying.

Stdin is one strict JSON object, at most 1,000,000 bytes. Optional description is a string of at most 100,000 characters or null. Blank descriptions are valid. References carry a UUID and an exact 64-character lowercase SHA-256 fingerprint.

Set kind to schedule or webhook. For a schedule, inside schedule, choose exactly one complete pair: scheduled_for with schedule_timezone, or recurring_cron with recurring_timezone. Copy the person's exact timestamp, cadence and IANA timezone without conversion or inferred defaults. overlap_policy defaults to skip, which holds the next occurrence while earlier work remains open. Select allow only for independent invocations that may overlap.

For an event Trigger, set kind to webhook, omit schedule and supply a webhook object: webhook_source_id copied from tama triggers sources, 1 to 50 event_names from that source's events (none when it shows any_event) and optional event_actions mapping a chosen event name to some of its actions, such as {"issues": ["opened"]}. Each matching event starts one run, and runs wait in line, so overlap_policy is queue or omitted. Without an event source, propose an Events connector first with tama propose connector <catalog-slug> --events.

Raw relationship ids, origin, status, accepted version, root Task and cursor fields are rejected. Offline --help includes complete input, output and error schemas. Replace these placeholders with exact inspected values:

{
  "scope_type": "workflow",
  "scope": {
    "existing_resource_id": "<INSPECTED_WORKFLOW_DEFINITION_UUID>",
    "existing_resource_fingerprint": "<INSPECTED_WORKFLOW_FINGERPRINT>"
  },
  "kind": "schedule",
  "overlap_policy": "skip",
  "schedule": {
    "recurring_cron": "0 9 * * 1-5",
    "recurring_timezone": "Europe/Berlin"
  }
}

Submission uses workflow:propose and resource-read permissions. Configured and learned creation autonomy decide review, including sampling. Human approval and immediate publication retain Workflow-management authority. MCP submits through propose_trigger with the same strict fields and a required idempotency key, but always waits for human review.

The result contains proposal.id, kind trigger, proposal_state, status (pending or applied), trigger_id and candidate_version_id. Pending results expose no accepted Trigger, root Task or execution cursor. Publication accepts the immutable candidate and creates its root Task atomically. Pending decisions remain linked to their originating Chat.

Errors exit nonzero with all field corrections on stderr. invalid_trigger_creation_input means correct every listed field. trigger_reference_unavailable means reinspect authorized resources. no_trigger_reviewers needs a workspace manager, forbidden means authority is missing, and retryable unavailable means retry the unchanged request. internal_error is a server error that retrying won't fix: check the current state with tama propose list before resubmitting.

tama propose update trigger

tama propose update trigger <trigger-id> --rationale <why> revises an accepted Trigger. Copy its exact reference and accepted version from tama triggers show into trigger and base_version_id. Omitted configuration stays unchanged. Description, overlap policy, typed schedule timing and exact owner, Project or Goal references may change. Pending review never changes accepted configuration. Approval rechecks current authority, references and the locked base.

Creating or revising a Trigger does not publish or start a Workflow definition. Direct Task scheduling keeps its existing contract. Lifecycle discovery and proposer-owned retraction use trigger for creation and trigger-update for revisions.

tama propose budget

tama propose budget --rationale <why> proposes an operational budget from one strict JSON object on stdin. Required scope_type is workspace, project, goal, task, team, agent, or workflow. Required scope_id is that resource's UUID, including the workspace UUID for workspace scope. Optional --workspace selects an authorized workspace.

Optional fields are limit_amount, currency, period, and ignore_subscription_usage. Cost limits are nonnegative decimal strings with scale at most two after removing trailing zeros and a maximum of 9999999999.99. Explicit null clears the cap. Creation without a cap is valid. Currency uses three uppercase letters, defaulting to USD. Period is daily, weekly, monthly, quarterly, yearly, or total, defaulting to monthly. ignore_subscription_usage is a boolean, defaulting to false.

The required rationale is a nonblank reason of at most 4,000 characters, supplied only through the flag. Stdin is bounded to 256 KiB. Unknown and duplicate fields are rejected. Identity, origin, lifecycle, archival, deletion, purchases, and subscriptions are not accepted fields. The command's offline --help includes complete strict input, success, and error JSON Schemas.

Configured and learned budgets:propose autonomy decides pending review versus application, including sampled review. pending leaves accepted budgets unchanged and routes the complete decision to budget managers in Inbox. applied publishes the candidate. The result's proposal includes its id, canonical budget kind, proposal_kind (create or update), proposal state, status, nullable target and applied budget ids, nullable base timestamp, and a complete budget candidate with scope and cap values. Task Machine links pending decisions to their originating Chat on the server. Neither status purchases usage, grants approval authority, or bypasses execution controls.

tama propose update budget

tama propose update budget <budget-id> --rationale <why> changes only the inspected budget's caps, currency, period, or subscription-usage setting. Read tama budget show <budget-id> first and copy its exact RFC3339 updated_at, including microseconds, into the required base_updated_at. Scope cannot change. Omitted settings preserve accepted values and explicit null caps clear them. At least one effective change is required, using the same bounds as budget creation.

A pending update leaves the accepted budget unchanged. Configured and learned budgets:update autonomy decides review versus application. A changed base reports stale_budget_base, so inspect again rather than guessing a timestamp. Invalid fields return nonretryable invalid_budget_proposal_input with every ordered, deduplicated correction. Each correction contains fixed guidance and an optional closed field name, never submitted values or arbitrary keys. The CLI prints all guidance on stderr and exits nonzero. Other codes distinguish no_budget_changes, budget_scope_exists, invalid_budget_scope, opaque budget_unavailable, proposal_unavailable, forbidden, retryable unavailable, and nonretryable internal_error for a server error.

Budget creation and revision proposals are discoverable as budget in tama propose list, search, show, and retract. Restore an archived budget through tama propose restore budget <budget-id> --rationale <why>, governed independently by budgets:restore. There is no destructive budget proposal command.

MCP exposes propose_budget, propose_update_budget, and budget_request_increase through budget read and proposal permissions, never management or approval authority. Each requires explicit workspace identity, rationale, and an idempotency key. Creation uses a strict attributes object. Revision uses a strict changes object and budget UUID. MCP always requires human review. Exact retries replay the saved result without another proposal or mutation audit, while changed input under the same key conflicts.

tama propose update repository

tama propose update repository <repository-id> --rationale <reason> proposes a change to an existing repository's name, clone URL, or default branch. First inspect the repository with tama repositories show, then copy its updated_at exactly. Repositories have no configuration-version UUID.

The required --rationale flag is a trimmed, nonblank string of at most 4,000 characters. --workspace <id-or-slug> selects an authorized workspace when needed. Read exactly one JSON object from stdin. This complete input schema excludes rationale, which comes from the flag:

{
  "type": "object",
  "additionalProperties": false,
  "required": ["base_updated_at"],
  "minProperties": 2,
  "properties": {
    "base_updated_at": {
      "type": "string",
      "format": "date-time",
      "minLength": 1,
      "maxLength": 64
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 160
    },
    "clone_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048
    },
    "default_branch": {
      "type": ["string", "null"],
      "minLength": 1,
      "maxLength": 255
    }
  }
}

At least one field must effectively change. Omission preserves its accepted value. default_branch: null selects the provider's default branch, while an empty or blank string is rejected. Name and clone URL cannot be null or blank. Clone URLs must use a supported Git form without embedded credentials. Identity, origin, archival, deletion, credentials, SSH setup, and global-default selection are unavailable through this command. Timestamp offsets represent instants, with persisted microseconds retained for comparison.

This synthetic example changes the name and clears an explicit branch:

tama propose update repository <repository-id> --rationale "Use the reviewed repository name and provider default" < repository-update.json

{
  "base_updated_at": "2026-10-03T12:34:56.123456Z",
  "name": "Synthetic repository",
  "default_branch": null
}

Success prints the following envelope. The nested repository is the complete candidate, not proof that accepted metadata changed. pending waits for review. applied means the candidate was published. Task Machine links pending decisions to their originating Chat on the server.

{
  "type": "object",
  "additionalProperties": false,
  "required": ["proposal"],
  "properties": {
    "proposal": {
      "type": "object",
      "additionalProperties": false,
      "required": ["id", "kind", "proposal_state", "status", "git_repository_id", "base_updated_at", "repository"],
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "kind": {
          "const": "repository-update"
        },
        "proposal_state": {
          "enum": ["proposed", "approved"]
        },
        "status": {
          "enum": ["pending", "applied"]
        },
        "git_repository_id": {
          "type": "string",
          "format": "uuid"
        },
        "base_updated_at": {
          "type": "string",
          "format": "date-time"
        },
        "repository": {
          "type": "object",
          "additionalProperties": false,
          "required": ["name", "clone_url", "default_branch"],
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 160
            },
            "clone_url": {
              "type": "string",
              "minLength": 1,
              "maxLength": 2048
            },
            "default_branch": {
              "type": ["string", "null"],
              "maxLength": 255
            }
          }
        }
      }
    }
  }
}

Failures exit nonzero and write content-free correction text to stderr. Invalid fields or unsupported keys report invalid_repository_update_input, unchanged candidates report ineffective_repository_update, changed observations report stale_repository_update, inaccessible targets report repository_unavailable, and denied authority reports forbidden. Temporary failures report retryable unavailable. internal_error is a server error that retrying won't fix: check the current state with tama propose list before resubmitting. Singular field failures include the known field and applicable max_length, never the submitted value. Multiple independent failures return an ordered, deduplicated corrections array. Each correction contains fixed error guidance and optional known field and max_length. Top-level error joins every correction so the CLI prints all guidance. Unknown keys use generic request guidance without naming the submitted key. After a stale observation, inspect again and review the new base before resubmitting. Pending review leaves accepted metadata unchanged, and MCP always requires human review. Publishing metadata never provisions access to a changed clone target.

The server error envelope has this schema. The CLI prints its combined correction text to stderr rather than printing an error envelope as successful stdout:

{
  "type": "object",
  "additionalProperties": false,
  "required": ["error", "code", "retryable"],
  "properties": {
    "error": {
      "type": "string"
    },
    "code": {
      "enum": ["invalid_repository_update_input", "ineffective_repository_update", "stale_repository_update", "repository_unavailable", "forbidden", "unavailable", "internal_error"]
    },
    "retryable": {
      "type": "boolean"
    },
    "field": {
      "enum": ["workspace_id", "repository_id", "base_updated_at", "name", "clone_url", "default_branch", "proposal_rationale"]
    },
    "max_length": {
      "enum": [36, 64, 160, 255, 2048, 4000]
    },
    "action": {
      "type": "string"
    },
    "reason": {
      "type": "string"
    },
    "hint": {
      "type": "string"
    },
    "corrections": {
      "type": "array",
      "minItems": 1,
      "maxItems": 16,
      "uniqueItems": true,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string"
          },
          "field": {
            "enum": ["workspace_id", "repository_id", "base_updated_at", "name", "clone_url", "default_branch", "proposal_rationale"]
          },
          "max_length": {
            "enum": [36, 64, 160, 255, 2048, 4000]
          }
        }
      }
    }
  }
}

The MCP tool is propose_update_repository. It requires explicit workspace_id, repository_id, rationale, changes containing the same strict stdin schema, and a nonblank idempotency_key of at most 128 characters (letters, digits, periods, underscores, colons, or hyphens). Reuse the key only for identical retries. Its success result has the same proposal projection. Errors carry safe code, message, retryable, optional field path, and optional max_length. Aggregate errors additionally carry corrections, each with message and optional path and max_length. Known metadata paths are under /changes, rationale uses /rationale, and identity paths use /workspace_id or /repository_id. Generic request guidance has no path.

tama propose list, search, and show

tama propose list returns one bounded page of proposals raised by the current agent in the current workspace. --kind <kind> filters by a creation or update kind or alias. --state proposed|active|rejected|all selects lifecycle state. Use all to inspect decision history. --limit defaults to 20 and is capped at 100.

When has_more is true, pass next_cursor to --after with the same kind and state.

tama propose search <query> searches pending proposal summaries raised by every agent in the current workspace. Use it before proposing to avoid repeating work that is already waiting for a decision. Search normalizes punctuation-separated terms and can match them across a proposal's title and rationale.

Task proposals also include their description, summary, plan, and acceptance criteria, while label proposals include the proposed name and description. This means a query can combine a package name, check name, and implementation phrase without requiring that exact sentence in one field.

--kind <kind> narrows the proposal type, --limit bounds one page, and --after <next_cursor> continues until has_more is false. Search does not grant access to another agent's proposal detail or retraction actions.

tama propose list
tama propose list --kind connector --state rejected
tama propose search 'provider validation failure' --kind task
tama propose search 'weekly customer report' --after <next-cursor>
tama propose show workspace 7df4b99c-504a-4746-915d-1ff11b15211c

tama propose show <kind> <proposal-id> returns one current-agent proposal, including approved or rejected history. For generated-playbook, it also returns the exact immutable bundle manifest and SHA-256 identity used for human review, so a later turn can reload instructions, relationships, Connectors, schedules, and execution settings without reconstructing them.

Other agents' and other workspaces' proposal details are not disclosed.

tama propose retract

tama propose retract <kind> <proposal-id> withdraws one still-pending proposal raised by the current agent. It accepts every creation kind and alias: workspace, restore, team, agent, skill, MCP/connector, task, label, project, repository, goal, workflow/promoted playbook, chat, catalog bundle, generated playbook, and Connector assignment. It also accepts every *-update lifecycle kind.

tama propose retract task 7df4b99c-504a-4746-915d-1ff11b15211c

Human invitation and role-change requests use invitation and role-change. Their withdrawal neutrally clears pending review without a Human verdict and cannot reverse approved access.

For ordinary creation proposals, retraction rejects the durable proposal, records that the proposing agent withdrew it, and completes its approval Inbox items. It cannot withdraw an approved or already rejected proposal. --workspace cannot escape a run's authorized scope, and there is no --agent flag. Success prints:

{
  "ok": true,
  "kind": "task",
  "id": "7df4b99c-504a-4746-915d-1ff11b15211c"
}

Additional visible command inventory

The command tree below completes the public surface. Run any listed command with --help for its arguments and flags. The focused skills explain the agent procedure and safety boundary where one applies.

Browser

tama browser operates the first-party browser attached to the current Run.

Use the browser commands for the action you need:

Each command uses the tama browser prefix. Run tama browser --help for the full command list.

Page and environment controls are tama browser viewport, tama browser pdf, tama browser geolocation, tama browser offline, tama browser network, tama browser network-block, and tama browser storage-clear. Tab controls are tama browser tabs, tama browser tab, tama browser tab new, tama browser tab switch, and tama browser tab close. tama browser run inspects visual-history segmentation.

Start browser work with tama browser run new "<short goal>", using a trimmed name of 1 to 64 Unicode code points. The name identifies that visual-history segment without clearing tabs or browser state. The optional --name on tama browser goal names the Browser Run evidence, not the objective, and accepts at most 64 Unicode code points. If omitted, Task Machine derives the Browser Run name from the objective, capped at 64 Unicode code points.

tama browser upload <ref> <path> [path...] accepts a snapshot reference to a native file input or a visible picker containing exactly one descendant file input. Relative paths are resolved from the invoking Task or Chat workdir. Absolute paths are used unchanged. It preserves the supplied file order. For supported live upload controls, the command waits within its existing deadline for the pending change to settle so the next browser command can observe the staged upload. If the visible picker contains no file input or several file inputs, the command fails without clicking the picker or choosing one from elsewhere on the page.

tama browser goal "<objective>" asks Task Machine to choose from the browser actions available in each current page observation and runs those actions within fixed step, request, and elapsed-time limits. Use --start-url <url> for approved navigation and --fields <file|-> to attach bounded JSON from a file or standard input. Relative file paths in file fields are resolved from the invoking Task or Chat workdir before the immutable field-context digest is calculated. Absolute paths are used unchanged:

{
  "fields": [
    {
      "name": "Post text",
      "kind": "text",
      "value": "Approved copy"
    },
    {
      "name": "Account password",
      "kind": "credential",
      "credential": "@publisher",
      "field": "password"
    },
    {
      "name": "Hero image",
      "kind": "file",
      "paths": ["/workspace/hero.png"]
    }
  ]
}

An objective contains 1-2,000 Unicode code points. A goal accepts at most 32 uniquely named fields, including the optional start URL, with at most 64 KiB of input JSON. Field names allow 160 UTF-8 bytes. A text value allows 16 KiB, a file field allows 1 to 16 paths, and credential fields are username, password, secret or totp. Use --max-steps, --max-policy-requests or --max-elapsed-seconds only to reduce the fixed 40-step, 60-request and 900-second limits.

Dense pages use bounded observation windows for later controls, text, frames and select choices. Windows report their actual ranges and whether the current observation covers the whole page. A partial view cannot establish absence. Continuing a window expires earlier references and still consumes the objective's original limits.

When step_limit, request_limit or elapsed_limit ends an objective with a live owned observation position, terminal JSON can include continue_window_ref. To inspect further, explicitly start a new bounded objective with tama browser goal "<new objective>" --continue-window "$live_ref" --fields new-fields.json, copying $live_ref exactly from that evidence. Do not reconnect the exhausted objective's --id to obtain a new budget. The new objective captures fresh references using only its own fields. Prior field values, credential bindings and action authority do not transfer. This path never automatically creates objectives, raises limits or replays writes.

The opaque checkpoint is single-use and belongs to that live broker observation. Another observation, page change, consumed checkpoint or cold/reset broker invalidates it. Stale or foreign references fail closed rather than restarting at window zero. Ordinary new objectives without --continue-window still begin at the first window. For an interrupted new objective's --id reconnect, repeat its original --continue-window flag and other immutable inputs. This does not replenish its budget or reapply its initial checkpoint after durable steps exist.

Task Machine sends ordinary text and semantic field descriptions to the Browser Goal provider. Credential references resolve just before filling, and file paths remain on the Worker. Credential values, ids, Vault syntax, filenames, and file paths do not reach the backend or provider. The provider selects only finite target-and-field combinations, observed select options, and code-owned key choices. It cannot generate arbitrary browser arguments.

The command keeps the ordinary Browser Run visual history, stops on blocked or ambiguous work, and treats reported completion as a candidate for parent verification rather than proof. Use --id <uuid> with the same objective and unchanged fields to reconnect to durable progress after an interrupted command. Browser Goals require authorized browser access and an available model that meets the Workspace's managed-AI requirements. Requiring zero data retention does not itself disable Browser Goals. Low-level browser commands remain available to inspect required inputs, verify results, and intervene.

A blocked goal returns a closed terminal_reason in its JSON and corrective guidance on standard error:

Backend failures retain specific categories such as unsupported_observation, stale_snapshot, step_limit, request_limit, elapsed_limit, usage_limit and budget_limit. The command prints bounded recovery guidance for the category. Unknown error text is redacted to browser_goal_request_failed. A policy block alone does not establish a Task Machine defect.

A failed or blocked command exits unsuccessfully. When durable execution state is available, the command still prints it as JSON. Check whether a prior write persisted before trying another action. Never replay an action reported as ambiguous_execution, and never raise a limit to conceal a failure. Report a new tooling defect once through tama feedback while continuing available task work.

tama browser fill <ref> --credential @name --field <field> injects an authorized Vault field without printing its value. Later snapshots identify the filled control by its accessible label, credential name, and selected field so another browser action can correlate fields from the same login. The value, credential id, and Vault reference syntax remain absent from snapshots.

A timed-out browser command reports browser_state as preserved, reset, or unknown, and reports action_outcome as ambiguous when the action may have applied. When an action may have changed the active document, document_state reports whether it was reached, reset, or could not be confirmed. A reset discards tabs and storage, so the next command starts in a blank context. unknown means the result did not establish browser state. A broker watchdog that cannot confirm shutdown retires the old context and starts future commands in a fresh one, while a transport failure may leave the current session available for inspection. Check with tama browser status or tama browser snapshot, and verify an ambiguous action's effect before retrying it.

Navigation waits for bounded page and rendering readiness. A reload timeout before document readiness is confirmed means only that readiness was not confirmed by the deadline. Use tama browser status or a fresh tama browser snapshot to inspect the current session, then independently verify whether the prior write persisted before retrying reload or writing again. The timeout does not establish whether the new document is inspectable or whether the write was saved or lost.

If reload reaches the document but times out on page load or later rendering readiness, the command still fails and the reached document remains available through the current session. Reload does not retry automatically and always expires earlier element references, so take a fresh snapshot before another element action.

tama browser storage-clear clears cookies for the current browser session, plus local storage, session storage, and IndexedDB scoped to the current page. Its successful response includes a bounded storage_clear object with cookies and site_storage statuses of cleared or unavailable. On opaque pages such as about:blank and browser error pages, cookies can be cleared while page site storage is unavailable. This is an expected successful result. The command never returns storage values or page content. Cookie failures and unrelated page-evaluation failures remain command errors. Unrelated page-evaluation errors state that cookies were cleared before current-page storage failed.

Library, feedback, logs, and MCP

• tama library opens Library discovery. tama library ls lists a path and tama library tree prints its bounded hierarchy. Folder and document results include server-issued Playbook reuse IDs and fingerprints.
• tama feedback [message] --type bug|idea|other|support [--workspace id-or-slug] [--submission-id UUID] prints its submission UUID to stderr before sending and returns a JSON receipt once the report and background processing job are durably saved. In a terminal, leave the message out to write it in your editor. A Task Machine Run cannot open an editor, so it passes the message inline. Redact private data first. Accepted means saved, not fixed. Keep working rather than waiting for classification. After an ambiguous failure, inspect tama feedback status <submission-id> or repeat the original command with --submission-id set to the printed UUID. A retry retains the original report instead of replacing it.
• When reporting an open problem again, include its existing task identifier, such as FEE-836. Task Machine considers that report and recently created feedback alongside related search results. A reference alone does not force attachment to the existing report.
• tama feedback status <submission-id> returns only your own receipt: submission_id, status (accepted, processing, completed or failed), action (created, attached or null), task and error. The final Task appears after processing, not during acceptance. failed retains the saved report for recovery and uses a content-free error category. Missing and foreign identities are indistinguishable. Candidate reports, classification decisions and intake credentials remain private. This CLI receipt-status command is not a remote MCP tool.
• tama logs prints local daemon logs for diagnosis. Each line starts with its UTC time.
• tama mcp manages workspace MCP servers for a human operator. tama mcp add, tama mcp assign, and tama mcp remove are unavailable to a job-scoped agent. Agents use governed proposals.

tama mcp list

tama mcp list [--workspace <id-or-slug>] [--status active|archived|all] prints a secret-free JSON array of accepted workspace Connectors. During a Run, the default is active, including Connectors needing setup. Outside a Run, omitting --status preserves the full accepted operator catalog. all includes current, setup and archived records. Proposed and rejected candidates stay excluded.

Each request reads a bounded page. The CLI follows next_cursor until has_more is false, preserves the selected lifecycle scope on every page, and prints the complete array only after all requests succeed. A failed or non-advancing page produces an error without partial output. Worker reads require mcp:read. Operator reads keep their existing permission boundary. Invalid --status values fail before any network request and name active, archived, and all as the allowed values.

The offline --help contains the complete output JSON Schema. Each record includes id, name, lifecycle state, transport metadata, Vault reference maps, and OAuth status/scopes. Accepted versioned records include current_version_id. Worker reads also include existing_mcp_server_id and the server-issued existing_resource_fingerprint for exact reuse. Reference maps contain credential_id and field, never credential values. Historical discovery cannot restore, assign, verify or execute a Connector. Remote MCP excludes this catalog under the existing recursive-configuration boundary.

tama mcp list --status archived
tama mcp list --status all

Proposal leaf commands

All creation leaves require --rationale: tama propose workspace, tama propose team, tama propose agent-instructions, tama propose skill, tama propose task, tama propose project, tama propose repository, tama propose goal, tama propose workflow, tama propose trigger, and tama propose document. Run the exact leaf with --help before constructing JSON or flags.

Typed revision leaves are tama propose update agent, tama propose update connector, tama propose update team, tama propose update project, tama propose update goal, tama propose update workflow, tama propose update trigger, tama propose update repository, tama propose update budget, tama propose update skill, and tama propose update playbook.

Versioned revisions require the current immutable base version. Repository revisions instead require the inspected updated_at as base_updated_at, with no version UUID. All reject unknown, ineffective, stale, or cross-workspace changes.

Assignment review

tama tasks assignment-review submits the structured outcome for the current assignment-review Run. It is not a general task edit command. Use its --help schema and submit exactly one reviewed assignment disposition.

tama tasks assignment-review candidates <task-id> reads up to twenty eligible Human reviewers when the Task requires Human review. The eligible Task creator appears first. Continue with --after <next_cursor> when has_more is true. The read uses the current assignee's permissions, takes no stdin, and changes no assignment. Each candidate provides a membership ID, display name, and task_creator indicator. A Task that does not require Human review returns an empty page.

From here

For how these commands fit together when a Worker comes online and picks up work, read Workers. The agent resource commands enforce the same role boundaries a person is held to. See permissions reference for the catalog. To choose where local agent work is stored and how Task Machine starts, see CLI setup.