@arnilo/prism 0.0.2 → 0.0.3

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.3] - 2026-07-08
+
+### Added
+
+- New first-party workspace package `@arnilo/prism-coding-agent` providing optional host coding tools (`shell`, `read`, `write`, `edit`) as Prism `ToolDefinition` objects. The package is opt-in and is **not** included in `@arnilo/prism-all` because the tools perform host shell/filesystem operations.
+- `createCodingTools`, `createReadOnlyTools`, and `createAllTools` aggregator factories for importing/registering coding tools.
+- Documentation: `docs/coding-agent-tools.md`, updated `docs/index.md` and `docs/tools.md`, and expanded `packages/coding-agent/README.md`.
+
+### Changed
+
+- Bumped all package versions from `0.0.2` to `0.0.3` (core, first-party workspace packages, and umbrella packages).
+- Updated `@arnilo/prism` peer dependency range in every first-party workspace package to `0.0.3`.
+- Updated umbrella package dependency pins to `0.0.3`.
+- `docs/release-and-install.md` now documents nine first-party workspace packages, thirteen total manifests, and the explicit install command for `@arnilo/prism-coding-agent`.
+
 ## [0.0.2] - 2026-07-05
 
 ### Added

package/dist/index.d.ts

@@ -53,5 +53,5 @@ export type { DispatchToolCallOptions, ToolFilter, ToolFilterInput, ToolRegistry
 export type { DuplicateRegistrationOptions, DuplicateRegistrationPolicy } from "./registry-options.js";
 export { generateValidateReviseLoop, isAgentLoopOptions, resolveLoop, singleShotLoop } from "./agent-loops.js";
 export declare const name = "prism";
-export declare const version = "0.0.2";
+export declare const version = "0.0.3";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -29,6 +29,6 @@ export { resolveInstructionInjectors, runInstructionInjectors } from "./instruct
 export { createToolRegistry, dispatchToolCall, filterTools } from "./tools.js";
 export { generateValidateReviseLoop, isAgentLoopOptions, resolveLoop, singleShotLoop } from "./agent-loops.js";
 export const name = "prism";
-export const version = "0.0.2";
+export const version = "0.0.3";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/docs/coding-agent-tools.md

@@ -0,0 +1,208 @@
+# Coding agent tools (first-party package)
+
+## What it does
+
+`@arnilo/prism-coding-agent` is an optional first-party package that provides host shell/filesystem tools as Prism `ToolDefinition` objects. It ships four tools — `shell`, `read`, `write`, `edit` — plus aggregator factories. The tools are **inert** until a host imports them and registers them into a `ToolRegistry`. Behavior is a behavioral port of the pi coding agent's `bash`/`read`/`write`/`edit` tools, adapted to Prism's `ToolDefinition` / `ToolResult` contracts (no `@earendil-works/*` or `typebox` dependencies; only `diff` plus the Node standard library).
+
+| Export | Purpose |
+| --- | --- |
+| `createShellTool(cwd, options?)` | `shell` tool: run a shell command and return combined output + exit code. |
+| `createReadTool(cwd, options?)` | `read` tool: read a text or image file into `TextContent` / `ImageContent`. |
+| `createWriteTool(cwd, options?)` | `write` tool: create or overwrite a file, creating parent directories. |
+| `createEditTool(cwd, options?)` | `edit` tool: precise exact-then-fuzzy text replacement in an existing file. |
+| `createCodingTools(cwd, options?)` | All four tools (`shell`, `read`, `write`, `edit`). |
+| `createReadOnlyTools(cwd, options?)` | Read-only subset: `read` only. |
+| `createAllTools(cwd, options?)` | Every tool the package provides (currently identical to `createCodingTools`). |
+| `detectSupportedImageMimeType(buf)` / `detectSupportedImageMimeTypeFromFile(path)` | Magic-byte image MIME detection (PNG/JPEG/GIF/WebP/BMP) used by `read`. |
+| `withFileMutationQueue(path, fn)` | Per-path serialization primitive re-exported for hosts. |
+
+Each factory returns a plain `ToolDefinition` (no auto-registration). Register what you need:
+
+```ts
+import { createToolRegistry } from "@arnilo/prism";
+import { createCodingTools } from "@arnilo/prism-coding-agent";
+
+const tools = createToolRegistry(createCodingTools(process.cwd()));
+```
+
+## When to use it
+
+Use this package when a host wants ready-made coding tools for an agent, session, or run, registered explicitly into a `ToolRegistry` and dispatched through the normal Prism tool harness. The tools perform **real** shell and filesystem operations on the host — they are not mocked or sandboxed. Use the individual factories when you need per-tool options or custom operation backends; use the aggregators when you want the default set.
+
+Do not use this package as a sandbox, permission policy, secret store, or provider loop. Prism gates tool dispatch with `PermissionPolicy` / `ToolValidator` / trust policies; the package performs no gating of its own. Do not register these tools for an untrusted provider.
+
+### pi name mapping
+
+| Prism (`@arnilo/prism-coding-agent`) | pi coding agent |
+| --- | --- |
+| `shell` | `bash` |
+| `read` | `read` |
+| `write` | `write` |
+| `edit` | `edit` |
+
+## Tools
+
+### `shell`
+
+Run a shell command and return combined stdout+stderr.
+
+**Inputs:**
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `command` | `string` | Shell command to execute (required). |
+| `timeout` | `number` | Timeout in **seconds** (optional; no default). |
+
+**Outputs:** a `ToolResult` whose `content[0]` is a `TextContent` with the combined output. Non-zero exit is **not** a tool error: it is returned as a normal result with `[Command exited with code N]` appended to the content and `exitCode` in metadata. Timeout and abort are error results that still carry the partial output captured so far.
+
+`shell` result `metadata`:
+
+| Field | Present when | Purpose |
+| --- | --- | --- |
+| `exitCode` | always | Process exit code, or `null` when the process was killed by timeout/abort. |
+| `truncation` | always | `TruncationResult` from the bounded output accumulator. |
+| `fullOutputPath?` | truncated only | Path to the spilled temp file holding the full output. |
+
+Shell resolution honors `options.shellPath` → `SHELL` env → `/bin/bash` → `sh`, and the process group is killed on timeout/abort (`process.kill(-pid)` on Unix, `taskkill /F /T` on Windows).
+
+### `read`
+
+Read a text or image file.
+
+**Inputs:**
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `path` | `string` | Path to the file (relative or absolute; `~` and `file://` expanded). Required. |
+| `offset` | `number` | Line to start reading from (1-indexed). |
+| `limit` | `number` | Maximum number of lines to read. |
+
+**Outputs:** text files become a single `TextContent`, truncated to `maxLines`/`maxBytes` (defaults 2000 lines / 50 KB) with a `Use offset=N to continue` footer when more remains. Image files (PNG/JPEG/GIF/WebP/BMP by magic bytes) become `[TextContent note, ImageContent]` with base64 `data` and `mimeType`. Read failures (missing file, offset beyond end, abort) are error results.
+
+`read` result `metadata`:
+
+| Field | Present when | Purpose |
+| --- | --- | --- |
+| `truncation` | text reads | `TruncationResult`. |
+| `image` | image reads | `{ mimeType, resized: false }`. |
+
+> `autoResizeImages` is accepted but is currently a documented no-op (deferred); images are returned at their original size with `image.resized = false`.
+
+### `write`
+
+Create or overwrite a file, creating parent directories as needed.
+
+**Inputs:**
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `path` | `string` | Path to the file to write (relative or absolute). Required. |
+| `content` | `string` | Content to write (empty string creates an empty file). Required. |
+
+**Outputs:** a `TextContent` confirmation naming the **absolute path** with UTF-8 byte and line counts (e.g. `Successfully wrote 42 bytes (3 lines) to /abs/path.txt`). Write failures and abort are error results. Empty `content` is valid.
+
+`write` result `metadata`: `{ bytes, lines, path }` (absolute path). Concurrent writes to the same path serialize through `withFileMutationQueue`; writes to different paths run in parallel.
+
+### `edit`
+
+Precise text replacement in an existing file via exact-then-fuzzy matching.
+
+**Inputs:**
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `path` | `string` | Path to the file to edit. Required. |
+| `edits` | `Array<{ oldText: string, newText: string }>` | Targeted replacements, each matched against the **original** file (not incrementally). No overlapping/nested edits. Required, non-empty. |
+
+Each `edits[].oldText` must match a unique, non-overlapping region of the original file. Matching is exact first, then fuzzy (unicode normalization / whitespace collapse). A BOM is stripped before matching and re-prepended on write; original line endings are restored.
+
+**Outputs:** a `TextContent` confirmation (`Successfully replaced N block(s) in {path}.`) plus `metadata`. Any failure — missing/unreadable file, no match, duplicate (non-unique) match, overlap, empty `oldText`, no-op edit, or abort — is an error result, and the file is left **unchanged** (the match runs before the write).
+
+`edit` result `metadata`: `{ diff, patch, firstChangedLine }` — a display-oriented diff, a standard unified patch, and the first changed line in the new file. These are host-readable; the model only sees the short confirmation (keeps model context small).
+
+## Outputs / response / events
+
+Every tool returns a `ToolResult` with `toolCallId`, `name`, `content` (`readonly ContentBlock[]`), optional `error`, and optional `metadata`. Mutating tools (`shell` with same cwd, `write`, `edit`) serialize per realpath through `withFileMutationQueue` so concurrent calls targeting one file do not interleave. The package emits no events of its own; hosts observe tool execution through the normal Prism `AgentEvent` stream via `dispatchToolCall`.
+
+## Request/response example
+
+```json
+// edit request
+{ "path": "src/app.ts", "edits": [{ "oldText": "const x = 1;", "newText": "const x = 2;" }] }
+```
+
+```json
+// edit success result
+{
+  "toolCallId": "call_1",
+  "name": "edit",
+  "content": [{ "type": "text", "text": "Successfully replaced 1 block(s) in src/app.ts." }],
+  "metadata": { "diff": "...", "patch": "--- src/app.ts\n+++ src/app.ts\n...", "firstChangedLine": 3 }
+}
+```
+
+```json
+// edit no-match result (file unchanged)
+{
+  "toolCallId": "call_2",
+  "name": "edit",
+  "error": { "message": "Could not find edits[0] in src/app.ts. The oldText must match exactly including all whitespace and newlines." }
+}
+```
+
+## Implementation example
+
+Minimal drop-in for any Prism app:
+
+```ts
+import { createToolRegistry } from "@arnilo/prism";
+import { createCodingTools, createReadOnlyTools } from "@arnilo/prism-coding-agent";
+
+// Full coding set (shell + read + write + edit) against the project root:
+const tools = createToolRegistry(createCodingTools(process.cwd()));
+
+// Or a read-only set for inspection-only agents:
+const ro = createToolRegistry(createReadOnlyTools(process.cwd()));
+```
+
+Customizing a single tool (force bash, cap output, delegate writes to a remote backend):
+
+```ts
+import { createShellTool, createWriteTool } from "@arnilo/prism-coding-agent";
+
+const shell = createShellTool("/repo", {
+  shellPath: "/bin/bash",
+  commandPrefix: "set -euo pipefail",
+  maxLines: 500,
+});
+
+const remoteWrite = createWriteTool("/repo", {
+  operations: {
+    writeFile: async (abs, content) => { /* ship to remote */ },
+    mkdir: async (dir) => { /* mkdir -p remotely */ },
+  },
+});
+```
+
+## Extension and configuration notes
+
+- **Pluggable operation backends.** Every tool accepts an `operations` seam so a host can delegate to a remote system (e.g. SSH) while keeping the tool's matching/serialization behavior: `BashOperations` (`shell`), `ReadOperations` (`read`), `WriteOperations` (`write`), `EditOperations` (`edit`).
+- **Per-tool options.** `ShellToolOptions` (`shellPath`, `commandPrefix`, `maxLines`, `maxBytes`, `tempFilePrefix`, `operations`, `spawnHook`); `ReadToolOptions` (`operations`, `autoResizeImages`, `maxLines`, `maxBytes`); `WriteToolOptions` (`operations`); `EditToolOptions` (`operations`).
+- **Aggregator options.** `ToolsOptions` (`{ shell?, read?, write?, edit? }`) threads each sub-object to the matching tool.
+- **`ToolsOptions`** and the per-tool option types are exported from the package barrel for host configuration.
+- No auto-discovery or manifest registration: import and register explicitly. This package registers no extensions and owns no globals (the mutation queue is a process-wide per-path map — see `ponytail:` note in the source).
+
+## Security and performance notes
+
+- **Host shell/filesystem access.** These tools run real commands and read/write real files. They provide **no sandbox**. Gate them with Prism `PermissionPolicy` / `ToolValidator` / trust policies before registering them for any provider turn. See [Host security guide](host-security.md) and [Security/auth/trust](settings-auth-trust-security.md).
+- **Non-zero exit is not an error.** A failing command is a normal `shell` result (exit code in metadata); only timeout/abort/spawn failures are error results. Do not assume `error == undefined` means the command succeeded.
+- **Bounded output.** `shell`/`read` accumulate output into a rolling tail bounded by `maxLines`/`maxBytes`; oversized output spills to a temp file (`fullOutputPath`), so memory use is bounded regardless of command output size.
+- **Per-path serialization.** Concurrent mutations to the same file serialize; concurrent mutations to different files do not block each other. The queue is a process-wide map — across sessions in one process, same-path writes still serialize (upgrade path: scope per registry if throughput matters).
+- **Single runtime dependency.** `diff` (for `edit` unified patch/diff generation) plus the Node standard library. No native modules; no image-processing native dependency (image auto-resize is deferred, so no `sharp`/WASM dependency).
+
+## Related APIs
+
+- [Tools](tools.md): the host-owned tool harness — `createToolRegistry`, `dispatchToolCall`, filtering, and the `ToolDefinition` contract these factories satisfy.
+- [Public contracts](public-contracts.md): `ToolDefinition`, `ToolResult`, `ToolExecutionContext`, `ContentBlock`, and `JsonObject` shapes.
+- [Host security guide](host-security.md): fail-closed checklist for permission policies, tool validation, and trust boundaries that must gate these tools.
+- [Tool conformance](tool-conformance.md): assertions for the tool-dispatch blocked-reason matrix these tools participate in.

package/docs/index.md

@@ -42,6 +42,7 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 
 ## Tools
 - [Tools](tools.md): register host-owned active tools with replace-or-error duplicate policy, apply exact allow/deny filtering, and dispatch tool calls.
+- [Coding agent tools](coding-agent-tools.md): optional first-party package `@arnilo/prism-coding-agent` providing `shell`, `read`, `write`, and `edit` tools (ported from pi) as `ToolDefinition`s a host registers; pluggable operation backends, per-path mutation serialization, and read-only/coding aggregators. Host shell/filesystem access — gate with permission/trust policies.
 
 ## Extensions/plugins
 - [Contribution discovery (workspace)](contribution-discovery.md): opt-in, realpath-contained directory scanner turning `SKILL.md`/`manifest.json` into inert `DiscoveredContribution` envelopes the host registers — no `import()`, no auto-activate, no provider scanning. (Per-agent `AGENT.md` bundles live under an app-controlled `configRoot`; see [Agent definitions](agent-definitions.md).)

package/docs/release-and-install.md

@@ -2,23 +2,24 @@
 
 ## What it does
 
-Prism is published as one core package plus eight first-party workspace packages and three umbrella convenience packages. This page describes how they are packed, what each tarball contains, how to install them, the required `@arnilo/prism` peer dependency, the release workflow, and the offline test budget.
+Prism is published as one core package plus nine first-party workspace packages and three umbrella convenience packages. This page describes how they are packed, what each tarball contains, how to install them, the required `@arnilo/prism` peer dependency, the release workflow, and the offline test budget.
 
 Core package:
 
 - `@arnilo/prism` — the runtime, contracts, registries, streaming events, CLI, and the `/docs` hub. `files`: `dist` (with `!dist/__tests__` and `!dist/**/*.map` negations), `docs`, `CHANGELOG.md`. `bin`: `prism` -> `./dist/cli.js`. `sideEffects`: `["dist/cli.js"]`.
 
-First-party workspace packages (each `peerDependencies: { "@arnilo/prism": "0.0.2" }`, non-optional; `sideEffects: false`):
+First-party workspace packages (each `peerDependencies: { "@arnilo/prism": "0.0.3" }`, non-optional; `sideEffects: false`):
 
 - `@arnilo/prism-provider-openai`, `@arnilo/prism-provider-openrouter`, `@arnilo/prism-provider-kimi`, `@arnilo/prism-provider-zai`, `@arnilo/prism-provider-opencode-go`, `@arnilo/prism-provider-neuralwatt` — provider adapters.
 - `@arnilo/prism-compaction-llm` — optional LLM-backed compaction strategy.
 - `@arnilo/prism-compaction-observational-memory` — optional source-backed observational memory.
+- `@arnilo/prism-coding-agent` — optional host shell/filesystem coding tools (`shell`, `read`, `write`, `edit`). **Not included in `@arnilo/prism-all`** because these tools perform real host operations and must be opted into explicitly.
 
 Umbrella packages (pure manifests, no code, no `dist`; ship only `README.md`; use hard `dependencies` to transitively install their family):
 
 - `@arnilo/prism-providers` — depends on all 6 `@arnilo/prism-provider-*` packages.
 - `@arnilo/prism-compaction` — depends on both `@arnilo/prism-compaction-*` packages.
-- `@arnilo/prism-all` — depends on `@arnilo/prism` + `@arnilo/prism-providers` + `@arnilo/prism-compaction` (the full kit in one install).
+- `@arnilo/prism-all` — depends on `@arnilo/prism` + `@arnilo/prism-providers` + `@arnilo/prism-compaction` (the full runtime/provider/compaction kit in one install). Does **not** include `@arnilo/prism-coding-agent`; install that separately.
 
 Each code package's `files` array is `["dist", "!dist/__tests__", "!dist/**/*.map", "README.md", "CHANGELOG.md"]`; `README.md`, `LICENSE`, and `CHANGELOG.md` ship in every code-package tarball, the core tarball also ships the `docs/` directory, and umbrella tarballs ship only `README.md` + `package.json`.
 
@@ -35,6 +36,7 @@ Consumers install the core package for the runtime and add first-party packages
 | Install core only | `npm install @arnilo/prism` |
 | Install core + all providers | `npm install @arnilo/prism @arnilo/prism-providers` |
 | Install core + compaction | `npm install @arnilo/prism @arnilo/prism-compaction` |
+| Install core + coding tools (opt-in) | `npm install @arnilo/prism @arnilo/prism-coding-agent` |
 | Install everything (core + providers + compaction) | `npm install @arnilo/prism-all` |
 | Install core + a single provider | `npm install @arnilo/prism @arnilo/prism-provider-openai` |
 | Build everything (core + workspaces) | `npm run build` |
@@ -71,7 +73,7 @@ A packed tarball contains only public compiled output and release files:
 - `README.md`, `LICENSE`, `CHANGELOG.md` in every package.
 - The core tarball additionally ships the full `docs/` directory (the docs hub).
 - `dist/cli.js` and the `bin` link in core.
-- **Tarball filenames.** npm strips the `@scope/` prefix, so the core package `@arnilo/prism` produces a tarball named `arnilo-prism-0.0.2.tgz`; first-party packages produce `arnilo-prism-provider-<name>-0.0.2.tgz` / `arnilo-prism-compaction-<name>-0.0.2.tgz`; umbrella packages produce `arnilo-prism-providers-0.0.2.tgz` / `arnilo-prism-compaction-0.0.2.tgz` / `arnilo-prism-all-0.0.2.tgz`. The CLI bin name `prism` is unaffected by the package name (`npx prism` still works; npm allows the bin field to differ from the package name).
+- **Tarball filenames.** npm strips the `@scope/` prefix, so the core package `@arnilo/prism` produces a tarball named `arnilo-prism-0.0.3.tgz`; first-party packages produce `arnilo-prism-provider-<name>-0.0.3.tgz` / `arnilo-prism-compaction-<name>-0.0.3.tgz` / `arnilo-prism-coding-agent-0.0.3.tgz`; umbrella packages produce `arnilo-prism-providers-0.0.3.tgz` / `arnilo-prism-compaction-0.0.3.tgz` / `arnilo-prism-all-0.0.3.tgz`. The CLI bin name `prism` is unaffected by the package name (`npx prism` still works; npm allows the bin field to differ from the package name).
 
 Excluded from every tarball by `files` negation:
 
@@ -88,9 +90,9 @@ Excluded from every tarball by `files` negation:
   "name": "host-app",
   "type": "module",
   "dependencies": {
-    "@arnilo/prism": "0.0.2",
-    "@arnilo/prism-provider-openai": "0.0.2",
-    "@arnilo/prism-compaction-observational-memory": "0.0.2"
+    "@arnilo/prism": "0.0.3",
+    "@arnilo/prism-provider-openai": "0.0.3",
+    "@arnilo/prism-compaction-observational-memory": "0.0.3"
   }
 }
 ```
@@ -100,7 +102,7 @@ Installing the provider/compaction packages without `@arnilo/prism` present prod
 ```text
 npm error code ERESOLVE
 npm error Could not resolve dependency:
-npm error peer @arnilo/prism@"0.0.2" from @arnilo/prism-provider-openai@0.0.2
+npm error peer @arnilo/prism@"0.0.3" from @arnilo/prism-provider-openai@0.0.3
 ```
 
 ## Implementation example
@@ -141,8 +143,8 @@ PRISM_LIVE_PROVIDER_TESTS=1 npm run test --workspaces --if-present
 
 ## Extension and configuration notes
 
-- **Required `@arnilo/prism` peer.** Every first-party package declares `peerDependencies: { "@arnilo/prism": "0.0.2" }` with no `peerDependenciesMeta` (non-optional). The range stays pinned to `0.0.2` for the 0.x series and will widen to `^1.0.0` at the 1.x stable release. Inside the workspace each package also declares `"@arnilo/prism": "file:../.."` in `devDependencies` so `npm install` resolves the peer locally; that devDependency is stripped from consumer installs and is not a runtime dependency.
-- **Public access.** All 12 manifests (9 code packages + 3 umbrellas) declare `"publishConfig": { "access": "public" }` so a manual `npm publish` of a scoped `@arnilo/prism-*` package defaults to public rather than `restricted` (paid). The `release.yml` flags (`npm publish --access public` + `npm publish --workspaces --access public`) are belt-and-suspenders backups.
+- **Required `@arnilo/prism` peer.** Every first-party package declares `peerDependencies: { "@arnilo/prism": "0.0.3" }` with no `peerDependenciesMeta` (non-optional). The range stays pinned to `0.0.3` for the 0.x series and will widen to `^1.0.0` at the 1.x stable release. Inside the workspace each package also declares `"@arnilo/prism": "file:../.."` in `devDependencies` so `npm install` resolves the peer locally; that devDependency is stripped from consumer installs and is not a runtime dependency.
+- **Public access.** All 13 manifests (10 code packages + 3 umbrellas) declare `"publishConfig": { "access": "public" }` so a manual `npm publish` of a scoped `@arnilo/prism-*` package defaults to public rather than `restricted` (paid). The `release.yml` flags (`npm publish --access public` + `npm publish --workspaces --access public`) are belt-and-suspenders backups.
 - **Map retention knob.** Source maps are emitted locally but stripped from tarballs by `!dist/**/*.map`. Removing that `files` negation ships maps in releases (larger tarballs, better consumer stack traces).
 - **Release workflow.** `.github/workflows/release.yml` has three jobs. `verify` runs the full SDK readiness gate on Node 24: `npm ci`, then `npm run sdk:ready` (`npm run typecheck`, network-free `npm test`, and `npm run pack:dry-run`). `node20-compat` runs on Node 20: `npm ci`, `npm run build`, then imports every public root `exports` default target from `dist/`. This proves the published package basics under the declared `engines.node >=20` without running docs examples, which require Node >=22.6 native TypeScript stripping. `publish` runs only on `refs/tags/v*` after both `verify` and `node20-compat` succeed: `npm run build`, then `npm publish --access public` for core (first, because packages require the `@arnilo/prism` peer on the registry) and `npm publish --workspaces --access public`. With no `NPM_TOKEN` secret it runs `--dry-run` instead of a real publish. `permissions.id-token: write` is set so `--provenance` can be added later without re-architecting permissions. Local `npm run release:dry-run` delegates to the same `npm run sdk:ready` gate.
 - **Adding a package.** New workspace packages are picked up automatically by `npm run build --workspaces`, `npm test --workspaces`, `npm run pack:dry-run`, the packaging guard (`src/__tests__/packaging.test.ts`), and the install-smoke test (`src/__tests__/install-smoke.test.ts`) via the workspace glob; add the package to both tests' config arrays for explicit per-package assertions.

package/docs/tools.md

@@ -203,5 +203,6 @@ await session.run(input, { validate: (_t, args) => args.dry ? "dry-run blocked"
 - [Middleware hooks](middleware-hooks.md): `tool_call` and `tool_result` middleware used during dispatch.
 - [Credentials and redaction](credentials-and-redaction.md): redaction helpers used for tool execution errors.
 - [Observational memory compaction package](compaction-observational-memory.md): optional exact-id recall tool factory.
+- [Coding agent tools](coding-agent-tools.md): optional first-party `@arnilo/prism-coding-agent` `shell`/`read`/`write`/`edit` tools a host registers into this harness.
 
 `DispatchToolCallOptions.permission` can provide a `PermissionPolicy`; denial emits `tool_execution_blocked` before validation or `execute()`. Middleware cannot bypass this guard. `AgentConfig.validator`/`RunOptions.validate` run after this guard; their output is redacted through the active `SecretRedactor`. Prism does not sandbox tools. See [Security/auth/trust](settings-auth-trust-security.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Agent harness for AI providers, agents, sessions, and tools.",
   "type": "module",
   "main": "./dist/index.js",
@@ -80,6 +80,7 @@
   "workspaces": [
     "packages/provider-*",
     "packages/compaction-*",
+    "packages/coding-agent",
     "packages/prism-providers",
     "packages/prism-compaction",
     "packages/prism-all"