@sage-protocol/pi-adapter 0.3.12 → 0.4.3

package/USAGE.md

@@ -8,54 +8,121 @@
 
 ## Integration Modes
 
-1. **pi CLI extension** — `pi install npm:@sage-protocol/pi-adapter` (no source changes)
+1. **Pi CLI extension** — `pi install npm:@sage-protocol/pi-adapter` (no source changes)
 2. **SDK embedding** — `createSageSessionConfig(...)` for harness source owners
 
-## pi CLI Mode
+## Pi CLI Mode
 
 ```bash
 pi install npm:@sage-protocol/pi-adapter
 pi list  # verify installed
 ```
 
-Restart pi and use normally. What loads automatically:
+Restart Pi and use it normally. The packaged extension provides:
 
-- custom tools: `sage_search`, `sage_execute`, `sage_status`, `sage_behavior`
-- skill suggestions: `sage suggest hook skill` (per-turn)
-- capture hooks: `sage capture hook prompt/response`
-- security hooks: `sage security scan-hook` (pre/post tool)
+- SessionStart Sage context, loaded inventory, MCP tools, and behaviors
+- Pi-native skill discovery through `<available_skills>` and `/skill:<name>`
+- prompt/response capture through `sage capture hook prompt/response`
+- observation of complete native `SKILL.md` reads and full `skills.get` loads
+- source- and session-qualified load receipts
+- `sage_mark_guided_use` for binding applied loaded skills to the exact prompt capture
+- optional pre/post-tool security scanning
+- explicit skill resolution for subagents that do not inherit Pi's native skill catalog
+
+The extension does not run `sage suggest hook skill` per prompt and does not
+inject `sage-suggested-skills`. It also has no suggestion auto-skip,
+auto-reject, or suggestion-quality widget lifecycle.
+
+## Native Skill Workflow
+
+1. Choose from Pi's native `<available_skills>` catalog.
+2. Load the selected skill with `/skill:<name>` or a complete `SKILL.md` read.
+3. Follow the loaded procedure.
+4. If at least one instruction, constraint, or output structure from it guided
+   the current turn, call:
+
+   ```text
+   sage_mark_guided_use({ skills: ["<loaded-key>"] })
+   ```
+
+The adapter observes successful complete loads, writes a load receipt qualified
+by Sage source and Pi session, and lets the daemon bind guided use to the exact
+active prompt capture. Partial reads, unloaded keys, ambiguous bare names,
+missing captures, and failed receipt/feedback writes fail closed. Loading a
+procedure without applying it is not use. Compaction and session replacement
+clear load eligibility.
+
+Manual ranking is still available when explicitly requested:
+
+```bash
+sage suggest skill "review this smart contract" --format json
+```
+
+That command does not inject a skill into Pi. Load the chosen full procedure
+through Pi's native flow before using it.
 
 ## SDK Integration
 
 ```typescript
-import { createAgentSession, createCodingTools } from '@earendil-works/pi-coding-agent';
-import { createSageSessionConfig } from '@sage-protocol/pi-adapter';
+import {
+  createAgentSession,
+  createCodingTools,
+  type ToolDefinition as PiToolDefinition,
+} from '@earendil-works/pi-coding-agent';
+import {
+  createSageSessionConfig,
+  type ToolDefinition as SageToolDefinition,
+} from '@sage-protocol/pi-adapter';
+
+function asPiCustomTools(tools: SageToolDefinition[]): PiToolDefinition[] {
+  // Type-shape compatibility across supported Pi minors; no runtime conversion.
+  return tools as unknown as PiToolDefinition[];
+}
 
 const sage = await createSageSessionConfig({
   sageBin: 'sage',
   source: 'pi-agent-core',
-  suggestLimit: 3,
+  enableRlmFeedback: true,
+  enableSecurityHooks: true,
 });
-
+const cwd = process.cwd();
+const securedTools = sage.wrapToolsWithSecurity(createCodingTools(cwd));
 const { session } = await createAgentSession({
+  cwd,
   model,
-  tools: sage.wrapToolsWithSecurity(createCodingTools(cwd)),
-  customTools: sage.customTools,
+  noTools: 'builtin',
+  customTools: asPiCustomTools([...securedTools, ...sage.customTools]),
 });
 
 const disposeSageHooks = sage.setupHooks(session);
-// on teardown: disposeSageHooks()
+// on teardown: disposeSageHooks(); await sage.mcpBridge.stop();
 ```
 
+Pi's `tools` option is a string allowlist, not a tool-definition array. The
+helper isolates the only compatibility cast between the adapter's tool shape,
+which spans supported Pi minors, and Pi's generic `ToolDefinition`; it performs
+no runtime conversion.
+
+The packaged Pi extension contains the Pi event-level native-load observer and
+`sage_mark_guided_use` registration. A custom SDK host that bypasses the
+extension must provide equivalent Pi event wiring if it wants those extension
+features; `createSageSessionConfig` still supplies bridge, SessionStart,
+capture, and security integration.
+
 ## Plugin Pattern
 
 ```typescript
 export async function setupSagePlugin(runtime) {
   const sage = await createSageSessionConfig({ source: 'pi-agent-core' });
+  const cwd = process.cwd();
+  const securedTools = sage.wrapToolsWithSecurity(runtime.createCodingTools(cwd));
+
+  // Pseudo host API: register definitions as custom tools before session creation.
+  runtime.registerCustomTools([...securedTools, ...sage.customTools]);
   const { session } = await runtime.makeSession({
+    cwd,
     model: runtime.model,
-    tools: sage.wrapToolsWithSecurity(runtime.tools),
-    customTools: sage.customTools,
+    noTools: 'builtin',
   });
   const dispose = sage.setupHooks(session);
   return {
@@ -65,38 +132,33 @@ export async function setupSagePlugin(runtime) {
 }
 ```
 
+A plugin host may name `registerCustomTools` differently; use its own custom-tool
+registration API. Do not put definitions in a `tools` option.
+
 ## Environment Variables
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `SAGE_BIN` | `sage` | Path to sage CLI |
-| `SAGE_PROFILE` | — | Sage config profile (e.g. `testnet`) |
-| `SAGE_SUGGEST_LIMIT` | `3` | Max skill suggestions per turn |
-| `SAGE_SUGGEST_DEBOUNCE_MS` | `800` | Minimum ms between suggestions |
-| `SAGE_SECURITY_HOOKS` | `1` | Enable pre/post tool security scanning |
-| `SAGE_RLM_FEEDBACK` | `1` | Enable prompt/response capture |
-| `SAGE_SHOW_HOOK_MESSAGES` | `0` | Display hook messages in chat UI |
+| `SAGE_BIN` | `sage` | Path to Sage CLI |
+| `SAGE_PROFILE` | — | Sage config profile (for example `testnet`) |
+| `SAGE_SECURITY_HOOKS` | `1` | Enable pre/post-tool security scanning |
+| `SAGE_RLM_FEEDBACK` | `1` | Enable prompt/response capture and native-use receipts |
+| `SAGE_SHOW_HOOK_MESSAGES` | `0` | Display SessionStart hook messages in the chat UI |
 | `SAGE_ALLOW_BASH_CLI` | `1` | Allow direct `sage ...` bash calls |
-| `SAGE_BEHAVIOR_ENRICH` | `0` | Enable behavior chain enrichment on suggestions |
-| `SAGE_AUTO_RESOLVE_SKILLS` | `1` | Auto-resolve skill content for subagents |
-| `SAGE_INJECT_TOOL_DOCS` | `1` | Inject Sage tool guardrails per-turn |
-
-### Skill Quality Annotations
-
-The widget automatically annotates suggested skills with execution quality data from the Sage daemon. No extra configuration needed — just ensure the daemon is running (`sage daemon start`).
-
-Annotations appear when the daemon has ≥3 recorded execution outcomes per skill:
+| `SAGE_AUTO_RESOLVE_SKILLS` | `1` | Resolve skills explicitly named in subagent tasks |
+| `SAGE_INJECT_TOOL_DOCS` | `1` | Add compact Sage tool guardrails each turn |
 
-- `✓` — ≥70% pass rate (reliable)
-- `⚠` — 40-70% pass rate (mixed)
-- `✗` — <40% pass rate (harmful — skipped in subagent contexts)
-- (none) — insufficient data
+### Deprecated Low-Level Compatibility
 
-Quality data is cached for the session lifetime. Skills with <30% pass rate and ≥3 samples are skipped during subagent auto-resolve.
+`suggestLimit`, `suggestDebounceMs`, and `enableProvision` remain exported in
+`SageP2Config` for low-level legacy callers. The default Pi path ignores them;
+do not use them in new configuration. `sageInjectSuggestion(...)` is likewise
+a deprecated no-op in 0.4.
 
 ## Project Config
 
-For monorepo development, keep pi thin — point at the Sage Pi export surface:
+For monorepo development, keep Pi thin and point it at the curated Sage Pi
+export surface:
 
 ```json
 {

package/dist/behavior/pi-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pi-executor.d.ts","sourceRoot":"","sources":["../../src/behavior/pi-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,KAAK,EAEX,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,eAAe,EAGf,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,+CAA+C;IAC/C,MAAM,EAAE,aAAa,CAAC;IACtB,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE;QACvB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,OAAO,CAAC;KACjB,KAAK,IAAI,CAAC;CACX;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,kBAAmB,YAAW,gBAAgB;IAC1D,QAAQ,CAAC,IAAI,0BAA0B;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAkC;gBAEnD,MAAM,EAAE,gBAAgB;IAK9B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAIjD,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO;IAKjC,OAAO,CACZ,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,gBAAgB,GACvB,OAAO,CAAC,eAAe,CAAC;IAqC3B;;;;;;;;;OASG;IACH,OAAO,CAAC,sBAAsB;IA6E9B;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;CAiB7B"}
+{"version":3,"file":"pi-executor.d.ts","sourceRoot":"","sources":["../../src/behavior/pi-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,OAAO,KAAK,EAEX,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,eAAe,EAGf,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,+CAA+C;IAC/C,MAAM,EAAE,aAAa,CAAC;IACtB,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE;QACvB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,OAAO,CAAC;KACjB,KAAK,IAAI,CAAC;CACX;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,kBAAmB,YAAW,gBAAgB;IAC1D,QAAQ,CAAC,IAAI,0BAA0B;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAkC;gBAEnD,MAAM,EAAE,gBAAgB;IAK9B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAIjD,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO;IAKjC,OAAO,CACZ,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,gBAAgB,GACvB,OAAO,CAAC,eAAe,CAAC;IAsC3B;;;;;;;;;OASG;IACH,OAAO,CAAC,sBAAsB;IAiH9B;;;;;;OAMG;IACH,OAAO,CAAC,qBAAqB;CAiB7B"}

package/dist/behavior/pi-executor.js

@@ -54,6 +54,7 @@ export class PiBehaviorExecutor {
         const startTime = Date.now();
         const results = [];
         // Render the plan as a controller prompt for the agent.
+        // This is plan injection (Smithers-style), not step completion.
         const controllerPrompt = this.renderControllerPrompt(plan, context);
         // Report plan to the agent via hook message
         if (this.sendMessage) {
@@ -63,19 +64,19 @@ export class PiBehaviorExecutor {
                 display: true,
             });
         }
-        // Mark all steps as pending — the agent will execute them via the
-        // controller prompt. We track them for observability.
+        // Steps remain awaiting_agent until the host has real step results.
+        // Never claim completed solely because the plan was rendered.
         for (const step of plan.steps) {
             const stepStart = Date.now();
-            context.onProgress?.(step.id, "pending");
+            context.onProgress?.(step.id, "awaiting_agent");
             results.push({
                 stepId: step.id,
-                status: "pending",
+                status: "awaiting_agent",
                 durationMs: Date.now() - stepStart,
             });
         }
         return {
-            status: "completed",
+            status: "awaiting_agent",
             steps: results,
             totalDurationMs: Date.now() - startTime,
             output: controllerPrompt,
@@ -93,11 +94,23 @@ export class PiBehaviorExecutor {
      */
     renderControllerPrompt(plan, context) {
         const lines = [];
-        lines.push("# Behavior Execution Plan");
+        // Smithers-inspired: plan is an authority envelope + step menu, not a runtime.
+        // Status stays awaiting_agent until steps are actually done.
+        lines.push("# Behavior Plan (controller inject — not a completed run)");
+        lines.push("");
+        lines.push("This is a **durable step plan** for you (the agent) to execute with tools.");
+        lines.push("The adapter has **not** completed these steps. Status: `awaiting_agent`.");
         lines.push("");
         lines.push(`**Task:** ${context.task}`);
         lines.push(`**Steps:** ${plan.steps.length}`);
         lines.push("");
+        lines.push("## Load rule (per step)");
+        lines.push("");
+        lines.push("1. Load the **full** skill procedure for the step (`/skill:<key>`, read SKILL.md, or skills.get).");
+        lines.push("2. Freestyle tools **under that skill's constraints** — ranking/plan text is not enough.");
+        lines.push("3. Only after step work is done, move to the next step in order.");
+        lines.push("4. Report outcomes with `sage suggest feedback outcome <skill-key> --status passed|failed` when a procedure guided work.");
+        lines.push("");
         if (context.mcpServersRequired.length > 0) {
             lines.push("## Required MCP Servers");
             for (const server of context.mcpServersRequired) {
@@ -115,6 +128,8 @@ export class PiBehaviorExecutor {
             lines.push(`### Step ${i + 1}: ${step.title}`);
             lines.push("");
             lines.push(`**Skill:** \`${step.skill_key}\``);
+            lines.push(`**Status:** awaiting_agent`);
+            lines.push(`**Load:** \`/skill:${step.skill_key}\` or \`sage library inspect skill get ${step.skill_key}\` or skills.get before freestyle`);
             if (step.uses.length > 0) {
                 lines.push(`**Depends on:** ${step.uses.join(", ")}`);
             }
@@ -123,6 +138,10 @@ export class PiBehaviorExecutor {
                 lines.push(step.instruction);
                 lines.push("");
             }
+            else {
+                lines.push(`_No body in plan — load full skill \`${step.skill_key}\` before acting._`);
+                lines.push("");
+            }
             // Subagent delegation hint for steps that benefit from isolation
             if (this.shouldSuggestSubagent(step, plan.steps.length)) {
                 lines.push(`> 💡 **Subagent hint:** This step may benefit from running in an isolated subagent.`);
@@ -139,6 +158,7 @@ export class PiBehaviorExecutor {
         lines.push("");
         lines.push("After completing all steps, synthesize the results into a coherent response.");
         lines.push("Reference findings from each step and note any cross-step insights.");
+        lines.push("Do not treat plan injection alone as success; only completed step work counts.");
         return lines.join("\n");
     }
     /**

package/dist/behavior/pi-executor.js.map

@@ -1 +1 @@
-{"version":3,"file":"pi-executor.js","sourceRoot":"","sources":["../../src/behavior/pi-executor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pi-executor.js","sourceRoot":"","sources":["../../src/behavior/pi-executor.ts"],"names":[],"mappings":"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"}

package/dist/behavior/types.d.ts

@@ -64,8 +64,14 @@ export interface BehaviorPlan {
     /** Ordered steps. */
     steps: PlanStep[];
 }
-/** Outcome of a single step execution. */
-export type StepStatus = "pending" | "running" | "completed" | "failed" | "skipped";
+/**
+ * Outcome of a single step execution.
+ *
+ * Smithers-style honesty: injecting a controller plan is not step completion.
+ * Use `awaiting_agent` when the agent still owns the work; never claim
+ * `completed` until the harness has real step results.
+ */
+export type StepStatus = "pending" | "awaiting_agent" | "running" | "in_progress" | "completed" | "failed" | "skipped";
 /** Result from executing a single plan step. */
 export interface StepResult {
     stepId: string;
@@ -96,8 +102,13 @@ export interface ExecutionContext {
 }
 /** Final result of executing a complete behavior plan. */
 export interface ExecutionResult {
-    /** Overall status: "completed" if all steps succeeded, "failed" if any required step failed. */
-    status: "completed" | "failed" | "partial" | "cancelled";
+    /**
+     * Overall status.
+     * - `awaiting_agent` / `in_progress`: plan injected; agent still owns steps (not completed).
+     * - `completed`: all steps actually finished successfully.
+     * - `failed` / `partial` / `cancelled`: terminal failure states.
+     */
+    status: "awaiting_agent" | "in_progress" | "completed" | "failed" | "partial" | "cancelled";
     /** Per-step results in execution order. */
     steps: StepResult[];
     /** Total execution duration in milliseconds. */

package/dist/behavior/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/behavior/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/behavior/types.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,26 +1,48 @@
 /**
  * Sage Protocol - Pi Adapter
  *
- * Provides Sage MCP integration for pi coding agent.
+ * Provides Sage MCP, SessionStart context, capture, security, behavior, and
+ * native skill-use integration for Pi. Pi itself owns skill discovery/loading
+ * through `<available_skills>`, `/skill:<name>`, and complete `SKILL.md` reads;
+ * default adapter setup does not inject per-prompt suggestions.
  *
  * @example
  * ```typescript
- * import { createAgentSession, createCodingTools } from '@earendil-works/pi-coding-agent'
- * import { createSageSessionConfig } from '@sage-protocol/pi-adapter'
+ * import {
+ *   createAgentSession,
+ *   createCodingTools,
+ *   type ToolDefinition as PiToolDefinition,
+ * } from '@earendil-works/pi-coding-agent'
+ * import {
+ *   createSageSessionConfig,
+ *   type ToolDefinition as SageToolDefinition,
+ * } from '@sage-protocol/pi-adapter'
+ *
+ * function asPiCustomTools(tools: SageToolDefinition[]): PiToolDefinition[] {
+ *   // Type-shape compatibility across supported Pi minors; no runtime conversion.
+ *   return tools as unknown as PiToolDefinition[]
+ * }
  *
  * const sage = await createSageSessionConfig({
  *   sageBin: 'sage',
  *   source: 'pi-agent-core',
- *   suggestLimit: 3,
+ *   enableRlmFeedback: true,
+ *   enableSecurityHooks: true,
  * })
- *
+ * const cwd = process.cwd()
+ * const securedTools = sage.wrapToolsWithSecurity(createCodingTools(cwd))
  * const { session } = await createAgentSession({
- *   tools: sage.wrapToolsWithSecurity(createCodingTools(process.cwd())),
- *   customTools: sage.customTools,
+ *   cwd,
+ *   noTools: 'builtin',
+ *   customTools: asPiCustomTools([...securedTools, ...sage.customTools]),
  * })
  *
  * const disposeSageHooks = sage.setupHooks(session)
  * ```
+ *
+ * The packaged Pi extension observes complete native skill loads and exposes
+ * `sage_mark_guided_use`. The legacy `sageInjectSuggestion` helper is a
+ * deprecated no-op in 0.4.
  */
 export * from './sage-pi-adapter.js';
 export * from './behavior/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,cAAc,sBAAsB,CAAC;AAGrC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAGH,cAAc,sBAAsB,CAAC;AAGrC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -1,26 +1,48 @@
 /**
  * Sage Protocol - Pi Adapter
  *
- * Provides Sage MCP integration for pi coding agent.
+ * Provides Sage MCP, SessionStart context, capture, security, behavior, and
+ * native skill-use integration for Pi. Pi itself owns skill discovery/loading
+ * through `<available_skills>`, `/skill:<name>`, and complete `SKILL.md` reads;
+ * default adapter setup does not inject per-prompt suggestions.
  *
  * @example
  * ```typescript
- * import { createAgentSession, createCodingTools } from '@earendil-works/pi-coding-agent'
- * import { createSageSessionConfig } from '@sage-protocol/pi-adapter'
+ * import {
+ *   createAgentSession,
+ *   createCodingTools,
+ *   type ToolDefinition as PiToolDefinition,
+ * } from '@earendil-works/pi-coding-agent'
+ * import {
+ *   createSageSessionConfig,
+ *   type ToolDefinition as SageToolDefinition,
+ * } from '@sage-protocol/pi-adapter'
+ *
+ * function asPiCustomTools(tools: SageToolDefinition[]): PiToolDefinition[] {
+ *   // Type-shape compatibility across supported Pi minors; no runtime conversion.
+ *   return tools as unknown as PiToolDefinition[]
+ * }
  *
  * const sage = await createSageSessionConfig({
  *   sageBin: 'sage',
  *   source: 'pi-agent-core',
- *   suggestLimit: 3,
+ *   enableRlmFeedback: true,
+ *   enableSecurityHooks: true,
  * })
- *
+ * const cwd = process.cwd()
+ * const securedTools = sage.wrapToolsWithSecurity(createCodingTools(cwd))
  * const { session } = await createAgentSession({
- *   tools: sage.wrapToolsWithSecurity(createCodingTools(process.cwd())),
- *   customTools: sage.customTools,
+ *   cwd,
+ *   noTools: 'builtin',
+ *   customTools: asPiCustomTools([...securedTools, ...sage.customTools]),
  * })
  *
  * const disposeSageHooks = sage.setupHooks(session)
  * ```
+ *
+ * The packaged Pi extension observes complete native skill loads and exposes
+ * `sage_mark_guided_use`. The legacy `sageInjectSuggestion` helper is a
+ * deprecated no-op in 0.4.
  */
 // Re-export everything from the main module
 export * from './sage-pi-adapter.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,4CAA4C;AAC5C,cAAc,sBAAsB,CAAC;AAErC,yCAAyC;AACzC,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,4CAA4C;AAC5C,cAAc,sBAAsB,CAAC;AAErC,yCAAyC;AACzC,cAAc,qBAAqB,CAAC"}

package/dist/sage-pi-adapter.d.ts

@@ -38,9 +38,12 @@ export interface AgentSession {
 export interface SageP2Config {
     sageBin?: string;
     sageProfile?: string;
+    /** @deprecated Low-level legacy suggestion compatibility; ignored by the default Pi path. */
     suggestLimit?: number;
+    /** @deprecated Low-level legacy suggestion compatibility; ignored by the default Pi path. */
     suggestDebounceMs?: number;
     timeoutMs?: number;
+    /** @deprecated Low-level legacy suggestion compatibility; ignored by the default Pi path. */
     enableProvision?: boolean;
     enableRlmFeedback?: boolean;
     enableSecurityHooks?: boolean;
@@ -62,6 +65,7 @@ export interface SageCommandRequest {
     args: string[];
     env: Record<string, string>;
     stdin?: string;
+    cwd?: string;
     timeoutMs: number;
 }
 export interface SageCommandResult {
@@ -75,18 +79,61 @@ export interface SkillVisibilityResult {
     libraryCount: number;
     skillCount: number;
 }
+export type SageNativeSkillLoadEvidenceTier = "full_serve" | "native_observed";
+export type SageNativeSkillLoadResult = {
+    schema: "sage.native-skill-load-signal.v1";
+    status: "recorded";
+    recorded: true;
+    qualified_key: string;
+    load_evidence_tier: "native_observed";
+    loaded_at_ms: number;
+} | {
+    schema: "sage.native-skill-load-signal.v1";
+    status: "ignored";
+    recorded: false;
+    reason?: string;
+} | {
+    schema: "sage.native-skill-load-signal.v1";
+    status: "failed";
+    recorded: false;
+};
+export interface SageNativeSkillUseRecord {
+    requested_name: string;
+    qualified_key: string;
+    load_evidence_tier: SageNativeSkillLoadEvidenceTier;
+    load_observed_at_ms: number;
+    recorded: boolean;
+}
+export interface SageNativeSkillUseResult {
+    schema: "sage.native-skill-use.v1";
+    status: "recorded";
+    capture_id: string;
+    capture_linkage: "explicit";
+    uses: SageNativeSkillUseRecord[];
+}
+export interface SageNativeSkillUseFailure {
+    code: "native_use_cli_unsupported" | "native_skill_use_unsupported" | "native_use_timeout" | "native_use_write_failed";
+    message: string;
+    recovery: string;
+}
+export type SageNativeSkillUseAttempt = {
+    result: SageNativeSkillUseResult;
+    failure: null;
+} | {
+    result: null;
+    failure: SageNativeSkillUseFailure | null;
+};
 export type SageCommandRunner = (request: SageCommandRequest) => Promise<SageCommandResult>;
 type SecurityDecision = {
     decision: "allow" | "block" | "warn";
     reason?: string;
 };
 export declare function defaultSageCommandRunner(request: SageCommandRequest): Promise<SageCommandResult>;
-/**
- * Clamp a single (possibly ANSI-styled) line to `width` visible columns so a
- * custom widget/status line can never trip pi's "Rendered line exceeds terminal
- * width" guard. Uses the host pi-tui truncateToWidth when resolvable (ANSI-aware,
- * preserves color); otherwise strips ANSI and hard-slices.
- */
+/** Return terminal-visible width while ignoring ANSI SGR sequences. */
+export declare function visibleWidthOf(line: string): number;
+/** Truncate one ANSI-styled line without counting styling bytes as columns. */
+export declare function truncateLineToWidth(line: string, width: number): string;
+/** Clamp a line so custom TUI/status rendering cannot exceed terminal width. */
 export declare function clampLineToWidth(line: string, width: number): string;
 export declare class SageMcpBridge {
     private command;
@@ -139,10 +186,12 @@ export declare class SageMcpBridge {
 export declare class SageHookRuntime {
     private config;
     private commandRunner;
+    private workingDirectory;
     private sessionContextCache;
     private skillVisibilityCache;
     private softFailureState;
     constructor(config: Required<Pick<SageP2Config, "sageBin" | "timeoutMs">> & SageP2Config);
+    setWorkingDirectory(cwd: unknown): void;
     private getSoftTimeout;
     private clearSoftFailure;
     private logSoftFailure;
@@ -155,15 +204,36 @@ export declare class SageHookRuntime {
      * Returns cached or empty summary when the CLI is unavailable.
      */
     getSkillVisibilitySummary(): Promise<SkillVisibilityResult>;
-    suggestSkill(prompt: string, sessionId?: string): Promise<string>;
-    capturePrompt(prompt: string, sessionId?: string): Promise<void>;
+    /**
+     * @deprecated Low-level compatibility helper. The default Pi path uses
+     * native skill discovery/loading and does not call this per prompt.
+     */
+    suggestSkill(prompt: string, sessionId?: string, model?: string): Promise<string>;
+    capturePrompt(prompt: string, sessionId?: string): Promise<string | undefined>;
     captureResponse(response: string, usage: {
         input?: string;
         output?: string;
-    }, sessionId?: string): Promise<void>;
-    recordSuggestionUse(skillKeys: string[], sessionId?: string): Promise<void>;
-    recordSuggestionSkip(sessionId?: string): Promise<void>;
-    recordExecutionOutcome(skillKey: string, status: "passed" | "failed" | "revised", queryPreview?: string, sessionId?: string, _model?: string): Promise<void>;
+    }, sessionId?: string, captureId?: string): Promise<boolean>;
+    recordSuggestionUse(skillKeys: string[], sessionId?: string, correlationId?: string): Promise<boolean>;
+    /**
+     * Atomically record use of procedures that Pi loaded natively. This path
+     * intentionally has no fallback to legacy suggestion feedback: the daemon
+     * must authorize every returned qualified record from session-scoped load
+     * evidence and link the complete batch to the exact capture.
+     */
+    recordNativeSkillUse(skillKeys: string[], sessionId?: string, captureId?: string): Promise<SageNativeSkillUseResult | null>;
+    recordNativeSkillUseAttempt(skillKeys: string[], sessionId?: string, captureId?: string): Promise<SageNativeSkillUseAttempt>;
+    /**
+     * Record a daemon load receipt for a full skill procedure this session
+     * loaded through Pi's native full SKILL.md read or sage_execute get. The
+     * structured result only reports `recorded: true` after validating the
+     * explicit CLI's versioned JSON receipt. Ignored and failed writes remain
+     * non-recorded so callers can retry honestly.
+     */
+    recordSkillLoadSignal(skillKey: string, sessionId?: string, via?: "slash" | "read"): Promise<SageNativeSkillLoadResult>;
+    recordSuggestionSkip(sessionId?: string, correlationId?: string): Promise<void>;
+    recordSuggestionReject(sessionId?: string, correlationId?: string): Promise<void>;
+    recordExecutionOutcome(skillKey: string, status: "passed" | "failed" | "revised", queryPreview?: string, sessionId?: string, _model?: string, correlationId?: string, captureId?: string): Promise<void>;
     scanPreTool(toolName: string, toolInput: Record<string, unknown>, sessionId?: string): Promise<SecurityDecision | null>;
     scanPostTool(toolName: string, toolInput: Record<string, unknown>, toolResult: unknown, sessionId?: string): Promise<SecurityDecision | null>;
     /**
@@ -223,6 +293,7 @@ export interface SageToolWrapOptions {
 export declare function wrapToolsWithSageSecurity(tools: ToolDefinition[], options: SageToolWrapOptions): ToolDefinition[];
 export declare function createSageExtensions(options: SageP2SessionOptions): {
     customTools: ToolDefinition[];
+    /** @deprecated Pi now handles native skill discovery and loading. This is a no-op. */
     sageInjectSuggestion: (userPrompt: string, session?: AgentSession, sessionId?: string) => Promise<void>;
     sageClearSuggestions: () => void;
     sageGetSuggestions: () => string;