@junghanacs/entwurf 0.12.9 → 0.13.0

package/scripts/agy-bridge-config.py

@@ -32,27 +32,42 @@ Subcommands (argv[1]):
       <target>` prefix / `invalid-json` / `not-configured` / `command <cmd>`. Never mutates.
 
   permission-install <settings_path> <state_path>
-      The OTHER half of "agy can call our bridge": registering the server (above) makes the tool
+      The OTHER half of "agy can call our bridge": registering the server (above) makes the tools
       reachable, but agy's permission engine defaults every `mcp` action to Ask, so every single
-      entwurf_v2 call stops for a y/n. This adds our allow rule to agy's settings.json.
+      call stops for a y/n. This adds our allow rules to agy's settings.json.
 
-      Ownership is ELEMENT-level, not subtree: we own exactly the string
-      `mcp(entwurf-bridge/entwurf_v2)` inside `permissions.allow`. The operator's own rules
-      (command(*), their ask/deny lists, everything else) are ours to preserve, never to manage —
-      granting ourselves broad permissions would be a trust decision that is not the installer's
-      to make. Same discipline as the single mcpServers key above. Idempotent; refuses a symlink.
+      Ownership is ELEMENT-level, not subtree: we own exactly the strings
+      `mcp(entwurf-bridge/<tool>)` for the tools the normal agy workflow calls, inside
+      `permissions.allow`. Every tool the server exposes is visible to the model; these are the
+      ones we auto-grant, which is a smaller set on purpose.
+      The operator's own rules (command(*), their ask/deny lists, everything else) are ours to
+      preserve, never to manage — granting ourselves broad permissions would be a trust decision
+      that is not the installer's to make. Same discipline as the single mcpServers key above.
+      Idempotent; refuses a symlink.
 
   permission-uninstall <state_path>
-      Honest inverse: remove OUR rule only if WE added it (an operator who already had the rule
-      keeps it), then drop the `allow`/`permissions` containers only if we created them and they
-      are now empty. Removes the settings file only if we created it and nothing else remains.
+      Honest inverse: remove each of OUR rules only if WE added that one (an operator who already
+      had a rule keeps it), then drop the `allow`/`permissions` containers only if we created them
+      and they are now empty. Removes the settings file only if we created it and nothing remains.
 
   permission-doctor <settings_path>
       One token line: `absent` / `invalid-json` / `not-configured` / `configured` /
-      `shadowed-by-<list> <rule>`. The shadow check exists because agy evaluates
+      `partially-configured <missing...>` / `covered-by-allow <rule>` /
+      `shadowed-by-<list> <broad|exact> <rule>`. The shadow check exists because agy evaluates
       Deny > Ask > Allow: an operator rule like `mcp(*)` in their ask list SILENTLY defeats our
       allow, and agy starts prompting again with our install still green. That would be a
-      debugging hole ("why is it asking me every time?"), so the doctor names it instead.
+      debugging hole ("why is it asking me every time?"), so the doctor names it instead — with
+      the SCOPE, because a broad rule takes every tool while an exact one takes only its own.
+
+  permission-state-doctor <state_path>
+      Is the OWNERSHIP RECORD itself readable? `absent` / `ok <n>` / `corrupt <why>`. Separate from
+      permission-doctor, which reads the settings file: runtime can be perfect while the record that
+      distinguishes our grants from the operator's is unreadable (hard rule 13, two axes). Uses the
+      same strict parser as install/uninstall, so "readable" has one definition. Never mutates.
+
+  permission-rules
+      Print the allow rules we own, space-separated. The single source the shell and gates render
+      from, so operator messages can never drift from what install actually writes.
 
 Exit codes: 0 ok · 2 no-state · 3 refuse-symlink · 4 invalid-json · 5 usage.
 """
@@ -62,23 +77,48 @@ import os
 import sys
 
 SERVER_KEY = "entwurf-bridge"
-STATE_SCHEMA_VERSION = 1
-
-# The ONE permission rule we own. Scoped to a single tool on our own server — not mcp(*), not the
-# server-wide mcp(entwurf-bridge): an installer grants itself the narrowest rule that makes the
-# thing it installed work, and nothing more. INSTALL still writes only this.
-ALLOW_RULE = f"mcp({SERVER_KEY}/entwurf_v2)"
-# Rules that MATCH our tool: the exact grant, the server-wide rule, and the action wildcard.
+# TWO independent state files, TWO independent schemas. They are versioned apart because they
+# change apart: widening the permission rule set says nothing about the MCP install-state's shape,
+# and stamping a bump onto a file whose layout never moved makes the version a lie — the next reader
+# to branch on it would be branching on noise.
+STATE_SCHEMA_VERSION = 1  # MCP install-state (server key + preimage); shape unchanged
+# 2: permission state records a rule SET (`rules` / `rulesExistedBefore`) instead of a single
+# `rule` / `ruleExistedBefore`. Install migrates a v1 state in place; uninstall reads both shapes.
+PERMISSION_STATE_SCHEMA_VERSION = 2
+
+# The permission rules we own — one per tool the NORMAL agy workflow calls. (Every tool the server
+# exposes is visible to the model; auto-granting is the smaller, deliberate set.) Each is
+# scoped to a single tool on our own server: not mcp(*), not the server-wide mcp(entwurf-bridge).
+# An installer grants itself the narrowest rules that make the thing it installed work, and nothing
+# more; three narrow grants are still narrow, and none of them is a trust decision about anyone
+# else's server.
+#
+# Granting ONLY entwurf_v2 was a shipped defect (measured 2026-07-27 on a live agy citizen): agy
+# defaults every mcp action to Ask, so `entwurf_peers` and `entwurf_self` stopped for a y/n on
+# EVERY call. The bridge was registered and two thirds of it was unusable — the same failure the
+# doctor already names for entwurf_v2, just never checked for the other two.
+#
+# The two tools deliberately NOT here, because a grant we do not need is a grant we should not take:
+#   entwurf_inbox_read   — native-push has no inbox to drain. An agy citizen has no meta-mailbox
+#                          directory at all (measured), so granting it would pre-approve a rail this
+#                          backend does not have.
+#   entwurf_register_native — explicit/manual fallback, not the normal birth path (DELIVERY.md):
+#                          agy births automatically from PreInvocation. Auto-approving a registration
+#                          verb the normal path never calls is exactly the excess this list avoids.
+ALLOW_RULES = tuple(f"mcp({SERVER_KEY}/{tool})" for tool in ("entwurf_v2", "entwurf_peers", "entwurf_self"))
+# Rules that MATCH one of our tools: its exact grant, the server-wide rule, and the action wildcard.
 # Membership here is a statement about agy's matcher, not about which list the rule sits in — the
-# same three rules cover entwurf_v2 wherever they appear. From a higher-precedence list they
-# override our allow (shadowing); from `allow` itself they already grant it (covering).
+# same rules cover our tools wherever they appear. From a higher-precedence list they override our
+# allow (shadowing); from `allow` itself they already grant it (covering). SCOPE differs, though:
+# the two broad rules cover every tool on the server, an exact rule only its own.
 #
-# The doctor used to read them ONE WAY ONLY — shadowing — and demanded a literal ALLOW_RULE string
+# The doctor used to read them ONE WAY ONLY — shadowing — and demanded a literal own-rule string
 # in `allow`. So a host whose operator had granted a broad `mcp(*)` (their trust decision, not
 # ours) was reported as "NOT granted, agy prompts on EVERY entwurf_v2 call": a false red about a
 # surface that in fact works. Reading the same coverage in both directions is the fix; treating
 # mcp(*) as matching in deny/ask but not in allow was never defensible.
-MATCHING_RULES = (ALLOW_RULE, f"mcp({SERVER_KEY})", "mcp(*)")
+BROAD_RULES = (f"mcp({SERVER_KEY})", "mcp(*)")  # cover EVERY tool on our server, not just one
+MATCHING_RULES = ALLOW_RULES + BROAD_RULES
 SHADOWING_RULES = MATCHING_RULES  # same set, higher-precedence lists
 # Deny > Ask > Allow (agy permissions engine).
 SHADOWING_LISTS = ("deny", "ask")
@@ -135,6 +175,68 @@ def _prior_state(state_path: str, managed_key: str, managed_path: str) -> dict:
     return prior
 
 
+class _PermissionStateError(Exception):
+    """A permission install-state we refuse to act on. Raised, not exited, so the doctor can REPORT
+    corruption while install/uninstall REFUSE on it — one parser, three honest reactions."""
+
+
+def _parse_permission_state(state: dict) -> tuple:
+    """Validate a permission install-state; return (rules, {rule: was-it-already-theirs}).
+
+    Two shapes, because install/uninstall/doctor can all meet a state file an older entwurf wrote:
+    schemaVersion 2 carries `rules` + `rulesExistedBefore`; schemaVersion 1 carried a single `rule`
+    + `ruleExistedBefore`. Either way the answer is the same question asked per rule, and a rule the
+    operator already had is theirs in both.
+
+    STRICT, because the failure mode deletes someone else's configuration. A missing or non-boolean
+    provenance entry read as "not theirs" silently promotes the operator's own rule to ours and the
+    inverse takes it away — `rulesExistedBefore: {}` alone would revoke every rule in the file. An
+    unknown version, a wrong type, or an INCOMPLETE provenance map is an error, never a permissive
+    default. Refusing is recoverable; deleting a grant we never owned is not.
+
+    ONE parser for every caller. Install used to do its own shallow shape check (dict? values bool?)
+    which an EMPTY map passed — `all()` of nothing is true — so a corrupt prior state was silently
+    overwritten with freshly re-captured provenance, the exact re-capture the state file exists to
+    prevent. A second, laxer copy of a strict rule is the same as not having the rule.
+    """
+    version = state.get("schemaVersion")
+    if version == PERMISSION_STATE_SCHEMA_VERSION:
+        rules = state.get("rules")
+        existed = state.get("rulesExistedBefore")
+        if not isinstance(rules, list) or not rules or not all(isinstance(r, str) for r in rules):
+            raise _PermissionStateError(
+                "`rules` must be a non-empty list of strings — refusing to guess which rules are ours")
+        if not isinstance(existed, dict):
+            raise _PermissionStateError(
+                "`rulesExistedBefore` must be an object — refusing to act on unreadable provenance")
+        missing = [r for r in rules if not isinstance(existed.get(r), bool)]
+        if missing:
+            raise _PermissionStateError(
+                f"no boolean provenance for {' '.join(missing)} — refusing to treat a rule that may "
+                "be the operator's as ours")
+        return tuple(rules), {r: existed[r] for r in rules}
+    if version == 1:
+        legacy = state.get("rule")
+        owned = state.get("ruleExistedBefore")
+        if not isinstance(legacy, str) or not isinstance(owned, bool):
+            raise _PermissionStateError(
+                "schemaVersion 1 needs a string `rule` and a boolean `ruleExistedBefore`")
+        return (legacy,), {legacy: owned}
+    raise _PermissionStateError(
+        f"unknown schemaVersion {version!r} — this entwurf does not know which rules that install "
+        "owned and will not touch any")
+
+
+def _owned_rules(state: dict) -> list:
+    """The rules in this install-state that are OURS to remove — never the operator's."""
+    try:
+        rules, existed = _parse_permission_state(state)
+    except _PermissionStateError as exc:
+        _die(4, f"agy-bridge: permission install-state is unusable — {exc}. Check permissions.allow "
+                "yourself, then delete the state file by hand if it is genuinely stale.")
+    return [r for r in rules if not existed[r]]
+
+
 def cmd_install(config_path: str, command: str, state_path: str) -> None:
     # REFUSE a symlink — it is someone else's SSOT (an agent-config link). Never clobber.
     if os.path.islink(config_path):
@@ -294,33 +396,62 @@ def cmd_permission_install(settings_path: str, state_path: str) -> None:
     # rule, we did not add it, so uninstall must not take it away. On a RE-install the rule on disk
     # is our own previous write — reading it as "pre-existing" would hand the operator credit for
     # our entry and strand it forever. So provenance is taken from the first install and carried.
-    on_disk = ALLOW_RULE in allow  # what the file says NOW (may be our own earlier write)
-    rule_existed = on_disk
+    on_disk = {rule: rule in allow for rule in ALLOW_RULES}  # what the file says NOW
+    # Provenance is PER RULE. A host can easily have granted one of these by hand (agy's own
+    # "always allow" prompt persists exactly one rule at a time — that is how an operator ends up
+    # owning entwurf_self while entwurf owns entwurf_v2), and a set-wide flag would either strand
+    # their rule or take it away. Each rule carries its own answer to "was this yours before us?".
+    rules_existed = dict(on_disk)
     prior = _prior_state(state_path, "managedSettingsPath", settings_path)
     if prior:
-        rule_existed = prior.get("ruleExistedBefore", rule_existed)
         detect_mode = prior.get("detectMode", detect_mode)
         settings_existed = prior.get("settingsExistedBefore", settings_existed)
         permissions_existed = prior.get("permissionsExistedBefore", permissions_existed)
         allow_existed = prior.get("allowExistedBefore", allow_existed)
-    if ALLOW_RULE not in allow:
-        allow.append(ALLOW_RULE)
+        # Carry recorded provenance forward, branching on the VERSION rather than on which keys
+        # happen to be present — a duck-typed read of a malformed state is how a wrong answer here
+        # becomes a deleted operator rule at uninstall time. A rule the prior state never described
+        # (a tool we only started granting now) keeps the preimage we just read from disk, which is
+        # the first honest observation we have of it.
+        # The SAME strict parser uninstall uses. A prior state we cannot read is a REFUSAL, not a
+        # licence to re-capture: overwriting it would replace the operator's recorded answer with a
+        # fresh reading of a file we ourselves wrote, which is precisely what this state file exists
+        # to prevent. Only rules the prior state actually RECORDED are carried; a tool we started
+        # granting later keeps the preimage read from disk, its first honest observation.
+        try:
+            _prior_rules, prior_existed = _parse_permission_state(prior)
+        except _PermissionStateError as exc:
+            _die(4, f"agy-bridge: prior permission install-state is unusable — {exc}. Refusing to "
+                    "overwrite provenance this entwurf cannot read; inspect it by hand.")
+        for rule in ALLOW_RULES:
+            if rule in prior_existed:
+                rules_existed[rule] = prior_existed[rule]
+    for rule in ALLOW_RULES:
+        if rule not in allow:
+            allow.append(rule)
 
     _atomic_write(settings_path, _dump(data))
 
     state = {
-        "schemaVersion": STATE_SCHEMA_VERSION,
+        "schemaVersion": PERMISSION_STATE_SCHEMA_VERSION,
         "managedSettingsPath": os.path.abspath(settings_path),
-        "rule": ALLOW_RULE,
+        "rules": list(ALLOW_RULES),
         "detectMode": detect_mode,
         "settingsExistedBefore": settings_existed,
         "permissionsExistedBefore": permissions_existed,
         "allowExistedBefore": allow_existed,
-        "ruleExistedBefore": rule_existed,  # true = the operator's rule, not ours to remove
+        # true = the operator's rule, not ours to remove
+        "rulesExistedBefore": {rule: rules_existed[rule] for rule in ALLOW_RULES},
         "installedAt": _now(),
     }
     _atomic_write(state_path, _dump(state))
-    sys.stdout.write(f"{'already-present' if on_disk else 'added'} {ALLOW_RULE}\n")
+    added = [rule for rule in ALLOW_RULES if not on_disk[rule]]
+    present = [rule for rule in ALLOW_RULES if on_disk[rule]]
+    if added:
+        sys.stdout.write(f"added {' '.join(added)}\n" if not present else
+                         f"added {' '.join(added)} (already-present {' '.join(present)})\n")
+    else:
+        sys.stdout.write(f"already-present {' '.join(ALLOW_RULES)}\n")
 
 
 def cmd_permission_uninstall(state_path: str) -> None:
@@ -331,6 +462,17 @@ def cmd_permission_uninstall(state_path: str) -> None:
     if not isinstance(settings_path, str):
         _die(4, f"agy-bridge: permission install-state {state_path} has no managedSettingsPath")
 
+    # DECIDE BEFORE MUTATING. Per rule: the operator already had it before us → it is theirs; leave
+    # it. Reads a v1 state (single `rule`) as well as v2, so an uninstall from an older install-state
+    # still removes exactly what that install added and nothing else.
+    #
+    # This runs FIRST, ahead of every write and removal, because a refusal has to leave the world
+    # untouched. It used to be computed inside the settings-exists branch and then, for a host whose
+    # settings file was gone, first reached only in the closing message — AFTER `os.remove(state_path)`
+    # had already run. A malformed state on such a host was "refused" with the state file deleted:
+    # the one record of what we owed the operator, destroyed by the safety check itself.
+    ours = _owned_rules(state)
+
     if os.path.islink(settings_path):
         _die(3, f"agy-bridge: refusing to uninstall — {settings_path} became a symlink since install "
                 f"(someone else's SSOT now). Resolve by hand.")
@@ -340,9 +482,8 @@ def cmd_permission_uninstall(state_path: str) -> None:
         perms = data.get("permissions")
         if isinstance(perms, dict):
             allow = perms.get("allow")
-            # The operator already had the rule before us → it is theirs; leave it.
-            if isinstance(allow, list) and not state.get("ruleExistedBefore", False):
-                perms["allow"] = [r for r in allow if r != ALLOW_RULE]
+            if isinstance(allow, list) and ours:
+                perms["allow"] = [r for r in allow if r not in ours]
                 # Drop only the containers WE created, and only while they are empty. An operator
                 # who has since added their own rules keeps their structure untouched.
                 if not state.get("allowExistedBefore", False) and perms["allow"] == []:
@@ -356,7 +497,8 @@ def cmd_permission_uninstall(state_path: str) -> None:
             _atomic_write(settings_path, _dump(data))
 
     os.remove(state_path)
-    sys.stdout.write(f"uninstalled {ALLOW_RULE} from {settings_path}\n")
+    what = " ".join(ours) if ours else "(nothing — every rule was already the operator's)"
+    sys.stdout.write(f"uninstalled {what} from {settings_path}\n")
 
 
 def cmd_permission_doctor(settings_path: str) -> None:
@@ -376,30 +518,77 @@ def cmd_permission_doctor(settings_path: str) -> None:
     # Precedence FIRST (Deny > Ask > Allow): a matching rule in a higher list means agy prompts (or
     # blocks) no matter what our allow says. Reporting `configured` there would be a green light on
     # a surface that is actually still stopping every call.
-    for list_name in SHADOWING_LISTS:
-        rules = perms.get(list_name)
-        if not isinstance(rules, list):
-            continue
-        for rule in rules:
-            if rule in SHADOWING_RULES:
-                sys.stdout.write(f"shadowed-by-{list_name} {rule}\n")
-                return
+    # SCOPE is part of the truth. `mcp(*)` and the server-wide `mcp(entwurf-bridge)` shadow every
+    # tool we grant; an exact rule like `mcp(entwurf-bridge/entwurf_self)` shadows ONLY that one and
+    # the other tools keep working. Both are red — but telling an operator that every entwurf call
+    # is blocked when only `entwurf_self` is would send them hunting the wrong thing. Broad first,
+    # so a host carrying both is described by the rule that actually covers the most.
+    # TWO passes over ALL the shadowing lists, not one pass per list. Broad-most-covering is a
+    # statement about the whole file: a deny of one exact tool alongside an ask of the server-wide
+    # rule is a host where EVERYTHING is shadowed, and reporting the exact hit merely because `deny`
+    # is scanned first would tell the operator "your other grants still work" while agy prompts on
+    # all of them. Precedence still decides WHICH list to name once the scope is settled.
+    for rule_set, scope in ((BROAD_RULES, "broad"), (ALLOW_RULES, "exact")):
+        for list_name in SHADOWING_LISTS:
+            rules = perms.get(list_name)
+            if not isinstance(rules, list):
+                continue
+            for rule in rules:
+                if rule in rule_set:
+                    sys.stdout.write(f"shadowed-by-{list_name} {scope} {rule}\n")
+                    return
 
     allow = perms.get("allow")
     if isinstance(allow, list):
-        if ALLOW_RULE in allow:
+        # EVERY tool we grant must be granted. A partial set is not a working surface: agy stops for
+        # a y/n on whichever tool is missing, which is the same "registered and unusable" state the
+        # doctor already refuses to call green — it was simply never checked past entwurf_v2.
+        if all(rule in allow for rule in ALLOW_RULES):
             sys.stdout.write("configured\n")
             return
-        # No rule of ours, but a BROADER operator rule in the same list already matches our tool.
-        # agy will not prompt; the call works. Say so — and say whose rule is carrying it, because
-        # the day the operator narrows that wildcard, our unowned grant disappears with it.
+        # Not every rule of ours is here, but a BROADER operator rule in the same list already
+        # matches our tools. agy will not prompt; the calls work. Say so — and say whose rule is
+        # carrying it, because the day the operator narrows that wildcard, the unowned grant goes.
         for rule in MATCHING_RULES:
-            if rule != ALLOW_RULE and rule in allow:
+            if rule not in ALLOW_RULES and rule in allow:
                 sys.stdout.write(f"covered-by-allow {rule}\n")
                 return
+        missing = [rule for rule in ALLOW_RULES if rule not in allow]
+        if len(missing) != len(ALLOW_RULES):
+            # Some of ours are present and some are not: name the gap rather than report a flat
+            # "nothing granted", which would read as "install never ran" on a half-granted host.
+            sys.stdout.write(f"partially-configured {' '.join(missing)}\n")
+            return
     sys.stdout.write("not-configured\n")
 
 
+def cmd_permission_state_doctor(state_path: str) -> None:
+    """Is the ownership record itself readable? One token line: `absent` / `ok <n>` / `corrupt <why>`.
+
+    Hard rule 13 — runtime truth and OWNERSHIP truth are separate axes. The settings file can carry
+    all three exact rules (runtime perfectly fine, agy prompts on nothing) while the state that says
+    WHICH of them are ours is unreadable. The permission doctor reads settings and would call that
+    host `configured`; the independent state check read only `managedSettingsPath` and agreed. So a
+    corrupt ownership record rounded up to a green overall verdict, and the operator would learn
+    about it at uninstall time — the worst possible moment to discover we cannot tell their rules
+    from ours. Same parser as install/uninstall, so there is exactly one definition of readable.
+    """
+    if not os.path.exists(state_path):
+        sys.stdout.write("absent\n")
+        return
+    try:
+        state = _load_config(state_path)
+    except SystemExit:
+        sys.stdout.write("corrupt not valid JSON\n")
+        return
+    try:
+        rules, _existed = _parse_permission_state(state)
+    except _PermissionStateError as exc:
+        sys.stdout.write(f"corrupt {exc}\n")
+        return
+    sys.stdout.write(f"ok {len(rules)}\n")
+
+
 def _now() -> str:
     import datetime
 
@@ -426,6 +615,17 @@ def main(argv: list) -> None:
         if len(argv) != 3:
             _die(5, "usage: agy-bridge-config.py doctor-static <config_path>")
         cmd_doctor_static(argv[2])
+    elif sub == "permission-state-doctor":
+        if len(argv) != 3:
+            _die(5, "usage: agy-bridge-config.py permission-state-doctor <state_path>")
+        cmd_permission_state_doctor(argv[2])
+    elif sub == "permission-rules":
+        if len(argv) != 2:
+            _die(5, "usage: agy-bridge-config.py permission-rules")
+        # The shell renders these in operator messages. It reads them from HERE rather than
+        # repeating the strings, so the rule set has exactly one source and a tool added to
+        # ALLOW_RULES can never drift out of what the doctor tells the operator to fix.
+        sys.stdout.write(" ".join(ALLOW_RULES) + "\n")
     elif sub == "permission-install":
         if len(argv) != 4:
             _die(5, "usage: agy-bridge-config.py permission-install <settings_path> <state_path>")

package/scripts/agy-bridge.sh

@@ -39,12 +39,15 @@ COMMAND="${AGY_BRIDGE_COMMAND:-entwurf-bridge}"
 STATE_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/entwurf/agy-bridge"
 STATE_FILE="$STATE_DIR/install-state.json"
 # agy's settings.json — the SAME file the statusline adapter owns, but a DIFFERENT element: it owns
-# the `statusLine` subtree, we own one string in `permissions.allow`. Element-level ownership on
+# the `statusLine` subtree, we own a few strings in `permissions.allow`. Element-level ownership on
 # both sides is what lets two adapters share a file without either clobbering the other (or the
 # operator's own rules). Tracked in its own state file so each half has an honest inverse.
 SETTINGS_FILE="${AGY_SETTINGS_CONFIG:-$HOME/.gemini/antigravity-cli/settings.json}"
 PERMISSION_STATE_FILE="$STATE_DIR/permission-state.json"
-ALLOW_RULE="mcp(entwurf-bridge/entwurf_v2)"
+# One narrow allow rule per tool the NORMAL agy workflow calls (all five MCP tools are visible to
+# the model; these are the ones auto-granted). Read from the config engine, never retyped here:
+# a second copy of this list is a drift bug waiting for the next tool we ship.
+ALLOW_RULES="$(python3 "$CONFIG_PY" permission-rules)"
 
 log()  { printf '%s\n' "$*"; }
 fail() { printf 'FAIL: %s\n' "$*" >&2; exit 1; }
@@ -131,8 +134,8 @@ install_permission() {
   set -e
   case "$rc" in
     0) log "  permission: ${out} in $SETTINGS_FILE" ;;
-    3) fail "permission refused (symlink) — $SETTINGS_FILE is someone else's SSOT; left intact. The MCP server is registered but NOT granted, so agy would prompt on every entwurf_v2 call. Add '$ALLOW_RULE' to permissions.allow there, or replace the symlink with a regular file and re-run." ;;
-    4) fail "permission invalid JSON — $SETTINGS_FILE could not be parsed; left intact. The MCP server is registered but NOT granted, so agy would prompt on every entwurf_v2 call. Repair that file, then re-run." ;;
+    3) fail "permission refused (symlink) — $SETTINGS_FILE is someone else's SSOT; left intact. The MCP server is registered but NOT granted, so agy would prompt on every entwurf tool call. Add these to permissions.allow there: $ALLOW_RULES — or replace the symlink with a regular file and re-run." ;;
+    4) fail "permission invalid JSON — $SETTINGS_FILE could not be parsed; left intact. The MCP server is registered but NOT granted, so agy would prompt on every entwurf tool call. Repair that file, then re-run." ;;
     *) fail "permission could not be granted (rc=$rc) — ${out}" ;;
   esac
 }
@@ -162,7 +165,7 @@ do_uninstall() {
   case "$rc" in
     0) log "  permission: ${out}" ;;
     2) : ;;                              # never granted → nothing to undo (idempotent)
-    3) fail "permission refused (symlink) — $SETTINGS_FILE became a symlink since install; our rule is STILL THERE. Remove '$ALLOW_RULE' from permissions.allow by hand at the link target." ;;
+    3) fail "permission refused (symlink) — $SETTINGS_FILE became a symlink since install; our rules are STILL THERE. Remove ours from permissions.allow by hand at the link target: $ALLOW_RULES" ;;
     *) fail "permission could not be revoked (rc=$rc) — ${out}" ;;
   esac
 }
@@ -209,7 +212,14 @@ doctor_permission() {
   status="$(python3 "$CONFIG_PY" permission-doctor "$SETTINGS_FILE")"
   case "$status" in
     configured)
-      log "  permission ($SETTINGS_FILE): allow → '$ALLOW_RULE' (agy calls entwurf_v2 without prompting)"; return 0 ;;
+      log "  permission ($SETTINGS_FILE): allow → $ALLOW_RULES (agy calls every entwurf tool without prompting)"; return 0 ;;
+    partially-configured\ *)
+      # SOME of our tools are granted and some are not. agy stops for a y/n on exactly the missing
+      # ones, so the bridge half-works — the most confusing shape there is ("it worked yesterday
+      # when I sent a message, why is it asking now?"). Name the missing rules, never round up to
+      # configured because the tool the operator happened to try first was granted.
+      log "  permission ($SETTINGS_FILE): DRIFT — granted, but NOT for: ${status#partially-configured } . agy defaults mcp to Ask, so every call to those tools prompts. Fix: ./run.sh install-agy-bridge"
+      return 1 ;;
     covered-by-allow\ *)
       # The operator's own broader rule already grants our tool, so entwurf_v2 does NOT prompt —
       # calling this DRIFT would be a false red about a working surface. But it is THEIR rule, not
@@ -228,27 +238,45 @@ except Exception:
     sys.exit(1)
 p = s.get("managedSettingsPath")
 same = isinstance(p, str) and os.path.isabs(p) and os.path.abspath(p) == os.path.abspath(sys.argv[2])
-sys.exit(0 if same and s.get("ruleExistedBefore") is False else 1)' "$PERMISSION_STATE_FILE" "$SETTINGS_FILE"; then
-        log "  permission ($SETTINGS_FILE): DRIFT — entwurf installed '$ALLOW_RULE' here and it is now GONE. Your '$covering' still covers the tool, so agy does not prompt today — but the grant entwurf owns (and repairs) no longer exists. Fix: ./run.sh install-agy-bridge"
+# Owned = WE added at least one rule. schemaVersion 2 answers per rule (`rulesExistedBefore`);
+# schemaVersion 1 had a single `ruleExistedBefore`. Read both — an old state file must not silently
+# report "we own nothing" and turn owned drift into a green NOTE.
+existed = s.get("rulesExistedBefore")
+if isinstance(existed, dict):
+    owned = any(v is False for v in existed.values())
+else:
+    owned = s.get("ruleExistedBefore") is False
+sys.exit(0 if same and owned else 1)' "$PERMISSION_STATE_FILE" "$SETTINGS_FILE"; then
+        log "  permission ($SETTINGS_FILE): DRIFT — entwurf installed its allow rules here ($ALLOW_RULES) and they are now GONE. Your '$covering' still covers the tools, so agy does not prompt today — but the grant entwurf owns (and repairs) no longer exists. Fix: ./run.sh install-agy-bridge"
         return 1
       fi
-      log "  permission ($SETTINGS_FILE): NOTE — we own no rule here, but your '$covering' in permissions.allow already matches $ALLOW_RULE, so agy calls entwurf_v2 without prompting. That grant is YOURS: narrow '$covering' and entwurf_v2 starts prompting again. Run ./run.sh install-agy-bridge if you want the narrow rule owned (and repaired) by entwurf."
+      log "  permission ($SETTINGS_FILE): NOTE — we own no rule here, but your '$covering' in permissions.allow already matches our tools, so agy calls them without prompting. That grant is YOURS: narrow '$covering' and every entwurf tool starts prompting again. Run ./run.sh install-agy-bridge if you want the narrow rules ($ALLOW_RULES) owned (and repaired) by entwurf."
       return 0 ;;
     not-configured|absent)
-      local what="'$ALLOW_RULE' NOT granted"
+      local what="none of $ALLOW_RULES granted"
       [ "$status" = absent ] && what="settings file absent, so no grant"
       if [ "$installed" -eq 1 ]; then
-        log "  permission ($SETTINGS_FILE): DRIFT — $what, but the bridge IS installed. agy defaults mcp to Ask, so EVERY entwurf_v2 call prompts: the server is registered and unusable without a y/n. Fix: ./run.sh install-agy-bridge"
+        log "  permission ($SETTINGS_FILE): DRIFT — $what, but the bridge IS installed. agy defaults mcp to Ask, so EVERY entwurf tool call prompts: the server is registered and unusable without a y/n. Fix: ./run.sh install-agy-bridge"
         return 1
       fi
       log "  permission ($SETTINGS_FILE): $what (bridge not installed here — nothing to grant yet)"; return 0 ;;
     invalid-json)
       log "  permission ($SETTINGS_FILE): INVALID JSON — cannot read the permission engine's config"; return 1 ;;
     shadowed-by-*)
-      local list rule
+      local list rest scope rule
       list="${status%% *}"; list="${list#shadowed-by-}"
-      rule="${status#* }"
-      log "  permission ($SETTINGS_FILE): SHADOWED — your '$list' list carries '$rule', and agy evaluates Deny > Ask > Allow, so it OVERRIDES our allow of '$ALLOW_RULE'. agy will keep prompting (or blocking) on every entwurf_v2 call until that rule is narrowed."; return 1 ;;
+      rest="${status#* }"          # "<scope> <rule>"
+      scope="${rest%% *}"
+      rule="${rest#* }"
+      # Say what is actually blocked. A broad rule takes the whole server; an exact rule takes ONE
+      # tool and the rest keep working — reporting that as a total outage sends the operator hunting
+      # the wrong config. Red either way: a tool we grant that agy still stops on is not green.
+      if [ "$scope" = broad ]; then
+        log "  permission ($SETTINGS_FILE): SHADOWED — your '$list' list carries '$rule', and agy evaluates Deny > Ask > Allow, so it OVERRIDES our allow of $ALLOW_RULES. agy will keep prompting (or blocking) on EVERY entwurf tool call until that rule is narrowed."
+      else
+        log "  permission ($SETTINGS_FILE): SHADOWED — your '$list' list carries '$rule', and agy evaluates Deny > Ask > Allow, so it OVERRIDES our allow of that ONE tool. Our other grants still work; agy will keep prompting (or blocking) on that tool alone until the rule is removed."
+      fi
+      return 1 ;;
     *) log "  permission ($SETTINGS_FILE): unexpected status '$status'"; return 1 ;;
   esac
 }
@@ -323,6 +351,23 @@ do_doctor() {
     elif [ "$pmanaged" != "$expected_settings" ]; then
       log "  state: FOREIGN TARGET (permission) — permission-state manages '$pmanaged', but agy reads '$expected_settings'. The grant recorded there is not the grant on this host."
       hard_fail=1
+    else
+      # Pointing at the right file is not the same as being READABLE. The schema and the per-rule
+      # provenance are what tell OUR grants from the operator's; without them the inverse cannot run
+      # and we would only find out at uninstall time. Runtime can be perfect (all rules present, agy
+      # prompting on nothing) while this axis is broken — hard rule 13 keeps them separate, so this
+      # is red on its own evidence and never rounded up by a green permission line above.
+      local pstate
+      pstate="$(python3 "$CONFIG_PY" permission-state-doctor "$PERMISSION_STATE_FILE")"
+      case "$pstate" in
+        ok\ *) : ;;
+        corrupt\ *)
+          log "  state: CORRUPT (permission) — the ownership record cannot be read: ${pstate#corrupt }. Runtime may be fine, but entwurf can no longer tell ITS grants from yours, so uninstall will refuse. Fix: ./run.sh install-agy-bridge (or delete $PERMISSION_STATE_FILE by hand once you have checked permissions.allow yourself)."
+          hard_fail=1 ;;
+        *)
+          log "  state: unexpected permission-state verdict '$pstate'"
+          hard_fail=1 ;;
+      esac
     fi
   fi
 

package/scripts/check-acp-carrier-augment.ts

@@ -18,6 +18,7 @@ import { strict as assert } from "node:assert";
 import { mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 import type { Context } from "@earendil-works/pi-ai";
 import {
 	buildPiContextAugment,
@@ -32,6 +33,7 @@ import { buildClaudeSessionMeta } from "../pi-extensions/lib/acp/tool-surface.ts
 import { ENTWURF_PROJECT_CONTEXT_OPEN_TAG } from "../protocol.js";
 
 const tmp = mkdtempSync(join(tmpdir(), "acp-carrier-augment-"));
+const REPO_DIR = fileURLToPath(new URL("..", import.meta.url));
 const BRIDGE_MARK = "operating through entwurf";
 
 // ===========================================================================
@@ -285,7 +287,37 @@ function ctxWith(firstUser: string): Context {
 	writeFileSync(join(bigHome, "AGENTS.md"), "X".repeat(80 * 1024));
 	const big = buildPiContextAugment({ backend: "claude", cwd: tmp, mcpServerNames: [], homeDir: bigHome });
 	assert.ok(Buffer.byteLength(big, "utf8") <= 50 * 1024, "augment is truncated to the 50KB cap");
-	assert.match(big, /context augment truncated to \d+ bytes/, "truncation leaves an honest marker");
+	assert.match(
+		big,
+		/context augment truncated to \d+ bytes/,
+		"truncation leaves an honest marker [QK:AUGMENT-TRUNC-MARKER]",
+	);
+}
+
+// ===========================================================================
+// 9) The shipped repo AGENTS.md fits with a realistic operator-global budget.
+//    This guards the real 2026-07-27 failure: project AGENTS.md alone exceeded
+//    the cap, tail-cutting its own later rules plus Current date/cwd. The cap
+//    remains an honest fallback; the maintained package prompt must not hit it.
+// ===========================================================================
+{
+	const budgetHome = mkdtempSync(join(tmpdir(), "acp-budget-home-"));
+	writeFileSync(join(budgetHome, "AGENTS.md"), "H".repeat(12 * 1024));
+	const actual = buildPiContextAugment({
+		backend: "claude",
+		cwd: REPO_DIR,
+		mcpServerNames: ["entwurf-bridge"],
+		homeDir: budgetHome,
+	});
+	assert.doesNotMatch(
+		actual,
+		/context augment truncated/,
+		"repo AGENTS.md + 12KB global baseline fits without truncation [QK:AUGMENT-BUDGET-FITS]",
+	);
+	assert.ok(
+		actual.includes(`Current working directory: ${REPO_DIR}`),
+		"non-truncated augment retains the trailing cwd fact",
+	);
 }
 
 console.log(
@@ -293,5 +325,5 @@ console.log(
 		"empty/whitespace/missing → null, shipped-default → non-empty v1 lever (preset replaced), carrier absent → no _meta.systemPrompt key, carrier change → " +
 		"signature change (stable carrier → stable signature); augment: prepended on `new` only (reuse delta has none), " +
 		"wire-only so it never enters contextMessageSignatures, entwurf cwd/AGENTS.md de-dup (present → drop only that " +
-		"section, home kept; absent → kept), day-granularity date, 50KB truncation marker",
+		"section, home kept; absent → kept), day-granularity date, 50KB truncation marker, shipped AGENTS budget",
 );