Repository navigation
v0.2.0-beta.4
Pre-releaseThe team lives in the repository. A .docket/ directory next to the code (roles, pipeline,
policies, settings, skills) is the team's configuration of record, applied by docket init or
docket pod <p> apply; eighteen shipped recipes cover teams, policy packs, methodology pipelines,
checks and tools. Since v0.2.0-beta.3 docket also gained a provider catalog of fourteen built-in
kind: provider documents, OpenTelemetry and Langfuse export with privacy levels, an operator
loop in which a gated task parks and waits in one inbox with notification channels, agent
consultations and evidence-v1, one git worktree per task, a network lockdown mode and an
execution envelope whose workspace isolation is opt-in (docket gates isolate on).
Breaking changes. docket has no installed base yet, so every compatibility path was removed
outright: docket auth is gone (use docket keys add and docket models provider add), tier
names (economy/standard/premium) are not accepted anywhere, removed commands are ordinary
unknown commands (exit 2), and the serve API is version 3. See Removed below.
Added
-
Console alone tells nobody, and docket now says so.
consoleis a silent channel dialect
(core.channel.SILENT_DIALECTS);Catalog.delivering()names the enabled channels that reach
an operator away from the terminal.docket doctorgains aNotifications:check, counted as
an issue once a pod exists (checks.notifications {ok, delivering}in--json);
docket serve --dispatchwarns once at startup,docket initafter the created summary and
docket pod <p> dispatchafter a flush that found events, all with one text naming
docket channels enable desktopandntfy --set topic=<topic>. On a TTY with a desktop
session,initoffersEnable desktop notifications now? [Y/n]and, on yes, enables it and
sends one test notification; nothing is ever enabled without that yes. The quick start's
"Run unattended" now opens with picking a channel.- Found by the first real park -> flush run: the same parked approval reached
desktopand
ntfytwice, once through its task and once standalone, because_park_callnever
recorded the task on the approval. It now does (context.taskId), and the inbox also folds
an approval whose token a waiting task holds, so one decision is one notification. - A consult's options can be answered from the CLI:
docket pod <p> answer --option <id>,
anddocket chatlists the options and prompts for one (Enter takes the recommended).
docket inboxprints a waiting task's question, its options and thedocket chathint,
and a parked task's held action with thedocket approve/denyhint (what the standalone
approval line showed before it was folded into its task).
Found live: the Lead asked a two-option question that Telegram and HTTP could answer and
the CLI could not, and the inbox showed only the task's description. - The built-in
desktopchannel now fires for a failed task too (on: [needs_you, task.failed]), the subscriptionntfyalready shipped; a task that fails while you are
away is something that needs you. A completed task still notifies nobody by default:
docket inboxlists it under "Done".
- Found by the first real park -> flush run: the same parked approval reached
-
The items carried out of Phases 36-38 (Waves 89-90, no phase).
docket pod <p> worktrees prune [--dry-run] [--force]removes finished tasks' worktrees and
merged branches, keeping (and naming) dirty, unmerged anddispatch --resume-able ones;
--forceremoves the worktree, keeps an unmerged branch and audits it.- A second SIGINT/SIGTERM makes
docket serveabandon in-flight sweeps: it requests
cancellation of each sweep run, exits 130/143, and the task endscancelled. approve_taskgrants a parked pod call for the rest of its task, bound to the role that
asked:docket approve <token> --option approve_task, Telegram/approve <token> task,
POST /approvals/<token>option, MCPapprovals_grant(option=). Each later hop of that role
gets one single-use pre-grant; at most 20 per task, dropped at a terminal status.- Channel notifications at the
conversationlevel carry a question's options and the
recommended id, and Telegram/answer <task> <option id>picks one. - A
run:step can carryenv:(refused forPATH,LD_*,PYTHON*,DOCKET_*and
credential names; the task coordinates win; values never reach the trace). The
anti-tautologyandmutationrecipes declare their overrides there. docket doctorlists every unjailed MCP server, global and per pod, and, when Docker is the
backend, warns if the jail image has nogit;config explainshowsisolateper server and
recipes show --jsonunjailed_mcp_servers.- A harness consult's
question.taskIdis the run token, not the session key.
-
The execution envelope (Phase 38, D-55, ADR 0020). With isolation on, an agent's
processes run in a jail, and nothing docket holds leaks into them.- Workspace isolation is opt-in (
docket gates isolate on; ADR 0021, see Changed). bwrap is
tried first, then Docker (DOCKET_SANDBOX_BACKENDstill forces one). With isolation on and
no usable backend a turn is refused before any model call, naming both fixes (install
bubblewrap, ordocket gates isolate off).docket doctorandgates isolate onprobe the real
backend. Inside the jail a task worktree's git dir and the repository's common dir are
writable, so an agent can commit;.git/hooks,.git/configandconfig.worktreestay
read-only, so the jail cannot plant code the host's nextgitwould run. docket gates network none|openand a podnetworksetting (noneonly narrows) cut the
jail's network: bwrap drops--share-net, Docker runs--network none. The default stays
open.network nonewith isolation off is refused at turn start.- stdio MCP servers start in the same jail as
bash(the turn's roots and network mode) unless
declaredisolate: false(docket mcp servers add --no-isolate, audited, shown bydoctor;
a recipe'skind: mcp-serverdocument may declare it too).code-intel'sast-grepserver
does, becauseuvxcannot write its cache in the jail. fetchresults pass thepre_inputhook like MCP results (fetch.result_blocked/
fetch.result_warn), through one shared screening function.verifyCmd,run:steps and an unjailedbashno longer inherit docket's credentials
(DOCKET_LLM_API_KEY, every provider-catalog credential name,TELEGRAM_BOT_TOKEN, every
stored secret name).docket serve --dispatchsweeps each pod in its own worker (DISPATCH_SWEEP_WORKERS,
default 4), so one pod's blocking hop no longer stalls the others. Stoppingservewaits for
in-flight sweeps.- A refused isolation or network posture settles the task
dispatch_refusedafter one attempt
(it was retried as a transient error).
- Workspace isolation is opt-in (
-
Verification-ready execution (Phase 37, D-54, ADR 0019). What a task brings back is its own,
screened and checkable by something other than docket.- One git worktree per task: at claim, a repo Implementer's task runs in
<implementer workspace>/tasks/<taskId>on branchdocket/<pod>/<taskId>, created from the
codebase HEAD and recorded on the task asworktree {dir, branch, baseCommit}. Evidence
baseCommitis that recorded commit, so a task'sdiffStatno longer counts earlier, unmerged
tasks.docket add/initcreates no worktree, and the per-member worktree and its
worktreeDir/worktreeBranchmeta are gone. Finished worktrees stay until the member is
removed; the operator merges the branch. - MCP tool results pass the
pre_inputhook as untrusted input before they reach the model:
blockrefuses the result naming the policy and server,redactscrubs it,warnpasses it;
each hit is audited (mcp_client.tool_result_blocked/_warn). - Command steps (
run:) receiveDOCKET_TASK_ID,DOCKET_BASE_COMMITand
DOCKET_HEAD_COMMIT, taken from the latest successful Implementer hop's evidence. - A
no_progressstop: a turn ends whenAGENT_LOOP_NO_PROGRESS_ROUNDS(default 3,0
disables) consecutive tool rounds only repeat calls and results already seen in the turn. - Recipes may ship
kind: mcp-serverdocuments undermcp-servers/(read/write declared as
access:).docket pod <p> applyinstalls them for that pod only, and nothing else does. A
turn's stdio MCP servers start in the turn's root. - Five recipes:
anti-tautology(new or changed tests must fail on the base commit),
mutation(mutmut on the changed source files, 80% threshold),spec-writerand
cross-family-review(two pinned models from different providers), andcode-intel
(ast-grep and a language server as read-only MCP servers). docket runs these checks and records
their output; it never scores them. - Known limits:
mutationscopes by file, not line, and is Python-only;anti-tautology
compares whole test files; the check recipes' overrides are read from the docket process
environment; finished task worktrees have no retention policy;fetchresults are not
screened.
- One git worktree per task: at claim, a repo Implementer's task runs in
-
Consultation packs and evidence-v1 (Phase 36, D-53, ADR 0018). An agent can now ask the
operator a structured question and an operator can see what a task did, from one builder on
every surface.consultis a built-inreadtool: the model asks adecision-kind question with options and
an optional recommendation (operator-v1.1QuestionV11, schemas under
docs/contracts/operator-v1.1/). In a single harness turn it is aquestion_askedevent
answered on stdin byquestionIdwith anoptionId; underrefusethe turn endsblocked
with the question on the v1.1 result. In a pod hop it parks the taskwaiting_inputand
answer_taskre-enters the same role with the answer.maxConsultationsPerTaskcaps it task-wide.- Approval packs: a gated call carries a screened, 500-character-bounded
rationaletaken from the
model's preceding text, and three options (approve_once,approve_task,deny).
approve_taskpre-grants identical calls within the turn only.docket approve|deny --reason,
HTTPreasonand a harnesscontent.reasonrecord why, with anactor, in the audit entry. - evidence-v1 (
core/evidence.py,docs/contracts/evidence-v1/): per-hop measured usage and a
trace link for a task, read throughdocket pod <p> evidence <task> [--json],
GET /tasks/<p>/<id>/evidenceand the harness result'stask.evidence. All three come from
one builder. Usage isnullwhen the endpoint reports zero. - Corrections ledger: deny reasons, Reviewer
REQUEST-CHANGEStexts and declined answers append to
<DOCKET_HOME>/corrections/<project>.jsonl, read withdocket pod <p> corrections. - Escalation metrics:
docket_tasks_started_total,docket_questions_total{kind,outcome}and
docket_decision_latency_secondson/metrics, anddocket metrics --escalation. They are
lifetime-of-current-storage counts, not monotonic totals. - Harness
filesno longer lists paths that were already dirty before the run or that the verify
command produced (P35-12). - Known limits: the parked consult question crosses to the answering process through an in-process
registry (out of process it fails closed);approve_taskdoes not survive a parked and resumed
hop; a single-turn consult'squestion.taskIdis the session key; options are not rendered in
Telegram or channel notifications.
-
Harness contract 1.1 is complete for an external supervisor (Phase 35, D-51, ADR 0017).
docket harness run --contract 1.1(opt-in;--contract 1.0stays byte-identical) adds
process lifecycle events forbash(process_started/process_exited, withpgidand
exitCodeorsignal);--answers stdinwith--answer-timeoutfor approvals and recipe
questions;fileson the result (written and edited paths, plusgit statusin a git
workspace);--token-file,--max-tokens,--policy;--recipe NAME|DIRwith--verify,
reporting the hops in ataskblock; andapprovalson the result, so a denied or timed-out
approval is visible without changingstatusor the exit code. The committed schema is
docs/contracts/harness-v1.1/schema.json, and an integration test validates every line of a
real subprocess run against it. Approval mode for a recipe run travels as the ephemeral pod's
setting, not an environment variable. -
Mechanisms for the recipe runner (Phase 35, P35-7).
core/harness_pipeline.pyruns one
recipe in place on an ephemeral pod for one task, through the same dispatch the pod uses. -
Fixes (Phase 35). Pod dispatch keeps its evidence (verify output, commit, base and
diffstat);requireVerifymakes a missing verify command fail a hop instead of advancing; a
guardrail_blockevent carries the action, not the policy id; pod-scoped roles get their own
token budget. Process groups forbashare cancellable bydocket runs canceland by SIGTERM
on the harness. -
The operator loop: tasks park instead of blocking, and every human touchpoint speaks one
contract (Phase 34, D-50, ADR 0016). An unattended pod's gated tool call no longer blocks a
hop for 120s with nobody watching:approvalMode: park(the default forserve --dispatch's
sweep and a non-interactivedispatch; an interactive TTY still resolves towait) records
the exact call and moves the task towaiting_approvalso the sweep moves on to the next pod
in the same pass, and granting it re-runs the hop carrying a single-use pre-grant matched by a
stable argument digest. A pipelineinputstep ({ask: {input: {from: <step>}}}) can instead
park a taskwaiting_inputto ask a real question, shaped as an MCP elicitation request/
result; the opt-inintakerecipe wires this to a Lead's typedTaskBrief
(objective/acceptance/resources/questions, verdictREADY/NEEDS-INPUT/REJECT) with
a deterministic pre-flight check of named secrets/paths/verify commands before the Implementer
ever runs.docket inbox(alsoGET /inbox, the MCPinboxtool, and Telegram's/status)
is a pure, derived view across every pod's tasks and approvals; nothing is pushed anywhere
until an operator enables akind: channeldocument (docket channels list|show|enable|disable|content|test|add|remove|export) — seven dialects ship, all off
exceptconsole, each declaringcontent: minimal|actions|conversationunder the same
confirmed-and-audited widening shape Phase 33 used for exporter privacy, and every
notification is a CloudEvents 1.0 envelope, withwebhooksigning deliveries per Standard
Webhooks. Parked work is answered fromdocket pod <p> answer,docket chat <task-id>,
POST /tasks/<id>/answer, the MCPtask_answertool, or Telegram's new fifth verb
/answer <task-id> <text>(still inbound-only, still screened bypre_input) — every one of
these resolves through the singlecore.answers.answer_taskfunction.docket pod <p> explain interruptionsforecasts what could pause a task before it runs, anddocket pod <p> pregrant <task-id> "<command>"pre-approves an exact, whitespace-normalized command (a rephrased one
still asks). Every task view now carries ana2aStatealongside docket's ownstatus, mapped
onto A2A 1.0.0'sTaskStateenum, though docket does not itself become an A2A server this
phase. Measured on the phase's own--scenario operator-looporacle:sweepBlockedSeconds
fell from roughly 12-13s to under 1s deterministically onceparkshipped, confirming the
blocking wait is gone — though under the local live model the same scenario still measured
138s, because the sweep remains one worker walking pods serially, a different and unfixed cost
left deferred with its own trigger. Two known limits:channels-health.jsonrecords delivery
counters that no CLI surface reads back yet, and mid-turn session resume (in place of a hop
re-run) stays deferred pending a measured trigger. -
Export privacy levels: you choose what leaves, and see it first (Phase 33, D-49, ADR 0015).
Eachkind: exporterdocument says what it shares beyond structure:privacy: minimal(the
default for every built-in),actions(tool arguments, error text),conversation(prompts,
replies, tool results) orfull(plus the system prompt), or an exactshare:list;
contentMaxCharsbounds each value. Content leaves only through an allowlist, filtered per
message part, and is captured into the local trace only while some enabled exporter grants
it, so atminimaleverywhere the local trace is what it was without exporters.
docket exporters privacy <name> <level>widens only after listing what starts leaving and to
which host (a TTY confirmation, or--yes) and recordsexporter.privacyin the audit log;
docket exporters preview <name>shows what a destination would receive from a real local
session, offline.listgainsSHARES,showa "Leaves this host" block, and every exported
session carriesdocket.privacy. Atconversation, Langfuse shows each generation's
Input/Output, each tool's result, and the trace's own Input and Output (the session's task and
its last answer, carried on the root and aliased by the built-inlangfusedocument), verified live with canaries at three levels; at
minimalno canary reached the collector, Langfuse or the local trace. Compared with the
pre-releasepayload: metadatadefault, an approval's command line and error text no longer
leave atminimal. Export pipelines start once per process, so a running
docket serveapplies a level change after a restart. -
Traces can go to OpenTelemetry and Langfuse (Phase 32, D-48, ADR 0014). A destination is
akind: exporterdocument (core/exporter.py): endpoint, auth (bearer/header/basic/
none, credential names only, never values),resource,aliasesand which event types to
send. Five ship in the wheel undertemplates/exporters/, all disabled:otel-collector,
jaeger,langfuse,honeycomb,phoenix; a global override inherits every field it does
not set. The one wire dialect,otlp-http(edges/adapters/exporters/otlp_http.py), is
deterministic OTLP JSON hand-rolled over stdliburllibwith a retry on 429/502/503/504 that
honoursRetry-After; D-24's cut of the OpenTelemetry SDK stands. Every turn starts the bounded
export pipeline lazily, flushes it on every return path (bounded byEXPORT_FLUSH_TIMEOUT_S
even if a destination hangs) and writes per-exporter health counters; zero enabled exporters
costs one catalog read.docket exporters list|show|enable|disable|test|add|remove|exportis
the CLI surface:enableresolves the declared credentials (prompting on a TTY, naming
docket keys add <NAME>off one), probes the endpoint, and writes only the minimal override.
docket config explainanddocket doctorreport each exporter; apod.yamlmay name
exporters:, whichapplyanddocket recipes showreport and never activate. One session
is one trace: every hop's model calls keep their own span ids (the key includes the role and
the call's timestamp, not only its iteration, which each hop restarts at 1), so does each hop
and each verification result, and the root is sent once, when the session ends, so a
destination that upserts by span id keeps every generation, every hop and one root, and
Langfuse's trace Input/Output show the task and the final answer rather than the first hop's. Verified live: a 4-hop dispatch against a Docker
otel-collectorproduced 29gen_ai.chatspans matchingdocket trace's 29llm_calllines
and 39execute_toolspans; replaying that dispatch's trace now gives 29 distinct generation
ids and one root, where before the fix Langfuse kept 12; a real dispatch reached Langfuse's own
dashboard with timing and token counts. See
observability-export.spec.md§"External verification". -
The model's own call is a trace event. Every chat-completions exchange (each turn
iteration, plus the compaction summarizer's own call) is a durablellm_calltrace record
carrying model, provider, measured latency and token counts, never a dollar figure.
ChatResponsegainsmodel,provider,latency_ms; the trace record gains an optional
task_id; the store gets its first owning spec,trace-store.spec.md.core/telemetry.py
projects trace records into a neutral span model with ids derived from the session id, never
random, andtrace_ingestnotifies subscribers before appending so a live consumer sees a
driver-projected session in order. -
A recipe library of three kinds, and a recipe that says what it brings. Twelve recipes
ship: the three teams, four policy packs that change no roster (git-safety,no-egress,
secrets-guard,prod-approval; every rule stated with the structuredtool/path/anyOf
predicates rather than free text, andsecure-build's andops-approval's own policies
rewritten the same way), and five methodology pipelines that are the practice (tdd,
spec-first,reflexion,dual-review,frugal). What a recipe brings is derived from its
directory, never declared:docket validate <dir>,docket pod <p> apply --dry-run,
docket init --recipeand the newdocket recipes list|showprint the same summary line.
pod.yamlgains an optionaldescription; a recipe name resolves against a directory path,
your own~/.docket/recipes/<name>/, then the shipped library;applyrecords the pod's
configSourceafter every validated apply, an all-skipone included, so composing recipes
and applying the exported.docket/leaves the record naming the repository. The page
docs/recipes.mdis generated from the recipes and checked in CI. -
Skills, in the Agent Skills shape.
skills/<name>/SKILL.md(front mattername+
description, the body on demand) is discovered from three scopes, nearest wins by name: the
repository's.docket/skills/, the pod's ownconfig/skills/(a recipe'sskills/is applied
there and exported back), and~/.docket/skills/. The system prompt carries a# Skillsindex
of screened descriptions; a new built-inskilltool of kindreadreturns the body or a file
inside the skill's directory through the same chokepoint, deniable per role.secure-build
shipssecurity-review,tddshipstest-first,spec-firstshipswriting-a-spec.
docket config explainlists the skills an agent sees. -
AGENTS.mdis read by default. When a pod'sprojectInstructionsis unset and the
codebase root holdsAGENTS.md, the file every other coding agent reads is composed as the
project-instructions section: screened throughpre_inputas untrusted, capped, reported; an
explicitprojectInstructionslist replaces the default.docket config explainnames the
files and their source. -
docket pod <p> apply <name>takes a shipped recipe by name. The argument resolves as a
directory if one exists there, else as one of the shipped recipes (secure-build,
research-review,ops-approval), exactly asdocket init --reciperesolves it, so a recipe
can be applied onto an existing pod without a path into the installed package. -
The team lives in the repo. A repository's
.docket/directory (the same shape every
shipped recipe anddocket pod <p> exportwrite:pod.yaml,roles/,pipeline.yaml,
policies/,plugins/) is the team's configuration of record.docket initdiscovers it,
validates every document before provisioning anything, and applies it after the pod exists;
docket init --recipe <name|dir>starts from a shipped or local recipe the same way (mutually
exclusive with a present.docket/);--no-applyprovisions only. Nothing is applied without
an operator command: dispatch,serve, schedules and the harness never read the directory. -
A pod knows where its team came from.
applyrecordsconfigSourceandconfigDigest
(written by nothing else;pod config setand apod.yamlsettingsmapping refuse them),
docket pod <p> exportdefaults to<codebase>/.docket/likeapply, anddocket config explain <agent>reports the source, the digest anddrift: yes|no. -
A pipeline step names its model.
model: cheap|strong|<provider>/<id>on a step, in the
canonical and the short form, wins for that hop only and is never written to the agent's
metadata;docket pipeline planprints it andvalidate/planrefuse an unknown provider
naming the step. -
One field says what a role may not do.
editRightsis retired from the role wire
format: a stored overlay that still carries it loads and drops it,roles shownever writes
it,roles listloses the column, anddocket validateprints anote:for a file that
still declares it.deniedTools(cannotin the short form) is the only capability statement. -
config explainsays where a model goes, anddoctorchecks the provider catalog.
docket config explain <agent> --jsoncarries aproviderblock (name, scope, dialect, base
URL, the credential's name and source, the exact model row's limits) and the human view prints
it under the model line, never a value;docket doctornames a malformed global provider
document by file and field, in the human pass and under--json. The configuration guide,
model-gateways page, troubleshooting page and quick start describe the catalog,export, the
Retry-Afterceiling and the evaluation-only/beta status Anthropic and Google give their
OpenAI-compatible layers. -
Registration verifies with the credential, and a provider round-trips through the CLI.
docket models provider add <file.yaml>(or theadd <name> <url> --model <id> [--credential NAME]shortcut) probes<url>/modelswith the resolved credential and
classifies the answer: only a transport failure refuses; 401/403 registers and names the
missing or rejected credential; 404 registers and says the route is unserved; a 200 that
advertises ids the document lacks prints them as suggestions.list,show [--json],
removeandexportcomplete the round trip (export-> fresh home ->add-> identical
show --json), anddocket models preset <name>prints one readiness line naming the
credential as present or missing. -
A provider can authenticate by header and send static headers.
auth: {type: header, header: api-key, credentials: [AZURE_KEY]}sends the credential under that header (Azure
OpenAI, a multi-workspace Anthropic key) andheaders:adds static headers to every request;
Authorization,Content-TypeandAcceptare refused at load. A bearer document's request
is byte-identical to before. -
Fourteen providers ship as built-in documents, and every table derives from them.
templates/providers/holdsanthropic,openai,google,openrouter,ai-gateway,
groq,mistral,deepseek,xai,cerebras,together,ollama,lmstudioand
local; presets, prices (withpricesAsOf), key-format prefixes, credential names and base
URLs are read from the catalog, sodocket models preset anthropic|openai|googleapplies
without a priorprovider addand a stored key alone readies a built-in hosted provider. A
provider absent from the catalog resolves only underDOCKET_LLM_BASE_URL. -
A retry waits as long as the provider asked, up to a ceiling. A retryable HTTP failure
carries the endpoint'sRetry-After(seconds or HTTP-date) throughTurnResult.retry_after_s;
the dispatch backoff ismin(max(2s x attempt, Retry-After), DISPATCH_RETRY_MAX_WAIT_S)
(default 60 s) and thehop_retrytrace event records it. -
A model provider is a
kind: providerdocument.core/provider.pyholds the catalog:
built-in documents undertemplates/providers/and the
operator's own in~/.docket/docket-providers.json, nearest-wins by name. A document names
its credentials (auth.credentials) and never holds a value;resolve_endpointreads the
catalog and the exact model row's limits. A pre-catalogfleet.json -> providersblock is
migrated once on first use (a literalapiKeymoves into the secret store under
<NAME>_API_KEY, auditedprovider.migrate), anddocket validate <file>accepts
kind: provider. -
A policy can call a Python predicate the operator applied, never one the agent wrote.
when: {plugin: <name>, with: {...}}runs a@predicatefrom~/.docket/plugins/or the
pod's ownconfig/plugins/-- the only two places ever imported; a file in the codebase is
invisible untildocket pod <p> applycopies it with its sha256. An unknown name, a raise, a
non-bool return or a call over its budget denies, naming the plugin; every call is audited as
policy.plugin.docket plugins list [--pod <p>]shows name, scope, file and hash. The
public API isdocket.plugins(PLUGIN_API_VERSION = "1.0.0"). -
Schemas an editor can use, and export in the short form.
docs/contracts/config-v1/
holds generated JSON Schemas for the four kinds, pinned byte-for-byte and shipped with the
package;docket pod <p> exportnow writes short-form YAML (a.mdbeside each role,kind:
andname:onpod.yaml) with a# yaml-language-server: $schema=header and a.schemas/
copy, and applying an export plans every itemskip. The shipped recipes and the
configuration guide show only the v1 short form. -
Outcomes route the pipeline, and every loop has a bound. A step's
on:map sends any
gate outcome -- a verdict marker,pass/failof a verify command -- tofail,stop, a
later step or an earlier one; a backward edge needsmax, andvalidate/planrefuse a
missing bound or an unreachable step.until: verifywithmaxretries a step until its
verify command passes. Every routing decision is aroute_takentrace event; the shipped
recipes and the one-rework-edge form are byte-identical. -
A step can be skipped, and a step can be a command.
when: {changed: "src/**"},
when: {var: name, is: value}orwhen: {memberPresent: role}skips a step (step_skipped
trace event, no hop).- lint: {run: "ruff check ."}runs a command in the pod's worktree
with no agent turn and no model tokens, classified like any shell-out (an unlisted command
asks, or fails underapprovalMode refuse); its exit code, or a single upper-case last
output line, is the outcome itson:map reads.planprints both. -
Every configuration file can say what it is, and one command validates them all. A
role, pipeline, policy orpod.yamlmay start withkind:andname:;docket validate [dir|file]checks every document under a directory (default.docket/) and prints
file:line field: message (valid: a, b, c; did you mean "b"?), exit 1 on any invalid file.
A file withoutkind:still loads, with one deprecation note per command. -
Policies read as "when this, then that". A policy may be short-form YAML (
kind: policy,
appliesTo,on: input|toolCall|output,when,then: allow|warn|ask|block|redact) with
structured predicates over the call itself --tool,path(glob over the path argument),
matches(regex over the rendered text),branch(glob over the worktree branch),anyOf
for OR -- evaluated inside the same chokepoint. The six shipped templates are now short-form
YAML; every existing JSON policy keeps loading unchanged.docket policies testtakes
--arg key=value. -
A pipeline step reads as "who, what is checked, where it goes".
- build: implementer
plusverify: true,verdict: [APPROVE, REQUEST-CHANGES],approval: <message>or
on: {REQUEST-CHANGES: {goto: build, max: 1}}; the canonical form is unchanged and still
whatplanprints. The three shipped recipes are written in the short form. -
A role file carries only what is enforced.
cannot: [write, edit, bash], one of
verdict/verify/approval,model: cheap|strong, andinstructions: <file.md>whose
Markdown becomes the role's prose (an optional## AGENTSsection supplies the red lines);
editRightsis derived fromcannot, never authored. -
A pod exports its own scope, and the round trip is the proof.
docket pod <p> export <dir> [--force]writes the pod's role overlay, its policies, its bound pipeline and apod.yamlof
members and non-default settings, never anything global; applying that directory to a fresh pod
in a fresh home reproduces the sameconfig explain --json.applyalso carries a recipe's
policies/*.jsoninto the pod, so the shipped recipes need no manual copy. -
A recipe applies to any pod in one command.
docket pod <p> apply [<dir>] [--dry-run] [--json](default<codebase>/.docket/) readsroles/*.yaml,policies/*.json,
pipeline.yamland a three-keypod.yaml(members,settings,pipeline), validates
everything before writing anything, is idempotent, and audits once aspod.apply. The three
shipped recipes carry apod.yamland their README's "Apply it" is that one command. -
Every resolved value says which scope it came from.
docket config explain <agent> --json
labels the role, each policy file, each loaded MCP server and each denied tool withscope: built-in | global | pod, anddocket doctornames a malformed pod role overlay entry or an
invalid pod policy file by pod, item and reason. -
A pod chooses its MCP servers and denies tools for every role in it.
docket pod <p> config set mcpServers a,blimits a pod to those catalog servers (unset means all; an unknown or stale
name is refused at write and refuses the dispatch naming it), andset deniedTools fetch
removes a built-in tool from every role of that pod on top of each role's own denials. -
The Lead's instruction is data. The
leadarchetype carries ahopInstruction(shown by
docket roles show lead); a global or pod overlay oflead, or a pipeline step's own
instructions, now changes what the Lead is told. Research, content and ops pods' Leads plan
for their real next role instead of an Implementer they do not have. -
A pod has its own role overlay and its own policies.
docket roles add|list|show --pod <p>
write and resolve~/.docket/workspaces/pods/<p>/config/roles.jsonabove the global overlay for
that pod alone, anddocket policies list|test|validate --pod <p>fold that pod's
config/policies/*.jsoninto the same most-restrictive-wins evaluation, so a pod's policies can
only add restrictions. Both reach a member's live turn, including a standalone one. -
An MCP server declares its kind and its exposed tools.
docket mcp servers add <name> --kind read|write --tools a,b -- <cmd>: a server declaredreadnow reaches a read-only role instead of
being dropped with everything else;--toolslimits which advertised tools register. Undeclared
servers keep the fail-closedwritedefault. -
A pod's dispatch settings are a typed, validated, writable configuration surface.
docket pod <p> config [get|set|unset] <key> [<value>](with--jsononget) covers nine
keys —budgetUsd,maxReworkCycles,turnTimeoutS,verifyTimeoutS,approvalMode,
allowCommands,pipeline,scheduleandprojectInstructions— validated at write and
audited aspod.config. An invalid stored value now refuses dispatch naming the key, instead of
silently falling back to a default, anddocket profile --budgetwritesbudgetUsdas a
number, not a string. -
An unattended dispatch can refuse instead of waiting on nobody. Setting a pod's
approvalModetorefusemakes a hop that would otherwise block on a human approval fail the
task at once, naming the tool and policy, instead of sitting on the approval timeout under an
unwatched schedule or serve sweep. The default (wait) is unchanged. -
A pod can allow its own tool binaries.
allowCommandsnames extra bash binaries that pod's
agents may run without an approval prompt, scoped to that pod and validated at write: a path, a
shell metacharacter, an opaque name (eval,source, ...) or a high-risk-class binary
(git,npm) is refused, and a redirected call still asks. -
A pipeline file can be a pod's default for every trigger.
docket pod <p> config set pipeline <file>validates the file, plans it against the pod's roster, and stores a
docket-owned copy with its hash; that pipeline then runs for a manual dispatch, a
serve --dispatchsweep, a schedule, and a webhook or MCP dispatch alike, not only a
manually-passed--file.unset pipelinerestores the blueprint default, and
docket pipeline planprints aSource:line naming which one would run. -
Custom roles can carry their own hop instructions, and pipeline steps can be parameterized.
A role archetype'shopInstruction(or one generated from its gate contract when unset) now
reaches a custom role's hop, and a pipeline step's owninstructionsfield overrides it. Step
instructions may reference${name}variables, resolved from repeatabledocket pipeline run --var key=valueflags as well as from a webhook payload; an unresolved variable refuses the
run instead of sending the literal placeholder. -
docket config explain <agent>shows the effective configuration with provenance. One
read-only command (with--json) reports the resolved model and endpoint, each prompt
section's size and fit status, the agent's tools after role denials plus the configured MCP
servers, the policies that apply to the role, the effective pipeline and its source, and
budgets, timeouts,approvalModeandallowCommands— each value tagged with what set it
(meta, policy, pin, pod setting, env or default). -
An operator-owned
INSTRUCTIONS.mdcomposes into every agent's prompt and survives
regeneration. docket never writes it.docket pod <p> sync [--dry-run]re-rendersSOUL.md,
AGENTS.mdandTOOLS.mdfrom the current role archetype and metadata for any pod member whose
template or archetype has gone stale, showing a diff first with--dry-run;docket doctor
flags pod members that are out of date. -
A pod can opt an agent into reading its own codebase's project instructions. Setting
projectInstructionsto one or more relative paths (for exampleAGENTS.md) composes those
files into the prompt right afterINSTRUCTIONS.md; each one is screened as untrusted input by
thepre_inputpolicy hook, a missing file shows a visible marker instead of failing silently,
and a path that would escape the codebase root is refused when the setting is written. Unset
(the default), nothing changes. -
Old runs, resolved approvals and closed conversations are pruned automatically and on
demand. The trace-retention window now also boundsdocket-runs.json, the approval store and
docket-conversations.json; only terminal records are removed, and live or pending ones are
never touched.docket runs prune [--days N] [--dry-run]anddocket conversations prune [--days N] [--dry-run]run it on demand. -
Three shipped recipes —
secure-build(implementer plus a security-vetter verdict gate),
research-reviewandops-approval— ship intemplates/recipes/: role, pipeline, an
optional policy pack and a README with the exact commands to apply them. Each is validated in
CI, andsecure-buildis proven end to end by a dispatch todoneon the fake driver.
Changed
-
Workspace isolation is opt-in (ADR 0021). A fresh install runs tools on the host and needs
no sandbox;docket gates isolate onjailsbashand stdio MCP servers in bwrap (Linux) or
Docker, and once on a turn with no backend is still refused.gates statusanddoctorread
off (default). Requirements are documented indocs/SECURITY-SIMPLE.md. -
Unknown
docket gatesanddocket contextsubcommands exit 2.gatesused to print its
usage and exit 0, andcontextsilently fell through toshow; both now name the unknown
subcommand and exit 2. -
docket audit verifyreports an unchained line as a break. A line withoutseq/
prev_hashused to be counted as "legacy", skipped, and treated as a chain restart; it now
fails verification at that line, like any other break. -
The
serveAPI version is 3./status.json(and the MCPstatustool) no longer carry a
gatewayfield,/healthanswers{"status":"ok"}, and thedocket_gateway_upmetric is
gone. The undocumented bare/statusroute is gone; use/status.json. -
The docs open with the newcomer path. The quick start is rebuilt as install → register a
model → create the team (recipe, plain, or a committed.docket/) → run a task → read the
record → export, edit, validate, apply → run unattended, with the terminal output of one real
run; the docs index leads with the tagline and a start-here order; the configuration guide
gains a complete.docket/example and the export→validate→apply loop, states that a broken
policy fails closed and that a pod selects its MCP servers; the agent-teams guide drops the
retired edit-rights column for the denied-tools one; every recipe README prints a command a
user can type; the site navigation lists Configuration and the Workflow guide. -
The README carries one pitch: agent teams as configuration, your rules, in YAML. The
front door opens with three sections -- the team you define (the.docket/directory and a
role and a pipeline in their short form), the run, and the gate and the record -- each
showing an asset captured from one real run, stating its limit beside the capability and
ending in the command that proves it, followed by the quick start, which now starts from a
shipped recipe and ends by writing the team back to the repository. The five-pain intro, the
eight guarantees and the sixteen-bullet feature list are folded into those sections or
relocated (best practices to the quick start, the tested adapter list to COMPATIBILITY.md,
which is now its only owner). The package, module and site descriptions carry the same
tagline. The prose tests that pinned the old headings were rebuilt from the new README's own
rules rather than carried forward. -
Non-software pods run their blueprint pipeline.
docket pod <p> dispatch,docket pipeline plan|runwithout--file,POST /dispatch/<p>, theserve --dispatchsweep, schedules and
Telegram/delegatenow resolve the Lead'sblueprintand run that blueprint's full roster and
gates. A research, content or ops pod used to run only its Lead; it now runs more hops and spends
more tokens per dispatch pass. Software and agentic-product pods, and any pod whose Lead has no or
an unknown blueprint, behave exactly as before. -
docket modelsno longer claims prices can be overridden indocket-models.json; no
pricing overlay is read. -
A prompt's context budget follows the resolved model's context window instead of a fixed
~24 KB for every model. A 200k-window endpoint now fits a full identity/memory/task-ledger
prompt that a fixed budget used to truncate; a 16k-window endpoint keeps today's behaviour.
CONTEXT_TOKEN_BUDGETand an archetype'stokenBudgetstill work as explicit overrides, and
docket maintain checkplus each turn'sprompt_composedtrace event report the effective
budget and what set it. -
A truncated or omitted prompt section is always marked, never silent. An oversized
SOUL.mdused to be able to pushHEARTBEAT.md,AGENTS.md,TOOLS.mdandMEMORY.mdout of
the prompt with nothing to say so; the runtime contract and task-ledger state are now protected
ahead ofSOUL.md, an oversized section is truncated with a visible marker, and every
composition'sprompt_composedtrace event lists each section's size and whether it was full,
truncated or omitted. -
There is one default model of record.
docket-models.json'sdefaultis now the only
source; the separate, sometimes-divergingfleet.jsondefault is no longer read. A
provider's display name derives from--modelunless--nameis given, instead of every entry
showing the shipped local model's caption. -
Built-in role templates no longer instruct an agent to do something the runtime forbids.
The generatedAGENTS.mdtext stops telling agents to writeHEARTBEAT.mddirectly (private
state is read-only on the live path);WORKFLOW_AUTO.mdis now labelled as the manual-path
contract it actually is.
Fixed
-
The jail could rewrite git metadata the host later runs: a submodule's hooks and config, a
linked worktree's.gitfile and itsgitdir/commondir, andinfo/attributesare now
read-only, and a missinghooks/dir or attributes file is created empty first so the jail
cannot create it. -
A jailed
git commitfailed whenever the operator's identity came from the environment or a
non-defaultHOME, and always under Docker: the jail now receives the operator's git identity
(never a credential). -
No inbox view,
/inboxresponse or channel notification ever carried a parked task's
questionorbrief: the fields existed and nothing filled them. -
A parked consult whose question lived only in the dispatching process stuck its task in
waiting_approvalwhen answered elsewhere; the question is now persisted (0600) and a missing
one fails the taskconsult_question_missing. -
git_branch_mergedread every branch checked out in a worktree as unmerged (it ignored git's
+marker). -
globandgrepno longer return or read files outside their roots through a symlink, a
symlinked directory, or a..in the pattern. -
The key-shaped redaction pattern no longer matches inside a word:
task=<id>was redacted to
ta[REDACTED]. -
A task paused on a question is a warning, not an error.
docket pod <p> dispatchrendered
waiting_inputwith the error marker; it now renders likewaiting_approval(found in the
Phase 36 live run). -
A canonical role file that says
kind: roleloads as written.load_role_filetreated
thekind:key as proof of the short form and normalized a canonical document, dropping its
deniedTools/gateContract/templates and then failing on a missing<name>.md; a document
carrying a canonical-only key now passes through, and one mixing both forms is refused naming
the keys. -
docket initcounts the members a.docket/or--recipeadded. The closingcreated with N membersline and the id list reported the blueprint roster only; they now report the
pod as it stands after the apply step. -
A recipe's own role no longer routes to the hosted default on a local fleet. A role a
recipe applied into a pod's overlay (security-vetter,model: strong) was resolved against
the global role registry only, so it fell to the compiled-inanthropic/claude-sonnet-4-6
while every other member followeddocket models preset local; the first dispatch then hit
the hosted vendor with no key (HTTP 401). Found by running the product for the new assets.
resolve_role_modelnow looks the archetype up in the member's pod registry and an unknown
role falls back to the registry's owndefault.docket pod <p> applyanddocket initalso
print the plan's[add]/[replace]/[skip]actions again; Rich had been reading them as
style tags and dropping them. -
A
cdprefix no longer turns an allowed command into an approval.cd,pwd,echo,
true,false,testand[joined the bash allowlist, socd <worktree> && git status
runs likegit status; an unattended implementer hop used to time out three times on exactly
that shape and fail.echowith an output redirect still asks, andexport/source/.still
ask.docket policies test pre_tool_callnow evaluates through the live gate's own function,
so it can no longer reportallowfor a command the gate asks about. -
GET /traces/<project>delivers every event exactly once across session files. An event
written in a second the cursor had already partly delivered, to a session file that sorts
earlier, was dropped while another was delivered twice. Events from the still-open second are
now held back until it closes; the cursor format is unchanged. -
docket help <command>prints that command's usage, or exits 1 naming an unknown command. -
docs/contracts/harness-v1/schema.jsonvalidates as JSON Schema. Its nested$refs
pointed at definitions the document did not contain, so a standard validator failed on
#/definitions/HarnessResult. The contract stays1.0.0; no field changed. -
The HTTP control plane sends
Cache-Control: no-store, as its spec always said; a bare
POST /approvals,/tasksor/dispatchis authenticated before it is answered400; and a
request body over 1 MiB is refused413without being read. -
Resolving an approval the other way answers
409, not404. Denying an approval that was
already granted (or the reverse) raised the same error as an unknown token, so
POST /approvals/<token>said the token did not exist. It now answers409naming the decision
that won. The same seam made one cancellation test flaky when the in-turn cancellation denied
first; the test now accepts either winner and still proves the tool never ran. -
docket cost <id> --jsonreturns that agent only. It used to return the whole fleet and
exit 0 even for an id that does not exist; an unknown id now exits 1 with nothing on stdout.
docket roles,gates,keys,policiesandmaintainreject an unrecognised--flagwith
exit 2 instead of silently ignoring it. -
POST /podsanddocket init --fromvalidate the project id. A project id such as
../../xused to provision workspaces and fleet registrations outsideDOCKET_HOME/workspaces.
core/provisioning.py::validate_project_id(lowercase alphanumeric segments joined by single
hyphens, at most 64 characters) now runs first inprovision_pod; the HTTP routes answer400
and the declarative file exits 1 for an invalid id. -
docket mcp servers add <name> -- <command>works from the real CLI. Click consumed the
--separator before the handler saw it, so the command's own help example always failed with
"Missing '--' separator". -
An approval granted or denied over MCP resumes or fails the dispatch task it gated, the same
asdocket approve/docket deny, the HTTP route and Telegram. A task decided over MCP used to
staywaiting_approval. -
docket maintain <id> rebuildno longer deletesmemory/*.md, and refuses a pod member with
exit 1 instead of overwriting its role prompt,TOOLS.mdandHEARTBEAT.mdwith the legacy
flat-agent templates. -
A
verifyCmdthat times out is killed as a whole process group, so a command that
backgrounds work no longer leaves orphaned processes behind after the hop moves on. -
POST /approvals/<token>accepts onlyhttportackaschannel. A Bearer holder used
to be able to record a decision ascli,mcp,telegramor eventimeout, forging another
surface's provenance in the hash-chained audit log and indocket_approvals_total. -
docket list --jsonanddocket info --jsonemitbudgetUsdas a number ornull(they
emitted the stored string, or""), anddocket snapshotemitslastActivity: "never", the
same sentinel/status.jsonuses. -
docket doctor's budget check anddocket cost's high-cost warning can fire. Both compared
recorded spend, whichDocketDriveralways reports as 0.0, so neither ever triggered. They now
read the same recorded-or-estimated figure the dispatch budget gate uses, labelled as an
estimate when it is one. -
A broken policy file now fails closed. An unloadable policy JSON, an uncompilable regex
pattern, or an unknownactionused to make every call on that hook evaluate toallow; each
now makes every call in that file's readable scope (or, if the JSON itself cannot be parsed,
all hooks) resolve to a block naming the file — across the live gate anddocket policies test.docket policies validatenow compiles every regex instead of accepting a pattern it
never checks,docket policies test pre_tool_calltakes--tool <name>so a non-bashtool
is not misclassified against the command allowlist, anddocket doctorreports a broken policy
file as an error. -
docket doctorreports a broken schedule, model-policy entry or overlay role by name instead
of silently skipping it, andservelogs a skipped schedule once per sweep.
docket pod <p> config set schedule "<spec>"validates and writes a schedule (previously
writable only by hand-editing the file), andunsetremoves it. -
docket deleteremoves a pod member's merged branch and its provisioning lock directory. A
mergeddocket/<pod>/<member>branch and stale lock entries used to survive teardown; an
unmerged branch is still kept, with the command to remove it printed. Newly created workspace
and pod directories are now0700. -
A deterministic dispatch refusal now fails the task instead of orphaning it. A refusal
raised inside a claimed task — an unknown pod member, an invalid stored setting, a membership
mismatch — used to leave the taskrunningwith no process behind it and no way to resume; it
now ends that taskfailedwith the refusal as its reason, and--resumepicks it up from its
last persisted hop. A pod's membership is now read from each agent's own recorded metadata
rather than guessed from its id string, which is what could raise that refusal for a hyphenated
custom role name in the first place. -
An approval's trace event is now filed under its pod, not the individual agent id —
matching wheredocket trace <project>anddocket metricsalready look for one.
Removed
fleet.json'ssecurity.isolationEnabledfield andcore.fleet.get_isolation_mode();
security.isolationModeis the only isolation state.- Every compatibility path is gone. docket has no installed base to migrate, so code that only
kept an old name, flag, route or file shape working was deleted.- Command aliases:
show,rm,remove,telegram,key,secret,log,usage,
check,security,export,completionandpolicyare unknown commands. Useinfo,
delete,wire,keys,logs,cost,doctor,gates,snapshot,completionsand
policies. - Removed-command notices:
auth,team,workflow/wf,eval/evals,model,
tier,billing,credits,monitor/mon,memory/mem,smart,ai,mode,
terminal/termand the top-levelreset,repair,fix,cleanupandcleanno longer
print a notice; they are plain unknown commands. - Flags and subcommands: the hidden
--debugflag and hidden_jsoncommand;
docket gates enable/disableandgates ... --force;docket init --gates/--no-gates
andinit --path(use--codebase);docket profile <id> policy(usedefault);
docket models ls(uselist); the trailing count indocket pod <p> add <role> <N>(use
--count/-n);docket maintain --distill-first(distilling first is the default;
--no-distill-firstremains);--jsonin place ofdocket audit's count argument (the
--jsonflag is unchanged);programmeras
a pod role alias forimplementer(programmerstays a role-policy key for
docket models set). - Approval-routing posture: the
approvalRoutingState/approvalRoutingModeflag that
nothing on the live path read, and the "Approval routing" line indocket gates status. The
tool-call gate is always on;docket gatesmanages only isolation (status,isolate,
classes). - Migrations of old files: a
defaults.modelorprovidersblock infleet.json, a
profiles:key indocket-models.json, the old Anthropic model-id aliases (claude-3.xto
4.x), and an exporter'spayload/payloadMaxCharskeys are no longer read or converted. docket doctorchecks: stale model names, theprofiles:key, a stray workspace.env,
leftover global specialist workspaces, metadata backfill, and quarantining a model-written
IDENTITY.md/BOOTSTRAP.mdinto.docket-archive/.doctor --jsondrops thefzf,
approvalRouting,routingMode,modelConfigandmodelRegistrykeys. The doctor footer
now points atdocket maintain [id] checkinstead of the removeddocket repair.- The
gatewayfield indocket snapshot,/status.jsonand the MCPstatustool, which
always readinactive. - fzf: the agent picker is the numbered one; fzf was never invoked and is no longer an
optional Homebrew dependency. SITES_DIRandDOCKET_LOG_DIR:docket initno longer creates~/Sitesor
/tmp/docket; nothing wrote there.docket installin the install script and Homebrew caveats: there is no such command;
first-time setup isdocket init.
- Command aliases:
docket authis gone. Store a key withdocket keys add <NAME>; register an endpoint
withdocket models provider add.docket keys setupwalks the provider catalog instead of a
fixed five-provider list.- docket no longer writes an API key into every workspace's
.envfile. Stored keys are
resolved only where they are read;keys addunder thekeyringbackend either stores through
secret-toolor refuses with an honest message instead of silently doing nothing.
Install
# Homebrew (macOS/Linux)
brew tap yielab/docket-cli https://github.com/yielab/docket
brew install docket-cli
# Or the version-pinned installer, which verifies the tarball's SHA-256 before extracting
curl -fsSL https://raw.githubusercontent.com/yielab/docket/v0.2.0-beta.4/install.sh \
| DOCKET_VERSION=0.2.0-beta.4 bashWorkspace isolation is opt-in: docket gates isolate on needs bubblewrap (Linux) or a running
Docker. See Workspace isolation.
Verify
Every asset is listed in SHA256SUMS, and the wheel, the sdist, the installer tarball, SHA256SUMS
and the SPDX SBOM carry a GitHub build-provenance attestation:
sha256sum --check SHA256SUMS
gh attestation verify docket-0.2.0b4-py3-none-any.whl -R yielab/docketdocket is beta software. Expect breaking changes between beta releases and verify consequential
outcomes yourself. Cost figures are token-based estimates, not billed spend.
Full changelog: v0.2.0-beta.3...v0.2.0-beta.4