pi-sage 0.2.3 → 0.2.4

package/.pi/extensions/sage/index.ts

@@ -335,6 +335,7 @@ function buildCallerContext(lastInputSource: InputSource | undefined, hasUI: boo
   const isRpcSource = lastInputSource === "rpc";
   const isSubagent = process.env.PI_SAGE_SUBAGENT === "1";
   const interactive = hasUI && lastInputSource === "interactive";
+  const isInteractiveSupervisor = interactive && roleHint === "supervisor";
 
   return {
     session: {
@@ -343,7 +344,7 @@ function buildCallerContext(lastInputSource: InputSource | undefined, hasUI: boo
     agent: {
       role: roleHint ?? "primary",
       isSubagent,
-      isRpcOrchestrated: isRpcSource || Boolean(roleHint && roleHint !== "primary")
+      isRpcOrchestrated: isRpcSource || Boolean(roleHint && roleHint !== "primary" && !isInteractiveSupervisor)
     },
     runtime: {
       mode: process.env.CI ? "ci" : hasUI ? (isRpcSource ? "rpc" : "interactive") : "non-interactive"

package/.pi/extensions/sage/policy.ts

@@ -22,11 +22,17 @@ export function isEligibleCaller(ctx: CallerContext | null | undefined): CallerD
     return { ok: false, blockCode: "subagent", reason: "Sage disabled for subagents" };
   }
 
-  if (ctx.agent.role !== "primary") {
+  const interactiveSupervisor =
+    ctx.agent.role === "supervisor" && ctx.session.interactive === true && ctx.runtime.mode === "interactive";
+
+  if (ctx.agent.role !== "primary" && !interactiveSupervisor) {
     return { ok: false, blockCode: "ineligible-caller", reason: "Only primary agent may invoke Sage" };
   }
 
-  return { ok: true, reason: "eligible" };
+  return {
+    ok: true,
+    reason: interactiveSupervisor ? "eligible (interactive supervisor)" : "eligible"
+  };
 }
 
 export function isHardCostCapExceeded(settings: SageSettings, budgetState: SageBudgetState): boolean {

package/AGENTS.md

@@ -11,7 +11,7 @@ Sage should improve decision quality for complex tasks while preserving strict s
 ## 2) Product Invariants (Do Not Violate)
 
 1. Sage invocation is restricted to **interactive top-level primary** sessions.
-2. RPC-orchestrated roles (`supervisor`, `worker`, `reviewer`, `merger`) cannot invoke Sage.
+2. RPC-orchestrated roles cannot invoke Sage. Exception: an interactive top-level `supervisor` context may invoke Sage when treated as the user-facing primary session.
 3. Sage is **single-shot** per call.
 4. Sage cannot recursively invoke Sage.
 5. Sage is **advisory-only** (analysis/recommendations, not implementation execution).

package/docs/SAGE_SPEC.md

@@ -182,8 +182,8 @@ Primary agent guidance to append:
 - `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).
+- `sage_consult` is callable only from top-level interactive user-facing sessions.
+- `sage_consult` is blocked for non-interactive/CI contexts and RPC-orchestrated roles. Exception: interactive top-level `supervisor` may be treated as primary.
 
 ## 8.2 Soft limits (defaults)
 Soft limits are policy/budget controls and are bypassable for explicit user requests (`force=true`).
@@ -213,7 +213,7 @@ Implement a deterministic `isEligibleCaller(context)` check before any policy/bu
 
 Required conditions (all must be true):
 1. `context.session.interactive === true`
-2. `context.agent.role === "primary"`
+2. `context.agent.role === "primary"` OR (`context.agent.role === "supervisor"` in interactive top-level context)
 3. `context.agent.isSubagent !== true`
 4. `context.agent.isRpcOrchestrated !== true`
 5. `context.runtime.mode !== "ci"`
@@ -241,20 +241,23 @@ function isEligibleCaller(ctx: CallerContext): { ok: boolean; blockCode?: string
   if (ctx.agent.isSubagent === true) {
     return { ok: false, blockCode: "subagent", reason: "Sage disabled for subagents" };
   }
-  if (ctx.agent.role !== "primary") {
+  const interactiveSupervisor =
+    ctx.agent.role === "supervisor" && ctx.session.interactive === true && ctx.runtime.mode === "interactive";
+  if (ctx.agent.role !== "primary" && !interactiveSupervisor) {
     return { ok: false, blockCode: "ineligible-caller", reason: "Only primary agent may invoke Sage" };
   }
-  return { ok: true, reason: "eligible" };
+  return { ok: true, reason: interactiveSupervisor ? "eligible (interactive supervisor)" : "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`
+For orchestrated multi-agent frameworks, map caller role metadata so these roles are ineligible by default:
 - `worker`
 - `reviewer`
 - `merger`
 
+`supervisor` is ineligible unless it is the interactive top-level user-facing session.
+
 If runtime only provides a session name/string, derive role via conservative matching and deny on ambiguity.
 
 ---
@@ -372,7 +375,7 @@ On tool-policy/data-policy block:
 
 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`.
+3. RPC-orchestrated agents cannot invoke `sage_consult` (interactive top-level `supervisor` exception).
 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.
@@ -410,7 +413,7 @@ On tool-policy/data-policy block:
 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).
+9. Add a caller-context + tool-policy test matrix (interactive primary allowed; interactive supervisor allowed; CI blocked; rpc-orchestrated roles blocked; subagent blocked; unknown context blocked; disallowed tool attempts blocked).
 
 ---
 
@@ -470,12 +473,12 @@ On tool-policy/data-policy block:
 - [ ] 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: `isEligibleCaller` allows interactive primary (and interactive supervisor exception); 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: RPC-orchestrated roles receive structured blocked result (interactive supervisor exception).
 - [ ] 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sage",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "private": false,
   "type": "module",
   "description": "Interactive-only advisory Sage extension for Pi",