easy-coding-harness 0.3.4 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,13 @@
 - `y`：常规功能升级
 - `z`：日常 bug 修复
 
+## 0.4.0
+
+- 升级跨 agent 交接模型：交接记录只保存交接前 agent、阶段、摘要和时间，不再要求也不保存下一任 agent。
+- 新增 `handoff-task` / `claim-task` 状态 API，交接方可写入 handoff 并释放当前 session，新 agent 可显式 claim 任务并读取最新交接摘要。
+- `ec-task-management` 升级为任务面板：列出未完成任务并标注继续/接手，接手任务展示上一任 agent。
+- `ec-workflow` 路由调整：有当前任务指针时优先继续；无指针时按提示词匹配未完成任务，未命中或无提示词时展示可继续/接手任务列表。
+
 ## 0.3.4
 
 - 修复 Claude Code 中任务已进入 ANALYSIS 但回复没有状态栏的问题：Claude 的 `UserPromptSubmit` 现在会先运行幂等的 `session-start.py`，再运行 `inject-workflow-state.py`，确保每轮提示词都能拿到最新 `status_context`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "easy-coding-harness",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "CLI scaffold for installing Easy Coding harness files into agent-native directories.",
   "repository": {
     "type": "git",

package/templates/common/bundled-skills/ec-meta/references/local-architecture/README.md

@@ -82,3 +82,8 @@ demand.
 continues. All platform-agnostic artifacts (dev-spec, execution.jsonl, task.json, memory)
 make cross-agent handoff lossless. `task.json.last_agent` records the last owner so a new
 agent knows a task was handed off rather than self-interrupted.
+
+Handoff is target-less. The leaving agent writes a `handoff` record with `from`, `stage`,
+`summary`, and `timestamp`, then releases its session pointer. It does not know or record the
+next agent. The receiving agent explicitly claims a task through the state API; that claim sets
+the new session pointer and updates `task.json.last_agent`.

package/templates/common/skills/ec-task-management/SKILL.md

@@ -1,23 +1,56 @@
 ---
 name: ec-task-management
-description: Read-only task panel — create and list Easy Coding tasks. Use when the user runs {{skill_trigger}}ec-task-management or asks to see what tasks exist or to create a task. Does NOT perform workflow recovery (that is ec-workflow) or closure (that is ec-task-close).
+description: Task panel for Easy Coding tasks. Use when the user runs {{skill_trigger}}ec-task-management, asks to see tasks, create a task, continue a task, or take over a task handed off by another agent.
 ---
 
 # ec-task-management — the task panel
 
-A focused information panel: create tasks and list them. Recovery and stage progression
-belong to ec-workflow; closure belongs to ec-task-close. This skill does neither.
+A focused task panel: list unfinished tasks, create tasks, and let the user choose one task
+to continue or take over. Stage progression still belongs to ec-workflow; closure belongs
+to ec-task-close.
 
 Communicate with the user in the user's language.
 
 ## Capabilities
 
-### List tasks
-Call the state API:
-`{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py list-tasks`.
-Show each task's id, title, status, created_at, and whether it is active. This is read-only.
+### List unfinished tasks
+
+Call the state API with the current agent id:
+`{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py list-tasks --agent <agent-id>`.
+
+Show only tasks whose `active` is true. For each task show:
+- id
+- title
+- status
+- created_at
+- action label:
+  - `continue` when `action == "continue"`
+  - `take over` when `action == "takeover"`
+- previous agent when `previous_agent` is present
+- latest handoff summary when `latest_handoff.summary` is present
+
+Use wording in the user's language. The important distinction is:
+- Continue: the current agent was already the last agent.
+- Take over: another agent was the last agent; show that previous agent.
+
+### Continue or take over a selected task
+
+When the user chooses a listed task, call:
+`{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py claim-task --session-file <P> --task-id <task-id> --agent <agent-id>`.
+
+Use the returned `status_context` as the authoritative status source for the rest of the
+current turn. Then report:
+- whether this was `continue` or `takeover`
+- the previous agent if returned
+- the latest handoff summary if returned
+- the current stage
+
+After claiming, hand control to ec-workflow semantics: read the task metadata and latest
+execution records, then resume from the current stage. Do not advance stages from this skill
+unless ec-workflow is explicitly invoked or the agent environment routes into it.
 
 ### Create a task
+
 Create through the state API, never by hand-editing `task.json` or session files:
 `{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py create-task --session-file <P> --task-id <MM-DD-short-name> --type <feature|bugfix|refactor|perf> --title "<one-line summary>" --agent <agent-id> --no-set-current`.
 
@@ -31,6 +64,7 @@ the current turn instead of older hook-injected status text.
 
 ## Boundaries
 
-- No workflow recovery — point the user to ec-workflow to resume or progress a task.
-- No closing/cancelling — that is ec-task-close.
-- Do not advance stages or run stage skills from here.
+- Do not close or cancel tasks — that is ec-task-close.
+- Do not advance stages directly from this skill.
+- Do not ask who the next agent will be. A takeover is decided by the agent that claims the
+  task, not by the agent that last handed it off.

package/templates/common/skills/ec-workflow/SKILL.md

@@ -29,33 +29,32 @@ replies are English.
    Do NOT bulk-read ABSTRACT.md or long memory here; ec-analysis loads them on demand.
 3. **State check + Intent routing.** Read the hook-injected breadcrumbs (`[current-task:X]`,
    `[workflow-state:Y]`, `[easy-coding:session-file:P]`) to determine the active task,
-   stage, and session file, then decide based on whether the user's message carries a
-   task-related prompt beyond the bare skill trigger.
-
-   **No prompt (bare trigger):**
-   - `current_task` set with an active stage → resume that stage (see Resume and handoff).
-   - `current_task` null → scan `.easy-coding/tasks/` for tasks whose status is not in
-     {COMPLETE, CLOSED}. Found → list them, let the user pick one to resume or start new.
-     None → ready for a new task.
-
-   **With prompt — intent routing:**
-   1. Collect all non-terminal tasks in `.easy-coding/tasks/`: read each task's folder name,
-      `task.json` fields (`title`, `type`, `status`). If a task passed ANALYSIS, also read
-      its dev-spec title line as extra matching signal.
-   2. Match the user's prompt against these identifiers (semantic match — the user saying
-      "继续做搜索" should match a task titled "添加搜索功能").
-   3. Route:
-      - Prompt matches `current_task` → resume with the prompt as additional context (the
-        user may be providing supplementary info, a revision request, or an answer to a
-        previous question).
-      - Prompt matches a different non-terminal task → ask the user: "Switch to «{matched
-        task title}»? Current task «{current task title}» will be suspended at {stage}."
-        On confirmation, perform a task switch (see Task switching below).
-      - Prompt matches no existing task AND `current_task` is set → ask the user: "Start a
-        new task? Current task «{current task title}» will be suspended at {stage}."
-        On confirmation, create the new task (step 4).
-      - Prompt matches no existing task AND `current_task` is null → create the new task
-        directly (step 4).
+   stage, and session file. Then call the task list API with the current agent id:
+   `{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py list-tasks --agent <agent-id>`.
+   Use only non-terminal tasks (`active == true`) for routing.
+
+   **Current task pointer exists:**
+   - The current task has priority. Resume it by default, even if the user only runs the bare
+     skill trigger.
+   - If the prompt clearly matches the current task, resume it with the prompt as additional
+     context.
+   - If the prompt clearly matches a different unfinished task, ask whether to switch to that
+     task. Show whether it is `continue` or `takeover`; for takeover show `previous_agent`.
+     On confirmation, claim the matched task (see Task switching).
+   - If the prompt clearly describes unrelated new work, ask whether to create a new task and
+     suspend the current one at its persisted stage.
+
+   **No current task pointer:**
+   - If the prompt matches exactly one unfinished task, show that task and ask whether to
+     continue/take it over. For takeover show the previous agent and latest handoff summary.
+     On confirmation, claim it (see Task switching).
+   - If the prompt matches multiple unfinished tasks, list the matches with `continue` /
+     `takeover` labels and ask the user to choose one.
+   - If the prompt matches none, or there is no prompt beyond the bare skill trigger, list all
+     unfinished tasks with `continue` / `takeover` labels. For takeover entries, show the
+     previous agent. Let the user choose one to claim, or choose to start a new task.
+   - If there are no unfinished tasks, create a new task only when the user supplied a real
+     task prompt; otherwise report that the harness is ready for a new task.
 
 4. **New task.** When creating a task (from step 3), create
    the task through the state API, which creates `task.json`, sets `status:"INIT"`, writes
@@ -98,10 +97,11 @@ any stage --[user abort via ec-task-close]--> CLOSED
 
 When the user confirms switching from task A to task B:
 1. Task A's status is already persisted in its `task.json` — nothing extra to save.
-2. Set the current task through the state API:
-   `{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py set-current --session-file <P> --task-id <task-b-id> --agent <agent-id>`.
+2. Claim the selected task through the state API:
+   `{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py claim-task --session-file <P> --task-id <task-b-id> --agent <agent-id>`.
 3. Use the returned `status_context` as the current status source, then read task B's
-   `task.json` to determine its current stage.
+   `task.json` to determine its current stage. If the result says `action:"takeover"`, tell
+   the user which previous agent owned the task.
 4. Resume task B's stage via the appropriate stage skill.
 
 No data is lost — task A's dev-spec, execution.jsonl, and test-strategy.md stay intact on
@@ -180,12 +180,12 @@ Hook breadcrumbs you may receive: `[workflow-state:X]`, `[current-task:Y]`,
 `[easy-coding:session-file:P]`, `[easy-coding:handoff-from:Z]`,
 `[easy-coding:init-required]`.
 
-Resuming an active task (whether from session restart, handoff, or task switch):
+Resuming an active task (whether from session restart, claim, handoff, or task switch):
 1. Read `task.json` and the dev-spec sections relevant to the current stage.
 2. Read the tail of `execution.jsonl` — the latest `plan` / `result` / `verify` / `handoff`
    records tell you exactly where work stopped.
-3. If `last_agent` differs from the current agent this is a cross-agent handoff: read the
-   latest `handoff` record first for the fast summary, then set `last_agent` to yourself.
+3. If the task was claimed from another agent, read the latest `handoff` record first for the
+   fast summary and tell the user which previous agent handed it off.
 4. Tell the user what is being resumed and from which stage, then continue.
 
 After a task switch, the same resume flow applies — the only difference is that `current_task`
@@ -193,13 +193,19 @@ was just changed by the switching procedure rather than being loaded from a prio
 
 Offering handoff — at WAITING_CONFIRM, after presenting the plan, offer exactly:
 1. Start implementation
-2. Hand off to another agent
+2. Write handoff and stop
 3. Revise the plan
-On option 2: append a `handoff` record to `execution.jsonl` —
-`{"type":"handoff","from":"<agent>","stage":"<stage>","summary":"<dense context: plan shape, key decisions, user emphases>","timestamp":"<ISO>"}` —
-update the task's `last_agent` in task.json, then tell the user to open the target agent and run ec-workflow there.
-Handoff is also legal at any other stage boundary on user request. The harness never
-switches agents by itself.
+On option 2, call:
+`{{PYTHON_CMD}} {{platform_config_dir}}/hooks/easy_coding_state.py handoff-task --session-file <P> --agent <agent-id> --summary "<dense context: plan shape, key decisions, user emphases>"`.
+
+The handoff record is target-less:
+`{"type":"handoff","from":"<agent>","stage":"<stage>","summary":"<dense context>","timestamp":"<ISO>"}`.
+It records who handed the task off, not who will take it next. Do not ask the user to name
+the next agent, and do not invent or store a next-agent field. After writing handoff, stop
+owning the task; another agent can use ec-task-management or ec-workflow to claim it.
+
+Handoff is also legal at any other stage boundary on user request. The harness never switches
+agents by itself; the next agent claims the task explicitly.
 
 ## Status line
 

package/templates/shared-hooks/easy_coding_state.py

@@ -242,6 +242,38 @@ def write_task(root: Path, task_id: str, task: dict) -> None:
     write_json(task_json_path(root, task_id), task)
 
 
+def execution_log_path(root: Path, task_id: str) -> Path:
+    assert_safe_task_id(task_id)
+    return root / ".easy-coding" / "tasks" / task_id / "execution.jsonl"
+
+
+def append_execution_record(root: Path, task_id: str, record: dict) -> None:
+    path = execution_log_path(root, task_id)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(record, ensure_ascii=False) + "\n")
+
+
+def latest_handoff_record(root: Path, task_id: str) -> dict | None:
+    path = execution_log_path(root, task_id)
+    if not path.exists():
+        return None
+    latest: dict | None = None
+    try:
+        for line in path.read_text(encoding="utf-8").splitlines():
+            if not line.strip():
+                continue
+            try:
+                record = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(record, dict) and record.get("type") == "handoff":
+                latest = record
+    except OSError:
+        return None
+    return latest
+
+
 def assert_safe_task_id(task_id: str) -> None:
     path = Path(task_id)
     if not task_id or path.is_absolute() or "/" in task_id or "\\" in task_id or ".." in path.parts:
@@ -432,7 +464,15 @@ def attach_status_context(
     return enriched
 
 
-def list_tasks(root: Path) -> list[dict]:
+def task_claim_action(task: dict, agent: str | None) -> str | None:
+    status = str(task.get("status") or "PENDING")
+    if status in TERMINAL_STATUSES or not agent:
+        return None
+    last_agent = task.get("last_agent")
+    return "continue" if not last_agent or last_agent == agent else "takeover"
+
+
+def list_tasks(root: Path, agent: str | None = None) -> list[dict]:
     tasks_dir = root / ".easy-coding" / "tasks"
     if not tasks_dir.is_dir():
         return []
@@ -444,6 +484,8 @@ def list_tasks(root: Path) -> list[dict]:
         if not task:
             continue
         status = str(task.get("status") or "PENDING")
+        action = task_claim_action(task, agent)
+        last_agent = task.get("last_agent")
         items.append(
             {
                 "id": entry.name,
@@ -452,7 +494,10 @@ def list_tasks(root: Path) -> list[dict]:
                 "status": status,
                 "active": status not in TERMINAL_STATUSES,
                 "created_at": task.get("created_at"),
-                "last_agent": task.get("last_agent"),
+                "last_agent": last_agent,
+                "action": action,
+                "previous_agent": last_agent if action == "takeover" else None,
+                "latest_handoff": latest_handoff_record(root, entry.name),
             }
         )
     return items
@@ -487,6 +532,77 @@ def clear_current_task(root: Path, agent: str, session_file: str | Path | None =
     return snapshot_state(root, session_file, session)
 
 
+def handoff_task(
+    root: Path,
+    agent: str,
+    summary: str,
+    task_id: str | None = None,
+    session_file: str | Path | None = None,
+) -> dict:
+    if not summary.strip():
+        raise StateError("Handoff summary is required.")
+    session = ensure_session(root, session_file)
+    resolved_task_id = task_id or session.get("current_task")
+    if not resolved_task_id:
+        raise StateError("No current task is set.")
+    task = load_task(root, str(resolved_task_id))
+    if task is None:
+        raise StateError(f"Task not found: {resolved_task_id}")
+    stage = str(task.get("status") or "PENDING")
+    if stage in TERMINAL_STATUSES:
+        raise StateError(f"Cannot hand off terminal task: {resolved_task_id}")
+
+    record = {
+        "type": "handoff",
+        "from": agent,
+        "stage": stage,
+        "summary": summary.strip(),
+        "timestamp": now_iso(),
+    }
+    append_execution_record(root, str(resolved_task_id), record)
+    task["last_agent"] = agent
+    write_task(root, str(resolved_task_id), task)
+
+    if session.get("current_task") == resolved_task_id:
+        clear_session_pointer(session, agent)
+        write_session(root, session, session_file)
+
+    snapshot = snapshot_state(root, session_file, session)
+    snapshot["task_id"] = str(resolved_task_id)
+    snapshot["handoff"] = record
+    snapshot["action"] = "handoff"
+    return snapshot
+
+
+def claim_task(root: Path, task_id: str, agent: str, session_file: str | Path | None = None) -> dict:
+    task = load_task(root, task_id)
+    if task is None:
+        raise StateError(f"Task not found: {task_id}")
+    status = str(task.get("status") or "PENDING")
+    if status in TERMINAL_STATUSES:
+        raise StateError(f"Cannot claim terminal task: {task_id}")
+
+    previous_agent = task.get("last_agent")
+    action = "continue" if not previous_agent or previous_agent == agent else "takeover"
+    latest_handoff = latest_handoff_record(root, task_id)
+    task["last_agent"] = agent
+    write_task(root, task_id, task)
+
+    session = ensure_session(root, session_file)
+    session["current_task"] = task_id
+    session["last_seen_task"] = task_id
+    session["last_seen_stage"] = status
+    session["last_agent"] = agent
+    write_session(root, session, session_file)
+
+    snapshot = snapshot_state(root, session_file, session)
+    snapshot["task_id"] = task_id
+    snapshot["action"] = action
+    snapshot["previous_agent"] = previous_agent
+    snapshot["latest_handoff"] = latest_handoff
+    return snapshot
+
+
 def create_task(
     root: Path,
     task_id: str,
@@ -675,7 +791,9 @@ def main() -> int:
     subcommands = parser.add_subparsers(dest="command")
 
     subcommands.add_parser("snapshot", parents=[common])
-    subcommands.add_parser("list-tasks", parents=[common])
+
+    list_tasks_parser = subcommands.add_parser("list-tasks", parents=[common])
+    list_tasks_parser.add_argument("--agent")
 
     create = subcommands.add_parser("create-task", parents=[common])
     create.add_argument("--task-id", required=True)
@@ -691,6 +809,15 @@ def main() -> int:
     clear_current = subcommands.add_parser("clear-current", parents=[common])
     clear_current.add_argument("--agent", required=True)
 
+    handoff = subcommands.add_parser("handoff-task", parents=[common])
+    handoff.add_argument("--agent", required=True)
+    handoff.add_argument("--summary", required=True)
+    handoff.add_argument("--task-id")
+
+    claim = subcommands.add_parser("claim-task", parents=[common])
+    claim.add_argument("--task-id", required=True)
+    claim.add_argument("--agent", required=True)
+
     transition = subcommands.add_parser("transition", parents=[common])
     transition.add_argument("--stage", required=True)
     transition.add_argument("--agent", required=True)
@@ -716,7 +843,7 @@ def main() -> int:
         if command == "snapshot":
             emit(snapshot_state(root, session_file))
         elif command == "list-tasks":
-            emit({"tasks": list_tasks(root)})
+            emit({"tasks": list_tasks(root, getattr(args, "agent", None))})
         elif command == "create-task":
             emit(
                 attach_status_context(
@@ -752,6 +879,24 @@ def main() -> int:
                     session_file,
                 )
             )
+        elif command == "handoff-task":
+            emit(
+                attach_status_context(
+                    root,
+                    handoff_task(root, args.agent, args.summary, args.task_id, session_file),
+                    args.agent,
+                    session_file,
+                )
+            )
+        elif command == "claim-task":
+            emit(
+                attach_status_context(
+                    root,
+                    claim_task(root, args.task_id, args.agent, session_file),
+                    args.agent,
+                    session_file,
+                )
+            )
         elif command == "transition":
             emit(
                 attach_status_context(