pi-code 1.0.4 → 1.0.6

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 }))] }
+  })
 }