Clone-when-needed is implied but never stated, so agents report it as a blocker #1227

New issue

Open

opened 2026-08-24 22:52:14 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-24 22:52:14 +00:00

Owner

What happened

During a long analysis session on 2026-08-24 the agent needed the coilysiren/lore working tree to author two composed sources. No checkout existed in the native session shadow. The agent reported this as a blocker across three separate turns, filed the content as Forgejo issues instead, and told Kai the skill authoring was "blocked on a lore checkout".

Kai's response: "checkout lore please - standing instructions should say to checkout any repo you need when you need it??? if not then make a fj issue".

She was right. The clone took one command and succeeded on the first try with the credentials already present.

Why the agent read it as blocked

The governing rule is Unlisted repository clones stay temporary in the universal base:

Before cloning a repository, the agent checks the host's expected-repositories list when that surface is configured. If the repository is not explicitly listed as one that belongs on disk, the agent clones it into the resolved temporary directory with a task-specific basename, never under the persistent projects or workspace tree, treats that clone as task-scoped, and removes it once the work is complete and remote-checkpoint requirements are satisfied. An absent or unreadable list does not authorize a persistent checkout.

Read carefully, this presupposes cloning is permitted and only governs where the clone lands. Read quickly, every clause is a restriction: check a list first, do not use the persistent tree, an absent list does not authorize. The section title leads with "stay temporary". The final sentence is a denial. Nothing anywhere states the affirmative case.

The result is a rule that answers "where do I put a clone" while never answering "may I clone", and an agent pattern-matching on caution concludes it may not.

Why this matters beyond one session

This is the same failure shape as a deferral announced in chat. The agent had read-only access it already held, a rule that permitted the action, and it still stopped and handed the work back. Front-load the context you know you need already says naming a gap is not closing it, and that an identified gap is a task rather than a disclaimer when the information is reachable with access the agent already holds. Fetching a repository is exactly that case, and the clone rule's framing works against it.

Proposed change

Add an affirmative opening sentence to the section, so the permission is stated before the constraint:

Fetch what you need. When a task requires a repository the agent does not have on disk, the agent clones it rather than reporting the absent checkout as a blocker. The rules below govern where the clone lands, not whether to make one.

Then the existing paragraph follows unchanged. Consider also renaming the section from Unlisted repository clones stay temporary to something that leads with the action rather than the restriction, for example Clone what you need, keep unlisted clones temporary.

Scope note

This is a wording change to the universal base only. It grants no new authority: read-only cloning of a repository the agent can already authenticate to was permitted before and remains so. Nothing about credentials, push rights, persistent-tree placement, or the serialized-checkout inversion changes.

coilysiren/lore issues 23 and 24, the work that stalled behind this
The Front-load the context you know you need and A deferral owes its issue sections, which this sits between in spirit

## What happened During a long analysis session on 2026-08-24 the agent needed the `coilysiren/lore` working tree to author two composed sources. No checkout existed in the native session shadow. The agent **reported this as a blocker across three separate turns**, filed the content as Forgejo issues instead, and told Kai the skill authoring was "blocked on a lore checkout". Kai's response: "checkout lore please - standing instructions should say to checkout any repo you need when you need it??? if not then make a fj issue". She was right. The clone took one command and succeeded on the first try with the credentials already present. ## Why the agent read it as blocked The governing rule is **Unlisted repository clones stay temporary** in the universal base: > Before cloning a repository, the agent checks the host's expected-repositories list when that surface is configured. If the repository is not explicitly listed as one that belongs on disk, the agent clones it into the resolved temporary directory with a task-specific basename, never under the persistent projects or workspace tree, treats that clone as task-scoped, and removes it once the work is complete and remote-checkpoint requirements are satisfied. An absent or unreadable list does not authorize a persistent checkout. Read carefully, this **presupposes** cloning is permitted and only governs *where the clone lands*. Read quickly, every clause is a restriction: check a list first, do not use the persistent tree, an absent list does not authorize. The section title leads with "stay temporary". The final sentence is a denial. Nothing anywhere states the affirmative case. The result is a rule that answers "where do I put a clone" while never answering "may I clone", and an agent pattern-matching on caution concludes it may not. ## Why this matters beyond one session This is the same failure shape as a deferral announced in chat. The agent had read-only access it already held, a rule that permitted the action, and it still stopped and handed the work back. `Front-load the context you know you need` already says naming a gap is not closing it, and that an identified gap is a task rather than a disclaimer when the information is reachable with access the agent already holds. Fetching a repository is exactly that case, and the clone rule's framing works against it. ## Proposed change Add an affirmative opening sentence to the section, so the permission is stated before the constraint: > **Fetch what you need.** When a task requires a repository the agent does not have on disk, the agent clones it rather than reporting the absent checkout as a blocker. The rules below govern where the clone lands, not whether to make one. Then the existing paragraph follows unchanged. Consider also renaming the section from **Unlisted repository clones stay temporary** to something that leads with the action rather than the restriction, for example **Clone what you need, keep unlisted clones temporary**. ## Scope note This is a wording change to the universal base only. It grants no new authority: read-only cloning of a repository the agent can already authenticate to was permitted before and remains so. Nothing about credentials, push rights, persistent-tree placement, or the serialized-checkout inversion changes. ## Related - `coilysiren/lore` issues 23 and 24, the work that stalled behind this - The `Front-load the context you know you need` and `A deferral owes its issue` sections, which this sits between in spirit

coilyco-ops added the

role/platform

priority

labels

2026-08-25 08:11:43 +00:00

coilyco-ops added the

autonomy

async-consult

label

2026-08-25 09:30:45 +00:00