Python owns
the loop

ticket = open("ticket.md").read()

while True:                                 # 1. no round count, no dollar cap
    reply = model(
        "Improve this ticket until it is DONE.\n" + ticket
    )
    if "DONE" in reply:                     # 2. stop is a token the model may emit
        open("ticket.md", "w").write(reply) # 3. writer overwrites the ticket it graded
        break
    ticket = reply                          # 4. next turn's memory is a string in RAM

1. 1. The loop never counts rounds or dollars. There is no exit except vocabulary.
2. 2. Stop lives in the model. "DONE" is a token the author is allowed to emit.
3. 3. The writer is the grader. The same string that claims completeness overwrites the ticket.
4. 4. There is no evidence file. The next turn's memory is a string in RAM.

WRITE_TOOLS = ("Edit", "Write", "NotebookEdit")   # 1. tools that can change a file
READ_TOOLS = ("Read", "Glob", "Grep")

LOOPS = {
    "enhancer": ("orchestrator", "doer", "judge"),  # 2. exactly three names
}

PURPOSE = {
    "orchestrator": "Owns the budget and the order. Writes nothing.",
    "doer": "Edits the ticket body. Nothing else in the repo.",
    "judge": "Scores the attempt. Reads reports and the diff. Holds no write path.",
}

READERS = ("orchestrator", "judge", "researcher")  # 3. roles that hold no write tool

FALLBACK_SCOPE = {
    "doer": (("tickets/**",), ()),                 # 4. when .loop.yml is silent
}

@dataclass(frozen=True)
class RolePlan:
    name: str
    purpose: str
    tools: tuple[str, ...]
    allow: tuple[str, ...] = ()
    deny: tuple[str, ...] = ()

    @property
    def can_write(self) -> bool:
        return any(tool in WRITE_TOOLS for tool in self.tools)   # 5. computed, not declared

1. 1. If a role's tool list contains none of these, the role cannot write. That is the definition, and nothing else gets a say in it.
2. 2. The cast for this loop is three names. A runtime that starts a fourth role has drifted from the table.
3. 3. A sentence saying "do not write files" can be ignored. A missing Write tool cannot be called.
4. 4. The target repo's .loop.yml knows nothing about the doer, so Python falls back to tickets/** and nothing else.
5. 5. can_write is membership in WRITE_TOOLS. If it is false and a runtime still hands the role Write, the runtime is wrong.

NO_WRITE = ["Edit", "Write", "NotebookEdit", "Bash"]   # 1. one longer than WRITE_TOOLS

def options_for(contract, loop: str = DEFAULT_LOOP):
    # ...
        tools = list(source["tools"]) if source else list(role.tools)
        if enhancer:
            tools = [tool for tool in tools if tool not in NO_WRITE]   # 2. strip
            if role.name == "doer":
                tools.append("Agent")                                  # 3. read-only Explore
        agents[name] = AgentDefinition(
            description=description,
            prompt=prompt,
            tools=tools,
            disallowedTools=NO_WRITE if enhancer or not role.can_write else NO_SHELL,  # 4.
            maxTurns=DEFAULT_MAX_TURNS,
            background=False,
            model="sonnet",
        )
    # ...
    if enhancer:
        kwargs.update(
            allowed_tools=["Agent"],       # 5. the parent may only spawn a named subagent
            disallowed_tools=NO_WRITE,
        )

1. 1. Bash is on the list because Bash is how a read only agent writes anyway.
2. 2. Every enhancer subagent loses Edit, Write, NotebookEdit and Bash. The judge cannot write the ticket it grades and the doer cannot write it either.
3. 3. The doer may spawn the built in read only explorer, which gets its own context too. Python still owns every candidate write.
4. 4. Repeating the list on disallowedTools is how an inherited Write does not sneak back in from the parent session.
5. 5. If the parent still held Write, it could skip the doer and edit the repo itself.

def scope_hook(repo: Path, role: RolePlan):
    """A PreToolUse hook that denies a write outside this role's scope.

    Returning an empty dict means "no opinion", which lets the call through.
    Denying needs the full hookSpecificOutput shape, so a typo here fails open.
    """
    scope = WriteScope(allow=list(role.allow), deny=list(role.deny))

    async def check(input_data, tool_use_id, context):
        if input_data["tool_name"] not in ("Edit", "Write", "NotebookEdit"):
            return {}                       # 1. a tool that cannot write
        raw = next(
            (input_data["tool_input"][k] for k in PATH_KEYS if k in input_data["tool_input"]),
            None,
        )
        if raw is None:
            return {}                       # 2. no path to check
        relative = _relative(repo, raw)
        if relative is not None and scope.permits(relative):
            return {}                       # 3. inside tickets/** for the doer
        where = relative or f"{raw} (outside the target repo)"
        return {
            "hookSpecificOutput": {         # 4. deny is a nested object
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",     # 5. the string, not False
                "permissionDecisionReason": (
                    f"{role.name} may write {', '.join(role.allow) or 'nothing'}. "
                    f"{where} is outside that scope."
                ),
            }
        }

    return check

1. 1. Three separate allow paths all return the same empty dictionary, which is also the shape a bug returns.
2. 2. Nothing to check means nothing to deny.
3. 3. A path the scope permits is allowed the same silent way.
4. 4. Miss the outer key and the SDK reads the return as no opinion.
5. 5. false, blocked and no are not deny. A path outside the target repo fails closed.

REQUIRED = {
    "bug": ["title", "steps", "expected", "actual", "environment"],
    "feature": ["problem", "proposal", "value", "criteria"],
    "ui": ["problem", "proposal", "value", "criteria", "wireframe"],
}


def check(kind: str, present_fields: list[str]) -> dict:
    if kind not in REQUIRED:
        raise ValueError(f"unknown ticket kind {kind!r}, expected one of {sorted(REQUIRED)}")
    required = REQUIRED[kind]
    present = set(present_fields)
    missing_fields = [f for f in required if f not in present]   # 1. computed here
    return {
        "kind": kind,
        "present_fields": [f for f in required if f in present], # 2. intersection only
        "missing_fields": missing_fields,
        "ready": not missing_fields,                             # 3. a boolean
    }

1. 1. The function never reads a ready key out of the model payload.
2. 2. A field the model invents is dropped rather than counted. It is not evidence.
3. 3. A bug does not need problem, proposal and value. A UI ticket needs a wireframe on top of the feature fields.

def check(
    round_: int,
    budget: int,
    signature: list[str],
    previous_signature: list[str] | None,
    usd: float = 0.0,
    max_usd: float | None = None,
    turns: int = 0,
    max_turns: int | None = None,
) -> dict:
    if previous_signature is not None and signature == previous_signature:
        return {"stop": True, "reason": "same signature two rounds running"}   # 1.
    if max_usd is not None and usd >= max_usd:
        return {"stop": True, "reason": "cost budget spent"}                   # 2.
    if max_turns is not None and turns >= max_turns:
        return {"stop": True, "reason": "max turns"}                           # 3.
    if round_ + 1 >= budget:
        return {"stop": True, "reason": "budget spent"}                        # 4.
    return {"stop": False, "reason": None}

1. 1. Stable failure. Two rounds found exactly the same gaps.
2. 2. Dollars are a hard cap. The figure comes from the SDK result, not from a role's word.
3. 3. Turns are a hard cap too.
4. 4. Four returns in Python. Completing a ticket is a different exit, owned by the orchestrator. The model cannot type a fifth return.

    def _improve(self, tkt, verdict: dict, comment: str | None, issue: int) -> list[str]:
        """Keep the draft only when it strictly closes gaps."""
        before = set(verdict["missing_fields"])
        candidate = self.draft(tkt, verdict["kind"], verdict["missing_fields"], comment)
        try:
            after_verdict = self.judge(candidate)
            after = set(after_verdict["missing_fields"])
            if after < before:                            # 1. proper subset, equal is not progress
                shutil.copyfile(candidate, tkt.path)      # 2. only Python copies
                set_front_matter(
                    tkt.path, id=tkt.id, state="draft", loop="enhancer", github_issue=str(issue)
                )
                self.gh.set_body(issue, strip_front_matter(tkt.path.read_text(encoding="utf-8")))
                self.gh.add_label(issue, "enhanced")
                return sorted(after)
            self.gh.comment(
                issue,
                f"The draft did not clear the rubric for a {verdict['kind']} ticket. "
                f"Still missing {', '.join(verdict['missing_fields'])}.",
            )
            return sorted(before)
        finally:
            candidate.unlink(missing_ok=True)             # 3. the candidate always dies

1. 1. A draft that trades value for criteria looks busy. That is how a loop spends its whole budget standing still.
2. 2. The doer and the judge hold no write tool, so the promotion from candidate to ticket is the orchestrator's move.
3. 3. Accepted or rejected, the candidate file is removed in finally.

def test_the_hook_allows_a_write_inside_scope(repo, doer):
    assert call(repo, doer, file_path=str(repo / "tickets" / "T001.md")) == {}   # 1.


def test_the_hook_denies_a_write_outside_scope(repo, doer):
    """The full shape matters. A typo anywhere in it fails open."""
    output = call(repo, doer, file_path=str(repo / "app" / "models.py"))["hookSpecificOutput"]
    assert output["hookEventName"] == "PreToolUse"                               # 2.
    assert output["permissionDecision"] == "deny"
    assert "outside that scope" in output["permissionDecisionReason"]


def test_a_path_outside_the_repo_is_denied(repo, doer):
    """Fail closed. A path outside the repo matches no allow rule for any role."""
    result = call(repo, doer, file_path="/etc/hosts")                            # 3.
    output = result["hookSpecificOutput"]
    assert output["permissionDecision"] == "deny"
    assert "outside the target repo" in output["permissionDecisionReason"]

1. 1. Recording the happy empty dictionary means a later change cannot silently start denying the doer's own scope.
2. 2. Every key in the deny envelope is asserted, because any one of them is the typo that fails open.
3. 3. A path that matches no allow rule does not get a free pass for failing to look like a ticket.

git clone https://github.com/RichardHightower/reliable-agentic-lab.git
cd reliable-agentic-lab/solutions/sol1_enhancer_agent_sdk

task setup     # folder-local .venv plus the Agent SDK and pytest
task table     # the role table. judge must print no in the writes column
task checks    # both demo assertion scripts
task test      # pytest against a stubbed SDK. no key, no clone

role              writes  scope
orchestrator      no      nothing
doer              yes     tickets/**
judge             no      nothing