pi-sage 0.2.0

package/README.md

@@ -0,0 +1,93 @@
+# pi-sage
+
+Interactive-only advisory Sage extension for Pi.
+
+## Runtime requirements (for users)
+
+- **Pi CLI** installed (`pi`) and available on PATH
+- **Pi version**: `0.64.0+` recommended
+- **Model access** configured in Pi (API keys / provider auth)
+- **OS**: Linux/macOS/Windows supported
+- **Optional**: `git` CLI for `git-review-readonly` profile
+
+> Important: Sage spawns a nested `pi` subprocess for consultations, so `pi` must be invokable from the environment where Pi itself is running.
+
+## Install
+
+### Global install (all projects)
+
+```bash
+pi install pi-sage
+```
+
+### Project-local install (current project only)
+
+```bash
+pi install -l pi-sage
+```
+
+Then in Pi run:
+
+```text
+/reload
+```
+
+## Usage
+
+- Ask naturally: “use Sage”, “get a second opinion”, etc.
+- Or the model may invoke Sage autonomously when appropriate.
+- Configure via:
+
+```text
+/sage-settings
+```
+
+## Tool profiles
+
+- `read-only-lite` (default): `ls, glob, grep, read`
+- `git-review-readonly`: adds restricted `bash` for allowlisted **read-only git** commands
+- `none`
+- `custom-read-only`
+
+## Settings files (global + project override)
+
+Sage settings are resolved in this order:
+
+1. `.pi/sage-settings.json` (project override)
+2. `~/.pi/agent/sage-settings.json` (global fallback)
+3. built-in defaults
+
+So yes: a global install can use global settings, and any project can override with its own `.pi/sage-settings.json`.
+
+## Install scope and file layout
+
+### Global install (`pi install npm:pi-sage`)
+
+Pi writes package source to:
+- `~/.pi/agent/settings.json`
+
+Package files are installed globally by npm (`npm install -g`), typically under npm's global prefix, e.g.:
+- Windows (typical): `%APPDATA%/npm/node_modules/pi-sage/`
+- macOS/Linux (typical): `<npm-global-prefix>/lib/node_modules/pi-sage/`
+
+Use `npm root -g` to see your exact global node_modules path.
+
+### Project-local install (`pi install -l npm:pi-sage`)
+
+Pi writes package source to:
+- `.pi/settings.json`
+
+Package files are installed under project-local Pi package storage:
+- `.pi/npm/` (project-local package cache/install root)
+
+### Settings files (independent of install scope)
+
+- Global Sage settings: `~/.pi/agent/sage-settings.json`
+- Project Sage settings: `.pi/sage-settings.json`
+
+Project settings always override global settings for that project.
+
+## Publishing note
+
+Package name `sage` is already taken on npm.
+`pi-sage` is currently available and is the intended publish name.

package/docs/SAGE_SPEC.md

@@ -0,0 +1,490 @@
+# Sage Specification (v0.1 Implementation Baseline)
+
+> Status: **Locked baseline for implementation**. Behavioral changes require updates to this spec, tests, and standards docs in the same change set.
+
+## 1) Summary
+
+**Sage** is a built-in-style extension capability for Pi that gives the primary agent access to a high-reasoning, isolated subagent for second opinions on complex tasks.
+
+Sage’s role is advisory: it provides analysis, feedback, and recommendations to the calling agent. Sage does **not** execute implementation work.
+
+This spec targets a **final architecture** (not MVP): Sage is implemented as a **subagent process** (separate `pi` invocation), not as an inline single `complete(...)` call.
+
+---
+
+## 2) Goals
+
+1. Let the primary agent consult Sage **autonomously** when useful.
+2. Let the operator request Sage via **natural language** (no `/sage` command).
+3. Provide `/sage-settings` for interactive configuration (model picker, budgets, limits, etc.).
+4. Keep Sage expensive/slower by design, with explicit guardrails.
+5. Preserve clear observability (what was asked, what Sage returned, cost/time/model used).
+6. Keep Sage in an advisory lane (reasoning/recommendations), not a code-execution lane.
+
+---
+
+## 3) Non-Goals (for v0.1)
+
+1. Multi-Sage swarms or planner/reviewer pipelines.
+2. Full UI dashboard beyond command-based configuration and standard tool rendering.
+3. Automatic persistent learning from previous Sage calls.
+4. Having Sage directly modify files, run shell commands, or perform orchestration actions.
+
+---
+
+## 4) Core UX Requirements
+
+### 4.1 Autonomous invocation (agentic behavior)
+- The primary agent can call Sage **without operator explicitly asking**.
+- Invocation is policy-gated (see Section 8).
+- Typical autonomous trigger cases:
+  - ambiguous root-cause debugging,
+  - risky architectural trade-offs,
+  - conflicting evidence,
+  - high-impact refactors.
+
+### 4.2 Operator invocation via natural language only
+- Operator can request Sage by saying things like:
+  - “Use Sage”
+  - “Get a second opinion”
+  - “Consult a stronger reasoning model”
+- There is **no `/sage` command**.
+- The main agent satisfies such requests by deciding to call the Sage tool.
+
+### 4.3 Settings command
+- Provide `/sage-settings` command only.
+- `/sage-settings` must include an interactive model selector sourced from Pi’s model registry (avoid manual exact-id typing).
+
+---
+
+## 5) Architecture
+
+## 5.1 Components
+
+1. **Sage Extension** (`.pi/extensions/sage/index.ts`)
+   - Registers tool: `sage_consult`
+   - Registers command: `/sage-settings`
+   - Injects system-prompt guidance (autonomous use criteria)
+   - Enforces budgets/limits/policy
+
+2. **Sage Runner** (subagent backend)
+   - Spawns isolated process:
+     - `pi --mode json -p --no-session --model <configured-model> ...`
+   - Provides dedicated Sage system prompt.
+   - Enforces **single-shot execution** per call (one request → one response).
+   - Enforces advisory tool policy (default `read-only-lite`: `ls,glob,grep,read`).
+   - Supports stricter `none` mode, optional `git-review-readonly` mode, and constrained custom read-only lists.
+   - Explicitly disables `sage_consult` inside Sage subprocess context to prevent subagent recursion.
+
+3. **Sage Settings Store**
+   - Project: `.pi/sage-settings.json`
+   - Global fallback: `~/.pi/agent/sage-settings.json`
+   - Precedence: project > global > defaults
+
+4. **Sage Prompt Policy Layer**
+   - Appends guidance to primary agent system prompt via `before_agent_start`.
+   - Adds tool `promptGuidelines` describing when to use Sage.
+
+---
+
+## 5.2 Why subagent process (final approach)
+
+- Hard context isolation.
+- Independent model/thinking/tool profile.
+- Better cancellation/error containment.
+- Better extensibility (future chain/parallel Sage patterns).
+- Stronger parity with Amp Oracle behavior.
+
+---
+
+## 6) Tool Contract: `sage_consult`
+
+## 6.1 Parameters
+
+```ts
+{
+  question: string;                 // Required: focused question to Sage
+  context?: string;                 // Optional: compressed relevant context
+  files?: string[];                 // Optional: relevant file paths
+  evidence?: string[];              // Optional: logs/errors/observations
+  objective?: "debug" | "design" | "review" | "refactor" | "general";
+  urgency?: "low" | "medium" | "high";
+  force?: boolean;                  // If true, bypass autonomous budget gates (used for explicit user request)
+}
+```
+
+## 6.2 Result shape
+
+Tool `content` returns human-readable markdown with analysis/recommendations for the primary agent.
+Tool `details` returns structured metadata:
+
+```ts
+{
+  model: string;
+  reasoningLevel: "minimal"|"low"|"medium"|"high"|"xhigh";
+  latencyMs: number;
+  stopReason: string;
+  usage?: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    totalTokens: number;
+    costTotal?: number;
+  };
+  toolUsage?: {
+    profile: "none"|"read-only-lite"|"git-review-readonly"|"custom-read-only";
+    callsUsed: number;
+    filesRead: number;
+    bytesRead: number;
+  };
+  policy: {
+    mode: "autonomous" | "user-requested";
+    allowedByContext: boolean;
+    contextReason?: string;
+    blockCode?: "ineligible-caller"|"non-interactive"|"ci-mode"|"rpc-role"|"subagent"|"unknown-context"|"tool-disallowed"|"path-denied"|"volume-cap";
+    allowedByBudget: boolean;
+    budgetReason?: string;
+  };
+}
+```
+
+---
+
+## 7) Prompt / Behavior Design
+
+## 7.1 Do we need system prompt patching?
+
+**Yes.** For reliable autonomous behavior, the primary agent needs explicit instruction in its system prompt for:
+- when to call Sage,
+- when not to call Sage,
+- how to summarize the consultation result,
+- cost/speed awareness.
+
+Without this, behavior is inconsistent and model-dependent.
+
+## 7.2 Injected guidance (conceptual)
+
+Primary agent guidance to append:
+
+- You may call `sage_consult` for complex reasoning, debugging ambiguity, high-risk changes, or when user asks for second opinion.
+- Do not overuse Sage for routine edits.
+- Sage is an advisor, not an executor: use Sage for analysis/recommendations, then implement changes in the primary agent flow.
+- Prefer one focused Sage question over multiple vague calls.
+- After Sage returns, synthesize result and proceed with concrete next steps.
+- If user explicitly asks for Sage/second opinion, prioritize making at least one Sage call unless blocked by hard safety limits.
+
+---
+
+## 8) Invocation Policy & Guardrails
+
+## 8.1 Modes and caller scope
+- `autonomousEnabled: boolean` (applies only in eligible interactive primary sessions; default: true there)
+- `explicitRequestAlwaysAllowed: boolean` (default: true)
+- `invocationScope: "interactive-primary-only"` (default and recommended)
+- `sage_consult` is callable only from the top-level interactive primary agent session.
+- `sage_consult` is blocked for non-interactive/CI contexts and RPC-orchestrated agent roles (e.g., supervisor, worker, reviewer, merger).
+
+## 8.2 Soft limits (defaults)
+Soft limits are policy/budget controls and are bypassable for explicit user requests (`force=true`).
+- `maxCallsPerTurn: 1`
+- `maxCallsPerSession: 6`
+- `cooldownTurnsBetweenAutoCalls: 1`
+- `maxQuestionChars: 6000`
+- `maxContextChars: 20000`
+
+## 8.3 Hard safety limits (non-bypassable)
+- Disallowed caller context (not top-level interactive primary session).
+- Model unavailable or no API key.
+- Timeout exceeded (`timeoutMs`, default `120000`).
+- Absolute cost cap exceeded (`maxEstimatedCostPerSession`, optional).
+
+## 8.4 Explicit user request behavior
+- If user explicitly requests Sage (“Sage”, “second opinion”, etc.), set `force=true` path to bypass soft limits.
+- Hard safety limits and caller-scope restrictions still apply.
+
+## 8.5 Recursion and interaction constraints
+- Sage subprocesses are **not allowed** to invoke `sage_consult`.
+- Every `sage_consult` call is **single-shot** (no multi-turn sub-conversation loop).
+- Primary agent should ask one focused question and then continue execution after one Sage response.
+
+## 8.6 Caller eligibility gate (concrete enforcement)
+Implement a deterministic `isEligibleCaller(context)` check before any policy/budget logic.
+
+Required conditions (all must be true):
+1. `context.session.interactive === true`
+2. `context.agent.role === "primary"`
+3. `context.agent.isSubagent !== true`
+4. `context.agent.isRpcOrchestrated !== true`
+5. `context.runtime.mode !== "ci"`
+
+Deny-by-default behavior:
+- If any required context field is missing/unknown, block invocation with `blockCode: "unknown-context"`.
+- Explicit user requests (`force=true`) do **not** bypass this gate.
+
+Recommended pseudocode:
+
+```ts
+function isEligibleCaller(ctx: CallerContext): { ok: boolean; blockCode?: string; reason: string } {
+  if (!ctx || !ctx.session || !ctx.agent || !ctx.runtime) {
+    return { ok: false, blockCode: "unknown-context", reason: "Missing caller context" };
+  }
+  if (ctx.session.interactive !== true) {
+    return { ok: false, blockCode: "non-interactive", reason: "Sage allowed only in interactive sessions" };
+  }
+  if (ctx.runtime.mode === "ci") {
+    return { ok: false, blockCode: "ci-mode", reason: "Sage disabled in CI mode" };
+  }
+  if (ctx.agent.isRpcOrchestrated === true) {
+    return { ok: false, blockCode: "rpc-role", reason: "Sage disabled for RPC-orchestrated agents" };
+  }
+  if (ctx.agent.isSubagent === true) {
+    return { ok: false, blockCode: "subagent", reason: "Sage disabled for subagents" };
+  }
+  if (ctx.agent.role !== "primary") {
+    return { ok: false, blockCode: "ineligible-caller", reason: "Only primary agent may invoke Sage" };
+  }
+  return { ok: true, reason: "eligible" };
+}
+```
+
+## 8.7 RPC role mapping guidance (orchestration frameworks)
+For orchestrated multi-agent frameworks, map caller role metadata so these roles are always ineligible:
+- `supervisor`
+- `worker`
+- `reviewer`
+- `merger`
+
+If runtime only provides a session name/string, derive role via conservative matching and deny on ambiguity.
+
+---
+
+## 9) Natural-Language Operator Invocation
+
+No `/sage` command is provided.
+
+Mechanism:
+1. User asks naturally for second opinion.
+2. Top-level interactive primary agent interprets request (with prompt guidance + tool availability).
+3. If caller scope is eligible, primary agent calls `sage_consult`; otherwise Sage is blocked and the agent proceeds with best-effort local reasoning.
+
+v0.1 decision:
+- Rely on primary model instruction-following for explicit-request detection.
+- Do **not** add a phrase-detection hook initially.
+- Add a hook later only if testing shows missed explicit user requests.
+
+---
+
+## 10) `/sage-settings` Command Spec
+
+## 10.1 Purpose
+Interactive command to configure Sage runtime behavior.
+
+## 10.2 Required settings
+1. **Enabled**: on/off
+2. **Autonomous mode**: on/off
+3. **Sage model**: picker from `modelRegistry.getAvailable()`
+4. **Reasoning level**: minimal/low/medium/high/xhigh
+5. **Timeout**: ms/seconds
+6. **Per-turn call limit**
+7. **Per-session call limit**
+8. **Cooldown between autonomous calls**
+9. **Tool profile for Sage subagent**:
+   - none (strict advisor mode)
+   - read-only-lite (`ls,glob,grep,read`) **default**
+   - git-review-readonly (`ls,glob,grep,read,bash`) with strict allowlisted git read commands only
+   - custom read-only list (must exclude mutating/execution tools)
+10. **Per-call max tool calls** (default: 10)
+11. **Per-call max files read** (default: 8)
+12. **Per-file max bytes** (default: 200KB)
+13. **Per-call max total bytes read** (default: 1MB)
+14. **Sensitive path denylist** (default on; configurable additions)
+15. **Cost cap** (optional)
+
+## 10.3 UX behavior
+- Use selection UI instead of free-text where possible.
+- Show currently active values and source (project/global/default).
+- Save options to project or global scope (user choice in command flow).
+- Include “Test Sage call” action to validate model/auth.
+
+---
+
+## 11) Security and Safety
+
+1. Sage subprocess executes with same local permissions as Pi.
+2. Sage subprocess must not have access to `sage_consult` (no autonomous agent recursion).
+3. `sage_consult` must be disabled for RPC-orchestrated agents and non-interactive sessions.
+4. Never pass secrets intentionally unless present in existing prompt/context.
+
+### 11.1 Tool-access policy (advisor model)
+1. Default Sage tool profile is `read-only-lite`: `ls,glob,grep,read`.
+2. Allow `none` profile for stricter environments.
+3. Custom profile must be read-only; mutating/execution tools are disallowed.
+4. Explicitly disallow: `edit`, `write`, git-mutating tools, orchestration-control tools, and network/http tools.
+5. Exception: `git-review-readonly` profile may allow `bash` only for allowlisted read-only git commands (e.g., status/diff/show/log/blame/rev-parse/branch --show-current).
+
+### 11.2 Data-access and volume guardrails
+1. Restrict reads to workspace/project roots.
+2. Denylist sensitive paths by default (e.g., `.env*`, `*.pem`, `*.key`, `id_rsa*`, credential stores).
+3. Enforce caps per Sage call:
+   - max tool calls: `10`
+   - max files read: `8`
+   - max bytes per file: `200KB`
+   - max total bytes read: `1MB`
+4. Cap `grep`/`glob` result counts to avoid context explosion.
+
+---
+
+## 12) Observability
+
+Each Sage call should expose:
+- mode (autonomous vs user-requested),
+- model + reasoning level,
+- tool profile used (`none`, `read-only-lite`, `git-review-readonly`, or `custom-read-only`),
+- elapsed time,
+- token usage + cost (if available),
+- refusal/error reason when blocked.
+
+Tool rendering should keep concise collapsed view and richer expanded view.
+
+---
+
+## 13) Failure Handling
+
+On Sage failure:
+1. Return structured error in tool result (`isError: true`).
+2. Primary agent continues without crashing.
+3. If failure was during explicit user-requested consultation, agent should state that Sage failed and proceed with best-effort local reasoning.
+
+On ineligible caller/context block:
+1. Return structured non-crashing block result with `policy.allowedByContext=false`, `policy.blockCode`, and `policy.contextReason`.
+2. Do not spawn Sage subprocess.
+3. Primary agent proceeds with best-effort local reasoning and briefly explains why Sage was unavailable.
+
+On tool-policy/data-policy block:
+1. Return structured non-crashing block result with `policy.blockCode` (`tool-disallowed`, `path-denied`, or `volume-cap`).
+2. Do not escalate privileges or relax guardrails automatically.
+3. Continue with available context and provide best-effort recommendations.
+
+---
+
+## 14) Acceptance Criteria (Draft)
+
+1. Primary agent autonomously invokes Sage at least once in a complex debug scenario without user explicitly asking (interactive top-level primary session).
+2. In CI/non-interactive mode, Sage invocation is blocked (non-bypassable caller-scope gate).
+3. RPC-orchestrated agents (supervisor/worker/reviewer/merger) cannot invoke `sage_consult`.
+4. User phrase “get a second opinion” in an eligible interactive primary session causes at least one Sage consultation in same task flow.
+5. Explicit user-requested Sage consultation can bypass soft limits, but still respects hard safety limits and caller-scope restrictions.
+6. No `/sage` command exists.
+7. `/sage-settings` lists available models interactively and persists selected model.
+8. Default Sage tool profile is `read-only-lite` (`ls,glob,grep,read`), with `none`, `git-review-readonly`, and constrained custom read-only options available.
+9. Sage tool profile blocks mutating/execution/network/orchestration tools (including `edit`, `write`, and `sage_consult`), except allowlisted git-read bash commands in `git-review-readonly`.
+10. Sage enforces per-call guardrails (max tool calls/files/bytes and capped `grep`/`glob` output).
+11. Sage calls obey hard safety limits (caller context, model/auth availability, timeout, optional absolute cost cap).
+12. Sage subprocess cannot invoke `sage_consult` (no recursion).
+13. Sage consultations are single-shot per call.
+14. Tool output shows model/latency/usage metadata, including tool profile/tool usage and block reason when context is ineligible.
+
+---
+
+## 15) Resolved Decisions (from review)
+
+1. Explicit user requests should bypass all soft limits.
+2. Sage invocation is restricted to interactive top-level primary sessions.
+3. Autonomous Sage calls are disabled in CI/non-interactive contexts via caller-scope gate.
+4. Sage is single-shot per call (no multi-turn Sage sub-conversations in v0.1).
+5. Start with model interpretation for explicit-request detection; add phrase-detection hook only if testing reveals reliability issues.
+6. Sage subagents cannot invoke other Sage subagents (no recursion).
+7. Sage is advisory-only and should not perform implementation actions.
+8. Default Sage tool profile is `read-only-lite` (`ls,glob,grep,read`) with strict guardrails; optional `git-review-readonly` exists for code-review workflows.
+
+---
+
+## 16) Implementation Order (Suggested)
+
+1. Build settings store + `/sage-settings` command.
+2. Implement `sage_consult` subprocess runner + structured result metadata.
+3. Add hard caller-context gate (interactive top-level primary only; block CI/RPC-orchestrated roles).
+4. Implement advisory tool policy (`read-only-lite`, `none`, `git-review-readonly`, constrained custom) and hard denylist for mutating/execution tools.
+5. Add data-volume guardrails (tool-call/file/byte caps + `grep`/`glob` result caps + sensitive-path denylist).
+6. Add system-prompt guidance injection for autonomous invocation.
+7. Add budget gates and policy telemetry.
+8. Add rendering polish and acceptance tests.
+9. Add a caller-context + tool-policy test matrix (interactive primary allowed; CI blocked; supervisor/worker/reviewer/merger blocked; subagent blocked; unknown context blocked; disallowed tool attempts blocked).
+
+---
+
+## 17) Concrete Implementation Checklist (`.pi/extensions/sage/index.ts`)
+
+### 17.1 Types and constants
+- [ ] Add `ToolProfile = "none" | "read-only-lite" | "git-review-readonly" | "custom-read-only"`.
+- [ ] Add `BlockCode = "ineligible-caller" | "non-interactive" | "ci-mode" | "rpc-role" | "subagent" | "unknown-context" | "tool-disallowed" | "path-denied" | "volume-cap"`.
+- [ ] Add `CallerContext` type:
+  - `session.interactive: boolean`
+  - `agent.role: string`
+  - `agent.isSubagent: boolean`
+  - `agent.isRpcOrchestrated: boolean`
+  - `runtime.mode: string`
+- [ ] Add `ToolPolicySettings` type:
+  - `profile`, `customAllowedTools`
+  - `maxToolCalls`, `maxFilesRead`, `maxBytesPerFile`, `maxTotalBytesRead`
+  - `sensitivePathDenylist`
+- [ ] Add constants:
+  - `READ_ONLY_LITE_TOOLS = ["ls", "glob", "grep", "read"]`
+  - `HARD_DISALLOWED_TOOLS = ["edit", "write", "bash", "sage_consult"]`
+  - default caps: `10` calls, `8` files, `200KB/file`, `1MB total`.
+
+### 17.2 Policy/guard functions
+- [ ] `resolveCallerContext(runCtx): CallerContext | null`
+- [ ] `isEligibleCaller(ctx): { ok: boolean; blockCode?: BlockCode; reason: string }`
+- [ ] `resolveToolPolicy(settings): ResolvedToolPolicy`
+- [ ] `validateCustomToolList(tools): { ok: boolean; disallowed?: string[] }`
+- [ ] `isPathAllowed(path, workspaceRoots, denylist): { ok: boolean; reason?: string }`
+- [ ] `checkVolumeCaps(usage, caps): { ok: boolean; blockCode?: "volume-cap"; reason?: string }`
+- [ ] `makeBlockedResult(blockCode, reason, partialDetails?)` helper for consistent tool responses.
+
+### 17.3 `sage_consult` handler flow
+- [ ] Step 1: Load merged settings (project > global > defaults).
+- [ ] Step 2: Resolve caller context.
+- [ ] Step 3: Apply hard caller gate (`isEligibleCaller`) **before** budget checks.
+- [ ] Step 4: If blocked, return structured result with:
+  - `policy.allowedByContext=false`
+  - `policy.blockCode`
+  - `policy.contextReason`
+- [ ] Step 5: Apply soft-budget gate (respect `force=true` bypass for explicit user requests).
+- [ ] Step 6: Build Sage subprocess invocation with restricted tool manifest based on resolved tool profile.
+- [ ] Step 7: Run single-shot subprocess with timeout.
+- [ ] Step 8: Collect model/latency/tokens + `toolUsage` + policy metadata.
+- [ ] Step 9: Return advisory markdown (`content`) + structured `details`.
+
+### 17.4 Subprocess/tool isolation
+- [ ] Ensure Sage subprocess tool registry excludes `sage_consult`.
+- [ ] Ensure mutating/execution/network/orchestration tools are unavailable to Sage profile resolution.
+- [ ] Ensure custom profile cannot include tools outside read-only allowlist.
+
+### 17.5 `/sage-settings` command wiring
+- [ ] Add profile picker: `none`, `read-only-lite`, `git-review-readonly`, `custom-read-only`.
+- [ ] For `custom-read-only`, show multi-select constrained to read-only tools.
+- [ ] Add numeric inputs for guardrails (tool calls/files/bytes).
+- [ ] Add editable sensitive-path denylist (with safe defaults preloaded).
+- [ ] Show effective scope/source (project/global/default) and save target.
+
+### 17.6 Test checklist
+- [ ] Unit: `isEligibleCaller` allows only interactive primary; blocks CI, non-interactive, subagent, rpc-role, unknown context.
+- [ ] Unit: `resolveToolPolicy` defaults to `read-only-lite` and strips/blocks disallowed custom tools.
+- [ ] Unit: `isPathAllowed` blocks denylisted paths and non-workspace paths.
+- [ ] Unit: `checkVolumeCaps` trips correctly on call/file/byte overages.
+- [ ] Integration: explicit user request with `force=true` bypasses soft limits but not caller gate.
+- [ ] Integration: RPC roles (`supervisor`, `worker`, `reviewer`, `merger`) receive structured blocked result.
+- [ ] Integration: Sage subprocess cannot call `sage_consult` (recursion test).
+- [ ] Integration: tool usage metadata is present in successful responses.
+- [ ] Integration: blocked results include `blockCode` + human-readable reason.
+
+### 17.7 Suggested file split (optional)
+- `index.ts` (extension registration + tool/command wiring)
+- `policy.ts` (caller gate, budget gate, block result helpers)
+- `tool-policy.ts` (profile resolution, path/volume guardrails)
+- `settings.ts` (load/merge/validate settings)
+- `runner.ts` (single-shot subprocess execution)
+- `types.ts` (shared interfaces/enums)
+- `__tests__/...` (unit + integration suites)