pi-code 1.0.4 → 1.0.5

package/README.md

@@ -37,23 +37,27 @@ One `pi install` and everything below loads on the next start. `pi list` shows w
 
 | Feature | Reads / provides | Extension |
 |---|---|---|
-| Global + project rules | `~/.claude/rules`, `.claude/rules` (+ `paths:` frontmatter scoping) | `claude-rules.ts` |
-| Custom slash commands | `.claude/commands/**/*.md` (namespaced `/dir:name`), `$ARGUMENTS`/`$1`, `` !`cmd` `` bash output, `@file` inlining, `allowed-tools`/`argument-hint` frontmatter (`model` is parsed but not yet applied); project commands gated on approval | `commands.ts` |
+| Global + project rules | `~/.claude/rules`, `.claude/rules` (nearest at or above cwd); unscoped rules inlined in full, `paths:`-scoped rules surfaced as pointers and auto-attached (the rule body is appended to a read/edit/write result when a matching file is touched, once per rule per session) | `claude-rules.ts` |
+| Custom slash commands | `.claude/commands/**/*.md` (namespaced `/dir:name`); `$ARGUMENTS` (with the `ARGUMENTS:` append when unused), 0-based `$ARGUMENTS[N]`/`$N`, named `arguments:` frontmatter, `${CLAUDE_SESSION_ID}`/`${CLAUDE_EFFORT}`/`${CLAUDE_SKILL_DIR}`/`${CLAUDE_PROJECT_DIR}` (in bodies and `allowed-tools` rules); `` !`cmd` `` and multi-line ```` ```! ```` bash (whitespace-bounded, merged stderr, 2-minute budget, a failure aborts the invocation with the documented exit-1 carveout), `@file` inlining; `allowed-tools` with `Bash(...)` and `Read`/`Edit`/`Write` path scopes enforced at call time (gitignore anchors, Edit governs writes), `disallowed-tools`, `argument-hint`, `model` (switches the session model for the command's turn, restored after), `shell: powershell` (runs the command's injected spans through PowerShell when a pwsh binary is present, else falls back to /bin/sh); `disable-model-invocation` is parsed but not applied; project commands gated on approval | `commands.ts` |
+| `/init` | generates a project context file: detects an existing `AGENTS.md`/`CLAUDE.md` (proposes improvements) or none (creates `AGENTS.md`, pi's preferred name), ingesting `.cursor/rules`, `.cursorrules`, and `.github/copilot-instructions.md` when present; drives the main agent with full tools via a prompt (not a tool-less completion) so it analyzes the codebase and writes the file itself | `init.ts` |
 | Skills | `.claude/skills` → pi skill discovery, project skills gated on approval (pi reads `name`, `description`, `disable-model-invocation`; `allowed-tools` is inert in pi's loader) | `skills.ts` |
-| Hooks | `.claude/settings.json` hooks: PreToolUse (blocks, rewrites input via `updatedInput`), PostToolUse (feedback and `additionalContext` land next to the tool result), PostToolUseFailure, SessionStart (context injection), UserPromptSubmit (blocks and injects context), Stop (a block continues the conversation), SubagentStart/SubagentStop, PreCompact, PostCompact, SessionEnd; Claude matcher semantics incl. `mcp__server__tool` names; payloads carry session_id, transcript_path, cwd, permission_mode, effort | `hooks.ts` |
-| Output styles | `.claude/output-styles` + active `outputStyle`; Claude replace semantics with `keep-coding-instructions`; bundled Explanatory/Learning/Proactive; `/output-style [name]` | `output-styles.ts` |
-| CLAUDE.md `@imports` | resolves `@path` imports pi's native loader skips; loads `CLAUDE.local.md` (approval-gated) | `context-imports.ts` |
-| MCP servers | user `~/.claude.json` (incl. per-project `projects[cwd]` local scope), `~/.pi/agent/mcp.json`; project `.mcp.json`, `.pi/mcp.json` (once approved; `enabledMcpjsonServers`/`disabledMcpjsonServers`/`enableAllProjectMcpServers` honored, consent keys only from non-repo settings); stdio/HTTP/SSE by `type`; `${VAR:-default}` expansion; `MCP_TIMEOUT`/`MCP_TOOL_TIMEOUT`; tools refresh on `list_changed` | `mcp.ts` |
+| Hooks | `.claude/settings.json` hooks: PreToolUse (blocks, rewrites input via `updatedInput`), PostToolUse (feedback and `additionalContext` land next to the tool result), PostToolUseFailure, SessionStart (context injection), UserPromptSubmit (blocks and injects context), Stop (a block continues the conversation), SubagentStart/SubagentStop, PreCompact, PostCompact, SessionEnd, Notification (idle_prompt, the type pi can source), InstructionsLoaded (observational: fires per loaded context file at session start, plus `path_glob_match` on a scoped-rule attach and `include` per resolved `@import`; deduped per session; `nested_traversal`/`compact` reasons never fire since pi does not lazily load nested CLAUDE.md or reload after compaction); `type: http` entries POST the payload (a 2xx JSON body renders the decision, everything else is non-blocking per Claude's contract), `type: prompt` evaluates in-process against the session model, `type: mcp_tool` calls a connected server's tool, and `type: agent` (experimental) spawns a read-only Read/Grep/Glob subagent that returns the JSON decision (a missing model/server/runner is non-blocking, only a PreToolUse timeout fails closed); Claude matcher semantics incl. `mcp__server__tool` names; payloads carry session_id, transcript_path, cwd, permission_mode, effort; `permissionDecision: "ask"` prompts via a confirm dialog (blocks when headless), SubagentStop/PostToolUseFailure are notify-only, and a timed-out PreToolUse/UserPromptSubmit hook fails closed at a 60s default (Claude: 600s, non-blocking) since pi has no permission backstop | `hooks.ts` |
+| Output styles | `.claude/output-styles` + active `outputStyle`; plus styles shipped by enabled plugins (manifest `outputStyles`, default `output-styles/`, ranked below the user's and project's own); Claude replace semantics with `keep-coding-instructions`; bundled Explanatory/Learning/Proactive; `/output-style [name]` | `output-styles.ts` |
+| CLAUDE.md `@imports` and rewriting | resolves `@path` imports pi's native loader skips (4-hop depth, budget-capped); loads every `CLAUDE.local.md` from the repo root down to cwd (approval-gated, root first); injects managed `claudeMd` from `managed-settings.json` at the top of context; honors `claudeMdExcludes` (glob/absolute-path skip list from user, approved-project, and managed settings, merged; managed content never excluded); strips block-level HTML comments from CLAUDE.md, rule, and imported bodies (fenced-code comments preserved), so a commented-out `@import` does not expand; with `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` set, loads `CLAUDE.md`/`.claude/CLAUDE.md`/`.claude/rules/*.md`/`CLAUDE.local.md` from each `--add-dir` directory (comma-separated for several, since pi's flag is single-value) | `context-imports.ts` |
+| MCP servers | user `~/.claude.json` (incl. per-project `projects[cwd]` local scope), `~/.pi/agent/mcp.json`; project `.mcp.json`, `.pi/mcp.json` (once approved; `enabledMcpjsonServers`/`disabledMcpjsonServers`/`enableAllProjectMcpServers` honored, consent keys only from non-repo settings); stdio/HTTP/SSE/WebSocket by `type` (WebSocket is url-only: any `headers`/`bearerToken`/`headersHelper` on a ws server is ignored with a warning); `${VAR:-default}` expansion; a `headersHelper` command whose stdout JSON merges into the transport headers (http/sse); managed `allowedMcpServers`/`deniedMcpServers` read from `managed-settings.json` only (`{serverName}` entries, applied globally across scopes, allow list exclusive with an empty array = lockdown, deny wins); `MCP_TIMEOUT`/`MCP_TOOL_TIMEOUT`; tools refresh on `list_changed`; bearer tokens, or OAuth for remote servers (browser login on 401 after a confirm, tokens under `~/.pi/agent/mcp-oauth`, silent refresh later) | `mcp.ts` |
 | Project trust | prompts before loading project config (MCP servers, hooks, agents, rules, output styles, commands, skills) that pi would otherwise trust silently | `internal/project-approval.ts` |
-| Subagents / Task | builtin Explore/Plan/general-purpose agents, `~/.claude/agents` and `~/.pi/agent/agents`, plus project `.claude/agents` and `.pi/agents`; agent roster with descriptions in the system prompt; `skills` preload; background runs with cancel and resume | `subagent/` |
+| Subagents / Task | builtin Explore/Plan/general-purpose agents, `~/.claude/agents` and `~/.pi/agent/agents`, plus project `.claude/agents` and `.pi/agents` (scanned recursively into subfolders) merged by default once the project is trusted (project wins on a name clash); frontmatter `tools`/`disallowedTools`/`model` (sonnet/opus/haiku/fable tier aliases or a concrete id)/`effort`/`skills` preload/`permissionMode: plan`/`maxTurns`/`memory` (`user`/`project`/`local` give the child its own persistent store under `.claude/agent-memory[-local]`, injected with Read/Write/Edit enabled, gated on auto memory; the parent conversation's memory is never loaded into a subagent, matching Claude); parallel and chain modes (pi extensions), one nesting level; background runs with cancel and resume | `subagent/` |
 | Plan mode | `plan_mode_complete` tool, tool snapshot/restore that survives `/reload` | `plan-mode/` |
 | Todo list | persistent overlay, status machine, compaction-safe | `todo.ts` |
 | Checkpoints / rewind | shadow-repo snapshots; restore overwrites checkpointed files, keeps files created later; 100 per session, repos pruned after 30 days | `git-checkpoint.ts` |
-| Persistent memory | per-project memories, index injected each session within Claude's 200-line/25KB bound; a save that would overflow it reports why | `memory.ts` |
-| WebSearch / WebFetch | key-free DuckDuckGo search, SSRF-guarded fetch | `web.ts` |
-| AskUserQuestion | 1-4 questions per call (asked in sequence), each with `header`, single- or `multiSelect` options, plus free-text | `question.ts` |
-| Statusline | Claude `statusLine` command contract (stdin JSON, `padding`, `refreshInterval`); built-in turn state + session cost fallback | `status-line.ts` |
-| Notifications | vendored example | `notify.ts` |
+| Persistent memory | per-repo memories under `~/.pi/agent/memory` keyed on the repository root (subdirectory sessions share one store, as Claude does; pi's own store, separate from Claude's), index injected each session within Claude's 200-line/25KB bound (YAML frontmatter and block HTML comments stripped before it counts or loads); a save that would overflow it reports why; a memory written with frontmatter gets a `modified:` ISO timestamp; honors `autoMemoryEnabled` (settings) and `CLAUDE_CODE_DISABLE_AUTO_MEMORY` (env) to turn it off, and `autoMemoryDirectory` (absolute or `~/`) to relocate the store | `memory.ts` |
+| WebSearch / WebFetch | key-free DuckDuckGo search (with `allowed_domains`/`blocked_domains`); SSRF-guarded fetch that prefers markdown via `Accept` then converts HTML, with Claude's 15-minute per-URL cache and an optional `prompt` that runs the page through the model in-process and returns the answer (falls back to markdown when headless or on error) | `web.ts` |
+| AskUserQuestion | 1-4 questions per call (asked in sequence), each with `header` and 2-4 options, single- or `multiSelect`, plus free-text | `question.ts` |
+| Statusline | Claude `statusLine` command contract (stdin JSON incl. `version`, `hook_event_name`, `session_name`, cost durations and line counters, context percentages; `padding`, `refreshInterval`, 300ms debounce); built-in turn state + session cost fallback | `status-line.ts` |
+| Notifications | terminal notification when a turn ends (OSC 777 / Kitty OSC 99 / Windows toast); honors `preferredNotifChannel` (`terminal_bell`, `notifications_disabled`, `iterm2_with_bell`, else desktop) from user settings; fires only when you "appear to be away" (approximated by turn duration, since pi exposes no terminal-focus signal) | `notify.ts` |
+| Claude plugins | installed marketplace plugins (`~/.claude/plugins/cache`), active per `enabledPlugins` in user settings only (a checked-out repo cannot flip which code-bearing plugins run, so project settings never toggle them): commands as `/plugin:name`, agents, hooks and MCP servers (tools aliased `mcp__plugin_<plugin>_<server>__<tool>`) and output styles with `${CLAUDE_PLUGIN_ROOT}`/`${CLAUDE_PLUGIN_DATA}` and `${user_config.KEY}` (from `pluginConfigs[id].options` in user settings) substituted; skill dirs contribute too, though pi's loader names them without the plugin prefix | `internal/plugins.ts` |
+
+pi has no general permission system, so most of what Claude routes through a permission prompt maps to hard behavior here: `allowed-tools` restricts the turn's tool set instead of pre-approving calls, and a hook that times out on PreToolUse or UserPromptSubmit fails closed. A hook's `permissionDecision: "ask"` is the exception: it shows a confirm dialog and lets the call through when you approve (a headless run has no dialog, so it blocks). Where a Claude restriction cannot be expressed at all (an argument-scoped grant in an agent's `tools:`), the definition is rejected rather than widened.
 
 `CLAUDE.md` itself needs no extension: pi loads `CLAUDE.md` / `AGENTS.md` context files natively (global + walking cwd to root). `context-imports.ts` only adds the `@import` resolution pi's loader lacks, appending the imported files without re-injecting the base.
 
@@ -71,4 +75,12 @@ scripts/e2e-full.sh     # every README feature end to end, model turns included
 scripts/record-demos.sh # re-records demos/*.tape with vhs at low thinking
 ```
 
-Extensions live in `extensions/`, tests in `tests/`. Install a local checkout with `pi install ./pi-code`, then `/reload` after edits.
+Extensions live in `extensions/`, tests in `tests/`. Install a local checkout with `pi install ./pi-code`, then `/reload` after edits. Development needs Node `>=22.19`.
+
+## Contributing
+
+Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, the test and review conventions, and the release process, and the [Code of Conduct](CODE_OF_CONDUCT.md) for community expectations. Report security issues privately as described in [SECURITY.md](SECURITY.md). Release notes are on the [Releases page](https://github.com/ilovepixelart/pi-code/releases).
+
+## License
+
+[MIT](LICENSE).

package/extensions/claude-rules.ts

@@ -2,14 +2,16 @@
  * Claude Rules Extension
  *
  * Replicates Claude Code's rules loading:
- * - Unscoped global rules (~/.claude/rules/*.md) are inlined in full into the system prompt.
- * - Path-scoped global rules and all project rules (.claude/rules/*.md) are listed as
- *   pointers the agent reads on demand.
- *
- * Path-scoped rules: a rule file may declare `paths:` frontmatter (a glob or
- * list of globs). Pointers surface that scope so the agent knows to read the
- * rule when working on matching files. Frontmatter is stripped from inlined
- * global rules.
+ * - Unscoped rules are inlined in full into the system prompt, global
+ *   (~/.claude/rules/*.md) and approved-project (.claude/rules/*.md) alike:
+ *   Claude loads rules without `paths:` frontmatter at launch with the same
+ *   priority as .claude/CLAUDE.md.
+ * - Path-scoped rules auto-attach: a rule file may declare `paths:` frontmatter
+ *   (a glob or list of globs). Its scope is surfaced upfront as a pointer, and
+ *   when a read/edit/write touches a file the globs cover, the rule body is
+ *   appended to that tool's result, once per rule per session. This mirrors
+ *   Claude Code, which attaches a scoped rule when a matching file is touched
+ *   rather than inlining it everywhere. Frontmatter is stripped from rule text.
  *
  * Adapted from the pi v0.74.2 claude-rules example.
  */
@@ -19,7 +21,11 @@ import * as os from 'node:os'
 import * as path from 'node:path'
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 
+import { publishInstructionLoad } from './internal/instruction-events.js'
+import { globToRegExpSource } from './internal/path-rules.js'
 import { isProjectApproved } from './internal/project-approval.js'
+import { findNearestDir } from './internal/project-root.js'
+import { stripBlockComments } from './internal/strip-comments.js'
 
 export interface Frontmatter {
   paths: string[]
@@ -64,6 +70,32 @@ export function parseFrontmatter(content: string): Frontmatter {
   return { paths: parsePaths(match[1]), body: content.slice(match[0].length) }
 }
 
+/**
+ * Whether a file path matches at least one of a rule's `paths:` globs. `*` stays in
+ * a segment, `**` crosses directories, a slashless pattern (`*.ts`) matches the
+ * basename at any depth (gitignore-style), and a trailing slash (`docs/`) scopes to
+ * that directory's contents. `./` and a leading `/` are stripped so a project-root
+ * anchored glob resolves the same as a bare one. A bare directory name without a
+ * trailing slash or `**` matches a file of that name, not the directory's contents;
+ * write `dir/**` to scope to a directory. `relPath` is the touched file relative to
+ * the rule set's root.
+ */
+export function pathMatchesGlobs(relPath: string, globs: string[]): boolean {
+  const posix = relPath.split(path.sep).join('/')
+  const base = posix.split('/').pop() ?? posix
+  return globs.some((raw) => {
+    let glob = raw.trim()
+    if (!glob) return false
+    if (glob.startsWith('./')) glob = glob.slice(2)
+    else if (glob.startsWith('/')) glob = glob.slice(1)
+    // A trailing slash means the directory's contents, like gitignore; `docs/` alone
+    // would compile to `^docs/$` and match nothing.
+    if (glob.endsWith('/')) glob += '**'
+    const target = glob.includes('/') ? posix : base
+    return new RegExp(`^${globToRegExpSource(glob)}$`).test(target)
+  })
+}
+
 /** A rule pointer line, annotated with its path scope when present. */
 export function formatRulePointer(rel: string, paths: string[], base = '.claude/rules'): string {
   const ref = `- ${base}/${rel}`
@@ -112,83 +144,155 @@ function findMarkdownFiles(dir: string, basePath = '', visited = new Set<string>
   return results
 }
 
-interface ProjectRule {
+interface ScopedRule {
   rel: string
   paths: string[]
+  /** The rule text, attached when a matching file is touched. */
+  body: string
 }
 
-interface GlobalRules {
-  inline: string
-  scoped: ProjectRule[]
+interface RuleSet {
+  inline: string[]
+  scoped: ScopedRule[]
 }
 
-/** Unscoped global rules are inlined; path-scoped ones keep their scope as pointers,
+const EMPTY_RULES: RuleSet = { inline: [], scoped: [] }
+
+/** Unscoped rules are inlined; path-scoped ones keep their scope as pointers,
  * mirroring Claude Code, where scoped rules attach only to matching files. */
-function readGlobalRules(globalRulesDir: string): GlobalRules {
+function readRules(rulesDir: string): RuleSet {
   const inline: string[] = []
-  const scoped: ProjectRule[] = []
-  for (const file of findMarkdownFiles(globalRulesDir)) {
+  const scoped: ScopedRule[] = []
+  for (const file of findMarkdownFiles(rulesDir)) {
     let parsed: Frontmatter
     try {
-      parsed = parseFrontmatter(fs.readFileSync(path.join(globalRulesDir, file), 'utf-8'))
+      parsed = parseFrontmatter(fs.readFileSync(path.join(rulesDir, file), 'utf-8'))
     } catch {
       continue // one unreadable rule must not take down session start
     }
-    if (parsed.paths.length > 0) scoped.push({ rel: file, paths: parsed.paths })
-    else if (parsed.body.trim().length > 0) inline.push(parsed.body.trim())
+    // Rule bodies get the same block-level comment strip as CLAUDE.md files
+    // before they reach the prompt or attach to a tool result.
+    const body = stripBlockComments(parsed.body).trim()
+    // A body that strips to nothing has nothing to inline or attach; attaching
+    // an empty text block to a tool result is rejected by the API when the
+    // result's content is a block array (image-bearing results).
+    if (body.length === 0) continue
+    if (parsed.paths.length > 0) scoped.push({ rel: file, paths: parsed.paths, body })
+    else inline.push(body)
   }
-  return { inline: inline.join('\n\n'), scoped }
+  return { inline, scoped }
 }
 
-function readProjectRules(projectRulesDir: string): ProjectRule[] {
-  return findMarkdownFiles(projectRulesDir).map((rel) => {
-    try {
-      return { rel, paths: parseFrontmatter(fs.readFileSync(path.join(projectRulesDir, rel), 'utf-8')).paths }
-    } catch {
-      return { rel, paths: [] }
-    }
-  })
+/** The system-prompt section for one rule set: inlined bodies, then scoped pointers. */
+function rulesSection(title: string, rules: RuleSet, base: string): string {
+  if (rules.inline.length === 0 && rules.scoped.length === 0) return ''
+  let section = `\n\n## ${title}`
+  if (rules.inline.length > 0) {
+    section += `\n\nThese rules always apply:\n\n${rules.inline.join('\n\n')}`
+  }
+  if (rules.scoped.length > 0) {
+    const scopedList = rules.scoped.map((rule) => formatRulePointer(rule.rel, rule.paths, base)).join('\n')
+    section += `\n\nPath-scoped rules, available in ${base}/:\n\n${scopedList}\n\nRead the relevant rule file with the read tool before working on the files it covers.`
+  }
+  return section
+}
+
+/** A scoped rule resolved to the root its globs match against, ready to attach. */
+interface AttachTarget {
+  key: string
+  globs: string[]
+  body: string
+  /** The absolute directory `paths:` globs are matched relative to. */
+  root: string
+  /** The rule file's absolute path, reported on the instruction-events bus. */
+  file: string
+  /** Claude's memory_type for the rule's origin: global rules are User config. */
+  memoryType: 'User' | 'Project'
 }
 
 export default function claudeRulesExtension(pi: ExtensionAPI) {
   const globalRulesDir = path.join(os.homedir(), '.claude', 'rules')
-  let globalRules: GlobalRules = { inline: '', scoped: [] }
-  let projectRules: ProjectRule[] = []
+  let globalRules: RuleSet = EMPTY_RULES
+  let projectRules: RuleSet = EMPTY_RULES
+  // The base a scoped-rule pointer is written against, so the model's read resolves.
+  // The project rules dir may sit at an ancestor of cwd, where a cwd-relative
+  // '.claude/rules' would point the read at a path that does not exist.
+  let projectRulesBase = '.claude/rules'
+  // Scoped rules ready to attach when a matching file is touched, and the set of
+  // rules already attached this session so each attaches at most once.
+  let attachTargets: AttachTarget[] = []
+  const attached = new Set<string>()
 
   pi.on('session_start', async (_event, ctx) => {
-    globalRules = readGlobalRules(globalRulesDir)
-    // Project rule filenames and their paths: frontmatter are surfaced in the system prompt.
-    // isProjectTrusted alone is true for a repo pi never asked about; see project-approval.
+    globalRules = readRules(globalRulesDir)
+    // Project rules are repository text landing in the system prompt, so they load
+    // only once the project is approved. isProjectTrusted alone is true for a repo
+    // pi never asked about; see project-approval.
     const approved = await isProjectApproved(ctx)
-    projectRules = approved ? readProjectRules(path.join(ctx.cwd, '.claude', 'rules')) : []
+    // Nearest at-or-above cwd, so a subdirectory session still reads the rules the
+    // approval walk gated on.
+    const projectRulesDir = approved ? findNearestDir(ctx.cwd, path.join('.claude', 'rules')) : null
+    projectRules = projectRulesDir ? readRules(projectRulesDir) : EMPTY_RULES
+
+    // Global globs are relative to cwd; project globs to the project root (the dir
+    // holding .claude), so `db/**` in a repo rule matches repo-relative paths even
+    // from a subdirectory session. Reset per session so a re-run re-attaches.
+    attached.clear()
+    const projectRoot = projectRulesDir ? path.dirname(path.dirname(projectRulesDir)) : ctx.cwd
+    attachTargets = [
+      ...globalRules.scoped.map((rule) => ({ key: `global:${rule.rel}`, globs: rule.paths, body: rule.body, root: ctx.cwd, file: path.join(globalRulesDir, rule.rel), memoryType: 'User' as const })),
+      ...projectRules.scoped.map((rule) => ({ key: `project:${rule.rel}`, globs: rule.paths, body: rule.body, root: projectRoot, file: path.join(projectRulesDir ?? path.join(ctx.cwd, '.claude', 'rules'), rule.rel), memoryType: 'Project' as const })),
+    ]
+    // Relative to cwd, which the read tool resolves: an ancestor dir yields a
+    // `../…/.claude/rules` the model can follow, where a bare '.claude/rules'
+    // would point at a nonexistent path under the subdirectory.
+    projectRulesBase = projectRulesDir === null ? '.claude/rules' : path.relative(ctx.cwd, projectRulesDir) || '.claude/rules'
 
     const hasGlobal = globalRules.inline.length > 0 || globalRules.scoped.length > 0
-    if (hasGlobal || projectRules.length > 0) {
-      ctx.ui.notify(`Rules loaded: global ${hasGlobal ? 'yes' : 'no'}, project ${projectRules.length}`, 'info')
+    const projectCount = projectRules.inline.length + projectRules.scoped.length
+    if (hasGlobal || projectCount > 0) {
+      ctx.ui.notify(`Rules loaded: global ${hasGlobal ? 'yes' : 'no'}, project ${projectCount}`, 'info')
     }
   })
 
   pi.on('before_agent_start', async (event) => {
-    let addition = ''
-
-    if (globalRules.inline.length > 0 || globalRules.scoped.length > 0) {
-      addition += `\n\n## Global Rules`
-      if (globalRules.inline.length > 0) {
-        addition += `\n\nThese rules always apply:\n\n${globalRules.inline}`
-      }
-      if (globalRules.scoped.length > 0) {
-        const scopedList = globalRules.scoped.map((rule) => formatRulePointer(rule.rel, rule.paths, '~/.claude/rules')).join('\n')
-        addition += `\n\nPath-scoped global rules, available in ~/.claude/rules/:\n\n${scopedList}\n\nRead the relevant rule file with the read tool before working on the files it covers.`
-      }
-    }
-
-    if (projectRules.length > 0) {
-      const rulesList = projectRules.map((rule) => formatRulePointer(rule.rel, rule.paths)).join('\n')
-      addition += `\n\n## Project Rules\n\nThe following project rules are available in .claude/rules/:\n\n${rulesList}\n\nRead the relevant rule file with the read tool before working on the files it covers; rules with an "applies when" scope are path-scoped.`
-    }
-
+    // Global first: Claude loads user-level rules before project rules, so project
+    // rules read later and take priority.
+    const addition = rulesSection('Global Rules', globalRules, '~/.claude/rules') + rulesSection('Project Rules', projectRules, projectRulesBase)
     if (addition.length === 0) return
 
     return { systemPrompt: event.systemPrompt + addition }
   })
+
+  // Lazy attach: when a file tool touches a path a scoped rule covers, append the
+  // rule body to that tool's result so it enters context, once per rule per session.
+  // This mirrors Claude Code, which attaches a scoped rule when a matching file is
+  // read or edited rather than inlining it upfront.
+  pi.on('tool_result', async (event, ctx) => {
+    if (attachTargets.length === 0) return
+    if (event.isError) return
+    if (event.toolName !== 'read' && event.toolName !== 'edit' && event.toolName !== 'write') return
+    const rel = (event.input as { path?: unknown } | undefined)?.path
+    if (typeof rel !== 'string' || rel.length === 0) return
+    const abs = path.resolve(ctx.cwd, rel)
+
+    const bodies: string[] = []
+    for (const target of attachTargets) {
+      if (attached.has(target.key)) continue
+      const relativeToRoot = path.relative(target.root, abs)
+      // A file outside the rule root cannot match its project-relative globs. Test for
+      // a real parent-traversal segment, not a leading '..' (a file named `..config` is
+      // inside the root).
+      if (relativeToRoot === '..' || relativeToRoot.startsWith(`..${path.sep}`) || path.isAbsolute(relativeToRoot)) continue
+      if (!pathMatchesGlobs(relativeToRoot, target.globs)) continue
+      attached.add(target.key)
+      bodies.push(target.body)
+      // The lazy attach is Claude's path_glob_match instruction load; the hooks
+      // extension bridges the bus event to the InstructionsLoaded hook. The
+      // once-per-session attach set above also bounds the events to one per rule.
+      publishInstructionLoad(pi.events, { file_path: target.file, memory_type: target.memoryType, load_reason: 'path_glob_match', globs: target.globs, trigger_file_path: abs })
+    }
+    if (bodies.length === 0) return
+    return { content: [...event.content, ...bodies.map((text) => ({ type: 'text' as const, text }))] }
+  })
 }

package/extensions/commands.ts

@@ -6,10 +6,11 @@
  * is what makes the rest of Claude's command contract reachable: namespaced
  * subdirectories (`frontend/build.md` is `/frontend:build`), `$ARGUMENTS` and
  * positional substitution, `` !`cmd` `` bash output, `@file` inlining, and the
- * `allowed-tools` and `argument-hint` frontmatter. `model` and
- * `disable-model-invocation` are parsed but not applied yet: pi has seams for both
- * (`pi.setModel`, and commands are user-invoked anyway), so they are a gap rather
- * than an impossibility.
+ * `allowed-tools`, `argument-hint` and `model` frontmatter (`model` switches the
+ * session model for the command's turn via `pi.setModel`, restored on turn_end).
+ * `shell: powershell` runs a command's injected spans through PowerShell when a
+ * pwsh binary is installed, falling back to /bin/sh so the command still works
+ * without one. `disable-model-invocation` is parsed but not applied yet.
  *
  * A project command body is repository-controlled text that can now run shell
  * commands and read files, so project commands load only once the project is
@@ -24,11 +25,52 @@ import * as os from 'node:os'
 import * as path from 'node:path'
 import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent'
 
-import { type DiscoveredCommand, discoverCommandFiles, expandDynamicContent, type ParsedCommand, parseCommandFile, substituteArgs } from './internal/command-file.js'
+import { matchesBashRules } from './internal/bash-rules.js'
+import { type DiscoveredCommand, discoverCommandFiles, expandDynamicContent, type ParsedCommand, parseCommandFile, resolvePowershellBinary, spanExec, substituteArgsDetailed, substituteVars } from './internal/command-file.js'
+import { matchesPathRules } from './internal/path-rules.js'
+import { type InstalledPlugin, installedPlugins } from './internal/plugins.js'
 import { isProjectApproved } from './internal/project-approval.js'
+import { findNearestDir, repoRoot } from './internal/project-root.js'
 
-/** Wall-clock budget for one `` !`cmd` `` span; a hung command must not wedge a turn. */
-const BASH_TIMEOUT_MS = 30_000
+type PathRuleTool = 'read' | 'edit' | 'write'
+
+/** Just enough of pi's Model to match and restore; getAvailable returns these. */
+interface ModelLike {
+  id: string
+  name?: string
+}
+
+/** Resolve a command's `model:` frontmatter to an available model. Claude accepts a
+ * tier alias (sonnet/opus/haiku/fable), a concrete id, or `inherit`; pi matches by
+ * exact id first, then a substring of the id or name (the same fuzzy rule the
+ * subagent uses). `inherit` and an unresolvable name leave the model unchanged. */
+function resolveCommandModel(model: string | undefined, available: ReadonlyArray<ModelLike>): ModelLike | undefined {
+  if (!model || model.toLowerCase() === 'inherit') return undefined
+  const needle = model.toLowerCase()
+  return available.find((m) => m.id.toLowerCase() === needle) ?? available.find((m) => m.id.toLowerCase().includes(needle) || (m.name ?? '').toLowerCase().includes(needle))
+}
+
+/** Substitute ${CLAUDE_*} into a path rule. A variable that expands to an absolute
+ * path at the anchor position (e.g. Read(${CLAUDE_PROJECT_DIR}/docs/**)) names that
+ * exact location, so it is marked with Claude's `//` filesystem-absolute anchor;
+ * otherwise resolveRule reads the single leading slash as project-relative and
+ * re-anchors it under the project root, where it can never match. */
+function substitutePathRule(rule: string, vars: Record<string, string | undefined>): string {
+  const substituted = substituteVars(rule, vars)
+  return rule.trimStart().startsWith('${CLAUDE_') && path.isAbsolute(substituted) ? `/${substituted}` : substituted
+}
+
+/** Wall-clock budget for one injected span: the Bash tool's documented 2-minute
+ * default, which is what Claude runs these commands under. */
+const BASH_TIMEOUT_MS = 120_000
+
+/** Context fields pi provides that Claude's ${CLAUDE_*} variables read from. */
+interface VarContext {
+  sessionManager?: { getSessionId?: () => string }
+  thinkingLevel?: string
+  model?: ModelLike
+  modelRegistry?: { getAvailable(): ReadonlyArray<ModelLike> }
+}
 
 function isDirectory(target: string): boolean {
   try {
@@ -39,10 +81,11 @@ function isDirectory(target: string): boolean {
 }
 
 /** Existing `.claude/commands` directories, user first then project. The project
- * directory is included only for approved projects. */
+ * directory is the nearest at or above cwd (bounded at the repository root, matching
+ * the approval walk) and is included only for approved projects. */
 export function commandDirs(cwd: string, home: string, trusted: boolean): string[] {
   const candidates = [path.join(home, '.claude', 'commands')]
-  if (trusted) candidates.push(path.join(cwd, '.claude', 'commands'))
+  if (trusted) candidates.push(findNearestDir(cwd, path.join('.claude', 'commands')) ?? path.join(cwd, '.claude', 'commands'))
   const dirs: string[] = []
   for (const dir of candidates) {
     if (!dirs.includes(dir) && isDirectory(dir)) dirs.push(dir)
@@ -59,27 +102,110 @@ export function collectCommands(dirs: string[]): DiscoveredCommand[] {
   return [...byName.values()]
 }
 
+/** A plugin's command files, namespaced `plugin:name` as Claude registers them.
+ * The manifest may point `commands` somewhere else; the default is `commands/`. */
+export function pluginCommands(plugins: InstalledPlugin[]): DiscoveredCommand[] {
+  const found: DiscoveredCommand[] = []
+  for (const plugin of plugins) {
+    const declared = plugin.manifest.commands
+    const dirs = (Array.isArray(declared) ? declared : [typeof declared === 'string' ? declared : 'commands']).map((entry) => path.resolve(plugin.root, String(entry)))
+    for (const dir of dirs) {
+      for (const command of discoverCommandFiles(dir)) {
+        found.push({ name: `${plugin.name}:${command.name}`, filePath: command.filePath, plugin: { root: plugin.root, dataDir: plugin.dataDir, ...(plugin.userConfig ? { userConfig: plugin.userConfig } : {}) } })
+      }
+    }
+  }
+  return found
+}
+
 export default function commandsExtension(pi: ExtensionAPI) {
   const registered = new Set<string>()
   /** Tool set to put back once the turn a restricted command drove has ended. */
   let pendingRestore: string[] | undefined
+  /** `Bash(...)` scopes enforced while that turn runs; lifted with the restriction. */
+  let pendingBashRules: string[] | undefined
+  /** Read/Edit path scopes enforced the same way, per pi file tool. */
+  let pendingPathRules: Partial<Record<PathRuleTool, string[]>> | undefined
+  /** The session model to restore after a command's `model:` override drove its turn. */
+  let pendingModelRestore: ModelLike | undefined
 
   pi.on('turn_end', async () => {
+    pendingBashRules = undefined
+    pendingPathRules = undefined
+    if (pendingModelRestore) {
+      void pi.setModel(pendingModelRestore as Parameters<typeof pi.setModel>[0])
+      pendingModelRestore = undefined
+    }
     if (!pendingRestore) return
     pi.setActiveTools(pendingRestore)
     pendingRestore = undefined
   })
 
-  async function runCommand(parsed: ParsedCommand, args: string, ctx: ExtensionCommandContext): Promise<void> {
-    const withArgs = substituteArgs(parsed.body, args)
-    const expanded = await expandDynamicContent(withArgs, ctx.cwd, async (shell) => {
-      // Hooks get CLAUDE_PROJECT_DIR, and a command's bash span is the same kind of
-      // project-scoped script. pi.exec takes no env, so it is exported in the script.
-      const projectDir = ctx.cwd.replaceAll("'", String.raw`'\''`)
-      const script = `export CLAUDE_PROJECT_DIR='${projectDir}'; ${shell}`
-      const result = await pi.exec('/bin/sh', ['-c', script], { cwd: ctx.cwd, timeout: BASH_TIMEOUT_MS })
-      return { stdout: result.stdout, stderr: result.stderr, code: result.code }
-    })
+  // The active-tool set has no argument dimension, so a scoped grant hands the turn
+  // the whole tool; the scope is enforced here instead, when the call arrives. Same
+  // steering-not-sandbox caveat as plan mode's guard.
+  pi.on('tool_call', async (event, ctx) => {
+    if (pendingBashRules && event.toolName === 'bash') {
+      const command = typeof event.input.command === 'string' ? event.input.command : ''
+      if (matchesBashRules(command, pendingBashRules)) return
+      return {
+        block: true,
+        reason: `allowed-tools: bash is scoped for this command.\nAllowed: ${pendingBashRules.join(', ')}\nCommand: ${command}`,
+      }
+    }
+    const rules = pendingPathRules?.[event.toolName as PathRuleTool]
+    if (!rules) return
+    const input = event.input as Record<string, unknown>
+    const filePath = typeof input.path === 'string' ? input.path : ''
+    const anchors = { cwd: ctx.cwd, projectRoot: repoRoot(ctx.cwd) ?? ctx.cwd, home: os.homedir() }
+    if (filePath && matchesPathRules(filePath, rules, anchors)) return
+    return {
+      block: true,
+      reason: `allowed-tools: ${event.toolName} is scoped for this command.\nAllowed: ${rules.join(', ')}\nPath: ${filePath}`,
+    }
+  })
+
+  async function runCommand(parsed: ParsedCommand, args: string, ctx: ExtensionCommandContext, filePath: string, plugin?: { root: string; dataDir: string; userConfig?: Record<string, string> }): Promise<void> {
+    const varCtx = ctx as unknown as VarContext
+    const projectRoot = repoRoot(ctx.cwd) ?? ctx.cwd
+    const vars: Record<string, string | undefined> = {
+      CLAUDE_SESSION_ID: varCtx.sessionManager?.getSessionId?.(),
+      CLAUDE_EFFORT: varCtx.thinkingLevel,
+      CLAUDE_SKILL_DIR: path.dirname(filePath),
+      CLAUDE_PROJECT_DIR: projectRoot,
+      CLAUDE_PLUGIN_ROOT: plugin?.root,
+      CLAUDE_PLUGIN_DATA: plugin?.dataDir,
+    }
+    const { text: withArgs, consumed } = substituteArgsDetailed(parsed.body, args, parsed.argumentNames ?? [])
+    // `${user_config.KEY}` is a plugin-command variable only; leave it literal in an
+    // ordinary command so a body that happens to contain the syntax is not stripped.
+    const substituted = substituteVars(withArgs, vars)
+    const withVars = plugin ? substituted.replace(/\$\{user_config\.([A-Za-z0-9_]+)\}/g, (_, key: string) => plugin.userConfig?.[key] ?? '') : substituted
+
+    let expanded: string
+    try {
+      expanded = await expandDynamicContent(withVars, ctx.cwd, async (script) => {
+        // Hooks get CLAUDE_PROJECT_DIR, and a command's shell span is the same kind of
+        // project-scoped script. pi.exec takes no env, so it is set in the script.
+        // stderr merges into stdout, as the Bash tool runs these for Claude. The
+        // resolver is passed by its imported binding so tests can stub the lookup.
+        const run = spanExec(parsed.shell, projectRoot, script, resolvePowershellBinary)
+        const result = await pi.exec(run.command, run.args, { cwd: ctx.cwd, timeout: BASH_TIMEOUT_MS })
+        // pwsh cannot merge a native command's stderr in-script (spanExec sets
+        // mergeStreams), so it is appended here; the sh script merges via 2>&1.
+        const stdout = run.mergeStreams ? result.stdout + result.stderr : result.stdout
+        return { stdout, stderr: result.stderr, code: result.code }
+      })
+    } catch (error) {
+      // A failed injected command aborts the invocation; the model never sees a
+      // half-expanded body. The notify carries Claude's failure message format.
+      ctx.ui.notify(error instanceof Error ? error.message : String(error), 'error')
+      return
+    }
+
+    // Claude appends the raw arguments when the command never read them, so what
+    // the user typed still reaches the model.
+    if (args.trim().length > 0 && !consumed) expanded += `\n\nARGUMENTS: ${args.trim()}`
 
     // allowed-tools restricts the turn the command drives, and the previous set is
     // restored when that turn ends. Restoring inline does not work: sendUserMessage is
@@ -96,13 +222,45 @@ export default function commandsExtension(pi: ExtensionAPI) {
       // intersects to nothing named only tools pi has none of: that restriction cannot
       // be expressed, and applying it as "no tools" is not what the command asked for.
       if (granted.length > 0 || parsed.allowedTools.length === 0) pi.setActiveTools(granted)
+      // The latest restricted command speaks for the turn: a later unscoped grant
+      // lifts an earlier command's scopes rather than stacking under them. Rules get
+      // the same ${CLAUDE_*} substitution as the body, so a rule can name a bundled
+      // script by its real path, as the skills docs show.
+      pendingBashRules = granted.includes('bash') ? parsed.bashRules?.map((rule) => substituteVars(rule, vars)) : undefined
+      pendingPathRules = undefined
+      if (parsed.pathRules) {
+        pendingPathRules = {}
+        for (const [tool, rules] of Object.entries(parsed.pathRules)) {
+          if (granted.includes(tool)) pendingPathRules[tool as PathRuleTool] = rules.map((rule) => substitutePathRule(rule, vars))
+        }
+      }
+    }
+    // Claude removes disallowed-tools from the pool while the skill is active;
+    // with both fields present the removal wins, as in subagent tool lists.
+    if (parsed.disallowedTools && parsed.disallowedTools.length > 0) {
+      const original = pendingRestore ?? pi.getActiveTools()
+      pendingRestore = original
+      const disallowed = parsed.disallowedTools
+      pi.setActiveTools(pi.getActiveTools().filter((tool) => !disallowed.includes(tool)))
+    }
+    // Claude's `model:` frontmatter overrides the model for this turn only, then the
+    // session model resumes; restore happens on turn_end like the tool-set restore.
+    // Applied before sendUserMessage so the turn it drives runs on the new model.
+    const target = resolveCommandModel(parsed.model, varCtx.modelRegistry?.getAvailable() ?? [])
+    if (target && varCtx.model && target.id !== varCtx.model.id) {
+      pendingModelRestore = pendingModelRestore ?? varCtx.model
+      await pi.setModel(target as Parameters<typeof pi.setModel>[0])
     }
     pi.sendUserMessage(expanded)
   }
 
   pi.on('session_start', async (_event, ctx) => {
     const trusted = await isProjectApproved(ctx)
-    for (const command of collectCommands(commandDirs(ctx.cwd, os.homedir(), trusted))) {
+    // Plugins are user-installed and enabled by user settings; a checked-out repo
+    // must not silently flip which code-bearing plugins run, so enablement is
+    // user-scoped and never reads the project settings chain (see installedPlugins).
+    const plugins = pluginCommands(installedPlugins(os.homedir()))
+    for (const command of [...collectCommands(commandDirs(ctx.cwd, os.homedir(), trusted)), ...plugins]) {
       // pi has no unregister, so a command already registered this process keeps its
       // original file binding; re-registering would only add a numbered duplicate.
       if (registered.has(command.name)) continue
@@ -123,7 +281,7 @@ export default function commandsExtension(pi: ExtensionAPI) {
           } catch {
             // fall back to what was parsed at registration
           }
-          await runCommand(current, args, commandCtx)
+          await runCommand(current, args, commandCtx, command.filePath, command.plugin)
         },
       })
     }