pi-landstrip 0.17.43 → 0.18.1

package/README.md

@@ -7,14 +7,13 @@ Subagents  3 active
 └─ ● running  @general  Design bounded summaries
 ```
 
-`pi-landstrip` is a [Pi](https://pi.dev/) extension that provides sandboxed Bash
-execution, OpenCode-compatible primary agents, and sandbox-aware subagents. It
-uses an Anthropic-compatible policy and delegates OS-level enforcement to
+`pi-landstrip` adds sandboxed Bash, primary agents, and sandboxed subagents to
+[Pi](https://pi.dev/). OS isolation is provided by
 [`landstrip`](https://github.com/landstrip/landstrip).
 
-The extension includes a shared [sandbox policy](./sandbox.json) and separate
-[agent configuration](./subagents.json). Global and trusted-project files can
-override both.
+The package includes a default [sandbox policy](./sandbox.json). Configure agents,
+subagent limits, permissions, and OpenCode imports under `landstrip` in Pi
+`settings.json`. Trusted project settings override global settings.
 
 Process-backed subagents require Pi >= 0.82.0, and Node.js >= 22.19.0.
 
@@ -46,15 +45,12 @@ Alternatively, place the extension under `~/.pi/agent/extensions/` (global) or
 
 On unsupported platforms the extension loads but leaves sandboxing disabled.
 
-On Windows, Pi's Git Bash/MSYS shell cannot run under LPAC. The packaged policy
-therefore selects standard AppContainer explicitly. This is weaker than LPAC because
-resources granted to `ALL APPLICATION PACKAGES` remain visible; `/sandbox` and the
-status line report the active backend and mode. There is no silent
-LPAC-to-standard fallback.
+Pi's Git Bash/MSYS shell cannot start in LPAC, so the default Windows policy uses
+standard AppContainer. `/sandbox` and the status line show the active Windows
+isolation. LPAC launch failures return an error.
 
-An optional restricted-user backend supports Git Bash without AppContainer. It
-requires one-time elevated host setup and persistent local accounts and WFP rules;
-see [Windows restricted-user setup](#windows-restricted-user-setup).
+Restricted-user isolation supports Git Bash with restricted local accounts. See
+[Windows restricted-user installation](#windows-restricted-user-installation).
 
 ## Disabling
 
@@ -71,20 +67,16 @@ processes, but without the outer Landstrip OS sandbox. The extension warns once
 per session. Agent tool permissions still apply, but they are not an OS isolation
 boundary.
 
-Trusted project config overrides global config except for the Windows backend,
-which can be selected only in the trusted global file. `/sandbox` updates a trusted
-project sandbox file when present, otherwise the global file. Pi versions without a
-project-trust API use only global configuration.
+Trusted project config overrides global config. `/sandbox` updates a trusted
+project sandbox file when present, otherwise the global file. Pi versions
+without a project-trust API use only global configuration.
 
 ## Behavior
 
-When Pi requests a sandboxed permission, the extension sends a host notification
-and opens a dialog. The user can allow once, allow for the session, persist for
-the project or globally, or reject. The dialog shows the exact path or domain
-being approved.
-
-Project approvals are written to `.pi/sandbox.json`; global approvals are
-written to `~/.pi/agent/sandbox.json`.
+When a command requests additional access, the extension opens an approval dialog.
+The user can allow once, allow for the session, save the approval globally or for the
+project, or reject it. Project approvals go to `.pi/sandbox.json`; global approvals
+go to `~/.pi/agent/sandbox.json`.
 
 The main agent remains a normal Pi process. `pi-landstrip` replaces Bash execution,
 including AI `bash` calls and manually typed shell commands (`!` and `!!`), with a
@@ -103,27 +95,39 @@ task's dedicated session directory. These paths are required to construct a
 normal Pi worker and are not persisted into `sandbox.json`. The worker receives
 write access only to its own session and temporary directories.
 
-Use `/sandbox` to inspect the active policy and toggle sandboxing. Use `/agents`
-to select the primary role, inspect worker configuration and status, and set the
-global or trusted-project concurrency limit.
+Use `/sandbox` to inspect or disable the sandbox. Use `/agents` to select a primary
+agent, inspect primary agents, subagents, and tasks, and set subagent limits.
+
+## Permission model
+
+Agent and sandbox permissions apply at different stages:
+
+| Layer              | Checked before or during | Controls                                   |
+| ------------------ | ------------------------ | ------------------------------------------ |
+| Agent permission   | Before tool dispatch     | Which tools an agent may call              |
+| Sandbox permission | During process execution | Filesystem and network access for commands |
+
+```text
+agent → agent permission → tool → sandbox → OS resource
+```
+
+Each layer prompts independently. An agent approval allows tool dispatch; sandbox
+restrictions still apply to the resulting process.
 
 ## Primary agents
 
-The `/agents` selector provides OpenCode-compatible `build` and `plan` roles by
-default. Build has normal development access; plan asks before shell commands
-and file changes. Built-in colors match OpenCode's default theme roles
-(`success`/green for build, `warning`/orange for plan) and appear in the status
-line and agent selectors.
-The selection controls the root system prompt and permissions and is restored
-with the session.
+`/agents` lists all configured agents and their modes. Press Enter to activate a
+visible primary agent. The built-in primary agents are `build` and `plan`. Build has
+normal development access; plan asks before shell commands and file edits.
+
+The selected prompt and permissions are stored in the session. Press `Ctrl+Shift+A`
+while Pi is idle to cycle through visible primary agents.
 
 ## Subagents
 
-Landstrip provides an OpenCode-compatible `task` tool. Each active task runs as a
-full `pi --mode rpc` process inside an outer Landstrip sandbox. The sandbox
-covers Pi, its plugins and tools, model requests, and descendant processes. The
-root Pi process supervises RPC, permissions, nesting, persistence, and result
-delivery.
+The `task` tool runs each subagent in a separate `pi --mode rpc` process inside a
+Landstrip sandbox. The root Pi process manages RPC, permissions, nesting, sessions,
+and results.
 
 Workers use normal Pi resource discovery and plugin loading, plus the
 `pi-landstrip` worker extension. Requested tools are composed inside the worker,
@@ -131,7 +135,7 @@ so plugins can add or replace implementations. Each task starts a fresh Pi
 process and plugin instances; continuing a `task_id` restores its persisted Pi
 session in a new process.
 
-The tool accepts the OpenCode task fields:
+The tool accepts these fields:
 
 ```json
 {
@@ -144,32 +148,18 @@ The tool accepts the OpenCode task fields:
 }
 ```
 
-Foreground tasks return the child result directly. Background tasks return a
-queued result and deliver completion automatically. Task rows show lifecycle
-state, current activity, tool-call count, elapsed time, and expandable output.
-Use `/subagents` to open an inspector with **Agents** and **Sessions** tabs. The
-Agents tab lists every available subagent type and its `built-in`, `global`, or
-`local` source. The Sessions tab inspects child transcripts; task rows can open a
-specific one with `/subagents <id>`. Completed and failed task metadata remains
-available after reload, and persisted sessions can be continued with `task_id`.
+Foreground tasks return their result directly. Background tasks return immediately
+and report completion later. The **Tasks** tab in `/agents` shows task status and
+output. Open a task with `/agents <id>`. Continue a saved session with `task_id`.
 
 Session switching or shutdown stops live workers. After an unclean restart,
 unfinished work is marked interrupted; completed but undelivered background
 results are delivered when the root session resumes.
 
-OpenCode-style permissions wrap each worker's composed tools: `deny` blocks,
-`ask` prompts in the root UI, and `allow` runs the tool. Other workers may
-continue while a prompt is open. Forwarded worker dialogs identify the agent,
-task summary, and task ID. An "Allow for this session" decision applies to the
-root session and its descendants.
-
-Tool permissions cannot widen the outer Landstrip policy. Sandbox approvals
-continue to use `.pi/sandbox.json` and `~/.pi/agent/sandbox.json`.
-
-Subagents fail closed when sandboxing is expected but unavailable, unsupported,
-or missing. An explicit `--no-sandbox` flag or `enabled: false` configuration is
-treated as an intentional opt-out and uses the warned unsandboxed process path.
-Unsupported Pi versions still fail task startup.
+Workers check agent permissions before tool dispatch: `deny` blocks, `ask` prompts in
+the root UI, and `allow` runs the tool. Required sandbox startup failures stop the
+task. With `--no-sandbox` or `enabled: false`, workers run without OS isolation and
+Pi shows a warning.
 
 ### Platform behavior
 
@@ -205,158 +195,134 @@ first.
 
 ## Configuration
 
-Subagent configuration is read from `~/.pi/agent/subagents.json` and, for trusted
-projects, `.pi/subagents.json`. Project values override global values; both are
-merged over the packaged [defaults](./subagents.json). The packaged subagent types
-are `explore`, `general`, and the OpenCode-compatible `scout` reconnaissance agent.
+Agent permissions are configured under `landstrip` in Pi `settings.json`. Sandbox
+permissions are configured in `sandbox.json`. The files use different schemas and
+control different stages.
+
+### Agent policy (`settings.json`)
+
+Agent settings are read from `~/.pi/agent/settings.json` and, for trusted projects,
+`.pi/settings.json`. Built-in subagents are `explore`, `general`, and `scout`.
 
-Sandbox policy remains in `~/.pi/agent/sandbox.json` and `.pi/sandbox.json`. Pi's
-`settings.json` only needs the normal package entry for the extension:
+Pi Markdown agents are loaded from `~/.pi/agent/agents/*.md` and, for trusted
+projects, `.pi/agents/*.md`. Nested directories are supported. Project Markdown
+agents override global Markdown agents. Settings under `landstrip.agent` override
+Markdown and OpenCode agents with the same name.
+
+Add agent configuration under `landstrip` in Pi `settings.json`:
 
 ```json
 {
-  "packages": ["npm:pi-landstrip"]
+  "landstrip": {
+    "maxSubagents": 2,
+    "agent": {
+      "review": {
+        "description": "Review code without modifying it",
+        "mode": "subagent",
+        "prompt": "Review the requested code and report concrete findings.",
+        "permission": {
+          "edit": "deny",
+          "bash": "ask"
+        }
+      }
+    },
+    "permission": {
+      "task": {
+        "*": "deny",
+        "review": "allow"
+      }
+    }
+  }
 }
 ```
 
-OpenCode Markdown agent import flags live in `subagents.json` as top-level
-`opencode` (both default to `true`):
+`landstrip.maxSubagents` sets the maximum number of concurrent subagents from 0 to 16. The default is 1; zero disables `task`. The `/agents` **Settings** tab provides
+**Maximum subagents (global)** and **Maximum subagents (local)**.
+
+`landstrip.permission` applies to every agent. Each
+`landstrip.agent.<name>.permission` map adds agent-specific rules; later matching
+rules win. Agent definitions support `mode`, `prompt`, `model`, `variant`, `steps`,
+`color`, `disable`, and `allow`/`ask`/`deny` permissions. `{file:path}` prompt
+references are resolved from the defining `settings.json`. Provider-specific fields
+belong under `options`.
+
+`hidden` removes an agent from `/agents`. A hidden, subagent-capable agent remains
+available to `task`. Agent `mode` controls activation: only `primary` and `all` agents
+can be selected as primary, while only `subagent` and `all` agents can be passed to
+`task`. Missing, ambiguous, or unauthenticated primary-agent models produce an error
+and leave the current agent active.
+
+OpenCode integration flags also live in Pi `settings.json` under
+`landstrip.opencode`; both default to `true`:
 
 ```json
 {
-  "maxSubagents": 0,
-  "opencode": {
-    "showGlobalAgents": true,
-    "showLocalAgents": true
-  },
-  "subagents": {
-    "agent": {}
+  "packages": ["npm:pi-landstrip"],
+  "landstrip": {
+    "opencode": {
+      "showGlobalAgents": true,
+      "showLocalAgents": true
+    }
   }
 }
 ```
 
-- `showGlobalAgents` imports Markdown agents from the OpenCode global config
-  directory (`$OPENCODE_CONFIG_DIR`, or `$XDG_CONFIG_HOME/opencode`, or
-  `~/.config/opencode`) under `agent/` and `agents/`.
-- `showLocalAgents` imports Markdown agents from the trusted project's
-  `.opencode/agent/` and `.opencode/agents/` directories.
+- `showGlobalAgents` imports `agent` definitions from `opencode.json` and
+  `opencode.jsonc`, plus Markdown agents under `agent/` and `agents/`, in the
+  OpenCode global config directory (`$OPENCODE_CONFIG_DIR`,
+  `$XDG_CONFIG_HOME/opencode`, or `~/.config/opencode`).
+- `showLocalAgents` imports `agent` definitions from project `opencode.json` and
+  `opencode.jsonc`, `.opencode/opencode.json` and `.opencode/opencode.jsonc`, and
+  Markdown agents under `.opencode/agent/` and `.opencode/agents/`.
+
+Set either flag to `false` to disable that OpenCode source. Project OpenCode agents
+override global OpenCode agents. Pi Markdown agents and `landstrip.agent` settings
+take precedence over OpenCode imports. Project sources require a trusted project.
+OpenCode config files support JSONC comments, trailing commas, and `{file:path}`
+prompt references.
 
-Set a flag to `false` to disable that source. OpenCode local agents override
-OpenCode global agents. Pi agent definitions from `subagents.json` (built-in,
-global, and local) take precedence over OpenCode imports with the same name;
-conflicts are silent. Local OpenCode agents are skipped when the project is
-untrusted, regardless of the flag.
+### Sandbox policy (`sandbox.json`)
 
-`subagents.json` accepts top-level `maxSubagents`, `opencode`, and `subagents`;
-sandbox fields belong in `sandbox.json`.
+Sandbox settings are read from `~/.pi/agent/sandbox.json` and, for trusted projects,
+`.pi/sandbox.json`. They control runtime filesystem and network access.
 
-The Windows sandbox fields are:
+Configure Windows sandbox fields in `sandbox.json`:
 
 ```json
 {
   "windows": {
-    "backend": "appContainer",
     "appContainerMode": "standard",
     "allowLoopback": false
   }
 }
 ```
 
-`backend` is `"appContainer"` or `"restrictedUser"`. It is a trusted host setting:
-only `~/.pi/agent/sandbox.json` can change it, and project configuration cannot
-override it. `appContainerMode` is `"lpac"` or `"standard"`; core Landstrip defaults
-to LPAC, while the Pi package defaults to standard mode for Git Bash compatibility.
-`allowLoopback` is independently opt-in and applies only to AppContainer.
+`appContainerMode` accepts `"lpac"` or `"standard"`. The Pi package defaults to
+standard mode for Git Bash. `allowLoopback` applies only to AppContainer. Landstrip
+selects Windows isolation automatically.
 
-### Windows restricted-user setup
+#### Windows restricted-user installation
 
-Provision the backend once before selecting it in global configuration:
+Provision restricted-user execution once to activate it:
 
 ```powershell
-npx @landstrip/landstrip windows setup
+npx @landstrip/landstrip windows install
 npx @landstrip/landstrip windows status
 ```
 
-Setup requests UAC elevation and defaults to eight restricted-network accounts, two
-unrestricted-network accounts, and proxy ports 60080-60111. Run
-`npx @landstrip/landstrip windows setup --help` for pool and port options. Then set
-`"backend": "restrictedUser"` in `~/.pi/agent/sandbox.json` and restart Pi.
+Installation requests elevation and creates eight restricted-network accounts, two
+unrestricted-network accounts, and proxy ports 60080–60111 by default. Use
+`windows install --help` to change these values. Restart Pi after installation.
 
-The extension checks installation health and reads the configured proxy range before
-launching a restricted worker. Restricted-user mode does not support
-`windows.allowLoopback` or `network.allowLocalBinding`. Remove the persistent
-accounts, WFP rules, runner, and recovered per-run ACL grants with:
+Before each launch, the extension checks the installation. A failed health check
+stops the task. Restricted-user isolation does not support `windows.allowLoopback`
+or `network.allowLocalBinding`. Remove the accounts, WFP rules, runner, and ACL
+grants with:
 
 ```powershell
 npx @landstrip/landstrip windows uninstall
 ```
 
-A subagent configuration example follows:
-
-```json
-{
-  "maxSubagents": 2,
-  "subagents": {
-    "agent": {
-      "review": {
-        "description": "Review code without modifying it",
-        "mode": "subagent",
-        "prompt": "Review the requested code and report concrete findings.",
-        "permission": {
-          "edit": "deny",
-          "bash": "ask"
-        }
-      }
-    },
-    "permission": {
-      "task": {
-        "*": "deny",
-        "review": "allow"
-      }
-    }
-  }
-}
-```
-
-`maxSubagents` is an integer from 0 through 16 controlling concurrent workers.
-The packaged default is 0, which removes the `task` tool while retaining primary
-roles. There is no separate subagent enable switch. The Settings tab in
-`/agents` edits this limit for global and trusted-project configuration.
-
-Agent modes, hidden/disabled agents, prompts, colors, and ordered
-`allow`/`ask`/`deny` permissions apply to primary agents and subagents. Prompt
-strings may include OpenCode-style `{file:path}` tokens; relative paths resolve
-against the `subagents.json` file that defines them. `color` accepts `#RRGGBB`
-or OpenCode theme names (`primary`, `secondary`, `accent`, `success`, `warning`,
-`error`, `info`). `hidden` only hides an agent from user-facing primary pickers;
-the model can still invoke a hidden subagent via `task`. Subagent workers also
-honor model selection, supported Pi thinking-level variants, and step limits.
-Primary agent activation currently changes the prompt and permissions only.
-Later matching permission rules win. Put provider-specific values under
-`options`; unknown agent fields are rejected. Agent permissions cannot weaken an
-enabled OS sandbox, grant filesystem access, or grant network access.
-
-## Configuration migration
-
-There is no compatibility loader for previous subagent configuration sources.
-Legacy keys in `settings.json` produce a migration warning. Move configuration as
-follows, then remove the old fields:
-
-- Move `agent` and `permission` from Pi `settings.json` or OpenCode JSON under
-  `subagents.agent` and `subagents.permission`.
-- Convert legacy `tools` booleans to explicit `permission` rules.
-- Move Markdown agent prompts into each `subagents.agent.<name>.prompt` string.
-- Put the worker limit in top-level `maxSubagents`; zero disables delegation.
-- Move `landstrip.opencode` flags from Pi `settings.json` to top-level
-  `opencode` in `subagents.json`.
-- Use `~/.pi/agent/subagents.json` for global configuration and
-  `.pi/subagents.json` for trusted project configuration.
-- Leave sandbox policy in `~/.pi/agent/sandbox.json` and `.pi/sandbox.json`;
-  those files are unchanged.
-
-Do not put these fields in Pi's `settings.json`; `pi-landstrip` does not read
-them there.
-
 ## Plugin API
 
 Pi extensions can discover the active Landstrip runtime through the versioned