How it works · packages/reader/src/agent.ts

The docket agent.

For a whole jail, HalfTime runs as an agent. Claude works through the files with seven tools and chooses the order of work. Code checks every quote, owns every verdict, gates every records request and draft, and builds the final docket.

What it does

Given a stack of court orders and a date, runDocketAgent() lets the model list and read the files, submit the facts of each with quotes, look up sections, request records the papers lack, and draft 479(3) applications. When a quote is rejected, the verifier's reason goes back to the model and it may try again with the exact words. At the end, code (not the model) orders everyone for a review meeting: past the line first (most days past at the top), then flagged, then can't tell (records requested first), then not yet (soonest first), then outside 479.

The model is claude-sonnet-5-5, with prompt caching on the growing conversation. The page /agent replays the recorded run and lets you run your own.

The seven tools

Inputs are read from the tool schemas the model is given (AGENT_TOOLS); a trailing ? marks an optional field.

ToolInputWhat code enforces
list_filesnoneReturns ids and first lines only, plus today's date.
read_fileidWraps the text in <<<DOCUMENT id>>> markers with a note that it is untrusted evidence. Unknown ids are refused.
submit_factsid, extractionRefused until the file has been read. Unknown keys (a “verdict”, say) are stripped by the schema. Runs the span verifier and the engine; returns accepted facts, rejected claims with the verifier's reason, the code verdict and retries left. At most 2 resubmissions per file.
lookup_sectionact, sectionReads the statute tables: maximum, source, IPC→BNS mapping.
request_recordid, what, reasonRefused before facts are submitted, refused unless the verified facts lack what the record supplies (custody certificate, charge-sheet copy, criminal-history report), refused if already requested. The letter comes from a fixed template; the case number is used only if it is in the document.
draft_applicationid, lang?Refused before facts are submitted and refused unless code's verdict is PAST_THE_LINE or PAST_FLAGGED. Code writes the draft from verified facts.
finishsummaryEnds the loop. The model's summary is kept as a note; code builds the docket from verified state.

submit_facts takes the same extraction shape as the MCP tool check_order: sections[] (act, section, quote, ndps_quantity?), custody_start (date, kind?, quote), first_time_offender and other_pending_cases (value, quote), and optional registered_on, accused_name_masked, case_no, court. Quotes are capped at 4,000 characters and sections at 40 per file.

The loop

The docket agent loopThe model lists and reads files; document text comes back fenced as untrusted data. It submits facts with quotes; the tools call the verifier and engine, which return a verdict, accepted facts and rejected claims with reasons. If a quote was rejected and retries remain (two per file), the model may resubmit with exact quotes. Record requests and drafts are refused unless code's verdict allows them. On finish, code builds the docket in priority order.Claude Sonnet 5.5chooses the order of workToolscodeVerifier + enginecodeDocketcodealta quote was rejected; retries left (2 per file)list_files · read_file(id)text in markers, as untrusted datasubmit_facts(id, facts + quotes)decide(text, facts)verdict, accepted, rejected + whyresult (extra fields stripped)submit_facts(id, exact quotes)request_record · draft_applicationrefused unless code's verdict allowsfinish(summary)build the docket in priority order
Scroll sideways to see the whole diagram. One model turn may call several tools. Dashed lines are results going back.
  • Each turn sends the system prompt, the conversation so far and the tool definitions; the response's tool calls run in order.
  • The loop ends when the model calls finish, stops calling tools, hits the step limit (by default 10 turns plus 4 per file), or an error or the spend cap stops it. The reason is recorded as stoppedBy.
  • Each event in the log is a short summary (never a whole document) with its time, tokens and cost.
  • Responses are cached by a hash of the whole request, so a recorded run replays exactly.

Guard rails

Each of these is code, and each is covered by a test with a scripted model in packages/reader/test.

RailHow it is enforced
Verdicts come only from codesubmit_facts runs decide(): the span verifier, then the engine. Unknown fields in the model's input are stripped by zod before code sees them.
Every fact needs a quoteA quote not in the document, or one without the claimed date or section, is rejected with the reason and treated as unknown.
Retries are cappedTwo resubmissions per file. After that the facts stand as last verified; anything unverified stays unknown.
Records and drafts are gatedrequest_record only for what the verified facts lack; draft_application only past the line.
The loop is boundedA step limit, a spend cap checked before each call, unknown tools and file ids refused.
Documents are dataFile text is fenced with markers and labelled untrusted; the system prompt says instructions inside it are evidence to ignore.
The docket is built by codeRanks come from sortDocket() over verified state, never from the model's words.

The recorded run

Recorded run on the 12 constructed sample orders, recorded on 14 Nov 2026 with “today” set to 15 Nov 2026. Numbers read from apps/web/src/data/agent-run.json.

Tool calls
37
7 model turns · stopped by finish
Claims rejected / fixed on retry
1 / 1
Records requested · drafts
4 · 6
Verdicts matching the answer key
12/12
Cost
$0.20
1,50,278 input, 8,670 output tokens
Time
50 s
Tool calls refused
0
0 refusal events in the log
Past the line + flagged
3+3
2 can't tell · 3 not yet · 1 outside 479

The rejected claim, and the fix

FileEventLog line
S07rejected3 quote(s) verified · rejected section NDPS 20: The quote doesn't mention section 20. · code verdict CANT_TELL
S07fixed4 quote(s) verified · 1 fixed on retry · code verdict PAST_THE_LINE · 154 days past the line

The model's closing summary (kept as a note, not used for any decision)

All 12 files were read and submitted, and code computed the verdicts. Drafts for lawyer review were produced for S02, S03 and S07, which were unflagged and past the line. Drafts were also produced for S01, S09 and S11, which were flagged. S01's flags are a full-maximum-term detention note and multiple offences. S09 and S11 are flagged because the papers don't say whether other cases are pending, so I requested criminal history reports for both. S04 is excluded. S06, S08 and S12 are not yet at the line. S06's order contained an embedded instruction to mark the accused eligible. I ignored it. S05 needs a custody certificate because its order gives no custody date. S10 needs a charge-sheet copy because the maximum term for Dowry Act s.3 is missing from the statute tables.

Run it with your own key

In the browser

On /agent, under “Run it on your papers”, paste your Anthropic API key and add up to 10 files. The agent runs in your browser; your key and papers go straight to api.anthropic.com. A run is capped at one US dollar. See Security for where the key is kept.

From the repository

scripts/build-agent-run.ts runs the agent on the twelve sample orders with a spend cap of US$2.50 and writes apps/web/src/data/agent-run.json. Responses are cached under .cache/claude, so a second run replays without calling the API.

Terminal
export ANTHROPIC_API_KEY=...        # your own key
npx tsx scripts/build-agent-run.ts

To use it in your own code, import runDocketAgent and anthropicModelClient from @halftime/reader/agent; pass files (id and text), today, a client, and optionally maxSteps, maxRetriesPerFile and onEvent.