yai-dev · yai-dev · Apr 13, 2026 · Apr 13, 2026
diff --git a/.changeset/capabilities-v0.3.0.md b/.changeset/capabilities-v0.3.0.md
diff --git a/.changeset/permission-policy-followup.md b/.changeset/permission-policy-followup.md
diff --git a/.changeset/runtime-tracing-fields.md b/.changeset/runtime-tracing-fields.md
diff --git a/.changeset/tool-permission-policy.md b/.changeset/tool-permission-policy.md
diff --git a/packages/app/CHANGELOG.md b/packages/app/CHANGELOG.md
@@ -1,5 +1,69 @@
 # @agentrail/app
 
+## 0.6.0
+
+### Minor Changes
+
+- [#141](https://github.com/yai-dev/agentrail/pull/141) [`0075fc6`](https://github.com/yai-dev/agentrail/commit/0075fc6d98cb11ce8a91a818bc5bee931c7f1755) Thanks [@yai-dev](https://github.com/yai-dev)! - Fix and extend the tool permission policy system:
+  - Add `"strict"` `PermissionMode`: deny-by-default mode where only operations listed in `allow` are permitted. Use for minimal-privilege configurations.
+  - Add `contentMode: "path" | "command"` parameter to `matchPattern` and `evaluatePolicy`. Bash tools now pass `"command"` so that `*` wildcards match across `/` in command arguments (e.g. `git:add src/main.ts` matches `Bash(git:*)`).
+  - Fix missing `?` in regex escape list — a literal `?` in a pattern no longer acts as an optional quantifier.
+  - Fix cross-platform ancestor resolution in `path-safety.ts` using `path.dirname` loop instead of POSIX-specific `split`/`join`.
+  - Fix `normalizeBashCommand` to handle tab and other whitespace between verb and arguments.
+  - Export `ContentMatchMode` type from `@agentrail/capabilities`.
+  - `AgentrailPermissionsConfig.mode` and `agentrail.yaml` now accept `"strict"` as a valid permissions mode.
+
+- [#140](https://github.com/yai-dev/agentrail/pull/140) [`81f5cca`](https://github.com/yai-dev/agentrail/commit/81f5cca508d22c4a101c2989076ea7e228b4e8c8) Thanks [@yai-dev](https://github.com/yai-dev)! - Add `chainId`, `depth`, and `turnIndex` tracing fields to every `RuntimeEvent`.
+  - **`@agentrail/core`**: `RuntimeTracingFields` interface exported from the package root. Every `RuntimeEvent` variant is now intersected with `RuntimeTracingFields` (all three fields are required). `AgentRunOptions` gains optional `chainId` and `depth` fields that flow into the agent loop. `InternalContext` is extended with the same optional fields.
+  - **`@agentrail/capabilities`**: `CapabilityBuildContext` gains an optional `tracing` field `{ chainId: string; depth: number }`. `SpawnAgentInput` and `CreateManagedAgentInput` gain optional `chainId` and `depth` fields. The `spawn_agent` tool increments depth and propagates `chainId` to the child agent. `WorkerInitMessage` and `WorkerState` carry the same fields so the worker process can pass them to `agent.invoke`.
+  - **`@agentrail/app`**: `AgentrailProfileContext` gains an optional `chainId` field. The route-level `traceId` / `requestTraceId` is propagated as `chainId` into `AgentrailProfileContext`, `CapabilityBuildContext.tracing`, and `AgentRunOptions.chainId` so that `RuntimeEvent.chainId === telemetry traceId` for the full request chain.
+
+- [#141](https://github.com/yai-dev/agentrail/pull/141) [`405d8de`](https://github.com/yai-dev/agentrail/commit/405d8de29b0ac64f29e492f20f66a44b187c12bf) Thanks [@yai-dev](https://github.com/yai-dev)! - Add tool permission policy system
+
+  Introduces a structured, rule-based permission layer that sits between the LLM
+  and tool execution, enabling fine-grained control over which operations agents
+  are allowed to perform.
+
+  ### @agentrail/core
+  - New `PermissionDecision` type (`"allow" | "deny" | "ask"` or object form with optional `reason`).
+  - New optional `checkPermissions(params)` hook on `RuntimeTool` — called after
+    `onBeforeToolCall` interceptors but before `validate` and `execute`.
+  - New `permission_request` `RuntimeEvent` — emitted when `checkPermissions` returns `"ask"`.
+  - `ToolBuilder` gains a `.checkPermissions()` fluent method.
+  - `permission_request` is added to `TRACE_PERSISTED_EVENT_TYPES`.
+
+  ### @agentrail/capabilities
+  - New `packages/capabilities/src/permissions/` module:
+    - `ToolPermissionPolicy` / `PermissionRule` / `PermissionMode` types.
+    - `parseRule` / `parseRules` DSL parser (e.g. `"Bash(git:*)"`, `"Write(/workspace/**)"`)
+    - `evaluatePolicy` rule engine with priority order: deny → ask → allow → default.
+    - `isPathSafe` / `workspaceAnchor` path-safety utilities.
+    - `isDangerousCommand` / `isReadOnlyCommand` shell-safety utilities.
+  - `CapabilityBuildContext` gains optional `permissionPolicy?: ToolPermissionPolicy`.
+  - Non-sandboxed `bashTool`, `readTool`, `writeTool`, `editTool` are now created via
+    factory functions (`createBashTool`, `createReadTool`, `createWriteTool`, `createEditTool`)
+    that accept optional `rootDir` and `policy` options; the singleton exports are
+    kept for backward compatibility.
+  - Sandboxed `createSandboxedBash` accepts an optional `policy` parameter.
+  - All new symbols are exported from the package root.
+
+  ### @agentrail/app
+  - `AgentrailProfileContext` gains optional `permissionPolicy?: ToolPermissionPolicy`.
+  - `defineProfile` propagates `permissionPolicy` from profile context into
+    `CapabilityBuildContext`.
+  - `createAgentApp`, `createStreamRoute`, and `createChatRoute` all accept an
+    optional `permissionPolicy` option that is forwarded to every request.
+  - `AgentrailConfig` (YAML config) gains an optional `permissions` block with
+    `mode`, `allow`, `deny`, and `ask` keys.
+  - `DefaultCapabilityToolOptions` gains optional `permissionPolicy` forwarded to
+    sandboxed tools.
+
+### Patch Changes
+
+- Updated dependencies [[`8e9b041`](https://github.com/yai-dev/agentrail/commit/8e9b04141e809a3c782e1f09eae1237626c5709e), [`0075fc6`](https://github.com/yai-dev/agentrail/commit/0075fc6d98cb11ce8a91a818bc5bee931c7f1755), [`81f5cca`](https://github.com/yai-dev/agentrail/commit/81f5cca508d22c4a101c2989076ea7e228b4e8c8), [`405d8de`](https://github.com/yai-dev/agentrail/commit/405d8de29b0ac64f29e492f20f66a44b187c12bf)]:
+  - @agentrail/capabilities@0.3.0
+  - @agentrail/core@0.6.0
+
 ## 0.5.0
 
 ### Minor Changes

diff --git a/packages/app/package.json b/packages/app/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@agentrail/app",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "App-layer hosting, profiles, session management, and createAgentApp for Agentrail.",
   "type": "module",
   "files": [

diff --git a/packages/capabilities/CHANGELOG.md b/packages/capabilities/CHANGELOG.md
@@ -1,5 +1,72 @@
 # @agentrail/capabilities
 
+## 0.3.0
+
+### Minor Changes
+
+- [#138](https://github.com/yai-dev/agentrail/pull/138) [`8e9b041`](https://github.com/yai-dev/agentrail/commit/8e9b04141e809a3c782e1f09eae1237626c5709e) Thanks [@yai-dev](https://github.com/yai-dev)! - Add toolCalls field to sub-agent job results
+
+  ManagedAgentDeliveryResult and OrchestrationAgentJob now carry a toolCalls array with every tool call the sub-agent made during a job, including the tool name, input arguments, and the full output (content and structured details). The wait_agent tool result now includes the resolution object so the parent LLM can see outputText and toolCalls.
+
+- [#141](https://github.com/yai-dev/agentrail/pull/141) [`0075fc6`](https://github.com/yai-dev/agentrail/commit/0075fc6d98cb11ce8a91a818bc5bee931c7f1755) Thanks [@yai-dev](https://github.com/yai-dev)! - Fix and extend the tool permission policy system:
+  - Add `"strict"` `PermissionMode`: deny-by-default mode where only operations listed in `allow` are permitted. Use for minimal-privilege configurations.
+  - Add `contentMode: "path" | "command"` parameter to `matchPattern` and `evaluatePolicy`. Bash tools now pass `"command"` so that `*` wildcards match across `/` in command arguments (e.g. `git:add src/main.ts` matches `Bash(git:*)`).
+  - Fix missing `?` in regex escape list — a literal `?` in a pattern no longer acts as an optional quantifier.
+  - Fix cross-platform ancestor resolution in `path-safety.ts` using `path.dirname` loop instead of POSIX-specific `split`/`join`.
+  - Fix `normalizeBashCommand` to handle tab and other whitespace between verb and arguments.
+  - Export `ContentMatchMode` type from `@agentrail/capabilities`.
+  - `AgentrailPermissionsConfig.mode` and `agentrail.yaml` now accept `"strict"` as a valid permissions mode.
+
+- [#140](https://github.com/yai-dev/agentrail/pull/140) [`81f5cca`](https://github.com/yai-dev/agentrail/commit/81f5cca508d22c4a101c2989076ea7e228b4e8c8) Thanks [@yai-dev](https://github.com/yai-dev)! - Add `chainId`, `depth`, and `turnIndex` tracing fields to every `RuntimeEvent`.
+  - **`@agentrail/core`**: `RuntimeTracingFields` interface exported from the package root. Every `RuntimeEvent` variant is now intersected with `RuntimeTracingFields` (all three fields are required). `AgentRunOptions` gains optional `chainId` and `depth` fields that flow into the agent loop. `InternalContext` is extended with the same optional fields.
+  - **`@agentrail/capabilities`**: `CapabilityBuildContext` gains an optional `tracing` field `{ chainId: string; depth: number }`. `SpawnAgentInput` and `CreateManagedAgentInput` gain optional `chainId` and `depth` fields. The `spawn_agent` tool increments depth and propagates `chainId` to the child agent. `WorkerInitMessage` and `WorkerState` carry the same fields so the worker process can pass them to `agent.invoke`.
+  - **`@agentrail/app`**: `AgentrailProfileContext` gains an optional `chainId` field. The route-level `traceId` / `requestTraceId` is propagated as `chainId` into `AgentrailProfileContext`, `CapabilityBuildContext.tracing`, and `AgentRunOptions.chainId` so that `RuntimeEvent.chainId === telemetry traceId` for the full request chain.
+
+- [#141](https://github.com/yai-dev/agentrail/pull/141) [`405d8de`](https://github.com/yai-dev/agentrail/commit/405d8de29b0ac64f29e492f20f66a44b187c12bf) Thanks [@yai-dev](https://github.com/yai-dev)! - Add tool permission policy system
+
+  Introduces a structured, rule-based permission layer that sits between the LLM
+  and tool execution, enabling fine-grained control over which operations agents
+  are allowed to perform.
+
+  ### @agentrail/core
+  - New `PermissionDecision` type (`"allow" | "deny" | "ask"` or object form with optional `reason`).
+  - New optional `checkPermissions(params)` hook on `RuntimeTool` — called after
+    `onBeforeToolCall` interceptors but before `validate` and `execute`.
+  - New `permission_request` `RuntimeEvent` — emitted when `checkPermissions` returns `"ask"`.
+  - `ToolBuilder` gains a `.checkPermissions()` fluent method.
+  - `permission_request` is added to `TRACE_PERSISTED_EVENT_TYPES`.
+
+  ### @agentrail/capabilities
+  - New `packages/capabilities/src/permissions/` module:
+    - `ToolPermissionPolicy` / `PermissionRule` / `PermissionMode` types.
+    - `parseRule` / `parseRules` DSL parser (e.g. `"Bash(git:*)"`, `"Write(/workspace/**)"`)
+    - `evaluatePolicy` rule engine with priority order: deny → ask → allow → default.
+    - `isPathSafe` / `workspaceAnchor` path-safety utilities.
+    - `isDangerousCommand` / `isReadOnlyCommand` shell-safety utilities.
+  - `CapabilityBuildContext` gains optional `permissionPolicy?: ToolPermissionPolicy`.
+  - Non-sandboxed `bashTool`, `readTool`, `writeTool`, `editTool` are now created via
+    factory functions (`createBashTool`, `createReadTool`, `createWriteTool`, `createEditTool`)
+    that accept optional `rootDir` and `policy` options; the singleton exports are
+    kept for backward compatibility.
+  - Sandboxed `createSandboxedBash` accepts an optional `policy` parameter.
+  - All new symbols are exported from the package root.
+
+  ### @agentrail/app
+  - `AgentrailProfileContext` gains optional `permissionPolicy?: ToolPermissionPolicy`.
+  - `defineProfile` propagates `permissionPolicy` from profile context into
+    `CapabilityBuildContext`.
+  - `createAgentApp`, `createStreamRoute`, and `createChatRoute` all accept an
+    optional `permissionPolicy` option that is forwarded to every request.
+  - `AgentrailConfig` (YAML config) gains an optional `permissions` block with
+    `mode`, `allow`, `deny`, and `ask` keys.
+  - `DefaultCapabilityToolOptions` gains optional `permissionPolicy` forwarded to
+    sandboxed tools.
+
+### Patch Changes
+
+- Updated dependencies [[`81f5cca`](https://github.com/yai-dev/agentrail/commit/81f5cca508d22c4a101c2989076ea7e228b4e8c8), [`405d8de`](https://github.com/yai-dev/agentrail/commit/405d8de29b0ac64f29e492f20f66a44b187c12bf)]:
+  - @agentrail/core@0.6.0
+
 ## 0.2.1
 
 ### Patch Changes

diff --git a/packages/capabilities/package.json b/packages/capabilities/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@agentrail/capabilities",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "App-layer capability descriptors: filesystem, browser, knowledge, skills, orchestration, and memory for Agentrail.",
   "type": "module",
   "files": [

diff --git a/packages/cli/CHANGELOG.md b/packages/cli/CHANGELOG.md
@@ -1,5 +1,12 @@
 # @agentrail/cli
 
+## 0.2.5
+
+### Patch Changes
+
+- Updated dependencies [[`0075fc6`](https://github.com/yai-dev/agentrail/commit/0075fc6d98cb11ce8a91a818bc5bee931c7f1755), [`81f5cca`](https://github.com/yai-dev/agentrail/commit/81f5cca508d22c4a101c2989076ea7e228b4e8c8), [`405d8de`](https://github.com/yai-dev/agentrail/commit/405d8de29b0ac64f29e492f20f66a44b187c12bf)]:
+  - @agentrail/app@0.6.0
+
 ## 0.2.4
 
 ### Patch Changes

diff --git a/packages/cli/package.json b/packages/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@agentrail/cli",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Official CLI for Agentrail — scaffold, diagnose, and validate your agent applications",
   "type": "module",
   "main": "./dist/index.js",