@kylecheng3146/agent-ops 0.2.3 → 0.2.5

package/README.md

@@ -325,9 +325,11 @@ and a missing second verdict is NOT_RUN. A same-target pair is still
 independent because the sessions and clones are fresh.
 
 Host network or loopback restrictions return `REVIEW_NOT_RUN` before any
-reviewer is started. A trusted outer host runner may rerun the exact same
-command once with both capabilities; the result remains NOT_RUN if that host
-is unavailable. There is no automatic permission bypass inside the repository.
+reviewer is started. The managed instructions require a trusted outer host
+runner to start the exact same command with both capabilities on its first
+invocation; an in-sandbox retry is not an elevation. The result remains
+`NOT_RUN` if that host is unavailable. There is no repository-level permission
+bypass.
 Reviewer attempts and preflight diagnostics remain visible in JSON. `--yes` is
 required because a complete run spends provider quota twice.
 

package/dist/runtime/src/install/harness.js

@@ -282,6 +282,18 @@ export function resolveHarnessSelection(value) {
 export const COMMON_AGENTS_BLOCK = DESCRIPTORS.codex.control.routing.desired;
 export const COMMON_CLAUDE_BLOCK = DESCRIPTORS.claude.control.routing.desired;
 export const COMMON_GEMINI_BLOCK = DESCRIPTORS.agy.control.routing.desired;
+function subagentInstruction(descriptor) {
+    // ponytail: keyed by instruction file, not harness id — codex and opencode
+    // share .agent-ops/AGENTS.md and install dedupe requires identical content.
+    switch (descriptor.control.instructionFile) {
+        case "CLAUDE.md":
+            return "Delegate it with the Task tool.";
+        case "GEMINI.md":
+            return "Delegate it with `invoke_subagent`: `research` for read-only scans, `self` for a bounded edit.";
+        default:
+            return "Delegate it with this harness's subagent or task tool when it has one; otherwise run the same bounded steps sequentially in this session.";
+    }
+}
 export function managedRules(descriptor, context) {
     const lines = [
         "# Loop Engineering",
@@ -296,10 +308,10 @@ export function managedRules(descriptor, context) {
         ""
     ];
     if (context.capabilities.includes("rules")) {
-        lines.push("For every change:", "", "1. Define two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope and preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain complete independent review before claiming completion, via", "   `agent-ops review --task <task-id> --yes` (or the CLI's equivalent invocation).", "   Never call a", "   review-target CLI (agy, codex, claude) directly — direct calls skip", "   the enforced read-only sandbox flags and can hang or fail on command", "   permission prompts.", "   Review runs exactly two fresh sessions: with three configured targets,", "   set `AGENT_OPS_HOST` to the current CLI id so it is excluded; with two", "   targets both run in configured order; with one target it runs twice.", "   The first session is necessary; a PASS then requires an adversarial", "   re-check carrying the first report. A first FAIL or NOT_RUN stops.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "exact matching trust record. Confirmed project init/update grants it", "automatically when verification commands are configured.", "");
+        lines.push("For every change:", "", "1. Define two to five mechanically verifiable acceptance criteria.", "2. Inspect the smallest relevant scope and preserve unrelated changes.", "3. Apply the smallest safe change.", "4. Run evidence-producing verification for every criterion.", "5. Obtain complete independent review before claiming completion, via", "   `agent-ops review --task <task-id> --yes` (or the CLI's equivalent invocation).", "   Never call a", "   review-target CLI (agy, codex, claude) directly — direct calls skip", "   the enforced read-only sandbox flags and can hang or fail on command", "   permission prompts.", "   Start this command through the trusted outer host runner as its first", "   and only invocation. On Codex, the outer tool request must use", "   `sandbox_permissions: \"require_escalated\"` so network and loopback", "   are available; in that same request, unset", "   `CODEX_SANDBOX_NETWORK_DISABLED` and set `AGENT_OPS_HOST` when three", "   targets are configured. The Codex shell form is", "   `env -u CODEX_SANDBOX_NETWORK_DISABLED AGENT_OPS_HOST=<current-host> agent-ops review --task <task-id> --yes`.", "   Do not run it once in the restricted sandbox and retry; changing the", "   variable inside that sandbox is not elevation.", "   Review runs exactly two fresh sessions: with three configured targets,", "   set `AGENT_OPS_HOST` to the current CLI id so it is excluded; with two", "   targets both run in configured order; with one target it runs twice.", "   The first session is necessary; a PASS then requires an adversarial", "   re-check carrying the first report. A first FAIL or NOT_RUN stops.", "", "Treat `.agent-ops/config.json` as verifier authority. Discovery output is", "only a proposal until a user confirms it. Repository commands require an", "exact matching trust record. Confirmed project init/update grants it", "automatically when verification commands are configured.", "");
     }
     if (context.capabilities.includes("task")) {
-        lines.push("Split a change that exceeds five acceptance criteria into subtasks:", "`agent-ops task create --parent <task-id>` records one, and", "`agent-ops task status --parent <task-id>` lists them. Each subtask", "carries its own criteria, verification, and independent review;", "completing one never completes its parent.", "");
+        lines.push("Split a change that exceeds five acceptance criteria into subtasks:", "`agent-ops task create --parent <task-id>` records one, and", "`agent-ops task status --parent <task-id>` lists them. Each subtask", "carries its own criteria, verification, and independent review;", "completing one never completes its parent.", "", "Delegate a subtask whose scope spans unknown files, broad scans, or an", "independent workstream instead of doing it inline. Name the bounded", "scope, the artifact to return, and the acceptance criteria it serves.", subagentInstruction(descriptor), "Read every returned artifact back yourself: integration, verification,", "and review stay with the coordinator.", "", "One writer at a time. `agent-ops verify` and `agent-ops review`", "fingerprint the working tree and report UNKNOWN when anything else", "writes it during the run, so delegate edits to one subagent at a time,", "or give each writer its own Git worktree and merge before verifying.", "Read-only delegation has no such limit and may run in parallel.", "");
     }
     if (context.capabilities.includes("lifecycle-summary")) {
         lines.push("Advisory lifecycle summaries and local logs are informational. Advisory", "failures must remain fail-open and cannot become verification evidence.", "");

package/dist/runtime/src/review/render.js

@@ -90,8 +90,9 @@ export function renderReviewResult(result) {
             lines.push(`Run: ${verifyCommand}, then run this review again.`);
         }
         if (result.reason === "host-required") {
-            lines.push("No reviewer ran: the host runner must restart this exact review with " +
-                "network and loopback permission.");
+            lines.push("No reviewer ran: start the outer host runner before the first invocation " +
+                "and run this exact review with network and loopback permission; do not " +
+                "retry inside the restricted sandbox.");
         }
         if (result.reason === "host-identity-required") {
             lines.push("Three configured targets require AGENT_OPS_HOST=agy|claude|codex; " +

package/dist/runtime/src/task/service.js

@@ -187,8 +187,11 @@ export class TaskService {
         const now = assertTimestamp(this.#now());
         return await this.#store.mutate((state) => {
             const record = findTask(state, taskId);
-            if (record.status !== "active") {
-                throw taskError("TASK_NOT_ACTIVE", "Only an active task can be attached to a session.");
+            // A completed task still accepts attachment: the completion gate wants
+            // the session bound to a completed task, so refusing here would make
+            // "complete, then attach" an unrecoverable order.
+            if (record.status === "archived") {
+                throw taskError("TASK_NOT_ACTIVE", "An archived task cannot be attached to a session.");
             }
             const currentIndex = state.sessions.findIndex((attachment) => attachment.sessionId === sessionId);
             const attachment = { sessionId, taskId, attachedAt: now };

package/docs/en/guides/configuration.md

@@ -93,10 +93,11 @@ would consume the following flag instead. It deliberately does not pass
 `--disable-slash-commands`, which disables plan-mode behavior.
 
 Host network or loopback restrictions return `REVIEW_NOT_RUN` before any
-reviewer is started. A trusted outer host runner may rerun the exact same
-command once with both capabilities; an in-sandbox retry is not an elevation
-and cannot produce a PASS. Every attempt, preflight result, and diagnostic is
-preserved in human and JSON output.
+reviewer is started. The managed instructions require a trusted outer host
+runner to start the exact same command with both capabilities on its first
+invocation; an in-sandbox retry is not an elevation and cannot produce a PASS.
+Every attempt, preflight result, and diagnostic is preserved in human and JSON
+output.
 
 Capability checks and model starts are reported on stderr, including under
 `--json`; stdout remains one final JSON envelope and raw reviewer output is

package/docs/en/spec/delegation.md

@@ -19,3 +19,13 @@ The coordinator MUST retain ownership of final integration and verification.
 - Evidence: The coordinator records the final command output.
 - Positive: `Reviewer reports PASS; coordinator reruns typecheck and tests.`
 - Negative: `Accept the delegated claim without inspecting the diff.`
+
+## DELEGATE-ISOLATION-001
+
+Concurrent delegated writers MUST NOT share one working tree.
+
+- Trigger: More than one delegated agent would edit files for the same task.
+- Action: Run delegated edits one at a time, or give each writer its own Git worktree and merge before verification.
+- Evidence: `agent-ops verify` returns a status other than `UNKNOWN` for the run.
+- Positive: `Read-only scans run in parallel; the single edit runs in the coordinator worktree.`
+- Negative: `Two subagents edit the same files while verification runs.`

package/docs/en/spec/review.md

@@ -93,9 +93,10 @@ before any reviewer invocation.
 - Trigger: The host declares disabled network or the loopback probe fails.
 - Action: Return `REVIEW_NOT_RUN / host-required` with the host restriction.
 - Evidence: `attempts` is empty and no target preflight or reviewer process ran.
-- Positive: A trusted outer host runner can retry the exact command once with both capabilities.
+- Positive: A trusted outer host runner starts the exact command once with both capabilities before any reviewer invocation.
 - Negative: Treat a child login error as proof that an authenticated reviewer is unavailable.
 
+The managed host instructions require this handoff before the first command.
 There is no repository-level permission bypass. An unavailable outer host runner
 MUST leave the result NOT_RUN rather than manufacture PASS.
 

package/docs/zh-TW/guides/configuration.md

@@ -82,9 +82,10 @@ agent-ops 刻意不傳會繞過權限邊界的 `--dangerously-skip-permissions`
 使 plan mode 失效的 `--disable-slash-commands`。
 
 Host 缺少 network 或 loopback 權限時，會在啟動任何 reviewer 前回傳
-`REVIEW_NOT_RUN`。可信任的外部 host runner 可以用兩項權限重跑同一個完整
-指令一次；在原 sandbox 內重試不算升權，也不能產生 PASS。文字與 JSON 輸出
-都會保留每次 attempt、preflight 與 diagnostic。
+`REVIEW_NOT_RUN`。Managed 規則要求可信任的外部 host runner 在第一次呼叫時
+就用兩項權限啟動同一個完整指令；不要先在原 sandbox 執行再重試，因為那不算
+升權，也不能產生 PASS。文字與 JSON 輸出都會保留每次 attempt、preflight 與
+diagnostic。
 
 Capability check 與模型啟動進度都寫到 stderr，包括 `--json` 模式；stdout
 仍只有最終 JSON envelope，且不會串流 reviewer 原始輸出。SIGINT 或 SIGTERM

package/docs/zh-TW/spec/delegation.md

@@ -21,3 +21,13 @@ English source version: 2026-07-23. Revalidate: when the English specification c
 - Evidence: 協調者記錄最終命令輸出。
 - Positive: `審查者回傳 PASS；協調者重新跑 typecheck 與測試。`
 - Negative: `不看 diff 就接受委派者的完成宣告。`
+
+## DELEGATE-ISOLATION-001
+
+並行的委派寫入者 MUST NOT 共用同一個工作區。
+
+- Trigger: 同一任務中有超過一個委派 agent 會修改檔案。
+- Action: 讓委派的修改依序進行，或為每個寫入者配置獨立 Git worktree，合併後再驗證。
+- Evidence: `agent-ops verify` 該次執行回傳非 `UNKNOWN` 的狀態。
+- Positive: `唯讀掃描並行執行；唯一的修改在協調者工作區進行。`
+- Negative: `兩個 subagent 在驗證執行期間修改相同檔案。`

package/docs/zh-TW/spec/review.md

@@ -86,11 +86,12 @@ fail closed。
 - Trigger: host 宣告 network disabled 或 loopback probe 失敗。
 - Action: 回傳 `REVIEW_NOT_RUN / host-required` 與 host restriction。
 - Evidence: `attempts` 為空，沒有 target preflight 或 reviewer process 執行。
-- Positive: 可信任的外部 host runner 可在具兩項能力的主機重跑同一指令一次。
+- Positive: 可信任的外部 host runner 在任何 reviewer invocation 前，以兩項能力啟動同一指令一次。
 - Negative: 把 child login error 當作 authenticated reviewer 不可用的證明。
 
-repository 不提供 permission bypass。外部 host runner 不可用時，結果 MUST 保持
-NOT_RUN，不得製造 PASS。
+Managed host 規則要求在第一次呼叫前完成這個 handoff。repository 不提供
+permission bypass。外部 host runner 不可用時，結果 MUST 保持 NOT_RUN，不得
+製造 PASS。
 
 ## REVIEW-EVIDENCE-001
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kylecheng3146/agent-ops",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Evidence-driven development loops for agy, Codex, Claude Code, and opencode",
   "type": "module",
   "license": "MIT",