openplanr 3.3.0 → 3.5.0

package/lib/host-packages/claude/openplanr/README.md

@@ -17,7 +17,7 @@ Follow with `/planr:plan` to decompose the specification into stories and tasks,
 ## Install the CLI
 
 Several skills call the deterministic `openplanr` CLI from the `openplanr` npm package, which ships
-this plugin at the same version (3.3.0):
+this plugin at the same version (3.5.0):
 
 ```bash
 npm install -g openplanr
@@ -34,24 +34,23 @@ The same skills ship for Codex and Cursor through the `openplanr` package.
 - Skills run inside Claude Code. The plugin makes no model calls of its own and sends no
   telemetry. It has no hooks and no MCP servers.
 - Skills call the `openplanr` CLI, bundled Node.js scripts, `git`, and the GitHub CLI (`gh`). They
-  read and write files in your repository.
+  read and write files in your repository. The design skills run every local design operation
+  through `openplanr design`; the plugin ships no design runtime.
 - The planning dashboard and local artifact reviews bind to loopback only.
-- Bundled scripts are readable JavaScript. The design studio and review stage pages ship as
-  readable source files; the local review server joins them after checking their recorded
-  SHA-256 digests, without downloading or decoding code.
+- Bundled scripts are readable JavaScript.
 - Skills and bundled scripts store and read no GitHub, Linear or model-provider credentials and
   send no agent credentials to OpenPlanr services. Coding-agent runs you request use that
   agent's own sign-in, described below.
-- Sharing a design or diagram review creates owner access keys for that review and stores them,
-  readable only by you, in `design-shares` or `diagram-shares` under `~/.planr` (or
-  `PLANR_HOME`; earlier installs used `~/.openplanr`). Design reviews and handoffs read the
-  record locally to show an existing share's link and status. The keys are sent only to the
-  review address stored with them, without cookies or redirects, when you share, update, sync
-  or export feedback, hand off, revoke, or recover that review. Recovery reads only the file
-  path you give.
-- While a local design studio page is visible, it syncs a review you shared before every 15
-  seconds. This pulls published team feedback and finishes delivering previously queued
-  review metadata; it never publishes local design changes.
+- Sharing a design or diagram review runs in the `openplanr` CLI, not in the plugin. The CLI
+  creates the review's owner access keys, stores them readable only by you under `~/.planr` (or
+  `PLANR_HOME`), and sends them only to the review address stored with them. The plugin's
+  bundled scripts read no owner keys and contact no OpenPlanr host.
+- Without the CLI, the design skills still write the design document, sources and
+  specification, marked unverified, and tell you the command to install it. On Claude Code,
+  the design skill can build on Claude's hosted design canvas instead.
+- While a local design studio page for a shared design is visible, it asks the CLI to sync the
+  review every 15 seconds. This pulls published team feedback and finishes delivering
+  previously queued review metadata; it never publishes local design changes.
 - When you ask `delegate` to run another coding agent, that agent's own CLI runs with its normal
   sign-in, environment, model routing, and trusted hooks or plugins. Checking a profile that
   uses a local model server reads its model list from that server's address without
@@ -59,7 +58,8 @@ The same skills ship for Codex and Cursor through the `openplanr` package.
 - Only when you ask:
   - `sync`, `sprint` and `status` reach GitHub and Linear through your coding agent's own
     GitHub or Linear connection, or through the GitHub CLI (`gh`) when it is signed in.
-  - `artifact` and the design skills share an encrypted review through `share.openplanr.dev`.
+  - `artifact` and the design skills share an encrypted review through the `openplanr` CLI,
+    which sends it to `share.openplanr.dev`.
   - Company workspaces, a pre-release hosted service, are used only when you configure one.
 
 ## Links

package/lib/host-packages/claude/openplanr/references/agents/shared/modes/shared/task-context-resolution.md

@@ -50,14 +50,14 @@ selector, searched location, and matching candidates instead of guessing.
 
 Return one concise implementation result:
 
-- **Outcome:** a `status` of completed, partial, or blocked, plus a concise
-  `summary`.
+- **Outcome:** a `status` of completed, partial, blocked, or
+  awaiting-acceptance, plus a concise `summary`.
 - **Task:** `planr-task` with its ID and path, or `direct-request` when no task
   artifact was used.
 - **Changed:** each path and its purpose, including directly required companion
   files not named by the task.
-- **Checks:** each command, its passed, failed, or not-run status, and a concise
-  detail.
+- **Checks:** each command, its passed, failed, or not-run status, a concise
+  detail, and the acceptance IDs it covers.
 - **Issues:** always include this field. For each issue, give the problem, impact,
   and next action; write `none` when the issues array is empty.
 

package/lib/host-packages/claude/openplanr/skills/artifact/references/design-sharing.md

@@ -40,8 +40,8 @@ repository notes, credentials or an entire specification into shared context.
 Open the design with `openplanr artifact <design-document.json>` after editing context;
 the route validates and renders it. If it reports a draft error and falls back to
 the previous working revision, fix that error before sharing the changed context.
-When working through an installed design
-skill instead, use its bundled `validate`, `render` and `open` utilities. Inspect
+When working through a design skill instead,
+use `openplanr design validate`, `render` and `open`. Inspect
 Welcome for the correct design title, purpose and review questions, then use the
 explicit Share or Publish action. If browser inspection is unavailable, state
 that the welcome is unverified. Changing the context file alone does not update

package/lib/host-packages/claude/openplanr/skills/delegate/SKILL.md

@@ -68,7 +68,8 @@ digest-acceptance step or permanently frozen setup baseline. See
 
 Use the returned pinned helper for subsequent actions. `dispatch`, bounded `wait`
 and `status` expose the exact session, native progress, inactivity and phase timings.
-Native tools, permissions, configuration and implementation loops remain native.
+Native tools, permissions, configuration and implementation loops remain native, except
+that Claude Code or Codex with no configured permission mode starts in its edit mode.
 Do not add bypass/force/yolo flags, blanket tool exclusions or silent model fallbacks.
 Local backend probes are compatibility diagnostics, not a separate execution policy.
 They read model metadata without submitting inference, loading models or sending

package/lib/host-packages/claude/openplanr/skills/delegate/references/integration-review.md

@@ -26,32 +26,38 @@ parent host's normal execution controls and configuration. They are not an OpenP
 OS sandbox. Arguments, exits, timings and bounded private failure diagnostics are
 saved separately from native-agent check claims.
 
-Verification normally runs in the prepared owned worktree. Ordinary ignored
-build/cache outputs are allowed. If preparation, a check or generation changes
-reviewable source/tests/configuration/generated files, the old review is invalid:
-inspect the updated candidate and review again before acceptance. If the source
-checkout makes the prepared tree stale, verification uses a fresh candidate only
-when needed, retaining the original native session/worktree.
+`review` commits the worktree's non-ignored state as the run branch tip and reviews
+`git diff base tip`. Verification runs in the owned worktree at that tip: checks see
+HEAD plus the selected files plus the delegate's changes, not the parent checkout's
+other uncommitted files, which the report lists. Ordinary ignored build/cache outputs
+are allowed. If preparation, a check or generation changes reviewable
+source/tests/configuration/generated files, the old review is invalid: inspect the
+updated candidate and review again before acceptance.
 
 Failed checks keep the candidate blocked. `baselineComparison: true` explicitly
-requests a relevant failed-check comparison; it is diagnostic and cannot turn a
-failure into acceptance. Earlier attempt evidence remains private. Narrowing a
+requests a relevant failed-check comparison in a temporary worktree at the base
+commit; it is diagnostic and cannot turn a failure into acceptance. Dependencies are
+not copied there, so include their setup in `preparation`. Earlier attempt evidence remains private. Narrowing a
 previously failed check set requires `checkSelectionReason`. With no applicable
 automated check, `reviewOnlyReason` allows explicitly unverified review-only
 integration; zero checks never produces a verified outcome.
 
 ## Checkout protection and recovery
 
-The integration lock, scope/Preserve checks, reviewed patch identity, destination
-compare-and-swap and recovery journal protect checkout writes. Concurrent user
-edits are never overwritten or rolled back. A source change during checks requires
-reviewing the actual candidate again. The journal records intended states before
-the first source write and recovery touches only helper-written paths that still
-match those states.
+The per-repository lock, scope/Preserve checks and the reviewed tip protect checkout
+writes. `apply` saves a restore point (`git stash create`) under the private ref
+`refs/planr-delegate/<runId>/restore`, then runs `git apply --check` and `git apply`
+with the saved `patch.diff`. A parent edit elsewhere in a changed file merges; an
+overlapping parent edit blocks with its path and leaves the checkout untouched.
+Concurrent user edits are never overwritten or rolled back.
 
-An interrupted source write must use `recover` with rollback (default) or accept
-after inspecting every journaled path. Keep conflicting user edits. Do not bypass
-a rejected helper by manually applying its patch.
+If `git apply` fails without writing, for example after a parent save between its check
+and the write, the run returns to review with the conflicting paths. An apply
+interrupted between its check and completion must use `recover`, which compares each
+patch path with its pre- and post-apply content. A fully applied patch can be accepted;
+rollback (default) restores only paths that match their post-apply content and keeps
+file permissions. Keep conflicting user edits. Do not bypass a rejected helper by manually applying
+its patch.
 
 Successful native integration closes the exact run, saves evidence/report and
 removes only its owned worktree unless retained. `status` recovers the five-field
@@ -61,8 +67,8 @@ deployment are outside this helper.
 Experimental generic protocol-v1 adapters and older pinned helpers retain their
 original check interface and lifecycle; native v2 does not expand their permissions.
 
-Destination publication claims the existing directory entry and compares its bytes before exclusive creation of the replacement. Concurrent replacements block integration. Claimed originals remain in private write custody (Git metadata, or destination-local custody when volumes differ) for crash recovery and writers holding an old inode; conflicts report their retained paths. Rollback uses the same guard and cannot discard a changed claimed original.
+## Process custody and runs pinned to older helpers
 
-Candidate identity is checked across verification and acceptance; a changed owned worktree is retained instead of automatically removed. Guarded writes validate parent-directory identities as well as final entries. The parent host provides filesystem containment: these checks are conflict detection, not an OS sandbox against processes that deliberately rename ancestors between syscalls. Process custody stops the owned process group; intentionally detached services and processes outside that group remain the native harness/operator responsibility. Independent commands must finish their work before returning success.
+Process custody stops the owned process group; intentionally detached services and processes outside that group remain the native harness/operator responsibility. Independent commands must finish their work before returning success. Cleanup checks that the owned worktree is still at the accepted tip after ownership reads, just before removal; a changed worktree is retained for inspection.
 
-Native interruption recovery validates the complete checkout against the journaled candidate identity before accepting saved verification. Cleanup validates accepted worktree contents after ownership reads, just before removal; an already absent owned worktree can still be unregistered. Concurrent editor saves detected at either boundary retain their files and require review or recovery.
+A run prepared by an older helper, without a run branch, finishes review, apply and recovery through that pinned helper. The current helper refuses its custody instead of integrating it.

package/lib/host-packages/claude/openplanr/skills/delegate/references/operator-guide.md

@@ -114,7 +114,31 @@ a GGUF filename or display label is not automatically its request ID. Apply an
 explicit model override only to this run through the existing native options;
 rewrite or enroll a saved profile only when the user requests it.
 
-If a native CLI uses read-only permissions for non-interactive runs, delegation reports attention rather than enabling writes. Resolve access in that CLI’s own configuration or explicitly authorized exact-session invocation, then continue the recorded session. Model summaries are never sufficient evidence of implementation.
+When the CLI's own settings choose no permission mode, dispatch and resume start
+Claude Code with `--permission-mode acceptEdits` and Codex with `--sandbox
+workspace-write`, so a stock install can edit files in its worktree. In
+`acceptEdits`, Claude also runs `mkdir`, `touch`, `rm`, `rmdir`, `mv`, `cp` and `sed`
+without asking, for paths in the worktree and the added context directory. A
+configured mode always wins: Claude `permissions.defaultMode` in user, project, local
+or managed settings files, or Codex `sandbox_mode` in `config.toml` or the project's
+`.codex/config.toml`, outside an inactive profile. Unreadable or oversized settings
+count as configured. Cursor runs with `--trust`. Other shell commands still follow
+the CLI's allowlist and approval settings, and no bypass flag is passed.
+
+Limits of this check: it reads settings files only, so system or MDM-delivered
+policies and Codex managed configuration are not seen. A Codex profile selected in
+one file but defined in the other is not matched. A project-level Claude
+`defaultMode`, including `"auto"`, counts as configured. The check runs again on each
+`resume`, so a settings change between turns can change the flag.
+
+If the CLI still denies an action, delegation
+reports attention rather than widening access. Resolve access in that CLI’s own configuration or explicitly authorized exact-session invocation, then continue the recorded session. Model summaries are never sufficient evidence of implementation.
+
+Cursor's CLI writes its own state back to `~/.cursor/cli-config.json` when a run
+ends, so `permissions.allow` entries added while a run is active can be lost. Add
+the commands the task needs (for example `Shell(pnpm)`) before `dispatch`. After an
+`E_ADAPTER_PERMISSION` attention state, wait until the run has stopped, edit the
+allowlist, then `resume` the same run.
 
 ## Diagnostics and unused runs
 

package/lib/host-packages/claude/openplanr/skills/delegate/references/run-handoff.md

@@ -1,7 +1,7 @@
 # Run/session lifecycle
 
-Each new run has private v2 records, a complete readable capsule, one owned detached
-worktree and a pinned helper snapshot. Records contain configuration references,
+Each new run has private v3 records, a complete readable capsule, one owned worktree
+on its run branch and a pinned helper snapshot. Records contain configuration references,
 not credential values. Old runs route operations through their unchanged pinned
 helpers; there is no automatic migration or permission expansion.
 

package/lib/host-packages/claude/openplanr/skills/delegate/references/worktree-custody.md

@@ -1,13 +1,21 @@
 # Worktree and context custody
 
-One run owns one detached worktree outside the user's checkout. Copy only selected
-dirty state, preserving starting bytes, deletion and the Git executable bit. Full
-required ignored planning and repository instructions live in the readable capsule.
-The source checkout and unrelated worktrees remain independent.
+One run owns one locked worktree on its own branch, `planr-delegate/<runId>`, outside
+the user's checkout. Only selected dirty state is copied, preserving starting bytes,
+deletion and the Git executable bit, then committed as the run's base commit without
+repository hooks. Full required ignored planning and repository instructions live in
+the readable capsule. The source checkout and unrelated worktrees remain independent.
 
-Custody records bind the run, worktree ownership, starting HEAD/index, selected
-source state and Preserve paths. Commits, staging, Preserve changes, scope violations
-and destination conflicts block acceptance. Integration scope constrains accepted
+Custody records bind the run, worktree ownership, base commit, selected source state,
+Preserve paths and the repository's refs. The delegate may commit; the run branch must
+stay checked out and descend from its base. The branch checked out in the parent at
+prepare may not be deleted or moved to a commit that contains the run's base, and a
+restore ref may not be deleted while its run is still applying or interrupted. Any
+other ref change, such as a branch switch, amend, reset, stash, fetch or tag, is a
+report warning.
+Preserve changes, scope violations, submodule (gitlink) changes, including ones that
+`ignore` settings hide, and patches the parent
+checkout no longer accepts block acceptance. Integration scope constrains accepted
 changes; it does not sandbox every native tool operation. Native tools, hooks,
 plugins and MCP run under the native harness's permissions and trusted configuration.
 
@@ -16,10 +24,10 @@ and join the candidate; no manual digest acceptance or immutable setup-path list
 needed. Ignored dependencies/build/cache outputs are ordinary worktree outputs.
 
 Successful native integration removes only the owned worktree by checking its
-ownership token and Git registration. Retention can be requested before dispatch.
+ownership token and Git registration, then deletes its run branch. Retention can be requested before dispatch.
 Failures/interruption retain custody. The private run keeps context, accepted patch,
 verification evidence, report and exact native session reference after cleanup.
 Old runs continue through their pinned helper; never broaden their policy or migrate
 their records automatically.
 
-Guarded integration keeps original directory entries for recovery and for writers holding the old inode. If Git metadata is on a different filesystem, private ignored write custody stays beside the destination and its location is recorded in the Git metadata before the first source write. Recovery validates that location inside the checkout. Existing metadata-based custody and pinned legacy helpers remain readable.
+Runs prepared by older helpers use detached worktrees and their own integration; they finish through that pinned helper.

package/lib/host-packages/claude/openplanr/skills/delegate/scripts/adapters/claude.mjs

@@ -5,9 +5,9 @@ import { capsuleDirectory } from './capsule.mjs';
 import { AdapterError, destinationFromEndpoint, invokeProcess } from './generic.mjs';
 import {
   createNativeProgress,
+  EDIT_DEFAULT_EXECUTION_POLICY,
   knownDestination,
   NATIVE_CAPABILITIES,
-  NATIVE_EXECUTION_POLICY,
   nativeFailure,
   nativeObserver,
   nativeTurn,
@@ -26,7 +26,7 @@ function routingVariables(env) {
   );
 }
 
-// Keeps only routing variables from settings files; callers expose source labels and origins.
+// Keeps routing variables and whether a default permission mode is set; callers expose source labels.
 async function readClaudeRoutingSettings(profile, env, cwd, options = {}) {
   const managedRoot =
     options.managedRoot ??
@@ -108,6 +108,7 @@ async function readClaudeRoutingSettings(profile, env, cwd, options = {}) {
       inspected.push({
         source,
         env: routingVariables(settings.env ?? {}),
+        ...(settings.permissions?.defaultMode !== undefined ? { defaultMode: true } : {}),
         ...(settings.policyHelper ? { opaqueRouting: true } : {}),
       });
     } catch (error) {
@@ -202,6 +203,16 @@ export async function resolveClaudeRouting(profile, env, cwd, options) {
   };
 }
 
+// Edit access only when no settings file chooses a mode; unreadable settings count as chosen.
+export async function claudeWriteFlags(profile, env, cwd, options) {
+  try {
+    const settings = await readClaudeRoutingSettings(profile, env, cwd, options);
+    return settings.some((entry) => entry.defaultMode) ? [] : ['--permission-mode', 'acceptEdits'];
+  } catch {
+    return [];
+  }
+}
+
 export async function resolveClaudeDestination(profile, env, cwd) {
   return (await resolveClaudeRouting(profile, env, cwd)).destination;
 }
@@ -263,6 +274,7 @@ async function execute({
     profile.executable,
     [
       ...profile.argv,
+      ...(await claudeWriteFlags(profile, env, cwd)),
       '--print',
       '--output-format',
       'stream-json',
@@ -317,7 +329,7 @@ export const claudeAdapter = Object.freeze({
     return {
       capabilities: NATIVE_CAPABILITIES,
       ...routing,
-      executionPolicy: NATIVE_EXECUTION_POLICY,
+      executionPolicy: EDIT_DEFAULT_EXECUTION_POLICY,
     };
   },
   run: execute,

package/lib/host-packages/claude/openplanr/skills/delegate/scripts/adapters/codex.mjs

@@ -1,11 +1,12 @@
+import { readFile, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { capsuleDirectory } from './capsule.mjs';
 import { AdapterError, invokeProcess } from './generic.mjs';
 import {
   createNativeProgress,
+  EDIT_DEFAULT_EXECUTION_POLICY,
   knownDestination,
   NATIVE_CAPABILITIES,
-  NATIVE_EXECUTION_POLICY,
   nativeFailure,
   nativeObserver,
   nativeTurn,
@@ -31,6 +32,39 @@ export async function resolveCodexDestination(profile, env) {
   return knownDestination(endpoint);
 }
 
+// Any uncommented sandbox_mode key outside an inactive [profiles.<name>] table counts as set.
+function sandboxModeSet(config) {
+  const active = /^\s*profile\s*=\s*["']([^"']+)["']/mu.exec(config.split(/^\s*\[/mu)[0])?.[1];
+  let skipped = false;
+  for (const line of config.split('\n')) {
+    const header = /^\s*\[\s*profiles\.(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_-]+))\s*\]/u.exec(line);
+    if (header) skipped = (header[1] ?? header[2] ?? header[3]) !== active;
+    else if (/^\s*\[/u.test(line)) skipped = false;
+    if (!skipped && /^[^#]*\bsandbox_mode["']?\s*=/u.test(line)) return true;
+  }
+  return false;
+}
+
+// Missing config means no sandbox choice; unreadable or oversized config counts as a choice.
+async function codexConfigChoosesSandbox(path) {
+  let config;
+  try {
+    if ((await stat(path)).size > 64 * 1024) return true;
+    config = await readFile(path, 'utf8');
+  } catch (error) {
+    return error.code !== 'ENOENT';
+  }
+  return sandboxModeSet(config);
+}
+
+// Workspace writes only when neither the user nor the project config chooses a sandbox.
+export async function codexWriteFlags(profile, env, cwd) {
+  const home = profile.configDir || env.CODEX_HOME || join(env.HOME ?? '', '.codex');
+  for (const path of [join(home, 'config.toml'), join(cwd, '.codex', 'config.toml')])
+    if (await codexConfigChoosesSandbox(path)) return [];
+  return ['--sandbox', 'workspace-write'];
+}
+
 async function execute({
   profile,
   cwd,
@@ -84,6 +118,8 @@ async function execute({
   const args = [
     ...profile.argv,
     'exec',
+    // `exec resume` takes no sandbox flag of its own; the parent `exec` flag applies.
+    ...(await codexWriteFlags(profile, env, cwd)),
     ...(sessionId ? ['resume'] : []),
     '--json',
     ...(!sessionId ? ['--add-dir', directory] : []),
@@ -141,7 +177,7 @@ export const codexAdapter = Object.freeze({
     return {
       capabilities: NATIVE_CAPABILITIES,
       destination: await resolveCodexDestination(profile, env),
-      executionPolicy: NATIVE_EXECUTION_POLICY,
+      executionPolicy: EDIT_DEFAULT_EXECUTION_POLICY,
     };
   },
   run: execute,

package/lib/host-packages/claude/openplanr/skills/delegate/scripts/adapters/native.mjs

@@ -20,6 +20,11 @@ export const NATIVE_EXECUTION_POLICY = Object.freeze({
   extensions:
     'Trusted native hooks, plugins and MCP may execute code or contact additional services. OpenPlanr does not sandbox these extensions.',
 });
+// Claude Code and Codex start in their edit mode when native settings choose none.
+export const EDIT_DEFAULT_EXECUTION_POLICY = Object.freeze({
+  ...NATIVE_EXECUTION_POLICY,
+  permissions: 'native-managed; edit mode when none is configured',
+});
 export const NATIVE_MANAGED_DESTINATION = Object.freeze({
   class: 'native-managed',
   origin: 'native-managed',