docket architecture
docket — agent teams as configuration. Your rules, in YAML.
The complete technical guide to how docket runs a repository's team of agents: roles, dispatch, memory, security and cost.
[!WARNING] Beta / early-stage software. The architecture below is implemented and automated-test-backed, but has not been QA-hardened in production. "Validated" in the Implementation Status section means covered by the automated suite, not field-proven — verify behavior against your own install. All cost figures are accounting estimates, not provider bills (see the README's cost limits).
Table of Contents
- Overview
- System Architecture
- Core Principles
- Performance Results
- Agent Roles
- Dispatch Internals
- Memory Management
- Security Model
- Cost Optimization
- Implementation Status
- Embedding docket-runtime
Overview
docket's design for a team of autonomous agents aims at: - Lower token usage through per-pod context isolation - Clean role separation — Lead orchestrates, Implementer codes, Reviewer/Tester gate - Layered, convention-based security through a read-only reviewer veto + checklist - Objective validation through behavior-only testing
The Problem (Before docket)
Engineer: "Fix the login bug"
↓
One shared context (or a shared agent pool) carries every
project's history at once:
→ Reads 100K+ tokens of mixed-project history
→ Implements fix, reviews its own work
↓
No isolation → projects contaminate each other's context
Total: ~220K tokens in one bloated window
The Solution (After docket)
Engineer: "Fix the login bug" (to the <project> pod's Lead)
↓
Lead: Owns this pod's context/memory + human comms
→ Reads this pod's workspace contract (WORKFLOW_AUTO.md + MEMORY.md + HEARTBEAT.md)
→ Decomposes the work, dispatches to the Implementer
→ NEVER edits code
↓
Implementer: Runs INSIDE the project workspace
→ Reads the project files it needs (full read/write)
→ Implements fix
↓
Reviewer (optional): Read-only veto on the diff
→ Runs 6-point security checklist
→ Approves
↓
Tester (optional): Runs reproduction steps (behaviour only)
→ PASS
↓
Each project's work stays inside its own pod + workspace, so
one project's context never bleeds into another's.
System Architecture
This section is the code-level companion to Core Principles below: those describe what a pod does; this describes how docket's own codebase is put together to make that real, safe to extend, and reversible if the underlying runtime ever needed to change.
Three layers, one direction of dependency
src/docket/ is organized into three layers, and imports only ever point inward:
cli/ -> core/ -> edges/
cli/(Typer + Rich) — argument parsing, the interactive picker, and every line of Rich-rendered output. This is the only layer allowed to talk to the user; a command aborts by raisingtyper.Exitand renders whatever typed resultcore//edges/handed back (aTaskResult, aVerifyResult, aCompactionResult) throughui.py'sinfo/success/warn/errorhelpers.core/(Pydantic models + pure services) — the domain: agent data models, role→model policy, dispatch's state machine, security/approval/audit/trace/policy logic.core/never importscli/, never importsui.py, and never prints — every function returns a typed result forcli/to render.edges/(the only side-effecting layer) —edges/store.pyis the single chokepoint for every docket-owned JSON read/write (atomic, filelocked, 0600 permissions,.bakrotation);edges/adapters/system.pywraps every shell-out todocker/bwrap/git, degrading gracefully when a binary is missing.
This is not a style preference — it is enforced by what each layer is allowed to import, and a couple of the newest modules in the tree exist specifically to keep the boundary from eroding (see the RuntimeDriver port, below).
No external daemon — docket owns the loop
Through Phase 18, Docket was a control plane wrapped around a separate agent daemon. An
Anti-Corruption Layer owned that daemon's state shape, every agent turn ran in its process, and
config changes restarted its gateway. Phase 19 (decision D-19) removed that architecture
outright, not incrementally. There is no external agent binary, shared daemon config,
auth-profile store, ACL module, or gateway service to restart. docket runs the agent turn itself
(core/agent_loop.py) and talks through one non-streaming OpenAI-compatible chat-completions
adapter; built-in gateways or explicitly registered compatible endpoints supply the base URL
(edges/adapters/llm.py, stdlib urllib, no vendor SDK).
This was a scope ruling, not a migration: no compatibility layer, no migration steps — a
pre-Phase-19 install's files at retired daemon-relative paths are simply not read again; the first
docket init creates a docket-native home from scratch under ~/.docket/ (DOCKET_HOME).
The RuntimeDriver port (decision D-14)
Before the daemon was removed, a mid-2026 audit found that the execution slice of docket's
coupling to it — parsing an agent turn's result, reading a session's on-disk JSONL, aggregating
token/cost usage — had started leaking around the ACL rather than being contained by it.
core/runtime_driver.py is the fix that outlived the daemon it was first built for: a single
typed Protocol — RuntimeDriver — that core/ and cli/ program against instead of a concrete
driver's on-disk knowledge. It has four members plus one ingestion helper:
run_turn— one costed agent turn: the hot pathcore/dispatch.py's pipeline calls for every hop, and, per decision D-18, docket's own self-originated LLM calls (memory distillation, see Memory Management)list_sessions/usage— durable-session enumeration and token/cost aggregationcapabilities— what this driver instance can actually promise (for example, whether it reports a real USD cost at all), so a caller never hardcodes an assumption about the one shipped driver's quirksread_new_turns— decodes session records past a caller-held offset into docket's own neutralSessionTurn/SessionSlicevocabulary, feedingcore/trace.py's ingestion sweep
edges/adapters/docket_runtime.py's DocketDriver — docket's own turn loop, running directly
against a configured model endpoint — is the one shipped implementation since Phase 19
P19-7b replaced the daemon-facing driver this port originally shipped with; a FakeDriver test
double (tests/fakes.py) is the one test double. This is a deliberately narrow move.
docket's architectural principles carry a standing ban on an AbstractBackend/plugin framework,
and decision D-14 revises that ban rather than repealing it: the port is containment of coupling
that already existed, not speculative generality. There is one shipped driver. A second real
driver still needs a real trigger (a paying user who needs a different runtime), not the existence
of the port itself; adding driver discovery, entry points, or a config-selectable backend ahead of
that would be scope creep, not follow-through. One consequence worth stating plainly: DocketDriver
never populates a real USD cost — usage().totals.cost_usd is always 0.0 — see
Cost Optimization and the README's cost limits.
Harness mode: one agent, one turn, for an external caller
docket harness run (decision D-35) is a second, narrower entry point beside pod dispatch: it runs one agent,
one turn loop, to completion, in a workspace and DOCKET_HOME the caller supplies, then exits.
It is not a pod and not a team — no Lead, no Implementer/Reviewer/Tester rotation — and it
provisions nothing: the caller has already prepared an isolated checkout at a known revision and
hands over a DOCKET_HOME of its own. It reuses DocketDriver unchanged — the same
RuntimeDriver port above, gaining its second caller ever —
and the same core/tools.py chokepoint, policy hooks, audit and trace: no second execution path.
stdout carries the wire contract only: newline-delimited HarnessEvent lines (docket's existing
core/trace.py vocabulary, inside a versioned envelope) followed by exactly one HarnessResult
line; every log goes to stderr. By default approvals are non-interactive
(ToolContext.approval_mode = "refuse", carried to the driver as the DOCKET_APPROVAL_MODE key
of run_turn's env dict -- an internal coordinate, not a variable an operator can export): a
verdict that would otherwise block the calling thread ends the run immediately with status:
blocked and a denial_kind of approval_unavailable, naming the tool, call id, policy id and
reason. Under --contract 1.1 --answers stdin the run waits instead, and the caller answers (see
below). Exit codes are the one
place this CLI departs from its flat 0/1 convention (specs/api/cli-interface.spec.md): 0 the
result is ok; 1 it ended failed, blocked, or cancelled; 2 refused before any turn
began — for example a missing DOCKET_LLM_BASE_URL, a DOCKET_HOME that resolves to the
operator's own default home, or DOCKET_NO_TRACE=1 (harness mode refuses to run unobserved rather
than run silently).
The contract is versioned (every line carries a v field) and published. --contract 1.0 is the
default and is byte-identical to the original wire (v 1.0.0). Its JSON
Schema is generated from the Pydantic models in core/harness.py at
docs/contracts/harness-v1/schema.json and pinned
byte-for-byte by a regenerate-and-diff test, with example transcripts at
tests/fixtures/harness-contract/v1/{ok,blocked,cancelled,refused}.ndjson. Full design reasoning
is in ADR 0001; the wire-level requirements are in
specs/api/harness-mode.spec.md.
Contract 1.1 (--contract 1.1, v 1.1.0, ADR 0017, Phase 35) is opt-in and is the contract an
external supervisor integrates against. Its schema is
docs/contracts/harness-v1.1/schema.json, and every line of
its fixtures validates against that committed file. It adds, all under the one run command:
- Process lifecycle. A
bashcall emitsprocess_startedandprocess_exitedevents (pgid, and eitherexitCodeorsignal), so a caller can see a live process group and signal it. - Answers on stdin.
--answers stdinwith--answer-timeout Smakes approvals wait. The caller writes one answer line per decision to stdin (acceptordecline, orcancel), and aquestionIdline answers a recipe run's question. Stdout stays NDJSON. - Written files. The result's
fileslists each path the run wrote or edited, plus, in a git workspace, whatgit statusreports. Paths are relative to the workspace. - Token file and limits.
--token-file PATHwrites the run token (mode 0600) before the first model request.--max-tokens Nbounds the turn's measured tokens, and--policy FILE(repeatable) adds validated policies for the run. - Recipe runs.
--recipe NAME|DIR, with--verify CMDand--taskor--task-file, runs one recipe in place for one task, and the result'staskblock lists its hops. It is mutually exclusive with--role, and refuses--max-tokensand--agent-id.requireVerifyis set, so an Implementer hop with no verify command fails. A--recipename is one ofdocket recipes list(for exampletdd); a pod blueprint name such assoftwareis not a recipe and is refused. - Approvals on the result.
approvalslists each approval the run requested and its outcome (accepted,declined,timed_outorunanswered). A denied approval still ends the run by its turn's own outcome, so a caller readsapprovals, not onlystatus, to tell them apart. - Consultation and approval packs.
question_askedevents carry an operator-v1.1 question (kind,options, optionalrecommendation); the caller answers with aquestionIdline carrying{"optionId": ...}.approval_requestedcarries arationaleand threeoptions(approve_once,approve_task,deny); acontent.reasonon the answer is screened and audited. A blocked consultation under the defaultrefusemode puts the question on the result. - Evidence. A recipe result's
task.evidenceis the evidence-v1 document for the task, identical todocket pod <p> evidence <task> --json(schema).
This is unrelated to DEVELOPMENT-HARNESS.md, which documents the contributor-side context harness — skill routing, hooks, token-efficient validation — for people and agents working on docket's own codebase, not this execution mode.
Configuration — one owner, one writer
Every agent's state lives in two docket-owned files, split by who reads them and written only
by docket, through edges/store.py:
.docket-meta.json, in each workspace — per-agent facts: kind, role, name, codebase, stack, model,modelSource, description,sessionKey,projectKey, budget, persona, and platform-era additions likeblueprint/workspaceKind/workDirand a pod's allocatedportRangeStart/portRangeCount/scratchDir~/.docket/fleet.json(core/fleet.py) — agent registration, channel bindings, gate/ isolation flags. Provider endpoints live indocket-providers.json(core/provider.py, the catalog ofkind: providerdocuments) since Phase 29
The org-wide default model lives in ~/.docket/docket-models.json's default field, not
fleet.json, so docket-models.json is the single source of record.
This is a narrower split than it looks: fleet.json deliberately does not duplicate model/
sessionKey/projectKey — those stay .docket-meta.json's job alone. Before Phase 19, the
second store was owned by an external daemon that could mutate it independently of Docket (or be
hand-edited, or touched by its own CLI) — which is exactly what
core/sync.py's drift check used to exist to catch. With both files now written only by docket
through one code path, "a different program touched this file" is no longer possible, and that
drift-detection machinery (the ACL, core/sync.py, docket doctor's session-key-sync check) is
retired along with the daemon rather than kept around for a problem that no longer exists.
Durable state docket owns
A model's context window is lost on reset, so docket keeps a handful of small, docket-owned
stores, all under ~/.docket/:
- Session history (
core/session.py,$SESSIONS_DIR, default~/.docket/sessions/) — durable per-session message history, loaded bycore/agent_loop.pybefore each turn and appended after it. Once a session outgrows the role's budget it is compacted on the live turn path: older messages are summarised, and an assistant tool call is never separated from its tool results. HEARTBEAT.md's dispatch ledger — every pod Lead'sHEARTBEAT.mdcarries a delimited, docket-owned region inside its## Active Taskslist thatcore/dispatch.pyupserts mechanically at claim, at every persisted hop, and at finalize — not prose an agent is trusted to keep current by convention.docket doctorflags a task the queue marksrunningwith no matching ledger entry, or a ledger entry for a task that no longer is, and--fixre-syncs the ledger to exactly what the queue says. See Dispatch Internals.- The conversation registry (
core/conversations.py,docket-conversations.json) — one record per channel thread docket is tracking (agent, peer, topic, status, a resume pointer), seeded ondocket wireand cleaned up on delete. Dispatch andservekeeplast_message/task_refcurrent automatically as a task moves, rather than that being a manualdocket conversations setchore. - The audit log (
core/audit.py,~/.docket/audit.log, 0600) — one JSON line per mutating operation; secret values are never logged. Every line carries a monotonicseqand aprev_hash(the SHA-256 of the previous line's canonical JSON), sodocket audit verifycan walk the chain and report the first broken link; a missing file is an honest chain start, not tampering, and a line withoutseq/prev_hashis reported as a break. Rotation does not restart the chain: the first entry after a size-triggered rotation names the generation it continues, checked against the single backup (audit.log.1), and an unsubstantiated claim is reported as a break. That makes erasure evident, not impossible — deletingaudit.logandaudit.log.1together still looks like a fresh install, and only one rotation back is verifiable. There is no environment kill switch — recording is best-effort (a write failure never raises) but cannot be silently disabled. - Traces (
core/trace.py,$TRACES_DIR/<project>/<session_id>.jsonl) — one append-only file per session, one line per observable event (hop starts, tool calls, gate outcomes, retries, guardrail trips, budget warnings).docket trace/docket metricsread this store;DOCKET_NO_TRACE=1disables writes. The same records, as they are written, are also the only input to trace export (core/telemetry.py): an enabledkind: exporterreceives them as OpenTelemetry spans, filtered by its privacy level, so a destination such as Langfuse shows a projection of this store, never a second source of truth. Conversation content (prompts, replies, tool output) enters this store only while some enabled exporter grants it. See Configuration §3.14.
These stores do not all go through edges/store.py's locked read-modify-write path — audit and
trace are exempt by design (line-independent JSONL appends, not a whole-document
read-modify-write), while session history, the conversation registry and the dispatch queue
backing the ledger do use store.py.
Core Principles
1. Per-Pod Context Isolation
Each project's context stays inside its own pod.
- Every pod has its own workspace and per-pod session key
- The Lead reads this pod's workspace contract (
WORKFLOW_AUTO.md,MEMORY.md,HEARTBEAT.md), not a shared cross-project history - The Implementer runs inside the project workspace, reading only the files it touches
- The Reviewer reads the diff only, not the entire file
- The Tester reads reproduction steps only, not code
Result: no project's context bleeds into another's, so per-agent token counts stay scoped to one project
2. Lean Pods by Default
Don't add workers you don't need.
docket init <project> provisions a lean Lead + Implementer pod:
Pod size Members When
─────────────────────────────────────────────────────
Lean (default) Lead + Implementer most projects
Full (--pod full) + Reviewer + Tester higher-stakes code
Custom (--with ...) Lead + Implementer + any pick the gates you want
Result: each project runs the smallest pod that does the job
3. Linear Pipeline (and it really runs)
Each role has ONE job. No overlapping work.
Lead → Implementer → Reviewer → Tester
(implement) (veto) (validate)
NOT:
Implementer ──┐
Reviewer ───┼→ All work in parallel
Tester ───┘ (wasteful, redundant)
This pipeline is no longer just a convention in the templates — docket actually executes it, one real agent turn per hop. Only the roles a pod has take part (a lean pod runs two hops: Lead → Implementer):
docket pod <project> delegate "Fix the null-token login crash" # queue a task
docket pod <project> queue # see the queue + per-task status/cost
docket pod <project> dispatch # run the pipeline once, now
docket serve --dispatch # background: drive every pod's queue
Three guarantees hold on every hop:
- Budget-gated. Before each hop docket checks the pod's token-based dollar estimate against
the Lead's budget cap (
docket profile <project>-lead --budget N). The first hop that would exceed it pauses the pod's Lead (docket profile <id> --resumeclears it) and leaves the task blocked, not run — every further claim against that pod is refused outright until it's resumed. - Traced. Each hop emits a trace event (
docket trace) on a per-task sessionagent:<project>:<task_id>— every run is auditable, no manual Telegram relay. - Pod-local. Dispatch only ever targets the project's own pod members. There is no cross-pod dispatch path — one pod can never run another pod's agents.
Each hop is a real, costed LLM turn, which is why dispatch is explicit (docket pod …
dispatch) or opt-in (docket serve --dispatch) — never silent. Plain docket serve is a
read-only monitor and does not dispatch. Stopping serve takes two signals when work is in flight:
the first (Ctrl-C or SIGTERM) stops new work and waits for the pod sweeps already running; a second
requests cancellation of each sweep run, so its task ends cancelled, and exits 130 or 143.
This is the outline; the actual state machine also retries a hop that fails on a transient hiccup
(a timeout or the model endpoint erroring — TurnResult.failure_kind's timeout/daemon_error,
a name that predates Phase 19 and now just means "the turn itself didn't complete cleanly," not a
live external process), can stop a task at a human approval gate, and generalizes what "Reviewer"
and "Tester" mean past those two hardcoded roles. See Dispatch Internals
for the full mechanics.
Result: No wasted parallel work — and the hand-off between roles actually executes.
4. Behavior-Only Validation
Tester validates behavior, not code.
Tester does NOT read: - The Implementer's implementation - The Reviewer's analysis - How the fix was done
Tester ONLY reads: - Reproduction steps - Expected behavior - Acceptance criteria
Why: Prevents bias. Tester can't give false positive just because "code looks good."
Performance Results
Token Usage
The lever docket actually controls is per-pod context isolation (see the
Before/After diagram above) — token reduction is what isolation
controls and what you can measure, not a fixed percentage. Read your measured token counts with
docket cost (it records no dollar spend; the budget gate uses a labelled token-based estimate,
and docket models shows comparative pricing); see
Cost Optimization below for the model-selection half of the story.
Response Time
Isolated pods process less context per turn, so the Lead can answer status/memory queries
quickly (it reads its own workspace contract — MEMORY.md/HEARTBEAT.md — rather than a full
cross-project history), while code changes still take as long as the Implementer needs to do the
work. Measure actuals for your own workload rather than relying on fixed figures.
Agent Roles
Concepts live in Agent Teams (Pods) — the canonical reference for the pod model (scope vs role, why pods exist, how to compose one). This document is the technical deep-dive: routing, context isolation, dispatch internals, and per-role wiring.
There are two kinds of agent. Pod roles are project-scoped and created per project by
docket init <project> (managed with docket pod <project>). Org specialists are shared
across the whole fleet and created lazily by the first docket init.
Pod Roles
Each project is an isolated pod with its own workspace and per-pod session key. A pod is a
lean Lead + Implementer by default; add a Reviewer and Tester with --pod full or
--with reviewer,tester.
Lead
Role: Per-pod orchestrator and human interface
Capabilities:
- Owns this pod's context, memory, and human (Telegram) comms
- Reads this pod's workspace contract — WORKFLOW_AUTO.md, MEMORY.md, HEARTBEAT.md — not
a full cross-project history
- Decomposes work and dispatches to the pod's workers — docket pod <project> dispatch
(or docket serve --dispatch) really runs the next hop, one costed agent turn at a time
- Holds the per-pod budget cap that gates every dispatch hop
(docket profile <project>-lead --budget N)
Tools: read, glob, grep, fetch, skill, consult — write/edit/bash are
structurally absent from its tool registry (core/archetypes.py's lead archetype declares denied_tools=("write",
"edit", "bash"), applied via ToolRegistry.without() every turn). This is a genuine tool-registry
removal, not an instruction the Lead is merely told to follow: a call to write/edit/bash
comes back as a tool-not-found denial before it ever reaches the gate. Dispatch to pod workers
happens structurally (docket's own dispatch pipeline invokes the next hop), not through a tool
call the Lead makes.
Cannot: - Edit code (ever — structurally, not just by instruction) - Run commands - Commit - Make architecture decisions alone
Model: cheap class (role policy) (coordination and dispatch, not reasoning-dense code work)
Implementer
Role: Code implementation specialist
Capabilities:
- Runs inside the project workspace, with full read/write on the project
- Reads the project files it needs directly (it is in the workspace, not handed a tiny brief)
- Implements the requested change
- Its hop's reply is captured directly by dispatch as a typed HandoffArtifact — no completion
file to write or poll for (see Dispatch Internals)
Tools: the full built-in set — read, write, edit, glob, grep, bash, fetch,
skill, consult. The
implementer archetype declares no denied_tools: "full-repo" means no built-in tool is off
limits. bash still passes through the same argument-aware high-risk classifier and approval
gate as every other tool call (see Security Model) — an unrestricted tool
registry is not the same thing as an unrestricted gate.
Cannot (by convention, not tool removal): - Review security (reviewer's job) - Run validation tests (tester's job) - Commit or push
Model: strong class (role policy) (code writing is reasoning-dense)
Reviewer (optional)
Role: Security and quality gatekeeper
Capabilities: - Read-only veto on the diff (bad code doesn't proceed) - 6-point mandatory security checklist - Reads the diff only, not the entire file - Verifies root cause addressed
Checklist: 1. ✓ No prompt injection 2. ✓ No hardcoded secrets 3. ✓ No SQL injection / XSS 4. ✓ Auth checks present 5. ✓ No dangerous operations 6. ✓ Test coverage
Tools: read, glob, grep, fetch, skill, consult — write/edit/bash are
structurally absent (denied_tools=("write", "edit", "bash")), so "read-only" is a genuine registry restriction, not
a SOUL.md-only instruction: a Reviewer that tries to call edit gets a tool-not-found denial.
Cannot (structurally): - Fix code (only reviews) - Execute tests - Commit
Model: cheap class (role policy) (structural review, not reasoning-dense)
Tester (optional)
Role: Behavior-only validation specialist
Capabilities: - Executes reproduction steps - Runs test suites - Binary verdict: PASS or FAIL - Does NOT read code (stays objective)
Tools: read, glob, grep, bash, fetch, skill, consult — write/edit are
structurally absent
(denied_tools=("write", "edit")); bash stays so the Tester can actually run the suite it
reports PASS/FAIL on. Staying objective by not reading the implementation is a convention
the Tester is instructed to follow (its prompt points it at reproduction steps, not the diff) —
the read tool itself is not removed, since the Tester needs it to read expected-behavior/
acceptance-criteria files.
Cannot (by convention, except write/edit which are structurally absent): - Review security - Fix failing tests - Commit
Model: cheap class (role policy) (validation is mechanical)
MCP tools. Tools from configured external MCP servers (docket mcp servers) reach a live turn
through the same chokepoint, namespaced mcp__<server>__<tool>. Denials apply by capability, not
by name. Every MCP server is write-capable unless the operator declares it --kind read (an
operator assertion, not something docket verifies). A role that denies write (Lead, Reviewer,
Tester) gets no tools from a server left at the default and all the tools of a --kind read
server; the Implementer gets both.
Org Specialists
Shared across all projects, created lazily by the first docket init. The manager is a cross-cutting
coordinator — not a router with a classifier, and it does not compress prompts into briefs.
It has no task queue of its own: per-pod dispatch
(docket pod <project> delegate/queue/dispatch) is the only queue, and the manager role is
transitional, being superseded by per-pod Leads.
Manager
Role: Cross-cutting coordination (transitional)
Capabilities: - Coordinates work that spans more than one pod (advisory/instruction-level; no task-queue tooling of its own — see Portfolio Manager below for the fleet-visibility surface that replaced it) - Reads memory/snapshots, not full history
Tools: the full built-in set is technically available — org specialists have no role
archetype in core/archetypes.py, so unlike a pod's Lead/Reviewer/Tester there is no
denied_tools list narrowing their registry. Its constraints are prompt-level only
(SOUL.md's "never edit code, run builds, or commit"), backstopped by the same tool-call gate and
high-risk classifier every call passes through (see Security Model) — not a
structural tool removal the way a pod role's is.
Cannot (by instruction, not tool removal): - Edit code - Run commands - Commit
Model: cheap class (role policy) (cross-cutting coordination, not code reasoning)
Knowledge
Role: Pattern extraction and memory distillation
Capabilities: - Extracts reusable patterns from completed tasks - Updates MEMORY.md with decisions - Maintains patterns/ library - Cross-project memory search
Tools: the full built-in set (read, write, edit, glob, grep, bash, fetch,
skill, consult) — like
every org specialist, it has no role archetype narrowing its registry; scope is prompt-level
(SOUL.md), not tool-enforced. There is no separate semantic memory-search tool — docket's own
turn loop has none of its own — so cross-project pattern extraction works by reading and
grep-ing memory files directly, the same tools available to any agent.
Cannot (by instruction, not tool removal): - Modify source code - Run tests - Commit
Model: cheap class (role policy) (distillation is mechanical)
Cost Target: <5K tokens/extraction
Security
Role: Deep security audits and HITL gatekeeper
Capabilities: - Deep threat modeling - HITL gate enforcement - Compliance audits (GDPR, HIPAA) - Proactive monitoring
Tools: the full built-in set (read, write, edit, glob, grep, bash, fetch,
skill, consult) — no
role archetype narrows it; the constraints below are prompt-level (SOUL.md), backstopped by the
same tool-call gate and high-risk classifier every agent's calls pass through.
Cannot (by instruction, not tool removal): - Modify code - Execute suspicious code - Approve own escalations - Commit
Model: strong class (role policy) (security reasoning required)
Cost Target: <10K tokens/audit
Portfolio Manager (optional)
Role: Cross-pod planning and visibility surface (opt-in)
Provisioned only by docket init --portfolio, which adds one portfolio-manager
(scope: org). The flag is read only by the first docket init, the one that builds the shared
foundation. It is a fleet-wide advisory layer, never a pod member. No dispatch path runs a turn
for an org specialist, so today the Portfolio Manager is a provisioned workspace with no
conversational entry point: Telegram accepts only five verbs and /delegate//answer work only
for a pod Lead binding.
Capabilities: - Sees fleet metadata — which pods exist, their queues, budgets, and health - Recommends where to focus, rebalance, or pause, in words for a human
Tools: the full built-in set is technically available (no role archetype narrows it), but its
prompt scopes it to reading fleet metadata (docket list/pod/cost/doctor surface) and
reporting in words — never project source.
Cannot (by instruction, not tool removal): - Read or edit project code (it sees metadata, not source) - Dispatch into pods (each pod's own Lead owns execution) - Be a pod member, or run another pod's agents - Commit
Model: cheap class (role policy) (planning/visibility, not reasoning-dense)
Memory Management
Problem: Large Shared Context
Before docket:
A shared agent reads:
- Full cross-project conversation history: 100K tokens
- All memory logs: 50K tokens
────────────────────────────────────
Total: 150K+ tokens per turn, growing across projects
Solution: Isolated pods + the workspace contract
After docket:
The pod's Lead reads:
- its composed prompt: SOUL.md, its startup contract, and bounded MEMORY.md and HEARTBEAT.md
The Implementer reads:
- only the workspace files it touches
────────────────────────────────────
Context stays scoped to one project's pod
There is no generated SNAPSHOT.md, and docket context has only show and project (any
other action exits 2). There is no separate semantic memory index —
docket's own turn loop has no memory_search tool of its own; an agent searches its memory files
the same way it reads any other file, with read/grep. What actually scopes a pod's context is
the workspace startup contract docket provisions on docket add/docket init and
docket doctor re-seeds if a workspace is missing one or has a stale version:
WORKFLOW_AUTO.md— the startup protocol. docket's own turn loop forces every agent to re-read this file after each context reset (its system-prompt composition re-injects it every turn), so docket anchors the codebase path and the resume/durability rules here — the one place guaranteed to survive compaction even whenSOUL.md/MEMORY.mdfall out of context.MEMORY.md— long-term curated project facts (what the project is, architecture, current state) — written by the agent, seeded with a stub on first run.HEARTBEAT.md— the durable in-flight task ledger. An agent is instructed to write multi-step work here before starting it; a pod dispatch hop additionally keeps its own delimited region in sync mechanically (see Dispatch Internals), so the ledger reflects real queue state, not only an agent's compliance.
Plus the dated memory/YYYY-MM-DD.md logs, read on demand rather than all at once. A fresh
HEARTBEAT.md seeds like this:
# HEARTBEAT.md — mywebsite-lead
_Your durable task ledger. It survives context resets; your working memory does not._
_The moment you accept multi-step work, record it here **before** you start. Read it first
every session — unchecked items mean you were interrupted, so resume them instead of greeting
as if idle._
## Active Tasks
_none yet_
## Pending Decisions
_none_
## Notes
_none_
docket context <id> show and docket context <id> project are read-only renderers over
exactly these files — recent memory-log lines, active tasks parsed from HEARTBEAT.md,
MEMORY.md's section headers, and last-activity/log-count stats. They display the contract; they
don't generate a separate summary artifact.
Memory Commands
# Read-only dashboard: recent memory logs, active tasks, session-size/last-active stats
docket context <id> show
# Project quick reference: codebase/stack/model, active tasks, MEMORY.md sections
docket context <id> project
# Summarize pending daily logs into MEMORY.md (see Memory Distillation below)
docket maintain <id> distill
# Re-seed a missing or stale WORKFLOW_AUTO.md / MEMORY.md / HEARTBEAT.md
docket doctor --fix
Memory Distillation
docket maintain <id> distill summarizes an agent's pending daily logs into MEMORY.md and
archives the originals into memory/.distilled/<day>/ rather than deleting anything outright.
This is docket's first self-originated LLM call (decision D-18): docket runs one turn as the
agent whose memory is being distilled to write the summary, through the same
RuntimeDriver.run_turn every dispatch hop uses — no new SDK dependency, no direct provider call.
docket maintain <id> clean and reset run distillation first by default before their own
memory-clearing step (--no-distill-first opts out and deletes without distilling) — so
routine maintenance never quietly throws away undistilled history. The contract fails closed:
a driver failure or an empty reply leaves the daily logs exactly where they were, and the
subsequent delete is aborted rather than proceeding over lost content. "Nothing to distill" (no
pending daily logs) is a different, harmless case — there's nothing undistilled to lose, so the
delete proceeds normally.
Security Model
Three automatic layers — instruction-level SOUL.md constraints (never commit/push/delete without
instruction), the Reviewer's 6-point checklist (prompt-injection patterns, hardcoded secrets,
SQL injection/XSS, auth checks, dangerous operations, test coverage) as a read-only veto, and a
final human git diff review. The enforced tool-call gate (policy engine plus argument-aware
high-risk command classifier) is always active and cannot be turned off, and an ask verdict can
be answered from any of four approval channels (CLI, HTTP, MCP, Telegram). bwrap/Docker workspace
isolation is opt-in (docket gates isolate on, which needs bubblewrap or Docker on the host;
docket gates network none then cuts the jail's network). Since Phase 34 (D-50), an unattended pod's
in-turn ask parks the task (waiting_approval) rather than blocking the turn, and a
separate, opt-in notification layer (docket channels, off by default except console) is what
tells a human one is waiting — the approval mechanism and its four channels are unchanged. Full
detail, including the exact reviewer checklist, gate/approval-channel mechanics and the operator
loop, lives in
SECURITY-SIMPLE.md — this section intentionally isn't a second copy.
A declarative policy engine (docket policies) adds a fourth layer on the dispatch path itself —
pre_input/pre_output hooks that can redact, warn, block, or route a task to human approval.
See The policy engine on the dispatch path for the
mechanics. Since Phase 19, this is no longer the whole in-turn story either: pre_tool_call —
the third policy hook, evaluated inside core/tools.py's dispatch_tool chokepoint alongside the
high-risk command classifier — is now live on every tool call docket's own turn loop makes,
closing the gap where docket's policy templates existed but nothing inside a running turn ever
evaluated them.
What leaves the machine is governed separately, and closed by default: every trace exporter
ships disabled and at privacy: minimal (structure only), sharing more is a confirmed command
recorded in the audit log, and the span projection is an allowlist, so an attribute nobody has
classified never leaves. SECURITY-SIMPLE.md's Layer 6 has the detail.
Cost Optimization
Model Selection
The role→model policy assigns each role to either the cheap class (high-volume / low reasoning-density) or the strong class (reasoning-dense):
| Class | Roles | Why |
|---|---|---|
| Cheap | Lead, Manager, Reviewer, Tester, Knowledge, Portfolio Manager | High-volume or mechanical work |
| Strong | Implementer, Security, repo agents | Code writing / security reasoning |
Change the policy for a role with docket models set <role> <provider/model>, or switch all
roles at once with a provider preset (docket models preset openai). Pins set via
docket profile <id> <model> are never touched by policy changes.
Result: routine orchestration and review runs on the cheap model class with
project-scoped context — fewer tokens at a lower per-token price. (docket records measured
tokens, not dollar spend; dollar figures are estimates — docket models for comparative pricing,
the budget gate for the per-pod estimate.)
Context Isolation Rules
Each pod is sealed:
❌ No agent reads another project's history or memory
✅ The Lead reads this pod's workspace contract; the Implementer reads its own workspace
Per-pod session keys keep context from accumulating across projects.
Why a status query stays cheap
Status / memory query:
The Lead reads this pod's MEMORY.md / HEARTBEAT.md
instead of a full cross-project history — no worker is spawned.
Implementation Status
Implemented Components ✅ (automated-test-backed, not yet field-hardened)
Lead: ✓ Per-pod orchestrator (owns context/memory, never edits code)
Implementer: ✓ Runs in the project workspace (full read/write)
Reviewer: ✓ Read-only veto (6-point checklist)
Tester: ✓ Behavior-only validation
Knowledge: ✓ Org specialist (tools + memory management)
Security: ✓ Org specialist (HITL gates + threat modeling)
Manager: ✓ Org specialist (cross-cutting coordination, transitional)
Features Implemented ✅
- [x] Memory management system (
docket context show/project) - [x] Pod delegation + dispatch (
docket pod <project> delegate/queue/dispatch) - [x] Workspace startup contract generation (
WORKFLOW_AUTO.md/MEMORY.md/HEARTBEAT.md) +docket doctorre-seeding of a missing or stale one - [x] Per-pod context isolation (workspace + session key)
- [x] Security checklist (6 points)
- [x] Behavior-only validation
- [x] HITL gate protocols
- [x] Cost tracking & optimization
- [x] Declarative role archetypes (
docket roles) and pod blueprints (docket init --blueprint) - [x] Docket-native pipeline format + executor (
docket pipeline validate/plan/run), generalized mechanical/verdict/approval gates and bounded rework - [x] Typed handoff artifacts between hops + a per-role token-budgeted context compiler
- [x] Run registry and cancellation (
docket runs) - [x] Declarative policy engine on the live dispatch path (
docket policies) - [x] RuntimeDriver port — one typed protocol, one shipped driver (
core/runtime_driver.py,edges/adapters/docket_runtime.py'sDocketDriver) - [x] docket as an MCP server (
docket mcp serve, optional[mcp]extra) - [x] Memory distillation (
docket maintain distill;clean/resetdistill first by default) - [x] Mechanically-maintained HEARTBEAT.md task ledger + conversation registry auto-population
- [x] Hash-chained, tamper-evident audit log (
docket audit verify) - [x] Harness mode (
docket harness run/docket harness status) — a versioned, non-interactive single-agent entry point for an external caller-owned workspace andDOCKET_HOME(see Harness mode above) - [x] The configuration contract:
docket config explainnames each effective value and the scope it came from (built-in, global, pod), anddocket doctornames every entry a loader skipped; per-podroles.jsonandpolicies/resolve above the global layer (--pod) - [x] Configuration format v1: every YAML document declares
kind:,docket validatechecks it, short forms normalize to the canonical one, pipelines route withon:and skip withwhen - [x] The provider catalog: model endpoints are
kind: providerdocuments, fourteen built in (docket models provider add|list|show|remove|export) - [x] The team in the repository:
.docket/is the pod's configuration of record (docket pod <p> apply|export,docket initapplies it), with drift reported byconfig explain - [x] Recipes, project instructions and skills: eighteen shipped recipes (
docket recipes), the codebase'sAGENTS.mdcomposed by default,skills/<name>/SKILL.mdread on demand - [x] Trace export:
kind: exporterdocuments over a zero-dependency OTLP/HTTP projection (docket exporters), five destinations built in, all off - [x] Export privacy levels (
minimal/actions/conversation/full, or an exactshare:list), shown before sharing (docket exporters show|preview) and widened only by a confirmed, audited command (docket exporters privacy) - [x] The operator loop: an unattended
askparks (waiting_approval) instead of blocking a sweep, a typed Lead intake brief with a deterministic resource pre-check, aninputpipeline step for a question rather than a permission (waiting_input), one derived inbox (docket inbox) every surface renders from,kind: channelnotifications delivered as CloudEvents (docket channels,docket notify, seven dialects, onlyconsoleon by default, and it sends nothing, sodocket doctorwarns until a delivering one is on), and answer surfaces (docket chat,docket pod <p> answer, HTTP, MCP) that all resolve through oneanswer_taskfunction
Documentation ✅
- [x] Quick Start Guide
- [x] Agent Teams (Pods) guide
- [x] Configuration guide (every file, what reads it, and trace export)
- [x] Workflow Guide
- [x] Recipe library (generated from the shipped recipes)
- [x] Models, gateways and harnesses
- [x] Security Model (Simple)
- [x] docket architecture (this doc)
- [x] Commands Reference
- [x] Troubleshooting guide
Dispatch Internals
docket pod <project> dispatch (and the opt-in docket serve --dispatch loop) drives a pod's
queued tasks through its pipeline, one real, costed agent turn per hop. Earlier drafts of this
document sketched a memory-file signaling protocol (TASK.md/DONE.md/APPROVED.md/
VALIDATED.md) with Telegram polling and a fixed 3-retry escalation — that was never what
core/dispatch.py implements. This section replaces it with the mechanism as it actually ships,
resolved against a declarative pipeline by core/orchestrator.py.
Task state machine
A queued task moves through pending → running → done | failed | blocked |
waiting_approval | waiting_input (plus cancelled via the run registry, below).
- Claiming is locked, not read-then-write.
pending→runningis a single locked read-modify-write (edges/store.py) that also persistsstartedAt,claimId, andclaimedAt— this is what stops two concurrentdispatch_podcalls on the same pod from double-running the same task (they may each claim and run different tasks concurrently, which is fine). - Hops persist as they complete, not only when the whole task finishes, so a crash mid-task
loses at most the in-flight hop. A stale
runningclaim (one whoseclaimedAthasn't advanced recently) is swept tofailedwithfailureKind: "stale_claim"and is resumable —dispatch_pod(..., resume=True)re-claims it and continues from the last persisted hop, replaying mid-rework position if needed, rather than restarting at hop 0. blockedis never silently rewritten topending. A budget-blocked task only re-enters the queue viaunblock_pod(a pod-wide budget change) orretry_task(one task, explicit); the same is true of a taskblockedonblockedReason: "input_expired"(an unanswered question past its deadline) or"resources"(a Lead intake brief naming a resource its own deterministic pre-check couldn't find, before any hop ever ran).waiting_approvalsits outside the normal forward flow, for either of two triggers: a pre-hopapprovalgate (unchanged), or — since Phase 34 (D-50, ADR 0016) — an in-turn tool-callaskthat would otherwise block the running hop. Which posture an unattended pod gets is resolved, not fixed:approvalMode: waitblocks the call as before (the default for an interactive TTY dispatch);park— the resolved default forserve --dispatch's sweep and a non-interactivedispatch— records the exact call and ends the turn instead of blocking it, so one stuck hop can no longer stall an entire sweep.docket approve/docket deny(CLI, HTTPPOST /approvals/<token>, MCP, or Telegram) resolve either trigger identically. A grant on a pre-hop gate hands the position back to the next claim as a single-use gate override; a grant on a parked call instead re-runs that same hop, carrying a single-use pre-grant matched by a stable argument digest so the model's identical next call passes once without asking again. A deny fails the task immediately withfailureKind: "approval_denied", and a parked approval left untouched past the pod'sapprovalExpiryHours(24h by default) expires the same way, via the same fail-closed sweep a pre-hop gate's pending approval already used.waiting_inputis for a question, not a permission: a pipelineinputstep (- ask: {input: {from: <step>}}, or the richer per-question schema a Lead's typed intake brief supplies) mints an MCP-elicitation-shaped question instead of running a hop.docket chat <task-id>,docket pod <p> answer,POST /tasks/<id>/answerand the MCPtask_answertool all resolve it through onecore.answers.answer_taskfunction, which routes the step's ownon:outcome (answered/declined) and reopens the taskpending. An unanswered question past its own deadline moves the task toblocked(blockedReason: "input_expired"), neverfailed.
Notifications: the derived inbox and channels
Nothing above pushes anything on its own. docket inbox (also GET /inbox, the MCP inbox
tool, and Telegram's /status, each scoped to the caller's own pod) is read-only, computed live
from the task list and the approval store rather than stored anywhere: every provisioned pod is
enumerated and each task sorted into needsYou (any waiting_* status, plus blocked),
failed, doneSince or running, with a pending approval added to needsYou unless its task
already carries it. A separate kind: channel document (docket channels) is what turns a
transition in that inbox into an actual push: seven dialects ship (console, desktop,
webhook, command, ntfy, email, telegram), only console enabled by default (and it sends nothing: docket doctor warns until a
delivering channel is on), each
declaring what it may do (notify/converse/decide, capped per dialect — only console and
telegram may ever decide) and how much of an event it carries (minimal by default, widened
the same confirmed, audited way docket exporters privacy widens a trace). docket notify flush
computes the diff against the last flush and delivers it — deduplicated, at-most-once, retried
twice per destination — and both serve's sweep and a foreground dispatch call it after their
own work. core/telegram.py's inbound bot is unchanged by any of this: it still only ever
replies to a message it received; a bound chat's push notification, when the telegram channel
is enabled and that chat id is explicitly listed in its actors, is this separate, opt-in
mechanism, never the bot module sending on its own initiative (see SECURITY-SIMPLE.md and
telegram-integration.spec.md).
Consultation, approval packs, evidence and escalation metrics
An agent that needs a human decision has two ways to ask. A gated tool call becomes an approval
whose pack carries the model's own preceding sentence as a rationale (screened, truncated to 500
characters, and a claim by the model rather than a fact) and three options: approve_once,
approve_task (the identical call for the rest of the task: within the turn, and in a pod for every
later hop of the role that asked, at most 20 per task) and deny. Choose it with docket approve
<token> --option approve_task, Telegram /approve <token> task, the HTTP POST's option or the
MCP approvals_grant option. docket approve|deny <token> --reason TEXT, the HTTP approval POST's
reason and the harness answer's content.reason record why, with an actor, in the audit entry.
The consult built-in (kind read) asks a typed question with options and an optional
recommendation. In a pod hop it parks the task waiting_input and answer_task re-runs the same
role with the answer in its message, bounded per task by maxConsultationsPerTask. The parked
question is persisted (0600, consult-parked/) until dispatch stores it on the task, so any process
can answer it. A channel at the conversation level lists the options and the recommended id, and
Telegram /answer <task> <option id> picks one.
docket pod <p> evidence <task-id> [--json] (also GET /tasks/<p>/<id>/evidence) prints the
evidence-v1 document for a task: per-hop measured token usage (null when the endpoint reports zero)
and a trace link made of the session key and a one-second window. A corrections ledger at
<DOCKET_HOME>/corrections/<project>.jsonl collects deny reasons, Reviewer REQUEST-CHANGES texts
and declined answers, read with docket pod <p> corrections [--json].
docket metrics --escalation and /metrics add docket_tasks_started_total,
docket_questions_total{kind,outcome} and docket_decision_latency_seconds. Like the other
counters they are lifetime-of-current-storage counts and must not be alerted on as monotonic.
Pipeline resolution and generalized gates
Before the platform work, dispatch hardcoded a four-role Lead → Implementer → Reviewer → Tester
order and its own Reviewer/Tester verdict parsing. Today core/orchestrator.py's resolve_plan
takes a PipelineSpec (the docket-native YAML format — docket pipeline validate/plan/run,
core/pipeline.py) plus a pod's live roster and the role-archetype registry (core/archetypes.py
— see docket roles), and produces a deterministic ExecutionPlan: the same spec, roster, and
registry always yield the same step DAG, independent of wall-clock time or dict-iteration order.
A pod with no pipeline file resolves the built-in default pipeline — behaviorally identical to
the old hardcoded order, so a pod created before any of this shipped keeps working unchanged.
Each resolved step's gate is one of three kinds, read from the step's own declaration or — if the
step doesn't declare one — its role archetype's gateContract:
mechanical— run a command; nonzero exit fails the step. This is the Implementer'sverifyCmdtoday (docket pod <project> add --verify "<cmd>"/set-verify), resolved against the member's real working tree (worktree → shared codebase → the member's own workspace dir).verdict— match the configured regex at the start of every non-blank line of a hop's output; exactly one distinct marker value is the verdict (zero or conflicting markers are unparseable); a match in the gate'spassValuesadvances the pipeline. This generalizes the Reviewer's APPROVE/REQUEST-CHANGES and the Tester's PASS/FAIL to an arbitrary marker vocabulary for any archetype (thecriticstarter's APPROVE/REJECT, for instance). A verdict gate can carry a boundedreworkedge — a REQUEST-CHANGES re-runs a target step (by default, back to the Implementer) up to a configured cycle budget (maxReworkCycles, default1) before a second rejection fails the task terminally. There is no fixed "3 retries then escalate to a human Engineer" — the bound is one small integer, and the terminal state is simplyfailed, visible viadocket pod <project> queue/docket runs.approval— the step must not proceed until an operator grants it through docket's headless approval channels; this is what produces awaiting_approvaltask.
A parallel group lets a step fan out into concurrently-run child steps (for example, one per
--count N duplicate role member); core/orchestrator.py's run_group runs them on a bounded
thread pool and joins before the pipeline advances past that position.
Retries and timeouts
A hop whose agent turn fails with a retryable failure kind (timeout or daemon_error — the
model endpoint erroring transiently, a legacy name since there is no daemon; nonzero_exit/invalid_output are not retried) is retried in
place, up to a per-role retry budget, with linear backoff; the attempt count is persisted per
hop. Every retry refreshes the task's claim timestamp, so a legitimately long retry loop can't be
mistaken for a stale claim by a different concurrent dispatcher. The agent-turn timeout and the
verifyCmd timeout are independent, each resolved as: an explicit CLI override
(docket pod <p> dispatch --timeout), then the pod Lead's own meta fields, then a built-in
default.
Structured handoff artifacts and the context compiler
Before the platform work, a hop's prompt was built by concatenating every prior hop's raw text
output, capped only by a process-wide byte budget. Today every hop produces a typed
HandoffArtifact (core/handoff.py: summary, files_changed, diff_ref, verdict, notes)
instead of a raw string, persisted alongside its hop record so --resume recovers it exactly.
files_changed and diff_ref are populated for a real Implementer hop via a git probe of its
working tree (uncommitted changes and the current branch name — not a diff against a fixed base
ref); notes is reserved in the schema but has no producer yet, honestly documented as such
rather than implied to be populated.
core/context.py's compile_artifact fits each prior hop's artifact into the next hop's
per-role token budget (RoleArchetype.token_budget, declared per archetype rather than one
global constant — 6000 by default). A hop further into the past gets a smaller share of that
budget, the same halving series a byte-budget stopgap originally used, now denominated in tokens.
If an artifact doesn't fit, fields are shed one at a time in a declared order — notes, then
diff_ref, then files_changed, then verdict — before summary itself is ever touched; only
once every droppable field is gone and it still doesn't fit is summary truncated, always with a
visible [... summary truncated: N bytes omitted ...] marker, never silently. Token counts are an
honest UTF-8-bytes ÷ CONTEXT_BYTES_PER_TOKEN (default 4) approximation — there is no tokenizer dependency, and this number is never used
to bill against, only to bound a prompt deterministically.
The run registry and cancellation
Every dispatch invocation — from the CLI, the serve webhook, a due schedule, the periodic sweep
loop, or an MCP dispatch tool call — creates a record in the run registry (core/runs.py)
before the work starts, and folds it to a terminal state (succeeded, failed, or cancelled)
when it finishes. docket runs queries it; this closed a real gap where background dispatch paths
used to swallow every exception and return before anything ran, leaving no run id and no way to
tell "done" from "failed" from "never ran."
docket runs cancel <id> persists one cancellation request and kills every pid recorded against
that run's process group (each hop subprocess starts its own session, so its pid doubles as its
group id). Queued work becomes cancelled atomically. Running work remains nonterminal and visibly
requested until the executor observes the signal and fully stops; then both the task and run become
cancelled, distinct from ordinary failure. An already-running in-process backend call returns to
the next safe checkpoint, where its response is discarded before any later tool or hop can start.
A run can have more than one pid recorded at once when a parallel step has multiple hops in flight.
The policy engine on the dispatch path
Declarative policies (docket policies, core/policy.py) are evaluated at two points on the live
dispatch path, not just in the CLI's own dry-run tester: pre_input once, at task enqueue (so the
same task text doesn't re-trip a wildcard-scoped policy at every hop), and pre_output on every
hop's real output, before it is embedded in the carried-forward artifact. A block verdict on
pre_input rejects the task before it is ever queued; a require_approval verdict enqueues it
straight into waiting_approval. A block on pre_output fails the hop the same way a failed
agent turn does; redact scrubs the text in place; warn only logs and feeds docket metrics.
In-turn tool calls have their own separate hook — pre_tool_call, evaluated by core/tools.py's
dispatch_tool on every call docket's own turn loop makes (Phase 19 P19-3) — which this
dispatch-level engine does not duplicate; docket policies test pre_tool_call <role> "<text>"
dry-runs that hook specifically, against bash by default. Pass --tool <name> to test a
non-bash tool instead, so it is evaluated on its own terms rather than misclassified against the
shell command allowlist.
FAQ
Q: Is docket an acronym?
A: No, it is a name. The design rests on four ideas: roles (the Lead orchestrates, the Implementer codes, a Reviewer or Tester gates), autonomy within clear responsibilities, context isolation per pod, and durable knowledge in each workspace's memory files.
Q: Is this the same as the original DOCKET.md proposal?
A: Similar spirit, adapted for what docket's own agent runtime can do: - ✅ Kept: Distinct agent roles, context discipline, security focus - ✅ Changed: Coordination is a real dispatch state machine driving costed agent turns (Dispatch Internals), not RPC and not memory-file signaling - ✅ Changed: Orchestration is a per-pod Lead, not a global router with a classifier - ✅ Changed: Security (separate specialist, not merged into Reviewer)
See Agent Teams (Pods) for the full role model details.
Q: Do I need to change how I use docket?
A: No. The first docket init creates the org specialists as part of the shared foundation,
and every docket init (run in a project directory, or docket init <project> [path]) provisions
that project's pod with the right templates. Everything else works the same.
Q: Will this break my existing agents?
A: No. Templates are generated per-pod by docket init (and per member by docket add) and
refreshed by
docket maintain <id> rebuild:
- Org specialists (manager, knowledge, security) are created lazily by the first docket init
- Each project pod (lead + implementer, optionally reviewer/tester) is isolated
- Project agents are never touched by another project's setup
Q: How much will I save?
A: See Cost Optimization above and Cost reporting and its limits — the short version is: token reduction from isolation is real and measured, but docket reports measured tokens; dollar figures are labelled estimates, never recorded spend, and never a savings promise.
Embedding docket-runtime
The standalone docket-runtime package (packages/docket-runtime/) builds from the same
source as the CLI and ships a narrow, versioned docket_runtime facade. An embedding application
registers and dispatches tools through docket's policy, approval, trace, and audit chokepoint
without adopting the CLI or the full agent loop. It is not published to any index — build it
from a checkout of this repository and start from
examples/runtime_embed.py.
Two optional adapter configurations have installed-artifact coverage:
| Adapter | Tested configuration | Boundary |
|---|---|---|
| OpenHands SDK | openhands-sdk==1.44.1, Python 3.12 |
Standard agent with defaults, native tools, plugins, skills, and MCP disabled |
| PydanticAI | pydantic-ai==2.37.0, Python 3.11 |
One sequential Docket toolset with no native or additional toolsets |
These claims apply when relevant tools are exclusively Docket-backed. ACP, native/provider tools, plugins/MCP added beside an adapter, and arbitrary framework configurations are outside the proof; this is not framework-neutral compatibility. The adapters use neither A2A nor OTLP: both run in process, and Docket's JSONL trace already preserves the identity fields the matrix tests. Trace export (Configuration §3.14) is a separate, operator-enabled projection of that trace from docket's own driver, and is not part of the adapter proof. Inspect the boundary or copy the lazy constructors from examples/runtime_adapters.py.
Next Steps
- First project:
docket initin the project directory (the first run also creates the org specialists; the pod is a lead + implementer) - Add another project pod:
docket init <project> [path] - Inspect context:
docket context <project>-lead show(quick per-agent view) - Test workflow: Assign bug fix, observe token usage
- Monitor spend:
docket cost(measured tokens; no recorded dollar spend)
References
- Quick Start Guide - Get started in 5 minutes
- Workflow Guide - Complete examples
- Security Model - Layered, convention-based security
- Commands Reference - All commands
- Agent Teams (Pods) - The canonical team model reference
- Decision records - One reasoned architectural decision per file, including harness mode (ADR 0001)
- specs/ - RFC 2119 functional/API/data specifications; the exact, CI-validated behavioral contract for anything summarized in this document
Last Updated: 2026-09-18 Status: Implemented, automated-test-backed — not yet field-hardened (see the beta warning at the top of this document)