@xingular/harness 1.3.1-unstable.8 → 1.4.0-unstable
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +122 -5
- package/NOTICE.md +26 -0
- package/builtin/skills/plugin-authoring/SKILL.md +20 -1
- package/dist/cli.js +2424 -1237
- package/dist/sdk/accounts/accounts.d.ts +26 -20
- package/dist/sdk/accounts/accounts.js +100 -63
- package/dist/sdk/agents/builtin.js +2 -0
- package/dist/sdk/commands/registry.d.ts +7 -0
- package/dist/sdk/commands/registry.js +1 -0
- package/dist/sdk/core/commandBudget.js +7 -2
- package/dist/sdk/core/workspaceWriteOperations.d.ts +24 -0
- package/dist/sdk/core/workspaceWriteOperations.js +21 -0
- package/dist/sdk/plugins/builtin.js +0 -4
- package/dist/sdk/plugins/discover.js +80 -4
- package/dist/sdk/plugins/install.js +26 -0
- package/dist/sdk/plugins/manifest.d.ts +2 -0
- package/dist/sdk/plugins/manifest.js +20 -1
- package/dist/sdk/prompt/compile.d.ts +4 -1
- package/dist/sdk/prompt/compile.js +8 -21
- package/dist/sdk/prompt/reporting.d.ts +2 -0
- package/dist/sdk/prompt/reporting.js +282 -0
- package/dist/sdk/prompt/standard.d.ts +12 -0
- package/dist/sdk/prompt/standard.js +53 -2
- package/dist/sdk/sessions/checkpoint.d.ts +7 -0
- package/dist/sdk/sessions/checkpoint.js +41 -0
- package/dist/sdk/sessions/compactionCheckpoint.d.ts +2 -0
- package/dist/sdk/sessions/compactionCheckpoint.js +2 -1
- package/dist/sdk/sessions/completionCheck.d.ts +49 -0
- package/dist/sdk/sessions/completionCheck.js +143 -0
- package/dist/sdk/sessions/continuation.js +1 -1
- package/dist/sdk/sessions/contracts.d.ts +97 -1
- package/dist/sdk/sessions/contracts.js +17 -0
- package/dist/sdk/sessions/goal.d.ts +145 -0
- package/dist/sdk/sessions/goal.js +405 -0
- package/dist/sdk/sessions/goalLoop.d.ts +37 -0
- package/dist/sdk/sessions/goalLoop.js +125 -0
- package/dist/sdk/sessions/goalPrompts.d.ts +4 -0
- package/dist/sdk/sessions/goalPrompts.js +93 -0
- package/dist/sdk/sessions/planMode.d.ts +31 -0
- package/dist/sdk/sessions/planMode.js +48 -3
- package/dist/sdk/sessions/registry.d.ts +6 -1
- package/dist/sdk/sessions/registry.js +4 -4
- package/dist/sdk/sessions/runStore.js +1 -0
- package/dist/sdk/sessions/runner.d.ts +9 -0
- package/dist/sdk/sessions/runner.js +65 -13
- package/dist/sdk/sessions/sessions.d.ts +10 -0
- package/dist/sdk/sessions/sessions.js +87 -10
- package/dist/sdk/sessions/stopGate.d.ts +78 -0
- package/dist/sdk/sessions/stopGate.js +143 -0
- package/dist/sdk/sessions/subagentService.d.ts +2 -0
- package/dist/sdk/sessions/subagentService.js +1 -1
- package/dist/sdk/sessions/workSlice.d.ts +61 -12
- package/dist/sdk/sessions/workSlice.js +102 -33
- package/dist/sdk/terminal/controller.d.ts +2 -2
- package/dist/sdk/terminal/controller.js +14 -4
- package/dist/sdk/terminal/credentialStore.d.ts +4 -0
- package/dist/sdk/terminal/credentialStore.js +33 -0
- package/dist/sdk/terminal/piExtension.d.ts +2 -1
- package/dist/sdk/terminal/piExtension.js +160 -27
- package/dist/sdk/terminal/terminals.js +27 -4
- package/dist/sdk/terminal/tui/commands.d.ts +2 -0
- package/dist/sdk/terminal/tui/commands.js +3 -0
- package/dist/sdk/terminal/tui/goalCommand.d.ts +19 -0
- package/dist/sdk/terminal/tui/goalCommand.js +83 -0
- package/dist/sdk/terminal/tui/planMode.d.ts +1 -1
- package/dist/sdk/terminal/tui/planMode.js +1 -1
- package/dist/sdk/terminal/tui/runtime.d.ts +3 -0
- package/dist/sdk/terminal/tui/runtime.js +21 -4
- package/dist/sdk/tools/askUser.js +1 -1
- package/dist/sdk/tools/todo.js +2 -1
- package/dist/terminal-opentui.js +1740 -627
- package/dist/terminal-pi.js +996 -407
- package/docs/architecture/02-sessions-and-runs.md +47 -11
- package/docs/architecture/04-prompt.md +83 -16
- package/docs/architecture/06-plugins-and-capabilities.md +16 -1
- package/docs/architecture/07-tools-and-gate.md +7 -2
- package/docs/architecture/09-accounts-and-connectors.md +9 -0
- package/docs/architecture/10-server-protocol.md +13 -0
- package/docs/architecture/11-terminal.md +38 -12
- package/docs/architecture/proposals/PROP-0041-bounded-work-slices.md +2 -0
- package/docs/decisions/ADR-0008-flexible-reporting-guidance.md +3 -0
- package/docs/decisions/ADR-0063-unfinished-work-handoffs.md +2 -0
- package/docs/decisions/ADR-0068-scope-and-completion-report.md +60 -0
- package/docs/decisions/ADR-0069-stop-gate-and-finish.md +130 -0
- package/docs/decisions/ADR-0070-terminal-slice-continuation.md +46 -0
- package/docs/decisions/ADR-0071-completion-check.md +104 -0
- package/docs/decisions/ADR-0072-codex-prompts-and-goal.md +105 -0
- package/docs/decisions/ADR-0073-large-reporting-prompt.md +84 -0
- package/docs/parity.md +4 -1
- package/docs/releases/1.3.1-unstable.9.md +54 -0
- package/docs/releases/1.4.0-unstable.md +18 -0
- package/docs/releases/README.md +1 -1
- package/docs/study/00-index.md +10 -0
- package/docs/study/STUDY-0004-turn-end-controls.md +123 -0
- package/docs/study/STUDY-0005-skill-installation-guidance.md +146 -0
- package/docs/study/STUDY-0006-reporting-prompts.md +81 -0
- package/docs/study/arms/04-skills.md +6 -0
- package/docs/terminal-tui.md +17 -7
- package/package.json +1 -1
- package/dist/sdk/tools/checkpoint.d.ts +0 -27
- package/dist/sdk/tools/checkpoint.js +0 -154
|
@@ -300,7 +300,12 @@ is approved but remains in progress; no completed cross-surface catalog is impli
|
|
|
300
300
|
commands. Generic browser actions and connected-app calls remain unavailable in plan mode. The
|
|
301
301
|
gate refuses unsafe calls before approvals, and the service rechecks before launch. The terminal activates plan-eligible
|
|
302
302
|
tools only for a plan request, then restores its normal set. Provider-cache effects of the tool-list
|
|
303
|
-
difference are not assumed (page 04, `INV-PRM-8`).
|
|
303
|
+
difference are not assumed (page 04, `INV-PRM-8`). Pi records a tool-set change only with the next
|
|
304
|
+
request, so the terminal brackets each plan request with `xingular-plan-tools` entries (`begin`
|
|
305
|
+
carries the normal set it replaced, then `end`). Whenever Pi rebuilds the active tools from the
|
|
306
|
+
transcript (a new runtime, resume, switch, fork or tree navigation), `normalToolsForBranch` returns
|
|
307
|
+
the bracketed normal set if the last recorded set is a plan's, so a plan never leaks into normal
|
|
308
|
+
mode.
|
|
304
309
|
- **INV-RUN-9** Subagent results reach the parent at native turn boundaries, at most once
|
|
305
310
|
automatically (typed receipts in native history). A parent joins outstanding children before it
|
|
306
311
|
completes.
|
|
@@ -319,24 +324,55 @@ is approved but remains in progress; no completed cross-surface catalog is impli
|
|
|
319
324
|
available with `workSlice.maxNewTokens`, counted on new input, cache writes and output and never on
|
|
320
325
|
the cached prefix: a few large reads pass any small cap before useful work, so the tool calls and
|
|
321
326
|
the clock are the bound and the token count is only a ceiling for whoever asks for one. At the
|
|
322
|
-
limit the guard refuses the next tool call
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
+
limit the guard refuses the next tool call and asks the model to stop and report where it is; the
|
|
328
|
+
harness then writes the checkpoint itself from the reply's files, checks and todo list (the model
|
|
329
|
+
has no checkpoint tool since ADR-0069). A non-handoff tool call after the refusal ends the reply. A
|
|
330
|
+
budget-ended reply is `interrupted` with terminal reason `slice_complete` (ADR-0053), unless it
|
|
331
|
+
continues: a headless run as a new run (`continueSlice`), a terminal reply in place as its next
|
|
332
|
+
slice (ADR-0070), both up to `maxSlices` and never after a fruitless or blocked slice. The budget
|
|
333
|
+
covers the whole reply: Pi emits `agent_start` for every continuation (a stop-gate nudge, delivered
|
|
334
|
+
subagent results, a plan repair), so the guard starts a new slice only on a person's message.
|
|
327
335
|
No call is refused for repeating: identical calls, a Bash check that keeps failing and repeated
|
|
328
336
|
`edit`/`write` results on one path are allowed as often as the work needs, because a distinct read
|
|
329
337
|
or another edit is not evidence of a loop. `todo_write` counts toward the tool-call budget and is
|
|
330
338
|
otherwise unconstrained. Third-compaction thrash detection remains: three context compactions in
|
|
331
|
-
one reply end it with the same handoff request. Plan-research children
|
|
332
|
-
|
|
339
|
+
one reply end it with the same handoff request. Plan-research children receive the configured bound
|
|
340
|
+
without a new capability and do not auto-continue. A new run
|
|
333
341
|
continues it only up to the policy's slice cap, only after a slice that changed a file, passed a
|
|
334
342
|
check or recorded a finished item, and never after a checkpoint that is `blocked`. A run may turn
|
|
335
343
|
the guard off with `workSlice.enabled: false`, and a launch may set `XINGULAR_WORK_SLICE=off` for
|
|
336
344
|
every run in that process; with it off a reply has no boundary — no checkpoint, no continuation —
|
|
337
|
-
and ends only when the model stops or a person interrupts.
|
|
338
|
-
|
|
339
|
-
|
|
345
|
+
and ends only when the model stops or a person interrupts. A reply the model ends on its own is
|
|
346
|
+
subject to the todo gate (INV-RUN-15) and, in a goal, the goal loop (INV-RUN-16); a continuation carries the todo it left (`continuation.ts`).
|
|
347
|
+
- **INV-RUN-15** A reply may not quietly end while its own todo list has open items (ADR-0069,
|
|
348
|
+
ADR-0072). In an attended top-level run (not plan, command, automatic, subagent or other related
|
|
349
|
+
runs) the **todo gate** acts at Pi's `agent_before_settle` boundary, unless the reply failed,
|
|
350
|
+
aborted or was ended by the slice guard: an item still `pending` or `in_progress` sends the reply
|
|
351
|
+
back with a displayed `xingular-stop-gate` message naming the open items and saying that the list
|
|
352
|
+
shows progress, not the limit of the work. No model is asked. A cap of three nudges per reply
|
|
353
|
+
applies, and no nudge follows one that produced no tool call other than `todo_write` or
|
|
354
|
+
`session_name`. Each nudge is an `extension.notice` from `stop-gate`. A reply settles `completed`
|
|
355
|
+
when no item is open; otherwise it is `interrupted` with terminal code `unfinished` and a
|
|
356
|
+
harness-written checkpoint, and a person continues it. **No model judges an ordinary reply**
|
|
357
|
+
(ADR-0072 removed ADR-0071's every-reply completion check); completion pressure there is the prompt
|
|
358
|
+
(`04-prompt.md`). `XINGULAR_STOP_GATE=off` at launch switches the gate off.
|
|
359
|
+
- **INV-RUN-16** A goal is the person's opt-in long run (ADR-0072). Only a person's own top-level run
|
|
360
|
+
carries one (`sessions.run` `goal`, or `/goal` in the terminal); never a plan, command, unattended
|
|
361
|
+
or child run. While its status is `active`, a reply that would end continues in place (the goal
|
|
362
|
+
loop, `sessions/goalLoop.ts`) with the continuation prompt, counting a round. Statuses are
|
|
363
|
+
`active | paused | blocked | usage_limited | budget_limited | complete`; the person sets, edits,
|
|
364
|
+
pauses, resumes and clears, the system limits (`budget_limited` at 30 rounds or 8 hours by default;
|
|
365
|
+
`usage_limited` on a provider usage limit; `blocked` after three automatic rounds with no activity,
|
|
366
|
+
three with only failed commands, or a provider error), and the model may only claim `complete`,
|
|
367
|
+
report `blocked` after the same blocker on three consecutive goal turns, or `paused` at the person's
|
|
368
|
+
request. A `complete` is a claim: at the next settle the same model, at low effort and with a fresh
|
|
369
|
+
context, checks it against the objective and the transcript; `done` completes the goal, `continue`
|
|
370
|
+
keeps it active with the reason, and no model, an error or an unreadable answer accepts it. The
|
|
371
|
+
loop never stops a goal for a round without a tool call alone. A goal that ends `blocked` settles
|
|
372
|
+
the run `needs_person`; one that ends paused, limited or stalled settles it `unfinished`. The run
|
|
373
|
+
record keeps the goal as `goalMode`. `XINGULAR_COMPLETION_CHECK=off` accepts every claim unchecked.
|
|
374
|
+
- **INV-RUN-14** A run event stream carries `checkpoint` (the handoff the harness derives from the
|
|
375
|
+
run's own evidence; runs written before ADR-0069 may hold one the model wrote) and `heartbeat`
|
|
340
376
|
(steps, elapsed time, last tool, compactions, slice, and the call budget). Every live reply emits a
|
|
341
377
|
heartbeat every 30 seconds, terminal replies included. A heartbeat older than five minutes while
|
|
342
378
|
the owner process lives marks the run `interrupted` with reason `stalled`; a run that never emitted
|
|
@@ -76,26 +76,93 @@ guidance for the effective tools. Terminal preparation defaults to standard sect
|
|
|
76
76
|
attributed add-on and task context, not a duplicate standard role or connection policy (PROP-0040).
|
|
77
77
|
|
|
78
78
|
Budgets (characters): variant sections 30,000 each (already capped at save, so never cut here);
|
|
79
|
-
references 12,000; Wiki pointer 2,500; tools 8,000; reporting
|
|
80
|
-
|
|
79
|
+
references 12,000; Wiki pointer 2,500; tools 8,000; reporting 18,000 (ADR-0073); the
|
|
80
|
+
standard session's sections: role 1,400, autonomy 2,600, permission 1,800, steering 2,000, writing
|
|
81
|
+
1,900 (ADR-0072); application sections their own `budget`.
|
|
81
82
|
|
|
82
83
|
## Reporting
|
|
83
84
|
|
|
84
85
|
Every pack ends with the harness's `reporting` section ("Reporting your work",
|
|
85
|
-
`REPORTING_GUIDANCE` in `prompt/compile.ts`). It is fixed text
|
|
86
|
-
with the outcome rather than the steps taken to reach it,
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
86
|
+
`REPORTING_GUIDANCE` in `prompt/reporting.ts`, imported by `prompt/compile.ts`). It is fixed text
|
|
87
|
+
that shapes the final reply: lead with the outcome rather than the steps taken to reach it, and
|
|
88
|
+
cover only what the person needs to act. The section defines content blocks, not a fixed heading
|
|
89
|
+
list ([ADR-0008](../decisions/ADR-0008-flexible-reporting-guidance.md),
|
|
90
|
+
[ADR-0073](../decisions/ADR-0073-large-reporting-prompt.md)): a change carries four required blocks
|
|
91
|
+
— outcome, what changed, how to test, and what to do next — while a question stays one to three
|
|
92
|
+
sentences and research carries only the blocks with content. How to test gives numbered steps with
|
|
93
|
+
exact commands or URLs, the expected result, what the agent already ran, and what the person must
|
|
94
|
+
run; what to do next names the person's action or says "Nothing needed". Optional blocks cover work
|
|
95
|
+
beyond the request (with why), departures from a plan (what and why), work that needs a person's
|
|
96
|
+
check (what is unverified, why, and the exact check), and open questions. Headings are the model's
|
|
97
|
+
choice — "How to test", "Try it" and "Verify" name the same block — and a heading must name its
|
|
98
|
+
content. The section ships five worked examples and an anti-pattern table, uses tables for files,
|
|
99
|
+
checks and comparisons, and caps a change at about 20–60 lines. A person, application or mode format
|
|
100
|
+
takes precedence. The section names no application, is never dynamic, and is never cut; its budget is
|
|
101
|
+
18,000 characters (ADR-0073).
|
|
102
|
+
|
|
103
|
+
## When a reply may end
|
|
104
|
+
|
|
105
|
+
A reply ends when the request is done, when the work-slice guard ends it (INV-RUN-13), when a person
|
|
106
|
+
interrupts, or when the work cannot continue without the person. An open todo item, a passing check,
|
|
107
|
+
a partial result or a long task is not such a reason. An ordinary reply is held to this by two
|
|
108
|
+
things (ADR-0069, ADR-0072): the words below, and the todo gate (INV-RUN-15), which sends back a
|
|
109
|
+
reply that ends while its todo list has open items. **No model judges an ordinary reply**; a goal's
|
|
110
|
+
completion claim is the one thing a model checks (INV-RUN-16). A reply that settles with work left is
|
|
111
|
+
`interrupted` (`unfinished`, or `needs_person` for a blocked goal), never `completed`.
|
|
112
|
+
|
|
113
|
+
The words decide what the model does before the gate has to act, and none of them may read as
|
|
114
|
+
permission to stop with work left. A person's own session (`launch.standard`, `prompt/standard.ts`)
|
|
115
|
+
reads five stable sections adapted from OpenAI Codex's gpt-6.1-sol instructions (Apache-2.0, see
|
|
116
|
+
`NOTICE.md`), the same for every model so the terminal and a host read the same text (INV-PAR-1):
|
|
117
|
+
|
|
118
|
+
- `role` — the assistant's job, and the extra work it does without asking (the obvious adjacent
|
|
119
|
+
step, what the work exposes, the check it needs) inside the working folder and away from what a
|
|
120
|
+
person must decide (a deploy, a secret, remote data, money). Extra work and departures from the
|
|
121
|
+
plan are allowed on those terms and reported at the end.
|
|
122
|
+
- `autonomy` — bias to action; persist until the intended goal is complete; "can you...", "help
|
|
123
|
+
me..." are instructions; no partial or "helpful enough" solution; an open todo item, a passing
|
|
124
|
+
check, a partial result or a long task is not a reason to end the turn; the todo list shows
|
|
125
|
+
progress and the request is the scope; which decisions are the agent's own; a document the request
|
|
126
|
+
points to is the request; a question the request or files already answer is not a question for the
|
|
127
|
+
person; the only reasons to stop, one of them a fix to a test or error that does not come from
|
|
128
|
+
this session's work (and then say exactly what is needed).
|
|
129
|
+
- `permission` — authorisation persists; finish the authorised work first so that approval is the
|
|
130
|
+
last step; no permission for reversible, read-only or already authorised work; a test or error
|
|
131
|
+
that does not come from this session's work is reported, not fixed, unless the person asks (a
|
|
132
|
+
failure is this session's work when the agent's changes caused it), and is kept off the todo
|
|
133
|
+
list; no messages to other people unless asked; when the agent must ask, it says why and where
|
|
134
|
+
the requirement comes from.
|
|
135
|
+
- `steering` — a new message steers the active task; a correction means "fix it"; compaction does
|
|
136
|
+
not end the task, and work across compactions is one chain.
|
|
137
|
+
- `writing` — plain words, the outcome first, evidence and limits, routine verification summarised,
|
|
138
|
+
no AI-slop phrases, no "X, not Y" contrast, no invented labels, no needless apology.
|
|
139
|
+
|
|
140
|
+
Other fixed text that shapes the end of a reply:
|
|
141
|
+
|
|
142
|
+
- `TODO_GUIDANCE` (`tools/todo.ts`): the list is progress, not scope; the request, and any document
|
|
143
|
+
it points to, is the scope; add steps as the work shows them; list a handoff's steps instead of one
|
|
144
|
+
"remaining work" item; before ending, compare the request, not the list, with what is done and
|
|
145
|
+
checked. An open step is work to do in this reply, not something to report.
|
|
146
|
+
- `reporting` (`REPORTING_GUIDANCE`): opens with "Reporting is for work that is finished or genuinely
|
|
147
|
+
blocked". When work is not finished, the first line says so, gives the specific reason and names
|
|
148
|
+
the next step. The final reply is self-contained, says what could not be done or verified, never
|
|
149
|
+
closes with an "If you want..." offer, and stays near 60 lines. Its `## What would make this
|
|
150
|
+
complete` heading applies only when the work stopped short and says never to stop early to write
|
|
151
|
+
it.
|
|
152
|
+
- `ask_user` (`tools/askUser.ts`): for a decision the request and files do not answer, never for
|
|
153
|
+
permission to do work inside the request; no answer means continue with best judgment (Codex's
|
|
154
|
+
Default-mode rule).
|
|
155
|
+
- In a person's own session the `Progress` tool group says that a reply with open items is sent back.
|
|
156
|
+
There is no tool to stop "on purpose": ADR-0069 removed `checkpoint_write` and ADR-0071 removed
|
|
157
|
+
`finish`. The only tool that ends work is `update_goal` in a goal the person started (INV-TOOL-9).
|
|
158
|
+
|
|
159
|
+
All of these are fixed text in the stable prefix, so changing them changes the cached prefix once.
|
|
160
|
+
A live terminal session keeps the pack, and the extension code, it started with; a harness update
|
|
161
|
+
reaches it only when the session restarts.
|
|
162
|
+
|
|
163
|
+
A goal's text (`sessions/goalPrompts.ts`, adapted from Codex's `ext/goal/templates`) is not in the
|
|
164
|
+
prefix: the continuation, round-cap and edit prompts ride as hidden user messages, with the
|
|
165
|
+
objective escaped and wrapped as data (INV-PRM-2).
|
|
99
166
|
|
|
100
167
|
## Delivery
|
|
101
168
|
|
|
@@ -53,7 +53,22 @@ callable result for one run.
|
|
|
53
53
|
route to another owner's template or guess a default (ADR-0061).
|
|
54
54
|
A package without a `package.json` name is named, described and versioned by the first of
|
|
55
55
|
`plugin.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, so an agent plugin
|
|
56
|
-
written for other harnesses installs as it is.
|
|
56
|
+
written for other harnesses installs as it is. The first of those manifests that declares
|
|
57
|
+
`skills` (a path or a list of paths) also brings those skill folders as package skill
|
|
58
|
+
contributions, so a plugin laid out for another harness contributes the skills it declares. A
|
|
59
|
+
declared path must stay inside the package, and a symlinked skill folder is skipped. Pi's own
|
|
60
|
+
`skills/` folder and `package.json` manifest take precedence, and a package whose settings entry
|
|
61
|
+
names skill patterns is left to that filter.
|
|
62
|
+
- **Skill installation routes.** A skill reaches a run as text from the working folder's `.pi/skills`
|
|
63
|
+
or `.agents/skills` (walking up to the repository root), the OS user's `~/.agents/skills`, the
|
|
64
|
+
state's `accounts/_shared/pi/skills`, a package's `skills` or a foreign manifest's declared paths,
|
|
65
|
+
or the pinned variant's `skills`. A model may write the first two; `~/.agents` is outside the
|
|
66
|
+
workspace, so a write there needs the person's approval. Variant, library, Hub and package
|
|
67
|
+
installs change committed state and are person acts (`/skills`, `/components`, `/hub`,
|
|
68
|
+
`/plugins`). A variant holds `SKILL.md` and flat `scripts/` files only. `plugins.install` takes a
|
|
69
|
+
package address: a GitHub or GitLab `tree`/`blob` page address is refused with the repository
|
|
70
|
+
address and these routes. The install guidance lives in the release-owned `plugin-authoring`
|
|
71
|
+
skill, not the always-on prompt ([STUDY-0005](../study/STUDY-0005-skill-installation-guidance.md)).
|
|
57
72
|
- **Package subagent profiles.** An installed package's agents folder (`agents/` unless
|
|
58
73
|
`harness.agents` names another) brings each Markdown file whose frontmatter has a `name` and a
|
|
59
74
|
`description` as an `agent` contribution (at most 50). It is text: it needs no trust and follows
|
|
@@ -147,8 +147,13 @@ beside the choices (INV-RC-3, INV-RC-4).
|
|
|
147
147
|
|
|
148
148
|
- **INV-GATE-1** Every tool call of every run passes the gate. No tool source bypasses it,
|
|
149
149
|
including extension-registered tools (which ask before every call) and the initial Bash command.
|
|
150
|
-
- **INV-TOOL-9**
|
|
151
|
-
|
|
150
|
+
- **INV-TOOL-9** The model has no tool that ends or hands off its own work (ADR-0071, ADR-0072):
|
|
151
|
+
neither `checkpoint_write` (PROP-0041, removed by ADR-0069) nor `finish` (ADR-0069, removed by
|
|
152
|
+
ADR-0071) exists. The one exception is `update_goal` in a goal the person started: it is offered
|
|
153
|
+
only while a goal exists, its `complete` is only a claim that the harness checks (INV-RUN-16), and
|
|
154
|
+
its `paused` needs the person's word. The model cannot create, resume or limit a goal. When a
|
|
155
|
+
reply stops, the harness decides how it settled (INV-RUN-15) and writes the checkpoint from the
|
|
156
|
+
run's evidence.
|
|
152
157
|
- **INV-TOOL-10** Bash keeps one command budget on every surface: 120 seconds when the call says
|
|
153
158
|
nothing, 300 seconds as the ceiling without a `reason`, 900 seconds as the maximum, and a timeout
|
|
154
159
|
returns the partial output with a narrowing instruction instead of blocking the reply.
|
|
@@ -60,6 +60,15 @@ skills, prompts, rules and Pi packages.
|
|
|
60
60
|
- **INV-ACC-4** A terminal's `/accounts` goes through the session socket's `accounts.*` calls, and
|
|
61
61
|
every one needs the session's control key. A command the model runs in the shell cannot make
|
|
62
62
|
an account change.
|
|
63
|
+
- **INV-ACC-5** A credential has one copy. A terminal's Pi keeps no `auth.json`: it reads its own
|
|
64
|
+
account's credentials with `accounts.credentials.read`/`list`, and a refresh or sign-in holds the
|
|
65
|
+
store's cross-process lock from `accounts.credentials.lease` to `accounts.credentials.commit`
|
|
66
|
+
(`terminal/credentialStore.ts`, at most 20 seconds, then the lease lapses unchanged). Like every
|
|
67
|
+
`accounts.*` call they need the control key, so the model's shell never sees a token. Two copies of
|
|
68
|
+
a rotating refresh token, each under its own lock, let the second refresh send a spent token and
|
|
69
|
+
fail with `invalid_grant`. An `auth.json` a terminal of an older version left is folded in under the
|
|
70
|
+
lock, a newer stored token never replaced, and removed once no other process has a terminal on the
|
|
71
|
+
account.
|
|
63
72
|
- **INV-MCP-1** Connector secrets live in the `SecretStore`; `connections.json` holds no secret.
|
|
64
73
|
Run events and traces are redacted before they are stored or shown.
|
|
65
74
|
- **INV-MCP-2** A session reaches only the connections its scope and the policy allow, and loses
|
|
@@ -79,6 +79,19 @@ harness → host { v: 1, id, call, params } host → harness { v: 1
|
|
|
79
79
|
- The run-event stream adds `checkpoint` (the bounded handoff) and `heartbeat` (steps, elapsed time,
|
|
80
80
|
last tool, compactions, slice, call budget). Hosts must accept both; an unknown event type is still
|
|
81
81
|
relayed in order (INV-RUN-3).
|
|
82
|
+
- `terminalCode` gains `needs_person` and `unfinished` (ADR-0069, ADR-0072): a reply that settled with
|
|
83
|
+
work left — `needs_person` when the run's goal ended `blocked`, `unfinished` when todo items stayed
|
|
84
|
+
open or a goal was paused, stalled or limited. Both are `interrupted`, carry a `checkpoint`, and
|
|
85
|
+
are not auto-continued; a host should offer the person Continue, as it does for `slice_complete`.
|
|
86
|
+
Stop-gate nudges arrive as `extension.notice` events with `extension: 'stop-gate'`.
|
|
87
|
+
- `sessions.run` accepts `goal { objective, rounds?, hours? }` (ADR-0072, INV-RUN-16) for a person's
|
|
88
|
+
own top-level run; it is refused with `invalid_request` for a plan, command, unattended or child
|
|
89
|
+
run, or an empty or over-long (4,000 character) objective. The objective is the request, and the
|
|
90
|
+
run continues in place while the goal is active. Goal rounds, claim checks and stops arrive as
|
|
91
|
+
`extension.notice` events with `extension: 'goal'`; a claim check's model request is one more
|
|
92
|
+
`usage.updated` request. Run records carry `goalMode` (`goalId`, `objective`, `status`, `limits`,
|
|
93
|
+
`rounds`, `timeUsedSeconds`, `claimed`, `lastReason`) while a goal exists; `goal` stays the
|
|
94
|
+
request text. A goal active at a work-slice boundary is carried into the continuation run.
|
|
82
95
|
- Run streams also carry `tool.refused` with the call id, name, refusal code and bounded reason.
|
|
83
96
|
Run records expose nullable `terminalCode`; `terminalReason` remains descriptive text. Older
|
|
84
97
|
records and events may omit the code. Trajectory search exposes both fields (pages 02 and 08).
|
|
@@ -58,7 +58,7 @@ Screen: transcript above the composer, centred dialogs, full-screen resource bro
|
|
|
58
58
|
(ADR-0064). With no usable saved selection, Pi's own fallback message stands.
|
|
59
59
|
- Normal mode keeps `ask_user` out of the active tool set. An attended plan request enables the
|
|
60
60
|
shared tool alongside its read-only set and restores the normal set on success, failure or
|
|
61
|
-
interruption. The question blocks until answered, then planning continues in the same run. There
|
|
61
|
+
interruption, and again after any rebuild from the transcript (page 02, `INV-RUN-8`). The question blocks until answered, then planning continues in the same run. There
|
|
62
62
|
is no terminal-only question alias (PROP-0040).
|
|
63
63
|
- The approved plan outcome contract on page 02 applies equally to the terminal and server:
|
|
64
64
|
only `plan_ready` offers a plan card and Implement; `blocked` reports unavailable required input
|
|
@@ -377,15 +377,38 @@ release.
|
|
|
377
377
|
Terminal tool-gate and work-slice refusals are relayed as `tool.refused` events with a code and reason; the original refusal text remains the tool response. Interrupted terminal runs record stop codes for work-slice limits, user abort, stalls and terminal closure.
|
|
378
378
|
|
|
379
379
|
Terminal replies carry the same work-slice guard as structured runs: 320 tool calls or 60 minutes,
|
|
380
|
-
with no new-token limit by default (PROP-0044), then a refusal that asks
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
`
|
|
388
|
-
|
|
380
|
+
with no new-token limit by default (PROP-0044), then a refusal that asks the model to stop and report
|
|
381
|
+
where it is. Terminal replies also carry the todo gate (INV-RUN-15, ADR-0069, ADR-0072): the
|
|
382
|
+
extension sends a reply that ends with open todo items back, up to three nudges, each `notice`
|
|
383
|
+
telemetry recorded as `extension.notice`, and at settle sends a harness-written `checkpoint` and the
|
|
384
|
+
`needs_person` or `unfinished` code, which the controller records on the active run, so an App
|
|
385
|
+
reading the same session sees the handoff. No model judges an ordinary reply. Plan replies are not gated. A reply that
|
|
386
|
+
reaches its budget after doing work continues in place as its next slice (ADR-0070): a
|
|
387
|
+
`xingular-slice-continue` message in the same run, a checkpoint and a notice per boundary, up to
|
|
388
|
+
`maxSlices` (8). A fruitless, blocked, failed, aborted or plan slice, or one whose todo items are all
|
|
389
|
+
done, is not continued; the reply then settles `interrupted` with terminal reason `slice_complete`
|
|
390
|
+
so the person or a host can continue it. A checkpoint card in the transcript is not built yet
|
|
391
|
+
(PAR-004). Start the terminal with `XINGULAR_WORK_SLICE=off` to launch a reply with no boundary at
|
|
392
|
+
all, or with key=value pairs such as `maxToolCalls=15,maxSlices=3` for a smaller policy; neither is
|
|
393
|
+
persisted, so the next launch without it restores the defaults.
|
|
394
|
+
|
|
395
|
+
## `/goal` (ADR-0072, INV-RUN-16)
|
|
396
|
+
|
|
397
|
+
`/goal <objective>` sets the session's goal and starts work at once; `--rounds N` and `--hours H`
|
|
398
|
+
before the objective set this goal's caps (30 rounds, 8 hours by default). Bare `/goal` shows the
|
|
399
|
+
status (status, objective, rounds, time used, last check, and the commands that apply). `/goal edit`
|
|
400
|
+
asks for a new objective (the same goal, its usage kept), `pause` stops a running reply and keeps the
|
|
401
|
+
goal, `resume` continues it, `clear` removes it. A subcommand matches only as the whole argument, so
|
|
402
|
+
"/goal pause now" is an objective. Setting a goal while an unfinished one exists asks first. Esc or
|
|
403
|
+
Ctrl-C on a running goal pauses it, as in Codex. The status bar shows `Pursuing goal (2m, round
|
|
404
|
+
3/30)`, `Goal paused (/goal resume)`, `Goal stalled (/goal resume)`, `Goal hit usage limits (/goal
|
|
405
|
+
resume)`, `Goal unmet (...)` or `Goal achieved (...)`.
|
|
406
|
+
|
|
407
|
+
The goal lives in the Pi session as a `xingular-goal-state` entry, so a reopened conversation shows
|
|
408
|
+
it, as `paused`: nothing resumes by itself. The model gets `get_goal` and `update_goal` only while a
|
|
409
|
+
goal exists (INV-TOOL-9). The goal loop is a second extension after the todo gate and before slice
|
|
410
|
+
continuation; a goal's slices continue even when every todo item is done. `/goal` is a `session`
|
|
411
|
+
command that uses `sessions.run` with `goal` (page 10); in plan mode the loop stays silent.
|
|
389
412
|
|
|
390
413
|
## Liveness and a reply that stops working (INV-RUN-14, ADR-0054)
|
|
391
414
|
|
|
@@ -397,9 +420,12 @@ terminal reply that stopped reporting by the same five-minute rule as a structur
|
|
|
397
420
|
A heartbeat proves the turn is alive, not that it is working. A reply that produces no event other
|
|
398
421
|
than a heartbeat for fifteen minutes — the state a model request that never returns leaves it in —
|
|
399
422
|
is ended: the controller queues the same `interrupt` command the person's Esc queues, the native turn
|
|
400
|
-
aborts, and the run records `interrupted` with reason `stalled`.
|
|
423
|
+
aborts, and the run records `interrupted` with reason `stalled`. Pi's abort reports back through
|
|
424
|
+
`terminal.interrupt` as Esc does; the controller passes that interrupt on as `stalled`, not
|
|
425
|
+
`user_abort`, when the stall watch asked for it. A reply whose oldest running tool
|
|
401
426
|
has run for thirty minutes ends the same way, and a reply waiting on an approval or question is never
|
|
402
|
-
cut short.
|
|
427
|
+
cut short. An interrupt, a stall included, also ends a settling reply's wait for its subagents
|
|
428
|
+
(`terminal.subagents.delivery`).
|
|
403
429
|
|
|
404
430
|
## Subagent activity monitor
|
|
405
431
|
|
|
@@ -9,6 +9,8 @@ affects: [INV-RUN-2, INV-RUN-3, INV-RUN-4, INV-RUN-12, INV-PRM-1, INV-PRM-2, INV
|
|
|
9
9
|
|
|
10
10
|
# PROP-0041: Bounded work slices, a durable checkpoint, and a stall guard
|
|
11
11
|
|
|
12
|
+
> **Amended by [ADR-0069](../../decisions/ADR-0069-stop-gate-and-finish.md):** the model no longer writes the checkpoint — `checkpoint_write` is removed and the harness writes it from the reply's evidence; the slice budget now covers the whole reply, including Pi's own continuations.
|
|
13
|
+
|
|
12
14
|
## Problem
|
|
13
15
|
|
|
14
16
|
A single reply can run for hours. Two measured sessions (STUDY-0003) ran 114 and 75 minutes in
|
|
@@ -5,9 +5,12 @@ status: accepted
|
|
|
5
5
|
created: 2026-10-21
|
|
6
6
|
updated: 2026-10-21
|
|
7
7
|
supersedes: ADR-0007
|
|
8
|
+
amended_by: ADR-0073
|
|
8
9
|
---
|
|
9
10
|
# ADR-0008 — Flexible reporting guidance with optional human inspection
|
|
10
11
|
|
|
12
|
+
> **Amended by [ADR-0073](ADR-0073-large-reporting-prompt.md):** flexible headings stand; the `reporting` section now names required content blocks and ships worked examples, and the later fixed headings (ADR-0068) are gone.
|
|
13
|
+
|
|
11
14
|
## Context and decision
|
|
12
15
|
|
|
13
16
|
ADR-0007 added stable, harness-owned guidance for final replies, but its fixed heading list could
|
|
@@ -7,6 +7,8 @@ updated: 2026-10-30
|
|
|
7
7
|
---
|
|
8
8
|
# ADR-0063 — Actionable handoffs for unfinished work
|
|
9
9
|
|
|
10
|
+
> **Amended by [ADR-0069](ADR-0069-stop-gate-and-finish.md):** this guidance now applies only when the work stopped on a blocker or a decision (`finish`), never as a way to end a reply with work left.
|
|
11
|
+
|
|
10
12
|
## Context and decision
|
|
11
13
|
|
|
12
14
|
A reply can accurately report blockers yet leave the person unable to tell what decision or
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: ADR-0068
|
|
3
|
+
title: Scope of the work and two required completion headings
|
|
4
|
+
status: superseded
|
|
5
|
+
created: 2026-10-30
|
|
6
|
+
updated: 2026-11-01
|
|
7
|
+
superseded_by: ADR-0073
|
|
8
|
+
supersedes: partial — ADR-0008
|
|
9
|
+
---
|
|
10
|
+
# ADR-0068 — Scope of the work and two required completion headings
|
|
11
|
+
|
|
12
|
+
> **Superseded by [ADR-0073](ADR-0073-large-reporting-prompt.md):** the two required headings and the fixed-label rule are replaced by content blocks and flexible headings. The scope rule in the `role` paragraph stands.
|
|
13
|
+
|
|
14
|
+
> **Amended by [ADR-0069](ADR-0069-stop-gate-and-finish.md):** `## What would make this complete` applies only when the work stopped short (blocked, needing the person, or handed back by the guard), and the deferred runner feature is now the stop gate.
|
|
15
|
+
|
|
16
|
+
## Context and decision
|
|
17
|
+
|
|
18
|
+
ADR-0008 removed the fixed heading list from the `reporting` section and kept every heading
|
|
19
|
+
optional. Two problems followed from a prompt that only described output:
|
|
20
|
+
|
|
21
|
+
1. Every run of the last seven days that ended with work left (207 of 822, 25 %) did so at a median
|
|
22
|
+
of 17 tool calls; the model treated the literal request as the whole assignment
|
|
23
|
+
(`outputs/diagnoses/2026-10-30-sweep.md`). Nothing in the prompt said the work extends to what the
|
|
24
|
+
request implies.
|
|
25
|
+
2. A person reading the final reply could not tell what had been done beyond their request, nor what
|
|
26
|
+
would finish the run. `README`-style prose hid both.
|
|
27
|
+
|
|
28
|
+
The `role` paragraph of a standard session now states the scope of the work — the job the request
|
|
29
|
+
implies, not only its literal words, inside the working folder and away from what a person must
|
|
30
|
+
decide (a deploy, a secret, remote data, money), without asking first inside those bounds — and the
|
|
31
|
+
`reporting` section requires two headings when they apply:
|
|
32
|
+
|
|
33
|
+
- `## Beyond what you asked` — anything done beyond the request, each piece with why the work needed it.
|
|
34
|
+
- `## What would make this complete` — the concrete remaining steps in order, naming the ones only
|
|
35
|
+
the person can decide.
|
|
36
|
+
|
|
37
|
+
`REPORTING_BUDGET` rises from 2,000 to 2,400 characters to hold them without cutting
|
|
38
|
+
(`prompt/compile.ts`).
|
|
39
|
+
|
|
40
|
+
## Consequences
|
|
41
|
+
|
|
42
|
+
- A run may do and report adjacent work that the person did not name; the second heading is what
|
|
43
|
+
makes that auditable and rejectable rather than silent.
|
|
44
|
+
- The stable prefix changes once per session for the three texts (`role`, `reporting`,
|
|
45
|
+
`TODO_GUIDANCE`). Measured with real requests only, under INV-PRM-8.
|
|
46
|
+
- Applications bundling the harness need a rebuild before any new session sees the wording; an
|
|
47
|
+
existing session keeps the prefix it compiled (observed: `context.json` `compiledAt` 16:33:36Z
|
|
48
|
+
reused by a run at 17:21Z).
|
|
49
|
+
- No stored data or protocol changes. Bounded autonomy is still enforced by the tool gate and the
|
|
50
|
+
workspace boundary; the prompt does not grant new reach.
|
|
51
|
+
|
|
52
|
+
## Alternatives considered
|
|
53
|
+
|
|
54
|
+
- Keep every heading optional (ADR-0008 as it stood): rejected — the two facts above were invisible
|
|
55
|
+
in the reply, so the person could not see either the extra work or the gap.
|
|
56
|
+
- One combined heading ("Summary"): rejected — extra work and remaining work are different decisions
|
|
57
|
+
for the person, and merging them hides which is which.
|
|
58
|
+
- Make autonomy a runner feature (continue when a todo is open): deferred, not rejected. The prompt
|
|
59
|
+
is the cheapest lever and was not yet in effect; `docs/research/2026-10-30-turn-end-controls.md`
|
|
60
|
+
records what other harnesses do and when a stop-hook style continuation is worth adding.
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
---
|
|
2
|
+
id: ADR-0069
|
|
3
|
+
title: A stop gate and a finish tool; the model's checkpoint tool is removed
|
|
4
|
+
status: accepted
|
|
5
|
+
created: 2026-10-31
|
|
6
|
+
updated: 2026-10-31
|
|
7
|
+
supersedes: partial — PROP-0041 (the model-written checkpoint), ADR-0068 (when the completion heading applies), ADR-0063 (scope of the unfinished-work guidance)
|
|
8
|
+
related:
|
|
9
|
+
- STUDY-0004
|
|
10
|
+
- ADR-0068
|
|
11
|
+
---
|
|
12
|
+
# ADR-0069 — A stop gate and a finish tool; the model's checkpoint tool is removed
|
|
13
|
+
|
|
14
|
+
> **Amended by [ADR-0071](ADR-0071-completion-check.md):** `finish` is removed; a completion check (the run's own model, fresh context) now decides `continue` / `needs_person` / `done` when a reply that did work ends with its list closed.
|
|
15
|
+
|
|
16
|
+
## Context
|
|
17
|
+
|
|
18
|
+
A reply the model ended on its own settled `completed` (`sessions/runner.ts`), and only a
|
|
19
|
+
guard-ended slice auto-continued (`continueSlice`: `terminalReason === 'slice_complete'`). Nothing
|
|
20
|
+
read the todo list when a reply ended.
|
|
21
|
+
|
|
22
|
+
- **Scale.** 207 of 822 runs in the week to 2026-10-30 ended with work left, at a median of 17 tool
|
|
23
|
+
calls; 81 left open todos (`outputs/diagnoses/2026-10-30-sweep.md`).
|
|
24
|
+
- **Worst case.** One terminal session, "Complete platform and API handoff", stopped three times in
|
|
25
|
+
a row with an open todo, at 23, 65 and 94 of 320 tool calls, after being told "dont stop". Its own
|
|
26
|
+
answer in between: "I stopped prematurely… the unfinished work was not all blocked by approval
|
|
27
|
+
gates."
|
|
28
|
+
- **Prompt fixes did not reach it.** ADR-0068's wording was in `src/` but not in `dist/`, and a live
|
|
29
|
+
terminal session keeps the pack and the extension code it started with.
|
|
30
|
+
|
|
31
|
+
**Hypothesis: the harness's own exit ramps make stopping easier.** Several texts made a polished,
|
|
32
|
+
incomplete stop a first-class outcome, with nothing pushing back:
|
|
33
|
+
|
|
34
|
+
- `checkpoint_write`, whose description said to call it "before you stop on purpose";
|
|
35
|
+
- `TODO_GUIDANCE`'s "before your final reply… leave unfinished or blocked steps accurate";
|
|
36
|
+
- ADR-0063's unfinished-handoff guidance;
|
|
37
|
+
- ADR-0068's `## What would make this complete`, "when the run could be more complete".
|
|
38
|
+
|
|
39
|
+
**What the run records show:**
|
|
40
|
+
|
|
41
|
+
- `checkpoint_write` was rarely called: 3 calls in 41 eligible top-level code runs.
|
|
42
|
+
- In run `62c7fc6c` the model wrote a checkpoint on its own ("the handoff remains incomplete…
|
|
43
|
+
continue remaining implementation", nothing `blocked`), made zero further tool calls, and ended.
|
|
44
|
+
It used the checkpoint as a sign-off.
|
|
45
|
+
- Runs that ended with open todos rose from 8% (146 runs before the tool existed) to 42% (19 after).
|
|
46
|
+
The second sample is small and mostly huge handoffs, so this is a signal, not proof. Stopping
|
|
47
|
+
early predates the tool.
|
|
48
|
+
|
|
49
|
+
Other harnesses enforce the end of a turn rather than describe it (STUDY-0004):
|
|
50
|
+
|
|
51
|
+
| Harness | Mechanism |
|
|
52
|
+
|---|---|
|
|
53
|
+
| Claude Code, Codex | `Stop` hook with `decision: block` and a reason |
|
|
54
|
+
| Cursor | `followup_message` with a loop limit |
|
|
55
|
+
| Amp | `agent.end → continue` |
|
|
56
|
+
| Ralph loop | A stop hook with a completion promise and an iteration cap |
|
|
57
|
+
| Gemini CLI | `complete_task` is "the ONLY way to finish" |
|
|
58
|
+
| Cline | `attempt_completion` with a double check |
|
|
59
|
+
|
|
60
|
+
## Decision
|
|
61
|
+
|
|
62
|
+
1. **Stop gate.** An extension at Pi's `agent_before_settle` boundary (`sessions/stopGate.ts`) runs
|
|
63
|
+
in every attended top-level run, structured and terminal. It is off in plan, command, automatic,
|
|
64
|
+
subagent and other related runs.
|
|
65
|
+
- When the reply's own `todo_write` list holds an open item and nothing was declared with
|
|
66
|
+
`finish`, it appends a displayed `xingular-stop-gate` message naming the open items and
|
|
67
|
+
continues the same run.
|
|
68
|
+
- It nudges at most three times per reply, and never again after a nudge that produced no tool
|
|
69
|
+
call other than `todo_write` or `finish`.
|
|
70
|
+
- It is silent for a reply with no todo list or a complete one, an aborted or failed reply, a
|
|
71
|
+
slice the guard ended, or a continuation another handler already requested.
|
|
72
|
+
- Each nudge is an `extension.notice` from `stop-gate`.
|
|
73
|
+
- It is deterministic: it reads the todo list and the declaration, never a model judgment.
|
|
74
|
+
2. **`finish`.** This is the one explicit way to stop with work open (`tools/finish.ts`):
|
|
75
|
+
- `blocked` or `needs_decision` with a reason, plus an optional `needs`;
|
|
76
|
+
- `done` is refused while any item is open;
|
|
77
|
+
- read-only and plan-safe.
|
|
78
|
+
3. **Honest stop codes.** A reply that settles with open items is `interrupted`, never `completed`:
|
|
79
|
+
- `needs_person` after a `finish` declaration;
|
|
80
|
+
- otherwise `unfinished`.
|
|
81
|
+
The runner (or the terminal extension) writes its checkpoint from evidence: done and next from the
|
|
82
|
+
todo list, blocked from the declaration, files and checks from the reply. Neither auto-continues;
|
|
83
|
+
the person continues the run. (A terminal reply that ended at its work-slice budget, not one of
|
|
84
|
+
these, continues in place since ADR-0070.)
|
|
85
|
+
4. **No model-written checkpoint.** `checkpoint_write` is removed. At a work-slice budget the guard
|
|
86
|
+
asks the model to stop and report, and the harness writes the checkpoint. A capability set pinned
|
|
87
|
+
before the removal gets `finish` in its place.
|
|
88
|
+
5. **One budget per reply.** The work-slice guard and the gate reset only on a person's message
|
|
89
|
+
(`before_agent_start` with `messageType: 'user'`). Pi emits `agent_start` for every continuation,
|
|
90
|
+
so resetting there gave every nudge, delivered subagent result or plan repair a fresh 320-call
|
|
91
|
+
budget.
|
|
92
|
+
6. **Exit ramps rewritten.**
|
|
93
|
+
- `role` names the only reasons to stop, and the gate.
|
|
94
|
+
- `TODO_GUIDANCE` asks for a list that is true at all times.
|
|
95
|
+
- `## What would make this complete` applies only when the work stopped short (blocked, needing
|
|
96
|
+
the person, or handed back by the guard), "never stop early in order to write this section".
|
|
97
|
+
- The `Progress` group explains the gate and `finish`.
|
|
98
|
+
- The terminal's launch tools now include `finish`, so its prompt says so.
|
|
99
|
+
7. **Subagent tool mismatch is visible.** `spawn_subagent` returns the child's effective `tools`, and
|
|
100
|
+
the read-only profiles say in their first line when a brief needs a tool they lack.
|
|
101
|
+
|
|
102
|
+
## Consequences
|
|
103
|
+
|
|
104
|
+
- A reply with open todos costs up to three more model requests before it is handed back. A reply
|
|
105
|
+
without a todo list costs nothing extra.
|
|
106
|
+
- A model can still stop with work open, but only by naming a blocker (`needs_person`) or by
|
|
107
|
+
exhausting the gate (`unfinished`). Both are visible in the record and offer Continue.
|
|
108
|
+
- Hosts must accept the two new stop codes (`10-server-protocol.md`). The external App needs a
|
|
109
|
+
release that shows Continue for them.
|
|
110
|
+
- The stable prefix changes once (`role`, `TODO_GUIDANCE`, `reporting`, `Progress`). Measured with
|
|
111
|
+
real requests only, under INV-PRM-8.
|
|
112
|
+
- A live terminal session keeps the code and pack it started with. The gate reaches it only after a
|
|
113
|
+
rebuild and a restart.
|
|
114
|
+
- **Measure:**
|
|
115
|
+
- the share of runs that end with open todos (baseline 81 of 207 `model_behaviour` runs);
|
|
116
|
+
- nudges per run (expected mostly 0–1; more than 3 in a row means the gate's test is wrong);
|
|
117
|
+
- the `unfinished` and `needs_person` rates.
|
|
118
|
+
|
|
119
|
+
## Alternatives considered
|
|
120
|
+
|
|
121
|
+
- **Widen `continueSlice` to `completed` runs with open todos** (STUDY-0004 option 2). Rejected for
|
|
122
|
+
the first layer: it starts a new run per continuation, needs `continuationOf` to reopen a
|
|
123
|
+
completed run, and does not cover the terminal, where the failing session ran. The gate keeps one
|
|
124
|
+
run and works on both surfaces.
|
|
125
|
+
- **Keep `checkpoint_write` and reword it.** Rejected: any always-available "record where you
|
|
126
|
+
stopped" tool is a sign-off. The harness already derives a better record from evidence.
|
|
127
|
+
- **A model-judged goal evaluator** (Claude Code `/goal`). Rejected, as in STUDY-0004: it adds a
|
|
128
|
+
model call per reply and judges only what the transcript shows.
|
|
129
|
+
- **Prompt only** (ADR-0068 as it stood). Rejected: the record shows the wording does not hold under
|
|
130
|
+
long tasks, and it cannot reach a live session.
|