Skip to content

Commit 62180da

Browse files
fix(agent-mode): the direction owns the pack change, not the caller (#323 review 2)
Seven findings from executing the routes the last round emitted. Three are the same defect the round before them was about, one directory down or one flag over; one is a security boundary the last round got wrong. **[P1] `--control-pack` on argv is not a human approval.** The reconciliation route was published as a coding-agent `edit` on the grounds that the value came from the command line rather than from inference. That is exactly backwards for the case that matters: a *governed* coding agent composes its own argv, so `init --write --control-pack read-only-agent` over a `financial-strict` manifest is a policy weakening an agent can request for itself — it drops `write` and `production_operation` obligations. The **direction** decides the owner now. A transition that keeps at least every obligation the manifest has today is an agent `edit`; one that drops any, or that names a pack this build cannot resolve, is `human_review_required` with no command, naming the effects and controls it would remove. `_weakened_pack_rules` moved to `core.control_packs.weakened_pack_obligations` beside the packs it compares, and `verify_policy` delegates: two implementations of "did this get weaker?" is how one of them stops seeing a downgrade (#410 §F). **[P1] The same-workspace capped retry dropped the invocation.** It is the one scope route that reruns *this* workspace, and it was built from the list a rerun in a **different** one may repeat — so `init --write --allow-unresolved-scope --max-python-files 1` emitted a retry without `--allow-unresolved-scope`, and following it returned the refusal it was issued to resolve, writing nothing. There are two lists now with one derivation: `_portable_setup_flags` is what transfers to another workspace, and `_invocation_flags` is that plus the two that only make sense in this one. The retry replaces the cap and nothing else. **[P2] Candidate commands dropped a raised parse cap.** It bounds how much is read, not which directory, so it transfers: without it a candidate inherited the root's truncation, refused again, and wrote no manifest while its `expects` promised one. It is in the portable list. **[P1] An adopted candidate lost the request one directory down.** `scope_candidate_actions` routes an adopted candidate to `doctor`, which reads a manifest that loads fine and advances to the gate under the pack that is *there*. Candidate routing now reconciles first, through the same shared route and the same ownership rule. **[P2] An explicit `--control-pack default` is a request.** Inferring "was this asked for?" by comparing against the default cannot see the one transition that can *only* weaken an existing manifest. Read from the parser instead — and note where the trap is: **typer vendors its own click**, so the returned `ParameterSource` is not the `click.core` enum and `is`/`==` against it are both false, silently, in the direction where every option reads as unasked. Compared by member name, with that written down. **[P2] The changelog contradicted itself** — one paragraph promised `execution: "failed"` on every failure envelope while another correctly documented the succeeded-refusal shape. It states only the schema-enforced invariants now. **[P3] A Windows-only test failure** — a hardcoded POSIX kit path in the parametrized argv expectation, derived from the `Path` now. Also: `docs/errors.json`'s `config_already_exists` hint still told consumers to hand-edit or delete the manifest, which is no longer the route that line carries; it describes the conditional routes and says why deleting is a person's decision rather than a recovery. Rebased onto main. **And one found while fixing.** The weakening route's prose ran past the 400-byte envelope cap, and the clause that got truncated was the one saying why a person owns the decision — leaving a route that read like a formatting quirk. The reason leads now and the effect list is fitted to what is left, the shape the placeholder review already uses. **Coverage executes the emitted commands**, as asked: the capped retry is followed and the manifest it promised has to exist; candidate commands are checked for the bound the root run was given; the adopted-candidate route is required not to be a `doctor` handoff while a request is outstanding; and the explicit-default case is paired with the omitted-flag control so neither can pass vacuously. The strengthening direction is pinned beside the weakening one for the same reason. Co-Authored-By: Claude Opus 5 <[email protected]>
1 parent abd9540 commit 62180da

13 files changed

Lines changed: 1012 additions & 144 deletions

‎CHANGELOG.md‎

Lines changed: 35 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -237,9 +237,11 @@
237237
payload to carry it. Every agent-mode error line from those three commands
238238
now carries the same envelope its `--json` payload would, projected from the
239239
same selected route as `next_action` and `next_actions[]`, so the three
240-
cannot disagree. A failure envelope is fail-closed by construction:
241-
`execution: "failed"`, `decision: "setup_incomplete"`, and every field of
242-
`permissions` false. Two lines still carry none, by design and by
240+
cannot disagree. What every setup error line guarantees is what the schema
241+
enforces for any setup envelope: `decision_source: "setup"`, a decision from
242+
the setup vocabulary, every field of `permissions` false, and never
243+
`control_state: "complete"` — the `execution` split is described below. Two
244+
lines still carry none, by design and by
243245
documentation: the shared `--workspace` refusal fires before a workspace
244246
exists, and `environment_error` is emitted before Agents Shipgate is running.
245247
Runtime contract 26 → 27; both the `AgentControl` union and the envelope
@@ -274,6 +276,36 @@
274276
`--minimal` and following it wrote a detected manifest where a legacy
275277
template was asked for.
276278

279+
**A pack change an agent asked for is not a pack change a human approved.**
280+
The reconciliation route above was published as a coding-agent `edit` because
281+
the value came from the command line rather than from inference. A *governed*
282+
coding agent composes its own argv, so that is not authenticated human
283+
provenance: `init --write --control-pack read-only-agent` over a
284+
`financial-strict` manifest drops `write` and `production_operation`
285+
obligations, and an agent could have requested it for itself. The direction
286+
decides the owner now — a transition that keeps every obligation the manifest
287+
has today is an agent edit, one that drops any obligation (or names a pack
288+
this build cannot resolve) is a human review naming what it would remove. The
289+
comparison is `weakened_pack_obligations`, moved beside the packs it compares
290+
and shared with the `control_pack_weakened` check rather than restated.
291+
292+
"Asked for" is read from the argument parser, not inferred by comparing
293+
against the default: an explicit `--control-pack default` over a
294+
`financial-strict` manifest is a request, and the only one that can *only*
295+
weaken.
296+
297+
**Scoped routing owed the same two things.** The capped retry is the one
298+
scope route that reruns the *same* workspace, and it was built from the list a
299+
rerun in a different one may repeat — so it dropped
300+
`--allow-unresolved-scope` and returned the refusal it was issued to resolve.
301+
Candidate commands dropped a raised `--max-python-files`, which bounds how
302+
much is read rather than which directory, so a candidate inherited the root's
303+
truncation and refused again while its `expects` promised a manifest. And an
304+
adopted candidate whose manifest selects a different pack went to `doctor`,
305+
losing the request one directory down. There are now two lists with one
306+
derivation — what transfers to another workspace, and that plus the two that
307+
only make sense in this one.
308+
277309
**`execution` is not a marker for "this line is an error".** The `error`
278310
field is. `execution` says whether the command reached an answer about the
279311
workspace, and both values occur on error lines: `"failed"` where it could

‎STABILITY.md‎

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -114,11 +114,26 @@ the "already exists — edit it directly or remove it before re-running init
114114
`next_action.kind == "edit"` here now sees `"command"` — **except** when this
115115
invocation asked for a manifest configuration the existing manifest does not
116116
carry. `init --write --control-pack <id>` over a manifest selecting a different
117-
pack now routes to an `edit` naming `policies.control_pack` and the exact value,
118-
because both onward routes would otherwise advance under the pack that is
119-
*there* and the request would be lost without anything saying so. "Asked for"
120-
means `--control-pack` at other than its default, the same rule that decides
121-
whether a recovery command repeats the flag.
117+
pack routes to a reconciliation naming `policies.control_pack` and the exact
118+
value, because both onward routes would otherwise advance under the pack that
119+
is *there* and the request would be lost without anything saying so. The same
120+
reconciliation is published for a scoped **candidate** project whose manifest
121+
selects a different pack, where the candidate's `doctor` route had the same
122+
effect.
123+
124+
"Asked for" is read from the argument parser rather than inferred by comparing
125+
against the default. An explicit `--control-pack default` over a
126+
`financial-strict` manifest is a request — and the only one that can *only*
127+
weaken — so a default-comparison could not see it.
128+
129+
**The owner of that route is the direction, not the caller.** A governed coding
130+
agent writes its own argv, so command-line arguments are not authenticated
131+
human provenance for loosening a gate. A transition that keeps at least every
132+
obligation the manifest has today is `agent_action_required` with a typed
133+
`edit`. One that drops any obligation, or that names a pack this build cannot
134+
resolve, is `human_review_required` with no command and names what it would
135+
remove. The comparison is `weakened_pack_obligations`, shared with the
136+
`control_pack_weakened` check rather than restated.
122137

123138
**2.** Every recovery command `init` publishes now repeats the **whole**
124139
invocation with only the invalid value corrected. They were built from the

‎docs/agent-contract-current.md‎

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -66,13 +66,27 @@ owes. The exit code (2) and the "already exists — edit it directly or remove
6666
it" sentence are unchanged.
6767

6868
**Unless the request was not applied.** `init --write --control-pack <id>` over
69-
a manifest that selects a different pack keeps an `edit` route, now naming
69+
a manifest that selects a different pack keeps a reconciliation route naming
7070
`policies.control_pack` and the exact value. Both onward routes would otherwise
7171
advance under the pack that is *there*, and the request would be lost with
7272
nothing saying so — a recovery that completes with less than the caller asked
73-
for reports success for work it did not do. "Asked for" means `--control-pack`
74-
at other than its default, the same rule that decides whether a recovery
75-
command repeats the flag.
73+
for reports success for work it did not do. The same reconciliation is
74+
published for a scoped **candidate** whose manifest selects a different pack,
75+
where a bare `doctor` had the same effect one directory down.
76+
77+
"Asked for" is read from the parser, not inferred: an explicit
78+
`--control-pack default` over a `financial-strict` manifest **is** a request,
79+
and it is the one that can only weaken.
80+
81+
**Who owns that edit is decided by the direction, not by who typed the flag.**
82+
A governed coding agent composes its own argv, so process arguments are not
83+
authenticated human provenance. A transition that keeps at least every
84+
obligation the manifest has today is `agent_action_required` with a typed
85+
`edit`; one that drops any obligation — or names a pack this build cannot
86+
resolve, where the direction is unprovable — is `human_review_required` with no
87+
command, naming the effects and controls it would remove. That is the same
88+
direction `verify_policy` raises `control_pack_weakened` for, computed by the
89+
same function.
7690

7791
**Two command values also move.** Every recovery `init` publishes now repeats
7892
the whole invocation with only the invalid value corrected — `--minimal`,

‎docs/errors.json‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,10 @@
4545
"additional_fields": [
4646
"path",
4747
"next_action",
48-
"next_actions"
48+
"next_actions",
49+
"control"
4950
],
50-
"recovery_hint": "Read the existing manifest. If it's stale, hand-edit it. If you want a fresh template anyway, delete the existing file first. `init --write` is intentionally write-once."
51+
"recovery_hint": "Follow `next_actions[0]` — this line carries an authoritative route (contract v27), and which one it is depends on what the run asked for. When the manifest already satisfies this invocation the route is `doctor` on it, which reports what that manifest still owes. When the run asked for a `--control-pack` the manifest does not select, the route names `policies.control_pack` and the exact value — a coding-agent `edit` when the change only tightens the gate, and a human `review` when it would require less of any effect, because command-line arguments are not a human approval for loosening one. An unresolved human-owned declaration outranks both, and that route names the field and the line. `init --write` is intentionally write-once: deleting the manifest to get a fresh template discards the declarations in it, which is a decision for a person rather than a recovery."
5152
},
5253
{
5354
"id": "input_parse_error",

‎llms-full.txt‎

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1504,13 +1504,27 @@ owes. The exit code (2) and the "already exists — edit it directly or remove
15041504
it" sentence are unchanged.
15051505

15061506
**Unless the request was not applied.** `init --write --control-pack <id>` over
1507-
a manifest that selects a different pack keeps an `edit` route, now naming
1507+
a manifest that selects a different pack keeps a reconciliation route naming
15081508
`policies.control_pack` and the exact value. Both onward routes would otherwise
15091509
advance under the pack that is *there*, and the request would be lost with
15101510
nothing saying so — a recovery that completes with less than the caller asked
1511-
for reports success for work it did not do. "Asked for" means `--control-pack`
1512-
at other than its default, the same rule that decides whether a recovery
1513-
command repeats the flag.
1511+
for reports success for work it did not do. The same reconciliation is
1512+
published for a scoped **candidate** whose manifest selects a different pack,
1513+
where a bare `doctor` had the same effect one directory down.
1514+
1515+
"Asked for" is read from the parser, not inferred: an explicit
1516+
`--control-pack default` over a `financial-strict` manifest **is** a request,
1517+
and it is the one that can only weaken.
1518+
1519+
**Who owns that edit is decided by the direction, not by who typed the flag.**
1520+
A governed coding agent composes its own argv, so process arguments are not
1521+
authenticated human provenance. A transition that keeps at least every
1522+
obligation the manifest has today is `agent_action_required` with a typed
1523+
`edit`; one that drops any obligation — or names a pack this build cannot
1524+
resolve, where the direction is unprovable — is `human_review_required` with no
1525+
command, naming the effects and controls it would remove. That is the same
1526+
direction `verify_policy` raises `control_pack_weakened` for, computed by the
1527+
same function.
15141528

15151529
**Two command values also move.** Every recovery `init` publishes now repeats
15161530
the whole invocation with only the invalid value corrected — `--minimal`,

‎src/agents_shipgate/checks/verify_policy.py‎

Lines changed: 9 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,6 @@
5959
control_phrase,
6060
effect_phrase,
6161
join_phrases,
62-
ordered_controls,
6362
)
6463
from agents_shipgate.core.check_ids import (
6564
SPLIT_CHECK_ID_ALIASES,
@@ -69,6 +68,7 @@
6968
from agents_shipgate.core.control_packs import (
7069
BUILTIN_CONTROL_PACKS,
7170
DEFAULT_CONTROL_PACK_ID,
71+
weakened_pack_obligations,
7272
)
7373
from agents_shipgate.core.policy_reason_codes import (
7474
POLICY_BASE_ABSENT_CHECK_ID,
@@ -368,29 +368,17 @@ def _weakened_pack_rules(
368368
) -> list[tuple[str, list[str]]]:
369369
"""Effects the head pack requires less of than the base pack did.
370370
371-
``None`` on the base side means the snapshot predates the field, which is
372-
by construction the ``default`` rule set — that build could not have
373-
loaded a manifest naming a pack. It is resolved to ``default`` and
374-
compared rather than skipped, so the "no pack is weaker than default"
375-
invariant is enforced here instead of assumed: if a weaker pack were ever
376-
added, this comparison would report it rather than stay silent.
371+
Delegates to :func:`weakened_pack_obligations`, which is where the rule
372+
lives now that the setup routes ask the same question: ``init`` deciding
373+
whether a requested pack change may be an agent-owned edit needs exactly
374+
this answer, and two implementations of "did this get weaker?" is how one
375+
of them ends up not seeing a downgrade (#410 §F).
377376
378-
An id neither side's build knows is handled before this is called: see
379-
``_unrecognized_pack_ids`` and the fail-safe branch in ``_compare``.
377+
Unresolvable ids never reach here — ``_compare`` routes them to the
378+
fail-safe first, because "cannot compare" is not "nothing changed".
380379
"""
381380

382-
base_pack = BUILTIN_CONTROL_PACKS.get(base_pack_id or DEFAULT_CONTROL_PACK_ID)
383-
head_pack = BUILTIN_CONTROL_PACKS.get(head_pack_id or DEFAULT_CONTROL_PACK_ID)
384-
# Unresolvable ids never reach here — ``_compare`` routes them to the
385-
# fail-safe first, because "cannot compare" is not "nothing changed".
386-
if base_pack is None or head_pack is None or base_pack.id == head_pack.id:
387-
return []
388-
weakened: list[tuple[str, list[str]]] = []
389-
for effect in sorted(base_pack.obligations):
390-
dropped = base_pack.obligations_for(effect) - head_pack.obligations_for(effect)
391-
if dropped:
392-
weakened.append((effect, ordered_controls(dropped)))
393-
return weakened
381+
return weakened_pack_obligations(base_pack_id, head_pack_id)
394382

395383

396384
@lru_cache(maxsize=1)

0 commit comments

Comments
 (0)