pi-open-agents 0.1.25 → 0.1.27

package/README.md

@@ -93,7 +93,7 @@ here — or native in pi itself:
 |---|---|
 | `AGENTS.md` adoption — anthropics/claude-code#31005 👍336, openai/codex#12115 👍109 | ✅ Native in pi: `AGENTS.md`/`CLAUDE.md` discovery with `AGENTS.override.md` layering |
 | Agent Skills standard (`.agents/skills/`) — agentskills/agentskills#15 👍183 | ✅ Native in pi; shared agents from `.agents/` (#7 aligns to the dotagents layout) |
-| Tool restrictions that actually reach subagents — anthropics/claude-code#18950 👍70 | ✅ Since v0.1.14, `tools:`/`permission:` restrict the child toolset via `--tools` (full parent inheritance → #8) |
+| Tool restrictions that actually reach subagents — anthropics/claude-code#18950 👍70 | ✅ Since v0.1.14 via `--tools`; full **deny/ask inheritance** (effective-set ceiling + arg patterns) since v0.1.27 |
 | Model selection per subagent / per call — sst/opencode#6651 👍71 | ✅ Per-agent `model:` + per-call `model:` override in `subagent()` (since v0.1.19) |
 | Reasoning effort per agent — Kilo-Org/kilocode#13105 👍8 | ✅ `thinking: off…xhigh` per agent, forwarded to the child process |
 | Delegation guards — Kilo-Org/kilocode#9985 | ✅ `allowedAgents` allowlist + `maxDepth` recursion limit |
@@ -167,6 +167,31 @@ active agent's rules *before it runs* — not just used to filter the toolset:
 > blocks matching *individual calls* (patterns included), not just statically
 > hiding whole tools. (#20)
 
+**Inheritance down the delegation chain (#8).** A subagent can never exceed
+the authority of the agent that delegated to it — in both directions of the
+rule language:
+
+- **Tool ceiling:** at delegation the parent's *live* tool set is snapshotted
+  (`pi.getActiveTools()`), minus tools it blanket-`deny`s or blanket-`ask`s
+  (`ask` is not authority: headless children have no approval bridge). The
+  child's own whitelist is intersected with that ceiling and passed via
+  `--tools` — an empty intersection becomes `--no-tools`, never "all tools".
+- **Argument patterns:** the parent's `deny`/`ask` rules (patterns included)
+  travel to the child's gate and are evaluated *last*, so the child cannot
+  widen them (`write: {"**/*.env": deny}` upstream blocks `.env` writes two
+  levels deep, whatever the child declares).
+- **Transitive:** the ceiling the child launches with *is* the child's active
+  set — a grandchild cannot regain any tool removed at an earlier hop.
+
+### Iterating on agents: `/reload`
+
+Edit a `.agent.md` file (or add/remove one) and run pi's built-in **`/reload`**
+— no session restart (#9). Agent definitions are re-discovered, the active
+agent is **kept** (your mid-session switch survives; `--agent` is a
+startup-only default), and a deleted/disabled active agent falls back cleanly
+with a warning. New agents appear in `/agents` and the `subagent` tool list
+immediately.
+
 ### Auto-injected delegation guidance
 
 If an agent has the `subagent` tool, the plugin automatically appends a
@@ -191,6 +216,12 @@ This means:
 - Each subagent runs with exactly the model and tools it declares
 - Skills load per-agent, with wildcard support (`security-*`, `git-*`)
 
+> **`skills:` is subagent-only (#19).** pi discovers skills once at session
+> startup and exposes no per-agent filter, so a **primary** cannot role-scope
+> them. Declaring `skills:` on a primary (or `all`) agent warns on apply and
+> the field is ignored; the subagent child receives exactly its listed skills,
+> injected into its system prompt.
+
 **Per-call model override:** the caller can override the agent's default for a
 single call — `subagent({ agent: "deep-research", task: "...", model: "zai/glm-5.3-flash" })`.
 Handy for "run this one task on the cheap model" without forking an agent
@@ -353,8 +384,8 @@ six sessions, zero chaos: that's the exact workstation setup documented in
 
 ## Roadmap
 
-- **Parent permission inheritance** for subagents — #8
-- **Agent hot-reload** (or `/reload-agents`) — #9
+- ~~**Parent permission inheritance** for subagents~~ — ✅ shipped in [0.1.27](https://github.com/andrea-tomassi/pi-open-agents/releases/tag/v0.1.27) (#8)
+- ~~**Agent hot-reload**~~ — ✅ works via pi's built-in `/reload`, shipped in [0.1.27](https://github.com/andrea-tomassi/pi-open-agents/releases/tag/v0.1.27) (#9)
 - ~~**Per-call model override** in `subagent()`~~ — ✅ shipped in [0.1.19](https://github.com/andrea-tomassi/pi-open-agents/releases/tag/v0.1.19) (#10)
 - **Parallel subagent limit** — #11
 
@@ -367,7 +398,7 @@ opening an issue or pull request.
 
 ```bash
 npm install
-npm test          # 117 tests
+npm test          # 178 tests
 npm run typecheck # tsc --noEmit
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-open-agents",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "Unified agent and subagent management for pi coding agent, with OpenCode-compatible agent definitions.",
   "keywords": [
     "pi-package",

package/src/index.ts

@@ -26,7 +26,7 @@ import { setShowAgentDescription, updateBanner } from "./tui/banner.ts";
 import { registerTuiControls } from "./tui/selector.ts";
 import { registerAgentTools } from "./tui/tools.ts";
 import { registerSubagentTool } from "./subagent/tool.ts";
-import { allowedAgentNames, isSubagentProcess } from "./subagent/env.ts";
+import { allowedAgentNames, isSubagentProcess, parentInheritedRules } from "./subagent/env.ts";
 import { registerPermissionGate } from "./permission/gate.ts";
 
 // ─── Settings ────────────────────────────────────────────────────────────────
@@ -111,6 +111,8 @@ export default function piOpenAgents(pi: ExtensionAPI): void {
         if (childName) return manager.getAgent(childName);
         return manager.getActive();
       },
+      // #8: restrictive rules handed down by the delegating parent (env JSON).
+      inheritedRules: () => parentInheritedRules(process.env),
     });
 
     // Subagent child processes are fully configured by the executor via CLI flags
@@ -131,9 +133,11 @@ export default function piOpenAgents(pi: ExtensionAPI): void {
       return;
     }
 
-    // Check for --agent CLI flag first (highest priority)
+    // Check for --agent CLI flag first (highest priority at startup).
+    // Skipped on reload: the flag is a startup default — a mid-session agent
+    // switch must survive /reload, so the session entry below wins instead.
     const agentFlag = pi.getFlag("agent");
-    if (typeof agentFlag === "string" && agentFlag) {
+    if (typeof agentFlag === "string" && agentFlag && event.reason !== "reload") {
       const agent = manager.getAgent(agentFlag);
       if (agent) {
         await manager.apply(agentFlag, pi, ctx);
@@ -142,8 +146,9 @@ export default function piOpenAgents(pi: ExtensionAPI): void {
       return;
     }
 
-    // Try to restore from session state (if resuming)
-    if (event.reason === "resume" || event.reason === "fork") {
+    // Restore from session state (resume, fork, or /reload — all must keep
+    // the agent the session was actually using, not re-apply startup defaults)
+    if (event.reason === "resume" || event.reason === "fork" || event.reason === "reload") {
       const entries = ctx.sessionManager.getEntries();
       const agentEntry = entries
         .filter((e: { type: string; customType?: string }) =>

package/src/permission/gate.ts

@@ -140,22 +140,32 @@ export interface PermissionGateOptions {
   resolveAgent: () => AgentDefinition | undefined;
   /** Session-scoped "always allow" memo (per process). Injectable for tests. */
   alwaysAllow?: Map<string, boolean>;
+  /**
+   * Rules inherited from the delegating parent (#8). Appended AFTER the
+   * agent's own rules — last-match-wins, so an inherited deny/ask always
+   * beats the child's own allow for the same call (authority ceiling).
+   */
+  inheritedRules?: () => PermissionRule[];
 }
 
 /**
  * Register the permission gate on the `tool_call` event.
  *
- * Does nothing for agents without permission rules.
+ * Does nothing when neither the agent nor the chain contributes rules.
  */
 export function registerPermissionGate(pi: ExtensionAPI, options: PermissionGateOptions): void {
   const alwaysAllow = options.alwaysAllow ?? new Map<string, boolean>();
 
   pi.on("tool_call", async (event, ctx: ExtensionContext) => {
     const agent = options.resolveAgent();
-    if (!agent?.permission) return undefined;
+    const ownRules = agent?.permission ? parsePermissionRules(agent.permission) : [];
+    const inherited = options.inheritedRules?.() ?? [];
+    if (ownRules.length === 0 && inherited.length === 0) return undefined;
 
     const input = (event as { input?: Record<string, unknown> }).input ?? {};
-    const rules = parsePermissionRules(agent.permission);
+    // Parent rules last: last-match-wins makes an inherited deny/ask beat
+    // the child's own allow — the authority ceiling cannot be widened (#8).
+    const rules = [...ownRules, ...inherited];
     const decision = decideToolCall(event.toolName, input, rules);
 
     if (!decision.gated || decision.action === "allow") return undefined;

package/src/primary/manager.ts

@@ -5,11 +5,28 @@
  * and coordinates with the executor for model/thinking/tools/prompt.
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentDefinition, ThinkingLevel } from "../types.ts";
 import { applyAgentConfig } from "./executor.ts";
 
+/**
+ * Warn when an agent that will act as PRIMARY declares `skills:`.
+ *
+ * `skills:` is honored only for subagent children (the executor injects them
+ * into the child's system prompt). pi loads session skills at startup and
+ * exposes no per-agent filter, so a primary cannot role-scope them — warn
+ * instead of silently ignoring (#19).
+ */
+export function warnAgentSkillsPrimary(agent: AgentDefinition | undefined, ui: ExtensionUIContext): void {
+  if (agent?.skills && agent.skills.length > 0 && agent.mode !== "subagent") {
+    ui.notify(
+      `Agent "${agent.name}": skills: (${agent.skills.join(", ")}) applies to subagent delegation only — primaries use pi's session-wide skill set (#19)`,
+      "warning",
+    );
+  }
+}
+
 interface OriginalState {
   model: Model<any> | undefined;
   thinkingLevel: ThinkingLevel;
@@ -56,6 +73,8 @@ export class AgentManager {
     const agent = this.agents.get(name);
     if (!agent) return false;
 
+    warnAgentSkillsPrimary(agent, ctx.ui);
+
     // Snapshot state on first apply (for restore on clear)
     if (this.activeName === undefined) {
       this.originalState = {

package/src/subagent/env.ts

@@ -19,6 +19,7 @@ export type RecursionEnv = Partial<
     | "PI_OPEN_AGENTS_SYSTEM_PROMPT_MODE"
     | "PI_OPEN_AGENTS_ALLOWED"
     | "PI_OPEN_AGENTS_SESSION"
+    | "PI_OPEN_AGENTS_PARENT_RULES"
     | "PI_OPEN_AGENTS_DEBUG",
     string
   >
@@ -65,6 +66,35 @@ export function isSubagentProcess(env: RecursionEnv): boolean {
   return depth !== undefined && depth > 0;
 }
 
+/**
+ * Get the parent's inherited deny/ask rules from env (issue #8).
+ *
+ * The delegating parent serializes the restrictive subset of its permission
+ * rules (deny/ask, pattern-level included) as JSON. The child's permission
+ * gate appends them after its own rules (last-match-wins → parent wins).
+ * Malformed or absent → no inheritance (empty list).
+ */
+export function parentInheritedRules(
+  env: RecursionEnv,
+): Array<{ permission: string; pattern: string; action: "deny" | "ask" }> {
+  const raw = env?.PI_OPEN_AGENTS_PARENT_RULES;
+  if (!raw) return [];
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(
+      (r): r is { permission: string; pattern: string; action: "deny" | "ask" } =>
+        typeof r === "object" &&
+        r !== null &&
+        typeof (r as any).permission === "string" &&
+        typeof (r as any).pattern === "string" &&
+        ((r as any).action === "deny" || (r as any).action === "ask"),
+    );
+  } catch {
+    return [];
+  }
+}
+
 /**
  * Get the system prompt mode from env.
  */
@@ -91,6 +121,7 @@ export interface SubagentEnvVars {
   systemPromptMode: SystemPromptMode;
   session: "none" | "fork";
   allowedAgents?: string[];
+  parentRules?: string;
   debug: boolean;
 }
 
@@ -111,5 +142,9 @@ export function buildSubagentEnv(vars: SubagentEnvVars): Record<string, string>
     env.PI_OPEN_AGENTS_ALLOWED = vars.allowedAgents.join(",");
   }
 
+  if (vars.parentRules) {
+    env.PI_OPEN_AGENTS_PARENT_RULES = vars.parentRules;
+  }
+
   return env;
 }

package/src/subagent/executor.ts

@@ -116,6 +116,17 @@ export interface RunSubagentOptions {
   session?: SubagentSessionInfo;
   /** Per-call model override ("provider/model-id"). Takes precedence over agent.model. */
   modelOverride?: string;
+  /**
+   * Parent's effective tool authority at delegation time (issue #8).
+   * The child's representable toolset is intersected with it; the result
+   * travels to the grandchild through pi's own active set (CLI ceiling),
+   * so authority can only shrink along the delegation chain.
+   * Undefined = no ceiling (unrestricted parent or host without
+   * getActiveTools). Empty array = hard zero-tool ceiling.
+   */
+  parentCeiling?: string[];
+  /** Parent's restrictive (deny/ask) permission rules, inherited into the child's gate via env. */
+  parentRules?: Array<{ permission: string; pattern: string; action: "deny" | "ask" }>;
   resolvePi?: () => Promise<PiResolution> | PiResolution;
   runner?: ProcessRunner;
   fs?: ExecutorFs;
@@ -185,6 +196,26 @@ function emptyUsage(): AgentUsage {
   return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0 };
 }
 
+/**
+ * Compose the child's `--tools` value under the parent ceiling (#8).
+ *
+ * - No ceiling → child's own whitelist as-is (undefined when unrestricted).
+ * - Ceiling + own whitelist → own ∩ ceiling, preserving own's order.
+ * - Ceiling only (child unrestricted) → the ceiling itself.
+ * - Empty result → "none": the caller must pass `--no-tools` — omitting
+ *   `--tools` would mean ALL tools and fail open.
+ */
+export function composeChildTools(
+  own: string[] | undefined,
+  ceiling: string[] | undefined,
+): string[] | "none" | undefined {
+  if (ceiling === undefined) return own && own.length > 0 ? own : undefined;
+  const base = own ?? ceiling;
+  const allowed = new Set(ceiling);
+  const result = base.filter((t) => allowed.has(t));
+  return result.length > 0 ? result : "none";
+}
+
 export function subagentSessionDir(
   cwd: string,
   agentDir = path.join(os.homedir(), ".pi", "agent"),
@@ -533,10 +564,12 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
     // Thinking level
     args.push("--thinking", options.agent.thinking);
 
-    // Tools whitelist
-    const toolsWhitelist = deriveToolsWhitelist(options.agent);
-    if (toolsWhitelist && toolsWhitelist.length > 0) {
-      args.push("--tools", toolsWhitelist.join(","));
+    // Tools whitelist, intersected with the parent's ceiling (#8)
+    const childTools = composeChildTools(deriveToolsWhitelist(options.agent), options.parentCeiling);
+    if (childTools === "none") {
+      args.push("--no-tools");
+    } else if (childTools) {
+      args.push("--tools", childTools.join(","));
     }
 
     // System prompt file (append or replace)
@@ -564,6 +597,9 @@ export async function runSubagent(options: RunSubagentOptions): Promise<AgentRes
       systemPromptMode: options.agent.systemPrompt,
       session: options.session?.effective ?? "none",
       allowedAgents: availableSubagentsForAgent(options.agent, options.availableAgents),
+      parentRules: options.parentRules && options.parentRules.length > 0
+        ? JSON.stringify(options.parentRules)
+        : undefined,
       debug: false,
     };
     const childEnv: NodeJS.ProcessEnv = {

package/src/subagent/tool.ts

@@ -21,8 +21,10 @@ import { getMarkdownTheme, keyHint } from "@earendil-works/pi-coding-agent";
 import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
-import type { AgentDefinition } from "../types.ts";
+import type { AgentDefinition, PermissionRule } from "../types.ts";
 import { spawnableAgents } from "../discovery/loader.ts";
+import { matchPermissionKey, toolToPermission } from "../permission/evaluator.ts";
+import { parsePermissionRules } from "../permission/parser.ts";
 import {
   availableSubagentsForAgent,
   resolveSubagentSession,
@@ -37,7 +39,12 @@ import {
   formatResultLines,
   formatUsage,
 } from "./render.ts";
-import { allowedAgentNames, isPastMaxDepth, type RecursionEnv } from "./env.ts";
+import {
+  allowedAgentNames,
+  isPastMaxDepth,
+  parentInheritedRules,
+  type RecursionEnv,
+} from "./env.ts";
 import { preview, shortenPath, stringArg } from "../utils/format.ts";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
@@ -78,6 +85,66 @@ function isValidModelSpec(spec: string): boolean {
   return slash > 0 && slash < spec.length - 1 && !/\s/.test(spec);
 }
 
+// ─── Permission Inheritance (#8) ─────────────────────────────────────────────
+
+type InheritedRule = { permission: string; pattern: string; action: "deny" | "ask" };
+
+function isRestrictive(
+  rule: PermissionRule,
+): rule is PermissionRule & { action: "deny" | "ask" } {
+  return rule.action === "deny" || rule.action === "ask";
+}
+
+/**
+ * Compute the parent's effective tool ceiling at delegation time (#8).
+ *
+ * Base = pi's live active set (the authority snapshot the child cannot
+ * exceed — and, in a child process, what the child's own delegates will
+ * see: the ceiling composes transitively down the chain). Tools the
+ * parent's own rules deny or ask over are REMOVED from the ceiling: `ask`
+ * is not authority — a headless child has no approval bridge, and an
+ * ask-only tool must not become a silently usable one down the chain.
+ *
+ * Returns undefined when the host exposes no active-set API (then no
+ * ceiling is applied and behavior matches pre-#8).
+ */
+export function computeDelegationCeiling(
+  activeTools: string[] | undefined,
+  rules: PermissionRule[],
+): string[] | undefined {
+  if (activeTools === undefined) return undefined;
+  const blanket = rules.filter(
+    (r) => r.pattern === "*" && (r.action === "deny" || r.action === "ask"),
+  );
+  return activeTools.filter((toolName) => {
+    const category = toolToPermission(toolName);
+    return !blanket.some((r) => matchPermissionKey(r.permission, category));
+  });
+}
+
+/**
+ * The restrictive rule set to hand to the child's gate (#8): the parent's
+ * own deny/ask rules PLUS rules inherited further up the chain (so
+ * patterns survive every hop). Deduped; later (own) entries win on overlap
+ * via last-match-wins — both are restrictive, so ordering only affects
+ * identical-pattern conflicts.
+ */
+export function composeInheritedRules(
+  own: PermissionRule[],
+  fromEnv: InheritedRule[],
+): InheritedRule[] {
+  const restrictiveOwn: InheritedRule[] = own.filter(isRestrictive);
+  const seen = new Set<string>();
+  const out: InheritedRule[] = [];
+  for (const rule of [...fromEnv, ...restrictiveOwn]) {
+    const key = `${rule.permission}\u0000${rule.pattern}\u0000${rule.action}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(rule);
+  }
+  return out;
+}
+
 function toToolResult(result: AgentResult) {
   return {
     content: [{ type: "text" as const, text: result.output || "(no output)" }],
@@ -270,6 +337,15 @@ export function registerSubagentTool(
         options.agentDir,
       );
 
+      // Permission inheritance (#8): snapshot the parent's live authority,
+      // strip blanket deny/ask tools, and carry restrictive patterns (own +
+      // inherited) into the child's gate via env.
+      const getActive = (pi as { getActiveTools?: () => string[] }).getActiveTools;
+      const activeTools = typeof getActive === "function" ? getActive.call(pi) : undefined;
+      const ownRules = activeAgent?.permission ? parsePermissionRules(activeAgent.permission) : [];
+      const parentCeiling = computeDelegationCeiling(activeTools, ownRules.filter(isRestrictive));
+      const parentRules = composeInheritedRules(ownRules, parentInheritedRules(env));
+
       const result = await runner({
         agent,
         task: params.task,
@@ -280,6 +356,8 @@ export function registerSubagentTool(
         agentDir: options.agentDir,
         session,
         modelOverride: params.model,
+        parentCeiling,
+        parentRules: parentRules.length > 0 ? parentRules : undefined,
         onProgress: (progress) => onUpdate?.(toProgressResult(progress)),
       });