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.
| Tool | Input | What code enforces |
|---|---|---|
| list_files | none | Returns ids and first lines only, plus today's date. |
| read_file | id | Wraps the text in <<<DOCUMENT id>>> markers with a note that it is untrusted evidence. Unknown ids are refused. |
| submit_facts | id, extraction | Refused 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_section | act, section | Reads the statute tables: maximum, source, IPC→BNS mapping. |
| request_record | id, what, reason | Refused 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_application | id, 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. |
| finish | summary | Ends 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
- 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 asstoppedBy. - 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.
| Rail | How it is enforced |
|---|---|
| Verdicts come only from code | submit_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 quote | A quote not in the document, or one without the claimed date or section, is rejected with the reason and treated as unknown. |
| Retries are capped | Two resubmissions per file. After that the facts stand as last verified; anything unverified stays unknown. |
| Records and drafts are gated | request_record only for what the verified facts lack; draft_application only past the line. |
| The loop is bounded | A step limit, a spend cap checked before each call, unknown tools and file ids refused. |
| Documents are data | File text is fenced with markers and labelled untrusted; the system prompt says instructions inside it are evidence to ignore. |
| The docket is built by code | Ranks 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
| File | Event | Log line |
|---|---|---|
| S07 | rejected | 3 quote(s) verified · rejected section NDPS 20: The quote doesn't mention section 20. · code verdict CANT_TELL |
| S07 | fixed | 4 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.
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.