copilotkit 4.27.0 → 4.29.0

package/onboarding/prompts/frontend/angular.md

@@ -6,13 +6,13 @@ This step asks the developer nothing. If the run must wait for the developer any
 the pause first:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-developer --about other
 ```
 
 Use the starter shortcut only if all these facts are true: the target directory holds no
 project, its name is a valid `init` project name, and the selected framework is ADK.
 If all three facts are true, record Angular as the selected frontend. Then run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read starter/clone` before you fetch documentation.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read starter/clone` before you fetch documentation.
 
 ## Documentation
 
@@ -59,7 +59,7 @@ you create or build an Angular project. If the installed version is lower, selec
 supported version first and use it for every later command in this project.
 
 If the pages support the selection, record Angular and these URLs. Then run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read credentials/finalize-plan`.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read credentials/finalize-plan`.
 
 If the documentation does not support the selection, or the two version lines do not fit
-together, run `npx --prefer-offline --yes copilotkit@4.27.0 onboard read unsupported/no-validated-path`.
+together, run `npx --prefer-offline --yes copilotkit@4.29.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/frontend/nextjs.md

@@ -6,7 +6,7 @@ This step asks the developer nothing. If the run must wait for the developer any
 the pause first:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-developer --about other
 ```
 
 Use the starter shortcut only if the target directory holds no project and its name is
@@ -22,7 +22,7 @@ These TypeScript options have starters: Claude Agent SDK TypeScript, LangGraph T
 Mastra, and Strands Agents TypeScript. The .NET option is Microsoft Agent Framework .NET.
 
 If all shortcut conditions are true, record Next.js as the selected frontend. Then run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read starter/clone` before you fetch documentation.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read starter/clone` before you fetch documentation.
 
 ## Documentation
 
@@ -73,7 +73,7 @@ also sets `outputFileTracingRoot`. Do not set `outputFileTracingRoot` to a
 different folder. For an existing frontend, name this change in the report.
 
 If the page supports the selection, record Next.js and this URL. Then run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read credentials/finalize-plan`.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read credentials/finalize-plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/frontend/plan.md

@@ -15,18 +15,18 @@ Every rule below is for a run that named neither.
 
 ## Use the recorded frontend
 
-Run `npx --prefer-offline --yes copilotkit@4.27.0 onboard setup-answers` and use its `frontend`. It holds
+Run `npx --prefer-offline --yes copilotkit@4.29.0 onboard setup-answers` and use its `frontend`. It holds
 the answer that `setup/questions` recorded, even after this conversation lost it. If the
 project has a frontend, preserve it and use the matching route below. Do not change
-application code in this phase. If neither settles it, ask one line as the setup message
-does: the recommendation first, in bold, and the alternatives on one `Other:` line, from
+application code in this phase. If neither settles it, ask one line as the options view
+of `onboard setup-message` does: the recommendation first, in bold, and the alternatives on one `Other:` line, from
 React SPA, Next.js, Angular, Vue 3, React Native, Slack, and Microsoft Teams. Record the answer with
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard setup-answers --frontend <name>`.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard setup-answers --frontend <name>`.
 
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-developer --about stack-choice
 ```
 
 When the recorded frontend is not Next.js, tell the developer in one sentence where it runs
@@ -38,15 +38,15 @@ words instead.
 
 Use exactly one matching internal route:
 
-1. React SPA: `npx --prefer-offline --yes copilotkit@4.27.0 onboard read frontend/react-spa`
-2. Next.js: `npx --prefer-offline --yes copilotkit@4.27.0 onboard read frontend/nextjs`
-3. Angular: `npx --prefer-offline --yes copilotkit@4.27.0 onboard read frontend/angular`
-4. Vue 3: `npx --prefer-offline --yes copilotkit@4.27.0 onboard read frontend/vue`
-5. React Native: `npx --prefer-offline --yes copilotkit@4.27.0 onboard read frontend/react-native`
-6. Slack or Microsoft Teams: `npx --prefer-offline --yes copilotkit@4.27.0 onboard read feature/channels/start`
+1. React SPA: `npx --prefer-offline --yes copilotkit@4.29.0 onboard read frontend/react-spa`
+2. Next.js: `npx --prefer-offline --yes copilotkit@4.29.0 onboard read frontend/nextjs`
+3. Angular: `npx --prefer-offline --yes copilotkit@4.29.0 onboard read frontend/angular`
+4. Vue 3: `npx --prefer-offline --yes copilotkit@4.29.0 onboard read frontend/vue`
+5. React Native: `npx --prefer-offline --yes copilotkit@4.29.0 onboard read frontend/react-native`
+6. Slack or Microsoft Teams: `npx --prefer-offline --yes copilotkit@4.29.0 onboard read feature/channels/start`
 
 If they chose Slack or Microsoft Teams, tell that node which one they chose so it
 does not ask again.
 
 If no listed frontend fits, run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/frontend/react-native.md

@@ -6,7 +6,7 @@ This step asks the developer nothing. If the run must wait for the developer any
 the pause first:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-developer --about other
 ```
 
 React Native has no starter. For a target directory that holds no project, build the new
@@ -25,7 +25,7 @@ documents `useRenderTool`, which is React Native's own hook for drawing a tool t
 already has. That is a different job and needs a tool in the agent.
 
 If the pages support the selection, record React Native and these URLs. Then run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read credentials/finalize-plan`.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read credentials/finalize-plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/frontend/react-spa.md

@@ -6,7 +6,7 @@ This step asks the developer nothing. If the run must wait for the developer any
 the pause first:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-developer --about other
 ```
 
 React SPA has no starter. For a target directory that holds no project, build the new
@@ -26,7 +26,7 @@ that import when Vite leaves the package external.
 - https://docs.copilotkit.ai/react-spa.md
 
 If the page supports the selection, record React SPA and this URL. Then run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read credentials/finalize-plan`.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read credentials/finalize-plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/frontend/vue.md

@@ -6,7 +6,7 @@ This step asks the developer nothing. If the run must wait for the developer any
 the pause first:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-developer --about other
 ```
 
 Vue 3 has no starter. For a target directory that holds no project, build the new
@@ -26,7 +26,7 @@ page above. Vue has its own `useComponent`, which is not the React package. Take
 that reference page rather than from a Vue generative-UI guide, which is not published.
 
 If the pages support the selection, record Vue 3 and these URLs. Then run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read credentials/finalize-plan`.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read credentials/finalize-plan`.
 
 If the documentation does not support the selection, run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/implementation/build-and-validate.md

@@ -13,7 +13,7 @@ acted on. Send one short report before you stop. The friction command follows th
 setting the developer already chose, so it needs no separate question.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+npx --prefer-offline --yes copilotkit@4.29.0 onboard friction --phase stop --category <slug> --message "<sentences>"
 ```
 
 `--message` takes one or two sentences: the step you stopped at and what stopped it.
@@ -31,7 +31,7 @@ name in the plan prompt, `credentials/write-plan`.
 
 ## Departing from the approved plan
 
-The developer saw a written plan and answered any risky change in it. The approved plan is
+The developer saw a written plan and answered any change in it that needs approval. The approved plan is
 that plan, with their answer. They were told that no question comes after it unless a step
 cannot be built as written. Such a step is therefore a change to the only thing they agreed
 to.
@@ -57,7 +57,7 @@ This prompt pauses for the developer in several places. Before you end your turn
 for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-developer --about uncommitted-file
 ```
 
 The existing agent's behavior is never a departure to record and carry on from. It is four
@@ -74,14 +74,14 @@ declines, use the route-out rules below.
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-developer --about agent-change
 ```
 
 ## The developer's uncommitted files
 
 `onboard start` backed up the developer's work, so nothing is recorded before an edit. The
 approved plan lists the files that had uncommitted changes under `Uncommitted files`. Each
-one is a risky change, so the developer's answer to the plan is their agreement to those
+one needs approval, so the developer's answer to the plan is their agreement to those
 edits. Any other such file is a file
 the plan does not name: ask the developer, as above.
 
@@ -97,12 +97,12 @@ or from an environment variable.
 If the CLI prints `## Stop: this run deleted or moved the developer's work` instead of a
 step, show the developer the list it printed, and run what they choose:
 the `onboard restore` command the tripwire stop prints, which names each deleted file, or
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard tripwire --continue`. Then read the step again. If
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard tripwire --continue`. Then read the step again. If
 you cannot ask, use the route-out rules below. Before you end your turn to wait for the
 developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-developer --about restore-files
 ```
 
 ## Implement the plan
@@ -116,7 +116,7 @@ Run this from the target app directory. The developer saw the id in the plan, so
 the first point at which it can be created:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 learning containers create --id <id> --name <name> --json
+npx --prefer-offline --yes copilotkit@4.29.0 learning containers create --id <id> --name <name> --json
 ```
 
 Pass the id the plan names. Take the name from the selected project's own display name, so
@@ -129,8 +129,11 @@ credentials step found it or another run made it. That is a container to reuse,
 failure to repair and not a reason to pick a new id. Any other error code: report it and
 stop onboarding, so no run wires a selector to an id the platform does not hold.
 
+When you start a subagent in the background, tell the developer in one sentence what it
+does. Then send nothing more until it returns.
+
 Spawn one implementation subagent. Tell it to run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read subagent/implement-and-validate` first and
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read subagent/implement-and-validate` first and
 follow the prompt it returns. Tell it to return at once, and say so, if that read is refused
 or fails, and not to wait for an approval. If it returns that way, stop that subagent. Run
 the same command yourself, then spawn a fresh subagent with the returned prompt and the same
@@ -138,10 +141,25 @@ handoff. Give it the plan, selected framework, frontend, model, exact target app
 selected documentation URLs, and the
 documentation policy recorded during framework selection or conversion planning. On a
 conversion, also give it the frozen criterion. Give it the paths that had uncommitted
-changes when the run started. Give it the developer's answer on the Skills install, so that it skips a
-declined install. Require it to implement every step in plan order
+changes when the run started. Require it to implement every step in plan order
 and run the full validation list. Wait for it.
 
+If only its closing `subagent-returned` checkpoint was refused, the subagent finished.
+Record no `refused` return and spawn nothing: run that checkpoint yourself, with the result
+the subagent returned.
+
+If the subagent returns because its harness refused any other command, record that return:
+
+```text
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase subagent-returned --brief implement-and-validate --result refused
+```
+
+Then run that command yourself, from the directory the subagent named. Spawn at most one
+fresh subagent for each refused command, with the same handoff and that command's result.
+If the fresh subagent is refused a command too, spawn no other. Follow the
+`subagent/implement-and-validate` brief yourself, as "When a subagent cannot work" in
+`research/gather` says.
+
 One subagent implements the whole plan. Do not divide the work across concurrent subagents,
 and do not spawn a second subagent to reconcile a split.
 
@@ -165,7 +183,7 @@ Report it and take the failure ending.
 If the implementation result does not start with `Status: passed`, do not continue to proof.
 
 Then run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read proof/round-trip`.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read proof/round-trip`.
 
 ## Repair rules
 
@@ -193,9 +211,9 @@ developer
 declined a file the plan does not name, or the run cannot ask them about it. A defect in a
 package this run installed is not a stack CopilotKit does not serve, and a command this run
 cannot get to pass is not one either. In those cases run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read stopped/run-failed`.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read stopped/run-failed`.
 
 A plan with no path to follow takes the unsupported ending: the fix requires changing the
 developer's existing agent or frontend, or the documentation does not support the plan. In
 those cases run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read unsupported/no-validated-path`.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read unsupported/no-validated-path`.

package/onboarding/prompts/proof/complete.md

@@ -24,7 +24,7 @@ friction commands follow the telemetry setting the developer already chose, so t
 separate question.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard friction --category <slug> --cost-seconds <seconds> --message "<sentences>"
+npx --prefer-offline --yes copilotkit@4.29.0 onboard friction --category <slug> --cost-seconds <seconds> --message "<sentences>"
 ```
 
 Put one or two sentences in `--message`. Pick one category from docs-missing, docs-wrong,
@@ -46,7 +46,7 @@ Pass the surface-check outcome the proof subagent returned, not the one you want
 web frontend, pass `--visual-check` and the URL the browser opened, unchanged:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard complete --visual-check <outcome> \
+npx --prefer-offline --yes copilotkit@4.29.0 onboard complete --visual-check <outcome> \
   --frontend-url <the url you opened>
 ```
 
@@ -74,7 +74,7 @@ this graph opens.
 nothing drove the frontend:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard complete --visual-check failed --blocked-by browser-control-unresponsive
+npx --prefer-offline --yes copilotkit@4.29.0 onboard complete --visual-check failed --blocked-by browser-control-unresponsive
 ```
 
 ## Write the handoff
@@ -98,10 +98,9 @@ only you can say:
 - What the project now does, and the first thing to try in it.
 - What changed since the developer approved the plan: every path, version, or step the run
   departed from, and why. Where nothing departed, say so in one line. A file the approved
-  plan named under `Files the run writes itself` or `Skills install` is not a departure, and
-  neither is a Skills install the developer declined.
-- Where this run installed the CopilotKit Skills, the Skills files the install added:
-  `.agents/skills/` and its links in `.claude/skills/`. Say that deleting both removes them.
+  plan named under `Files the run writes itself` is not a departure.
+- A page-context warning the proof recorded: name the framework, and say that the page's data
+  does not reach its model yet.
 - Every change to the existing agent's behavior: its instructions, its tools, its model or
   provider, or its memory. Name each one and its file, and say the developer approved it.
   Where none changed, write `none`.

package/onboarding/prompts/proof/oss-baseline.md

@@ -1,12 +1,15 @@
 # Prove the existing OSS baseline
 
 Do not prove the baseline yourself. Spawn one proof subagent. Tell it to run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read subagent/prove-oss-baseline` first and follow
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read subagent/prove-oss-baseline` first and follow
 the prompt it returns. Tell it to return at once, and say so, if that read is refused or
 fails, and not to wait for an approval. If it returns that way, stop that subagent. Run the
 same command yourself, then spawn a fresh subagent with the returned prompt and the same
 handoff. Give it the repository findings and exact CLI package spec.
 
+When you start a subagent in the background, tell the developer in one sentence what it
+does. Then send nothing more until it returns.
+
 Give it the browser or device control you recorded in the preflight as well. The subagent
 proves the runtime from a shell and needs no browser for that. The control is for the one
 predicate that drives the existing frontend. Where the preflight recorded `unavailable`, say
@@ -15,10 +18,26 @@ for a substitute.
 
 Wait for the subagent to finish.
 
+If only its closing `subagent-returned` checkpoint was refused, the subagent finished.
+Record no `refused` return and spawn nothing: run that checkpoint yourself, with the result
+the subagent returned.
+
+If the subagent returns because its harness refused any other command, record that return:
+
+```text
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase subagent-returned --brief prove-oss-baseline --result refused
+```
+
+Then run that command yourself, from the directory the subagent named. Spawn at most one
+fresh subagent for each refused command, with the same handoff and that command's result.
+If the fresh subagent is refused a command too, spawn no other. Follow the
+`subagent/prove-oss-baseline` brief yourself, as "When a subagent cannot work" in
+`research/gather` says.
+
 Record what that proof returned before you route on it:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard proof --step oss-baseline --outcome <passed|failed|skipped> [--predicate <1-6>]
+npx --prefer-offline --yes copilotkit@4.29.0 onboard proof --step oss-baseline --outcome <passed|failed|skipped> [--predicate <1-6>]
 ```
 
 Report the gate whatever it returned. Use the list below. A proof that never ran is `skipped`, not failed. The command prints one line and sends
@@ -40,7 +59,7 @@ Do not change project files before this proof ends. Starting existing developmen
 processes and their ignored runtime files is allowed.
 
 If the subagent proves the `both-oss` predicate, keep its evidence with the plan and run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read conversion/plan`. That project already works.
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read conversion/plan`. That project already works.
 What it needs is the conversion, not a build.
 
 A failed baseline does not end the run, and this step does not repair it. Decide which
@@ -55,7 +74,7 @@ pass. This proof only reads.
 A failed baseline whose cause is in the project is the starting state of this project. So
 is an operational failure still there after the third attempt. Record the starting state
 `both-copilotkit-unproved` and run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read credentials/plan`. This prompt is served
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read credentials/plan`. This prompt is served
 whenever a project looks like an OSS integration, so a baseline that did not prove is an
 ordinary starting state rather than a failure. The build that follows fixes the
 integration, and `proof/round-trip` proves the result, with its own bounded repair cycle.
@@ -75,5 +94,5 @@ operational. Run the proof again, three times in total, then record the starting
 above and go on. Both causes lead to the same plan.
 
 If the proof cannot identify the running process safely, or it exposes a secret, run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read stopped/run-failed`. Neither means the
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read stopped/run-failed`. Neither means the
 project is unsupported: each means this run did not establish what it needed to.

package/onboarding/prompts/proof/round-trip.md

@@ -1,15 +1,17 @@
 # Prove the user journey
 
 Do not do the proof work yourself. Spawn one proof subagent. Tell it to run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read subagent/prove-round-trip` first and follow the
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read subagent/prove-round-trip` first and follow the
 prompt it returns. Tell it to return at once, and say so, if that read is refused or fails,
 and not to wait for an approval. If it returns that way, stop that subagent. Run the same
 command yourself, then spawn a fresh subagent with the returned prompt and the same handoff.
 Give it the selected framework, frontend, model, approved plan, selected documentation URLs,
 and validation evidence. Give it the documentation policy recorded during framework
 selection or conversion planning. On a conversion, also give it the frozen criterion. Give
-it the paths that had uncommitted changes when the run started. Give it the developer's answer on the Skills install and the
-Skills result the implementation returned.
+it the paths that had uncommitted changes when the run started.
+
+When you start a subagent in the background, tell the developer in one sentence what it
+does. Then send nothing more until it returns. This holds for a repair subagent too.
 
 Give it the frontend files that publish the page context and register the tools, by path,
 from the Files changed sections the implementation returned. The subagent sends what those
@@ -32,16 +34,29 @@ device control, and have it report `skipped-cloned-starter` rather than a missin
 capability: nothing was unavailable, the run declined to spend it. That outcome completes
 the run.
 
-Give the subagent this guide for continued-development tools:
-https://docs.copilotkit.ai/build-with-agents.md
-
 Wait for the subagent to finish. Its result arrives as a notification. Do not sleep to
 pass the time.
 
+If only its closing `subagent-returned` checkpoint was refused, the subagent finished.
+Record no `refused` return and spawn nothing: run that checkpoint yourself, with the result
+the subagent returned.
+
+If the subagent returns because its harness refused any other command, record that return:
+
+```text
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase subagent-returned --brief prove-round-trip --result refused
+```
+
+Then run that command yourself, from the directory the subagent named. Spawn at most one
+fresh subagent for each refused command, with the same handoff and that command's result.
+If the fresh subagent is refused a command too, spawn no other. Follow the
+`subagent/prove-round-trip` brief yourself, as "When a subagent cannot work" in
+`research/gather` says.
+
 Record what that proof returned before you route on it:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard proof --step round-trip --outcome <passed|failed|skipped>
+npx --prefer-offline --yes copilotkit@4.29.0 onboard proof --step round-trip --outcome <passed|failed|skipped>
 ```
 
 Report the gate whatever it returned. A proof that never ran is `skipped`, not failed. A
@@ -53,7 +68,7 @@ the next one starts. Until then, `onboard proof-check` counts the next failure a
 If the CLI prints `## Stop: this run deleted or moved the developer's work` instead of a
 step, show the developer the list it printed, and run what they choose:
 the `onboard restore` command the tripwire stop prints, which names each deleted file, or
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard tripwire --continue`. Then read the step again. If
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard tripwire --continue`. Then read the step again. If
 you cannot ask, use the route-out rules below.
 
 Never repair, reset, or revert a file the developer changed outside this run. That holds for
@@ -63,19 +78,24 @@ developer's, however right the diagnosis is and however small the fix. Ask the d
 allow the change, or route out. Never send it to a repair worker without their answer.
 
 This prompt pauses for the developer in several places. Before you end your turn to wait
-for the developer, report the pause:
+for the developer, report the pause. For the tripwire choice:
+
+```text
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-developer --about restore-files
+```
+
+For a file the plan does not name:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-developer --about uncommitted-file
 ```
 
 If the proof result starts with `Status: passed`, run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read proof/complete`. A performed surface outcome with
-the full round trip is core success even if a continued-development tool fails. A skipped
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read proof/complete`. A skipped
 surface outcome still enters `proof/complete`. The CLI records `skipped-cloned-starter` and
 `skipped-no-browser-tool` after a passed round trip as complete, and `skipped-no-device` as
 blocked. Do not describe a
-skipped surface as proved. Keep the Skills result separate from the proof result.
+skipped surface as proved.
 
 A passed result can carry the surface-check outcome `failed` with the cause
 `browser-control-unresponsive`. It means that the browser tool stopped answering, not that
@@ -97,7 +117,7 @@ credentials step found the model key missing, or the vendor refused it, and the
 started nothing. Do not send it to a repair worker. Run the `onboard credentials` command
 that its detail names, and act on its answer as `credentials/settle-credentials` says. Ask
 the developer its question, report the pause with
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-model-credential`, and
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-model-credential`, and
 end your turn. When the key settles, run the proof subagent again. If you have not recorded
 this attempt yet, record it first, with the outcome it ended with. This attempt does not
 count toward the three.
@@ -124,7 +144,7 @@ fault, so this is not a route-out. Ask the developer to send one message in the
 thread, and to give you that thread's id. Give them the app URL and the request words from
 the result. Tell them where the id is: in the browser's network tools, the request the page
 sends to the runtime URL carries `threadId` in its body. Report the pause with
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer` and end your
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-developer --about thread-id` and end your
 turn. When the developer gives the id, start a new proof subagent with
 the full original proof handoff, the pinned Step 1 record, and the thread id. Tell it to run
 the proof checks with `--thread <id>`. This attempt does not count toward the three. Use the
@@ -167,19 +187,19 @@ that returns blocked because the repair needs a file the plan does not name. Han
 way `implementation/build-and-validate` does: pause and ask the developer, add the file to
 the handoff if they allow it, and use the route-out rules below if they decline. Then spawn a
 fresh repair worker with this repair handoff, not the whole-plan implementation handoff: the
-plan, the proof evidence, the paths that had uncommitted changes when the run started, the
-files the developer allowed, and the developer's answer on the Skills install.
+plan, the proof evidence, the paths that had uncommitted changes when the run started, and
+the files the developer allowed.
 
 Before you end your turn to wait for the developer, report the pause:
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard checkpoint --phase awaiting-developer
+npx --prefer-offline --yes copilotkit@4.29.0 onboard checkpoint --phase awaiting-developer --about uncommitted-file
 ```
 
 Restart each project-owned process changed by the repair. Then spawn a fresh proof subagent
 with the full original proof handoff, failed proof evidence, and new validation evidence.
 This handoff includes the plan, documentation, policy, current process IDs, ports,
-surface-control state, the continued-tools guide, and the failed attempt's pinned Step 1
+surface-control state, and the failed attempt's pinned Step 1
 record. Carry that record so the second attempt sends the request the first one failed on.
 A fresh subagent given the plan alone writes its own request where the plan named none, and
 its grounding check then speaks about a question the failed attempt never asked.
@@ -191,7 +211,7 @@ takes the developer path above instead.
 
 Route out only when the failure is not yours to fix, when the same proof still fails after
 three attempts, or when no evidence of the round trip can be produced. In those cases run
-`npx --prefer-offline --yes copilotkit@4.27.0 onboard read stopped/run-failed`. The stack is supported:
+`npx --prefer-offline --yes copilotkit@4.29.0 onboard read stopped/run-failed`. The stack is supported:
 this run did not finish, which is a different ending and a different report. All three are
 about the round trip itself. A round trip that proved is not one of them, whatever failed
 after it.
@@ -202,7 +222,7 @@ friction command follows the telemetry setting the developer already chose, so i
 separate question.
 
 ```text
-npx --prefer-offline --yes copilotkit@4.27.0 onboard friction --phase stop --category <slug> --message "<sentences>"
+npx --prefer-offline --yes copilotkit@4.29.0 onboard friction --phase stop --category <slug> --message "<sentences>"
 ```
 
 `--message` takes one or two sentences: the step you stopped at and what stopped it.