@greppleai/grip 0.1.6 → 0.1.7

package/docs/extensions.md

@@ -898,7 +898,7 @@ Current working directory.
 
 Backend-aware file and shell operations for extensions. These APIs use the same active backend as Grip's built-in tools: local by default, or a remote daemon when configured.
 
-Use these APIs for extension tools and extension-owned automation that reads files, writes files, lists directories, or executes shell commands. This is the only safe way for extension tools to run shell commands because it preserves Grip's active execution boundary. Direct local process APIs (`child_process`, `pi.exec`, shell libraries, etc.) bypass the configured tool backend and will run on the local machine even when Grip tools are remote.
+Use these APIs for extension tools and extension-owned automation that reads files, writes files, lists directories, or executes shell commands in the active backend. For deliberate host execution from a managed sandbox, use the separately approved `ctx.execHostProcess()` (direct argv) or `ctx.execHostCommand()` (shell) below. Direct local process APIs (`child_process`, `pi.exec`, shell libraries, etc.) bypass the configured tool backend and will run on the local machine even when Grip tools are remote.
 
 ```typescript
 pi.registerTool({
@@ -941,6 +941,36 @@ Options:
 
 Use `ctx.toolOperations` directly when you need backend-aware file operations such as `readFile`, `writeFile`, `stat`, `readdir`, `glob`, or `grep`.
 
+`ctx.isSandbox()` returns `true` while this session has an active sandbox daemon connection, whether started or attached; it updates when you switch sessions or disconnect. It is `false` for local sessions and other remote tool backends. This indicates where workspace tools run, **not** whether guest paths have a verified host mount: both approved host APIs still require a known mapping and per-command approval.
+
+### ctx.execHostProcess() (direct host argv)
+
+`ctx.execHostProcess(executable, args, { question, explanation?, cwd?, signal?, timeout? })` uses the **same per-invocation approval and mount checks** as the shell API below, but runs a host executable with an argument array using `spawn(..., { shell: false })`. Grip displays the executable, argument array, and translated host cwd. When provided, `explanation` is displayed separately as **unverified** context alongside the extension's `question`; it can contain model-generated text and does not replace the exact argv or cwd. It returns `{ stdout, stderr, code, killed }`; `timeout` is in milliseconds. **Stdout and stderr are raw host output and may contain secrets; filter them before returning tool results to the model.** Use this for host Git when shell execution is not acceptable. This API is unavailable outside a connected mapped sandbox; use `pi.exec(file, args, options)` for direct local processes when no sandbox is active (no approval prompt).
+
+```typescript
+await ctx.execHostProcess("git", ["pull", "--rebase", "origin", "main"], {
+  question: "Run Git pull using host credentials?",
+  explanation: params.explanation, // model input, clearly labeled unverified in the approval
+  signal: ctx.signal,
+});
+```
+
+### ctx.execHostCommand() (managed sandboxes)
+
+A reviewed extension can deliberately run a shell command on the host while a Lima-managed sandbox is active. Use `ctx.execHostCommand(command, { question, cwd?, signal?, timeout?, onChunk? })`. Grip prompts **for every invocation** in the editor area, with the extension's question plus the exact command and translated host cwd generated by Grip. "No", Escape, cancellation, or missing UI denies execution; there is no remember/always-allow option. In RPC mode, the client must answer the `select` dialog; print and JSON modes cannot approve.
+
+```typescript
+const result = await ctx.execHostCommand("printf diagnostics", {
+  question: "Run diagnostics on the host?",
+  cwd: ctx.toolOperations.cwd, // guest path, e.g. /workspace/project
+  signal: ctx.signal,
+});
+```
+
+The optional `cwd` is a **guest** directory, defaulting to the active guest working directory. `ctx.toolOperations.mapWorkspaceDirectoryToHost?.(guestPath)` maps an existing directory within a verified mount to its host counterpart, without executing anything. Host commands run in that translated directory; they do not change the guest cwd or run the configured backend shell prefix. Grip automatically supplies a mount mapping only for sandboxes it starts with a known host source. Arbitrarily attached daemons and remote backends without a verified mapping fail closed, even if their paths look similar to host paths. Guest paths outside the mount and host symlinks escaping the mount are rejected.
+
+**Trust boundary:** Extensions run as host-side JavaScript and can still use Node `fs`, `child_process`, or legacy `pi.exec` directly without this prompt. The approval is mandatory for `ctx.execHostCommand()` and `ctx.execHostProcess()`, **not** a process-wide restriction on extension code. Review extensions before loading them; use `ctx.execToolBackend()` for ordinary sandbox work. Host Git can load repository-controlled config, remotes, credential helpers or filters from a writable mount; unrestricted Git argv can also select remote URLs or programs to run on the host. An approved direct Git process and a model-provided explanation alone are not isolation for host credentials.
+
 ### ctx.getLspStatus() / ctx.configureLsp()
 
 Normal Grip extensions share the single `AgentSession`-owned LSP runtime. Inspect it without creating a parallel manager:

package/docs/sandbox.md

@@ -4,9 +4,9 @@
 
 The command appears in slash-command completion but not in model-visible catalogs, system prompts, tool definitions, templates, skills, or rules. This is not a permission boundary: a model with host shell access may still invoke Lima directly.
 
-`/new --sandbox` starts a fresh conversation in the same connected sandbox (started or attached) without starting another VM. Plain `/new` starts a local session; if there is no active sandbox, `/new --sandbox` does the same. Sandbox connections are remembered in memory only while Grip remains running.
+`/new` starts a fresh conversation in the same connected sandbox (started or attached) without starting another VM. When no sandbox is connected, `/new` starts a local session. Sandbox connections are remembered in memory only while Grip remains running.
 
-Inside a connected sandbox, `/cd <directory>` changes the guest working directory for subsequent tools within the existing mounted workspace. `/cd` without an argument returns to the guest workspace root. It does not change the host session directory, remount the workspace, or reconnect the daemon. The guest working directory resets to the mount root after a session switch or reconnection.
+Inside a connected sandbox, `/cd <directory>` changes the guest working directory for subsequent tools within the existing mounted workspace; completion lists directories from the guest, and the footer displays the guest working directory. `/cd` without an argument returns to the guest workspace root. It does not change the host session directory, remount the workspace, or reconnect the daemon. In a VM that mounts one host project at `/workspace`, `/workspace/planner` is not another mounted host project; open that project as a separate workspace, or attach a daemon whose workspace root contains both projects. The guest working directory resets to the mount root after a session switch or reconnection. Reviewed extensions may explicitly call `ctx.execHostProcess()` (direct argv) or `ctx.execHostCommand()` (shell) to run on the host after per-operation user approval; only managed sandboxes with a verified mount can translate guest directories to host directories. See [Extensions](extensions.md#ctxexechostprocess-direct-host-argv).
 
 Lima-managed sandboxes allow workspace tools (`read`, `write`, `edit`, `ls`, `find`, and `grep`) to access paths anywhere in the guest filesystem, including outside the mounted workspace. This does not mount additional host directories; guest OS permissions still apply. `/cd` remains within the mounted workspace. An attached daemon stays workspace-confined by default: only enable `--daemon-allow-full-filesystem` when the daemon runs inside an intentionally isolated guest, never on an untrusted host. Existing guest daemons need an update or restart to enable this access.
 

package/docs/sessions.md

@@ -23,7 +23,7 @@ For the JSONL file format, active `Session` API, and `SessionManager` lifecycle
 | Command | Description |
 |---------|-------------|
 | `/resume` | Browse and select previous sessions |
-| `/new [--sandbox]` | Start a new session; `--sandbox` reuses the active sandbox connection |
+| `/new` | Start a new session, reusing the active sandbox connection if connected |
 | `/name <name>` | Set the current session display name |
 | `/session` | Show session info |
 | `/tree` | Navigate the current session tree |

package/docs/skills.md

@@ -64,11 +64,11 @@ For project-level Claude Code skills, add to `.grip/settings.json`:
 ## How Skills Work
 
 1. At startup, Grip scans skill locations and extracts names and descriptions
-2. The system prompt includes available skills in XML format per the [specification](https://agentskills.io/integrate-skills)
-3. When a task matches, the agent uses `read` to load the full SKILL.md (models don't always do this; use prompting or `/skill:name` to force it)
+2. The system prompt includes available skill names and descriptions in XML, without file locations
+3. When a task matches, the agent calls `load_skill` with a skill name (or an array of names) to load the full instructions. The tool reports the skill directory for resolving relative references. Use `/skill:name` to force a skill from the UI.
 4. The agent follows the instructions, using relative paths to reference scripts and assets
 
-This is progressive disclosure: only descriptions are always in context, full instructions load on-demand.
+This is progressive disclosure: only descriptions are always in context, full instructions load on-demand. For example, use `load_skill({"name":"pdf-processing"})` for one skill or `load_skill({"name":["pdf-processing","data-analysis"]})` for several. Skills with `disable-model-invocation: true` remain user-only via `/skill:name`.
 
 ## Skill Commands
 
@@ -146,7 +146,7 @@ Per the [Agent Skills specification](https://agentskills.io/specification#frontm
 | `compatibility` | No | Max 500 chars. Environment requirements. |
 | `metadata` | No | Arbitrary key-value mapping. |
 | `allowed-tools` | No | Space-delimited list of pre-approved tools (experimental). |
-| `tools` | No | Tool name or YAML list of lazy tools to load automatically when the skill is loaded via `read` or `/skill:name`. |
+| `tools` | No | Tool name or YAML list of lazy tools to load automatically when the skill is loaded via `load_skill`, `read`, or `/skill:name`. |
 | `disable-model-invocation` | No | When `true`, skill is hidden from system prompt. Users must use `/skill:name`. |
 
 Example with associated lazy tools:

package/docs/usage.md

@@ -41,7 +41,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/scoped-models` | Enable/disable models for Ctrl+P cycling |
 | `/settings` | Thinking level, theme, message delivery, transport |
 | `/resume` | Pick from previous sessions |
-| `/new [--sandbox]` | Start a new session; `--sandbox` reuses the active sandbox connection |
+| `/new` | Start a new session, reusing the active sandbox connection if connected |
 | `/cd [directory]` | Change working directory (within the existing guest mount when sandboxed) |
 | `/name <name>` | Set session display name |
 | `/session` | Show session file, ID, messages, tokens, and cost |

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "grip-extension-custom-provider-anthropic",
 	"private": true,
-	"version": "0.1.6",
+	"version": "0.1.7",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "grip-extension-custom-provider-gitlab-duo",
 	"private": true,
-	"version": "0.1.6",
+	"version": "0.1.7",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "grip-extension-sandbox",
 	"private": true,
-	"version": "0.1.6",
+	"version": "0.1.7",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "grip-extension-with-deps",
 	"private": true,
-	"version": "0.1.6",
+	"version": "0.1.7",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/npm-shrinkwrap.json

@@ -1,17 +1,17 @@
 {
 	"name": "@greppleai/grip",
-	"version": "0.1.6",
+	"version": "0.1.7",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@greppleai/grip",
-			"version": "0.1.6",
+			"version": "0.1.7",
 			"license": "MIT",
 			"dependencies": {
-				"@greppleai/grip-agent-core": "^0.1.6",
-				"@greppleai/grip-ai": "^0.1.6",
-				"@greppleai/grip-tui": "^0.1.6",
+				"@greppleai/grip-agent-core": "^0.1.7",
+				"@greppleai/grip-ai": "^0.1.7",
+				"@greppleai/grip-tui": "^0.1.7",
 				"@silvia-odwyer/photon-node": "0.3.4",
 				"chalk": "6.0.1",
 				"cross-spawn": "7.0.6",
@@ -72,11 +72,11 @@
 			}
 		},
 		"node_modules/@greppleai/grip-agent-core": {
-			"version": "0.1.6",
-			"resolved": "https://registry.npmjs.org/@greppleai/grip-agent-core/-/grip-agent-core-0.1.6.tgz",
+			"version": "0.1.7",
+			"resolved": "https://registry.npmjs.org/@greppleai/grip-agent-core/-/grip-agent-core-0.1.7.tgz",
 			"license": "MIT",
 			"dependencies": {
-				"@greppleai/grip-ai": "^0.1.6",
+				"@greppleai/grip-ai": "^0.1.7",
 				"ignore": "7.0.13",
 				"typebox": "1.4.3",
 				"yaml": "2.9.1"
@@ -86,8 +86,8 @@
 			}
 		},
 		"node_modules/@greppleai/grip-ai": {
-			"version": "0.1.6",
-			"resolved": "https://registry.npmjs.org/@greppleai/grip-ai/-/grip-ai-0.1.6.tgz",
+			"version": "0.1.7",
+			"resolved": "https://registry.npmjs.org/@greppleai/grip-ai/-/grip-ai-0.1.7.tgz",
 			"license": "MIT",
 			"dependencies": {
 				"@anthropic-ai/sdk": "1.1.0",
@@ -110,8 +110,8 @@
 			}
 		},
 		"node_modules/@greppleai/grip-tui": {
-			"version": "0.1.6",
-			"resolved": "https://registry.npmjs.org/@greppleai/grip-tui/-/grip-tui-0.1.6.tgz",
+			"version": "0.1.7",
+			"resolved": "https://registry.npmjs.org/@greppleai/grip-tui/-/grip-tui-0.1.7.tgz",
 			"license": "MIT",
 			"dependencies": {
 				"get-east-asian-width": "1.7.0",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@greppleai/grip",
-	"version": "0.1.6",
+	"version": "0.1.7",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"gripConfig": {
@@ -38,9 +38,9 @@
 		"prepublishOnly": "npm run clean && npm run build && npm run shrinkwrap"
 	},
 	"dependencies": {
-		"@greppleai/grip-agent-core": "^0.1.6",
-		"@greppleai/grip-ai": "^0.1.6",
-		"@greppleai/grip-tui": "^0.1.6",
+		"@greppleai/grip-agent-core": "^0.1.7",
+		"@greppleai/grip-ai": "^0.1.7",
+		"@greppleai/grip-tui": "^0.1.7",
 		"@silvia-odwyer/photon-node": "0.3.4",
 		"chalk": "6.0.1",
 		"cross-spawn": "7.0.6",