pi-landstrip 0.17.42 → 0.18.0

package/README.md

@@ -12,9 +12,10 @@ execution, OpenCode-compatible primary agents, and sandbox-aware subagents. It
 uses an Anthropic-compatible policy and delegates OS-level enforcement to
 [`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 extension includes a shared [sandbox policy](./sandbox.json). Agent definitions,
+worker limits, shared permissions, and OpenCode integration flags live under
+`landstrip` in Pi `settings.json`. Trusted-project settings override global settings
+and built-in agent defaults.
 
 Process-backed subagents require Pi >= 0.82.0, and Node.js >= 22.19.0.
 
@@ -47,14 +48,14 @@ 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.
+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 implementation and mode. There
+is no silent LPAC-to-standard fallback.
 
-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).
+Optional restricted-user installation supports Git Bash without AppContainer.
+It requires one-time elevation and persistent local accounts and WFP rules; see
+[Windows restricted-user installation](#windows-restricted-user-installation).
 
 ## Disabling
 
@@ -71,20 +72,17 @@ 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 sandboxed command requests access not already covered by policy, 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 requested. Project approvals are written to `.pi/sandbox.json`;
+global approvals are written 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,19 +101,56 @@ 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 the active policy and toggle sandboxing. `/agents` is the
+single interface for selecting the primary role, inspecting every configured agent
+and task session, and setting the global or trusted-project concurrency limit.
+
+## Permission model
+
+Agent permissions and sandbox permissions are separate policy layers. They have
+different targets and make decisions at different stages:
+
+| Layer              | Target                                           | Decision point       | Governs                                                             |
+| ------------------ | ------------------------------------------------ | -------------------- | ------------------------------------------------------------------- |
+| Agent permission   | A primary agent or subagent                      | Before tool dispatch | Whether that agent may invoke a tool with the declared arguments    |
+| Sandbox permission | A sandboxed command and its descendant processes | During execution     | The filesystem and network operations the command actually attempts |
+
+The execution path is:
+
+```text
+agent → agent permission check → tool command → sandbox → OS resource
+```
+
+The two kinds of query are triggered independently. An agent `ask` decision comes
+from the selected primary or subagent definition and holds the tool call before it is
+dispatched. A sandbox query comes from the command reaching the OS boundary. Where
+the platform supports dynamic queries, such as Linux seccomp traps, this can happen
+after the process has started; the broker holds the operation while the user decides.
+
+Neither policy can replace the other:
+
+- An agent `allow` permits tool dispatch but cannot widen the sandbox.
+- A sandbox approval permits a concrete OS operation but does not authorize an agent
+  to invoke a tool denied by its agent policy.
+- Agent policy describes tool requests known before dispatch. Sandbox policy constrains
+  executable behavior, including unexpected or malicious native code.
+- Agent and sandbox approvals are tracked separately and do not imply one another.
+
+For example, an agent may be allowed to invoke Bash, while the launched executable is
+still blocked or queried when it attempts `openat("/home/user/.ssh/config")` or
+`connect("127.0.0.1:5432")`.
 
 ## 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 TUI agent palette
-(`secondary` for build, `accent` for plan) and appear in the status line and
-agent selectors.
+The `/agents` dialog provides one catalog for every configured agent. Each entry
+shows whether its mode is `primary`, `subagent`, or `all`; primary-capable entries
+can be activated from the list. OpenCode-compatible `build` and `plan` roles are
+provided by default. Build has normal development access; plan asks before shell
+commands and file changes. Their built-in colors appear in the status line and
+agent catalog.
 The selection controls the root system prompt and permissions and is restored
-with the session.
+with the session. Press `Ctrl+Shift+A` while Pi is idle to cycle through enabled
+primary agents; switching is blocked while an agent run is active.
 
 ## Subagents
 
@@ -147,24 +182,20 @@ 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`.
+The **Sessions** tab in `/agents` inspects child transcripts and supports parent and
+sibling navigation. Open a specific task directly with `/agents <id>`. Completed and
+failed task metadata remains available after reload, and persisted sessions can be
+continued 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`.
+Agent permissions wrap each worker's composed tools: `deny` blocks dispatch, `ask`
+prompts in the root UI, and `allow` runs the tool. Other workers may continue while
+an agent-permission prompt is open. Forwarded dialogs identify the agent, task
+summary, and task ID. An "Allow for this session" decision applies to the root
+session and its descendants.
 
 Subagents fail closed when sandboxing is expected but unavailable, unsupported,
 or missing. An explicit `--no-sandbox` flag or `enabled: false` configuration is
@@ -205,157 +236,180 @@ 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.
+The two permission layers deliberately use different configuration files:
+
+- Agent policy belongs under `landstrip` in Pi `settings.json`. It controls which
+  primary agents and subagents exist and which tools they may dispatch.
+- Sandbox policy belongs in `sandbox.json`. It controls the filesystem and network
+  operations attempted by sandboxed commands and worker processes.
+
+Rules cannot be copied between these files: the schemas, targets, and enforcement
+stages are different, so an agent rule is neither valid nor equivalent as a sandbox
+rule, or vice versa.
+
+### Agent policy (`settings.json`)
+
+Agent configuration is read from `landstrip` in `~/.pi/agent/settings.json` and, for
+trusted projects, `.pi/settings.json`. Project values override global values; both
+are merged over internal defaults. The built-in subagents are `code-reviewer`,
+`explore`, `general`, and the OpenCode-compatible `scout` reconnaissance agent.
+
+The read-only `code-reviewer` is available without additional configuration: delegate
+with `task` using `subagent_type: "code-reviewer"`. It can read and search files and
+run a fixed set of non-mutating Git inspection commands; all other tools are denied.
 
-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:
+An agent configuration example follows. This belongs in Pi `settings.json`, not
+`sandbox.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` is an integer from 0 through 16 controlling concurrent
+workers. The default is 1, making `task` and `code-reviewer` available immediately.
+Set it to 0 to remove 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.
+
+`landstrip.permission` defines the shared baseline inherited by every agent. Each
+`landstrip.agent.<name>.permission` map overrides that baseline. 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 `settings.json` file that
+defines them. `color` accepts `#RRGGBB` or OpenCode theme names (`primary`,
+`secondary`, `accent`, `success`, `warning`, `error`, `info`). `hidden` removes an
+agent from the user-facing catalog; the model can still invoke a hidden agent whose
+mode supports subagent work via `task`.
+
+Primary agents honor configured models and supported Pi thinking-level variants;
+omitting either preserves the current session setting. A model may use the full
+`provider/model` name or a bare model ID when that ID is unique. Selection fails
+without changing the active primary agent when the model is missing, ambiguous, or
+unavailable for authentication. Subagent workers also honor model selection,
+supported Pi thinking-level variants, and step limits. Later matching permission
+rules win. Put provider-specific values under `options`; unknown agent fields are
+rejected.
+
+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 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.
+Project settings override global settings, including each OpenCode flag. Set a flag
+to `false` to disable that source. OpenCode project agents override global OpenCode
+agents. Definitions from `landstrip.agent` (built-in, global, and project) take
+precedence over OpenCode imports with the same name; conflicts are silent. Project
+Pi settings and project OpenCode agents are skipped when the project is untrusted;
+global OpenCode agents still load when `showGlobalAgents` is enabled.
 
-`subagents.json` accepts top-level `maxSubagents`, `opencode`, and `subagents`;
-sandbox fields belong in `sandbox.json`.
+OpenCode JSONC comments and trailing commas are supported. `{file:path}` prompt tokens
+resolve relative to the OpenCode config file or Pi `settings.json` that defines them.
 
-The Windows sandbox fields are:
+### Sandbox policy (`sandbox.json`)
+
+Sandbox policy is read from `~/.pi/agent/sandbox.json` and, for trusted projects,
+`.pi/sandbox.json`. It grants runtime filesystem and network access to sandboxed
+commands; it does not grant an agent permission to dispatch a tool. Likewise, an
+agent `allow` cannot grant filesystem or network access through the sandbox.
+
+For example, Windows sandbox fields belong in `sandbox.json`, not Pi
+`settings.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` 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 while AppContainer is
+active. Windows implementation selection is automatic and cannot be changed by
+project configuration.
 
-### 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.
+Install requests UAC elevation and defaults to eight restricted-network
+accounts, two unrestricted-network accounts, and proxy ports 60080-60111. Run
+`npx @landstrip/landstrip windows install --help` for pool and port options, then
+restart Pi. Uninstalling returns Landstrip to AppContainer automatically.
 
-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:
+The extension checks the active implementation and installation health before a
+sandboxed launch. An unhealthy installation fails rather than falling back to
+AppContainer. 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:
 
 ```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:
+`subagents.json` is no longer supported. Move its values into the corresponding
+global or project Pi `settings.json`, then delete the old file:
 
-- Move `agent` and `permission` from Pi `settings.json` or OpenCode JSON under
-  `subagents.agent` and `subagents.permission`.
+- Move top-level `maxSubagents` to `landstrip.maxSubagents`.
+- Move `subagents.agent` to `landstrip.agent`.
+- Move `subagents.permission` to `landstrip.permission`.
+- Move top-level `opencode` to `landstrip.opencode`.
 - 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.
+- Move legacy top-level Pi `agent`, `permission`, `subagents`, and `maxSubagents`
+  settings under `landstrip`.
+- Leave sandbox policy in `~/.pi/agent/sandbox.json` and `.pi/sandbox.json`; those
+  files are unchanged.
+
+An existing `~/.pi/agent/subagents.json` or trusted-project `.pi/subagents.json`
+produces an actionable migration diagnostic instead of being loaded.
 
 ## Plugin API