feat(agents): sd switch, message action, skill update

- sd switch checkpoints and starts another agent from sd context - message button on agents page, refused while blocked - skill teaches agent prompt/cmd/wait/switch - drop claude StopFailure hook (not in claude 2.1.289) - update task.md
codejunction · Oct 4, 2026 · Oct 3, 2026 · Oct 3, 2026 · Oct 4, 2026 · Oct 4, 2026
commit c5937e1019dae7ee7433685ec11db36e5bc8cfd0
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -23,6 +23,7 @@ All notable changes to shelldeck are listed here. The format follows [Keep a Cha
 - Screen detection rules moved into a versioned bundled file (`agent_detection/default.toml`), with per-agent local overrides in `<config>/agent-detection/<agent>.toml`. Invalid overrides are ignored and reported by `sd agent explain`.
 - `sd agent explain` (and `--file`): why an agent has its state, without showing screen text.
 - Context page: task and state editor, memory with verify/invalidate, decisions, related projects, and cross-project search.
+- `sd switch AGENT`: checkpoint the task and continue with another agent, which starts from `sd context`. *Message* action on the AI agents page. The skill teaches `sd agent prompt/cmd/wait` and `sd switch`. The Claude hook no longer registers `StopFailure`, which Claude Code 2.1.289 doesn't have.
 - Hand-off files include a context snapshot, and the installed agent skill teaches the context workflow.
 
 ## [0.0.6] - 2026-10-01

diff --git a/README.md b/README.md
@@ -211,6 +211,7 @@ sd remember FACT / sd discover FINDING [--type T] [--file F]   add to project me
 sd decide TITLE [-r REASON]          record a settled decision (sd decisions lists them)
 sd task update [STATUS] [--task --step --next --tests --error]   update the active task and state
 sd knowledge verify ID [--status S]  mark knowledge VERIFIED, REVIEWED, STALE or INVALIDATED
+sd switch AGENT [--note TEXT]        checkpoint this project's task and continue it with another agent in a new terminal
 sd projects / sd project NAME / sd relate PROJECT   known projects, one project, link related projects
 sd install-skill [AGENT...] [--remove]   teach agent CLIs the sd team commands (automatic on server start)
 sd edit FILE / sd view FILE          open a file in shelldeck's editor / viewer

diff --git a/docs/agent-integrations.md b/docs/agent-integrations.md
@@ -18,7 +18,7 @@ approve, deny or block a tool.
 
 | Agent | What is installed | Where (env override) | Session/resume |
 | --- | --- | --- | --- |
-| Claude Code | Hook entries for `SessionStart`, `UserPromptSubmit`, `Pre/PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `Notification`, `SubagentStart`, `PreCompact`, `Stop`, `StopFailure` (all `async`) | `~/.claude/settings.json` (`CLAUDE_CONFIG_DIR`) | yes: `claude --resume <id>` |
+| Claude Code | Hook entries for `SessionStart`, `UserPromptSubmit`, `Pre/PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `Notification`, `SubagentStart`, `PreCompact`, `Stop` (all `async`; names checked in Claude Code 2.1.289) | `~/.claude/settings.json` (`CLAUDE_CONFIG_DIR`) | yes: `claude --resume <id>` |
 | Gemini CLI (v0.26+) | Hook groups (`matcher: "*"`) for `SessionStart`, `BeforeAgent`, `Before/AfterTool`, `PreCompress`, `AfterAgent`, `Notification` (approval) | `~/.gemini/settings.json` (`GEMINI_DIR`) | yes: `gemini --resume <id>` (docs: session management) |
 | Cursor (editor and CLI) | `hooks.json` entries for the watching hooks (`sessionStart`, `beforeSubmitPrompt`, `after*`, `postToolUse*`, `subagentStop`, `preCompact`, `stop`) | `~/.cursor/hooks.json` (`CURSOR_DIR`) | yes: `cursor-agent --resume <id>` |
 | GitHub Copilot CLI | Its own file; each event's command names the event, because Copilot's payloads don't | `~/.copilot/hooks/shelldeck.json` (`COPILOT_HOME`) | yes: `copilot --resume=<id>` |

diff --git a/docs/task.md b/docs/task.md
@@ -139,6 +139,12 @@
   (replace / disable / add), invalid overrides ignored and reported in
   `sd agent explain` (rule id, manifest source/version, warning). The server's
   heuristic uses it; the wheel includes the file; docs/agent-detection.md added.
+- **2026-10-04 — Remaining CLI/UI items:** `sd switch <agent>` (checkpoint +
+  start the agent via `/api/agent-start` with a `sd context` kickoff), a
+  *Message* action on the AI agents page (refused while blocked), and the skill
+  now teaches agent prompt/cmd/wait/switch. Claude hook events were checked
+  against Claude Code 2.1.289's bundle: `StopFailure` doesn't exist there and was
+  removed. Checked live.
 - **2026-10-04 — Docs:** README, CHANGELOG (Unreleased), CLAUDE.md,
   `docs/agent-automation.md` and `docs/agent-report.schema.json` describe the
   lifecycle, report API, waits and context commands.
@@ -269,7 +275,7 @@ conversation without affecting unrelated Codex hooks.
 
 ### Task 3.3: Claude Code integration
 
-- [ ] Verify the current Claude Code hook schema and event names before writing
+- [x] Verify the current Claude Code hook schema and event names before writing
   an installer.
 - [x] Install/remove only Shelldeck-owned hook entries and scripts.
 - [x] Report native session identity; preserve screen detection for state.
@@ -403,12 +409,12 @@ attribution; stale detection works on file changes; verification CLI works.
 - [x] Add `sd context [PROJECT]` — show current or named project context.
 - [x] Add `sd memory [search <query>]` — show/search project memory.
 - [x] Add `sd projects` and `sd project <name>` — list/show projects.
-- [ ] Add `sd handoff` / `sd handoffs` / `sd done <id>` — enhanced with
+- [x] Add `sd handoff` / `sd handoffs` / `sd done <id>` — enhanced with
   full context snapshots (task, state, memory, decisions, git, tests, files,
   events, next action, related projects — section 44).
 - [x] Add `sd resume` — resume most recent incomplete task.
-- [ ] Add `sd switch <agent>` — create handoff and switch active agent.
-- [ ] Add agent-accessible commands: `sd context`, `sd recall`, `sd memory`,
+- [x] Add `sd switch <agent>` — create handoff and switch active agent.
+- [x] Add agent-accessible commands: `sd context`, `sd recall`, `sd memory`,
   `sd handoff`, `sd done`, `sd tell <agent>`, plus optional `sd remember`,
   `sd decide`, `sd discover`, `sd task update` (section 34).
 
@@ -452,12 +458,12 @@ at checkpoints; sensitive files are excluded.
 
 ### Task 5.7: Background processing and performance
 
-- [ ] Add background worker infrastructure for knowledge extraction,
+- [~] Add background worker infrastructure for knowledge extraction (Markdown projection and context calls run off the event loop; no LLM extraction or embeddings yet),
   embedding generation, Markdown projection, event compaction, stale
   detection, and indexing (section 56).
-- [ ] Ensure agent terminal interaction never blocks on context processing
+- [x] Ensure agent terminal interaction never blocks on context processing
   (section 55): startup <100ms, recall <100ms, SQLite search <50ms.
-- [ ] Implement failure handling: context system failure logs warning but
+- [x] Implement failure handling: context system failure logs warning but
   agent execution continues (section 57).
 
 **Primary files:** new `shelldeck/workers.py`, `shelldeck/context_store.py`,
@@ -490,7 +496,7 @@ settings.
 - [x] Add atomic `sd agent prompt --wait` semantics.
 - [x] Add agent attach/rename commands (rename; manually started agents are attached automatically by process detection).
 - [x] Add an event subscription endpoint/transport and `sd events subscribe`.
-- [ ] Update the installed skill only after these commands are tested.
+- [x] Update the installed skill only after these commands are tested.
 
 **Done when:** supervisors can wait for an agent state transition without
 polling screen text, and a new agent process cannot satisfy an old wait.
@@ -500,7 +506,7 @@ polling screen text, and a new agent process cannot satisfy an old wait.
 - [x] Add a prioritized attention section to `static/agents.js`.
 - [x] Display semantic state, source, reason, elapsed time, model/context,
   role/title, and integration health.
-- [~] Add direct actions appropriate to the viewer's permissions (open, open next and resume done; peek/answer/message via CLI): open, peek,
+- [x] Add direct actions appropriate to the viewer's permissions (open, open next, message, native commands, resume; peek/answer via CLI): open, peek,
   answer, message, resume, diagnose, reassign, and close.
 - [x] Add project sidebar rollups with accessible text/icon state indicators.
 - [x] Keep completed agents visible until reviewed; do not re-alert unchanged

diff --git a/shelldeck/cli.py b/shelldeck/cli.py
@@ -1257,6 +1257,24 @@ def resume(json_: bool = typer.Option(False, "--json", help="Print JSON.")):
     typer.echo(out["text"])
 
 
+@app.command()
+def switch(
+    agent: str = typer.Argument(..., help="The agent to continue with: claude, codex, gemini, devin, ..."),
+    note: str = typer.Option("", "--note", "-n", help="Where you stopped, saved as the current step."),
+    model: str = typer.Option("", "--model", "-m"),
+):
+    """Hand this project's work to another agent: checkpoint the task and state, then open the new agent in a new terminal
+    of the same project, told to start from `sd context`. The current agent keeps running until you close it."""
+    me = os.environ.get("SHELLDECK_SESSION_ID", "")
+    sessions = _api("/api/sessions")["sessions"]
+    mine = next((s for s in sessions if s["id"] == me), None)
+    _api("/api/context/state", "POST", {**_where(), **({"step": note} if note else {}), "next_action": f"continue with {agent}"})
+    body = {"agent": agent, "model": model, "prompt": "Continue this project's task where the last agent stopped. First run: sd context"}
+    body |= {"project_id": mine["project_id"]} if mine and mine.get("project_id") else {"cwd": os.getcwd()}
+    r = _api("/api/agent-start", "POST", body)
+    typer.echo(f"checkpoint saved; {agent} started as {r['session']['nick']} ({r['session']['id']}). It starts from sd context.")
+
+
 @app.command()
 def recall(
     query: str = typer.Argument(..., help="What you're looking for, e.g. \"authentication architecture\"."),

diff --git a/shelldeck/hook.py b/shelldeck/hook.py
@@ -26,7 +26,7 @@
 EVENTS: dict[str, dict[str, str | None]] = {
     "claude": {"SessionStart": IDLE, "UserPromptSubmit": WORKING, "PreToolUse": WORKING, "PostToolUse": WORKING,
                "PostToolUseFailure": WORKING, "PermissionRequest": BLOCKED, "SubagentStart": WORKING, "PreCompact": WORKING,
-               "Stop": DONE, "StopFailure": IDLE, "SessionEnd": None, "Notification": None},
+               "Stop": DONE, "SessionEnd": None, "Notification": None},  # names checked in Claude Code 2.1.289's cli.js
     "gemini": {"SessionStart": IDLE, "BeforeAgent": WORKING, "BeforeTool": WORKING, "AfterTool": WORKING, "PreCompress": WORKING,
                "AfterAgent": DONE, "Notification": BLOCKED, "SessionEnd": None},
     "cursor": {"sessionStart": IDLE, "beforeSubmitPrompt": WORKING, "afterShellExecution": WORKING, "afterFileEdit": WORKING,

diff --git a/shelldeck/static/agents.js b/shelldeck/static/agents.js
@@ -1,6 +1,6 @@
 // AI agents page: coding agents running in terminals, every known agent CLI with its models, and launch.
 import { ATTENTION, S, attentionOf, orderedProjects, projectColor, refreshProjects, showSession } from "./app.js";
-import { api, esc, icon, toast, toastError } from "./ui.js";
+import { api, esc, icon, promptDialog, toast, toastError } from "./ui.js";
 
 // pasted into an agent so it knows how to reach the others in its project
 const TEAM_PROMPT = `You are one of several AI coding agents working in this project, each in its own shelldeck terminal with a person's name ($SHELLDECK_NICK).
@@ -181,7 +181,8 @@ function commandMenu(r) {
   const cmds = (COMMANDS[r.agent] || []).filter((c) => !c.takes_arg);
   if (!cmds.length) return "";
   const opts = cmds.map((c) => `<option value="${c.action}">${esc(c.action)} (${esc(c.command)})${c.verified ? "" : " ?"}</option>`).join("");
-  return `<select class="sm" data-agent-cmd="${r.session_id}" aria-label="Run a ${esc(r.label)} command"><option value="">Command…</option>${opts}</select>`;
+  return `<button class="btn sm" data-message="${r.session_id}" title="Send a prompt (refused while it waits on a question)">Message</button>
+    <select class="sm" data-agent-cmd="${r.session_id}" aria-label="Run a ${esc(r.label)} command"><option value="">Command…</option>${opts}</select>`;
 }
 
 async function onCommand(e, el) {
@@ -202,6 +203,19 @@ async function onCommand(e, el) {
 
 async function onClick(e, el) {
   if (e.target.closest("select")) return; // the command menu, not "open terminal"
+  const msgTo = e.target.closest("[data-message]")?.dataset.message;
+  if (msgTo) {
+    const text = await promptDialog("Message the agent", "", { label: "Prompt", ok: "Send" });
+    if (!text?.trim()) return;
+    try {
+      await api("/api/agent-prompt", { method: "POST", body: { session_id: msgTo, text } });
+      toast({ title: "Sent" });
+    } catch (err) {
+      if (String(err?.message || err).includes("agent_blocked")) toast({ title: "Not sent", body: "It is waiting on a question: answer that first.", kind: "warn" });
+      else toastError(err);
+    }
+    return;
+  }
   const sid = e.target.closest("tr[data-sid]")?.dataset.sid;
   if (sid) return showSession(sid);
   if (e.target.closest("[data-copy-prompt]")) {

diff --git a/shelldeck/team.py b/shelldeck/team.py
@@ -181,7 +181,12 @@ def one_line(text: str, limit: int = 2000) -> str:
   records a settled decision; check `sd memory` first so you don't duplicate one.
 - `sd task update [IN_PROGRESS|BLOCKED|DONE] --task "..." --step "..." --next "..." --tests "..." --error "..."`
   updates the task and state. Run it when the plan or step changes, after tests, and before you stop.
-- `sd agent status [name]` shows agent states; `sd agent wait <name> --until idle --timeout 10m` waits for one.
+- `sd agent status [name]` shows agent states; `sd agent wait <name> --until done --timeout 10m` waits for one
+  (exit 0 reached, 2 timeout, 3 it exited). `sd agent prompt <name> "text" --wait` sends a follow-up and waits for it.
+- `sd agent cmd <name> compact` runs that agent's own slash command (compact, clear, model, status, review, ...;
+  `sd agent cmd <agent> --list`). Commands and prompts are refused while the agent waits on a question.
+- `sd switch <agent> --note "where I stopped"` hands this project's task to another agent in a new terminal; it
+  starts from `sd context`. Use it only when the user asks.
 Never put passwords, tokens or keys into these commands.
 
 Rules: