@kylecheng3146/agent-ops 0.2.4 → 0.2.6

package/dist/runtime/src/hooks/completion-gate.js

@@ -7,6 +7,9 @@ import { collectBaseChangePaths, collectChangeSurface } from "../verify/change-s
 import { calculateSourceFingerprint } from "../verify/source-fingerprint.js";
 const FINGERPRINT = /^[a-f0-9]{64}$/u;
 const SESSION = /^[^\0\r\n]{1,256}$/u;
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\"'\"'")}'`;
+}
 function gateResult(action, status, code, remedy) {
     return { action, status, code, ...(remedy === undefined ? {} : { remedy }) };
 }
@@ -142,7 +145,7 @@ export class CompletionGateService {
         }
         catch (error) {
             return error instanceof AgentOpsError && error.code === "TASK_SESSION_UNATTACHED"
-                ? gateResult("block", "FAIL", "COMPLETION_GATE_TASK_REQUIRED", "Attach this conversation to a formal task.")
+                ? gateResult("block", "FAIL", "COMPLETION_GATE_TASK_REQUIRED", `Attach this conversation to a formal task: agent-ops task create --title <title> --criterion <json> --criterion <json> (two to five criteria), then agent-ops task attach --task <task-id> --session ${shellQuote(sessionId)}.`)
                 : gateResult("block", "UNKNOWN", "COMPLETION_GATE_TASK_UNAVAILABLE", "Repair task state with agent-ops doctor before stopping.");
         }
         if (stored.status !== "complete") {

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",
@@ -299,7 +311,7 @@ export function managedRules(descriptor, context) {
         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/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/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/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/package.json

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