pi-code 1.0.60 → 1.0.62

package/extensions/internal/command-file.ts

@@ -18,6 +18,8 @@ import * as path from 'node:path'
 
 import { parseFrontmatter } from '@earendil-works/pi-coding-agent'
 
+import { CLAUDE_TOOL_MAP } from './claude-tool-names.js'
+
 /** The pi file tools a Claude path rule can govern. */
 export type PathRuleTool = 'read' | 'edit' | 'write'
 
@@ -27,6 +29,12 @@ export interface ParsedCommand {
   allowedTools?: string[]
   /** Claude `Bash(...)` specifiers, present only when every bash grant is scoped. */
   bashRules?: string[]
+  /** Claude `WebFetch(domain:...)` specifiers, on the same unscoped-wins rule. */
+  domainRules?: string[]
+  /** Claude `Agent(...)`/`Task(...)` agent names, on the same unscoped-wins rule. */
+  agentRules?: string[]
+  /** Claude `Skill(...)` name patterns, on the same unscoped-wins rule. */
+  skillRules?: string[]
   /** Claude path rules per pi file tool, from Read(...)/Edit(...)/Write(...) grants. */
   pathRules?: Partial<Record<PathRuleTool, string[]>>
   /** Names from the `arguments:` frontmatter list, mapped to positions in order. */
@@ -58,34 +66,6 @@ export interface DiscoveredCommand {
   plugin?: { root: string; dataDir: string; userConfig?: Record<string, string> }
 }
 
-/** Claude tool names are PascalCase and do not all exist in pi: `Glob` is pi's
- * `find`. Lowercasing alone left `glob` in the list, and since pi has no tool by
- * that name the grant was silently dropped when the list was intersected with the
- * active tools. Shared with the subagent's own frontmatter parsing. */
-const CLAUDE_TOOL_MAP: Record<string, string> = {
-  read: 'read',
-  write: 'write',
-  edit: 'edit',
-  bash: 'bash',
-  grep: 'grep',
-  glob: 'find',
-  ls: 'ls',
-  // Claude's names for the tools this package registers itself. Without these a
-  // perfectly ordinary `allowed-tools: WebFetch, WebSearch` matched no pi tool and
-  // the intersection left the turn with nothing.
-  webfetch: 'web_fetch',
-  websearch: 'web_search',
-  todowrite: 'todo',
-  todoread: 'todo',
-  task: 'subagent',
-  askuserquestion: 'question',
-  exitplanmode: 'plan_mode_complete',
-  // Claude's name for the tool this package registers so the model can run user slash
-  // commands; without it `allowed-tools: SlashCommand` matched nothing and the grant
-  // could neither keep nor drop the tool.
-  slashcommand: 'slash_command',
-}
-
 /**
  * The pi tool name for one grant entry, scope and all: `Bash(git add:*)` is `bash`.
  * Keeping the scope in the name matched nothing when the list was intersected with
@@ -135,6 +115,14 @@ export interface ToolGrants {
   /** Claude `Bash(...)` specifiers, present only when every bash grant is scoped:
    * an unscoped `Bash` entry is the wider grant and wins over its scoped siblings. */
   bashRules?: string[]
+  /** Claude `WebFetch(domain:host)` specifiers, same unscoped-wins rule as bash.
+   * Dropping them granted unrestricted web_fetch to a command that asked for one host. */
+  domainRules?: string[]
+  /** Claude `Agent(AgentName)` names from `Agent(...)` or the legacy `Task(...)`,
+   * same unscoped-wins rule. Dropping them granted the whole subagent tool. */
+  agentRules?: string[]
+  /** Claude `Skill(name)` / `Skill(name *)` specifiers, same unscoped-wins rule. */
+  skillRules?: string[]
   /** Claude path rules per pi file tool, absent for a tool with an unscoped grant.
    * Edit scopes govern writes too, as Claude documents; Write scopes are honored
    * rather than Claude's accept-and-warn-then-ignore, which would fail open here. */
@@ -150,18 +138,32 @@ const PATH_RULE_TOOLS: Record<string, Array<PathRuleTool>> = {
   write: ['write'],
 }
 
+/** pi tools whose Claude specifier is a scalar argument scope rather than a path
+ * rule: `Bash(cmd)`, `WebFetch(domain:host)` and `Agent(AgentName)`. One list, so a
+ * tool cannot be granted a scope here and quietly miss the unscoped-wins rule. */
+const ARG_RULE_TOOLS = ['bash', 'web_fetch', 'subagent', 'slash_command'] as const
+type ArgRuleTool = (typeof ARG_RULE_TOOLS)[number]
+
+const isArgRuleTool = (name: string): name is ArgRuleTool => (ARG_RULE_TOOLS as readonly string[]).includes(name)
+
 /** The tools, scopes, and path rules accumulated while scanning one grant list. */
 interface GrantAccumulator {
   tools: string[]
   scopedEntries: string[]
-  bashRules: string[]
-  bashUnscoped: boolean
+  argScopes: Record<ArgRuleTool, string[]>
+  argUnscoped: Set<ArgRuleTool>
   pathScopes: Record<PathRuleTool, string[]>
   pathUnscoped: Set<PathRuleTool>
 }
 
 function createGrantAccumulator(): GrantAccumulator {
-  return { tools: [], scopedEntries: [], bashRules: [], bashUnscoped: false, pathScopes: { read: [], edit: [], write: [] }, pathUnscoped: new Set() }
+  return { tools: [], scopedEntries: [], argScopes: { bash: [], web_fetch: [], subagent: [], slash_command: [] }, argUnscoped: new Set(), pathScopes: { read: [], edit: [], write: [] }, pathUnscoped: new Set() }
+}
+
+/** The scopes for one argument-ruled tool, or undefined when it has none or when an
+ * unscoped grant for it makes it wide. The wider grant wins, as it does for bash. */
+function argRules(acc: GrantAccumulator, tool: ArgRuleTool): string[] | undefined {
+  return !acc.argUnscoped.has(tool) && acc.argScopes[tool].length > 0 ? acc.argScopes[tool] : undefined
 }
 
 /** Coerce a raw grant value to its string entries: a YAML list stays a list, a
@@ -186,7 +188,7 @@ function addGrantEntry(acc: GrantAccumulator, item: string): void {
   if (!acc.tools.includes(name)) acc.tools.push(name)
   const open = entry.indexOf('(')
   if (open === -1) {
-    if (name === 'bash') acc.bashUnscoped = true
+    if (isArgRuleTool(name)) acc.argUnscoped.add(name)
     for (const tool of PATH_RULE_TOOLS[name] ?? []) acc.pathUnscoped.add(tool)
     return
   }
@@ -195,7 +197,7 @@ function addGrantEntry(acc: GrantAccumulator, item: string): void {
   // An empty specifier (`Bash()`, `Read()`) matches nothing and must not read as
   // the unscoped grant it explicitly is not: it is recorded so the tool stays
   // restricted, and the matchers treat an empty rule as matching no input.
-  if (name === 'bash') acc.bashRules.push(scope)
+  if (isArgRuleTool(name)) acc.argScopes[name].push(scope)
   for (const tool of PATH_RULE_TOOLS[name] ?? []) acc.pathScopes[tool].push(scope)
 }
 
@@ -217,10 +219,14 @@ function buildPathRules(acc: GrantAccumulator): ToolGrants['pathRules'] {
  *
  * Claude scopes a grant to arguments: `Bash(git add:*)` allows exactly those commands.
  * pi's active-tool list is per tool, with no argument dimension, so the base tool is
- * granted and the scope is kept: commands.ts enforces bash scopes at tool_call time,
- * and the subagent's frontmatter parsing rejects a scoped grant it cannot express.
- * A scope on any other tool is dropped, which widens that grant; bash is the one
- * whose widening reaches everything, so it is the one enforced.
+ * granted and the scope is kept for commands.ts to enforce at tool_call time. Every
+ * specifier Claude documents for an allow rule is kept: `Bash(cmd)`, the Read/Edit
+ * path rules, `WebFetch(domain:host)` and `Agent(AgentName)`. The subagent's own
+ * frontmatter parsing still rejects a scoped grant outright, since it has no
+ * call-time seam to enforce one in.
+ *
+ * Claude's `Tool(param:value)` form is not among them: the permissions reference
+ * confines it to deny and ask rules, and `allowed-tools` is an allow surface.
  */
 export function parseToolGrants(raw: unknown): ToolGrants | undefined {
   const items = coerceGrantItems(raw)
@@ -230,7 +236,10 @@ export function parseToolGrants(raw: unknown): ToolGrants | undefined {
   return {
     tools: acc.tools,
     scopedEntries: acc.scopedEntries,
-    bashRules: !acc.bashUnscoped && acc.bashRules.length > 0 ? acc.bashRules : undefined,
+    bashRules: argRules(acc, 'bash'),
+    domainRules: argRules(acc, 'web_fetch'),
+    agentRules: argRules(acc, 'subagent'),
+    skillRules: argRules(acc, 'slash_command'),
     pathRules: buildPathRules(acc),
   }
 }
@@ -293,6 +302,9 @@ export function parseCommandFile(content: string): ParsedCommand {
     argumentHint: hint(frontmatter['argument-hint']) || undefined,
     allowedTools: grants?.tools,
     bashRules: grants?.bashRules,
+    domainRules: grants?.domainRules,
+    agentRules: grants?.agentRules,
+    skillRules: grants?.skillRules,
     pathRules: grants?.pathRules,
     argumentNames: parseArgumentNames(frontmatter.arguments),
     // A scope on a disallow entry only denies more than asked, so the drop is safe.

package/extensions/internal/mcp-oauth.ts

@@ -18,6 +18,7 @@ import * as path from 'node:path'
 import { getAgentDir } from '@earendil-works/pi-coding-agent'
 import type { OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js'
 import type { OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js'
+import { errorMessage } from './values.js'
 
 interface StoredAuth {
   client?: OAuthClientInformationMixed
@@ -105,6 +106,12 @@ export class FileOAuthProvider implements OAuthClientProvider {
     fs.writeFileSync(this.storePath, JSON.stringify(this.data), { mode: 0o600 })
   }
 
+  /** The configured callbackPort alone, absent when only a remembered port exists.
+   * The caller needs the two apart: a configured port is a hard requirement. */
+  configuredRedirectPort(): number | undefined {
+    return this.oauth?.callbackPort
+  }
+
   /** The configured callbackPort (Claude: for pre-registered redirect URIs), else
    * the port a prior login registered, so a re-login can bind the same one. */
   savedRedirectPort(): number | undefined {
@@ -193,13 +200,19 @@ export class FileOAuthProvider implements OAuthClientProvider {
 /** A one-shot loopback listener for the authorization redirect. Loopback redirect
  * URIs are the RFC 8252 pattern for native apps. A preferred port (from a prior
  * login) is tried first so a re-login keeps the registered redirect_uri; if it is
- * taken, an ephemeral port is used. */
-export async function startCallbackServer(preferredPort?: number): Promise<{ server: http.Server; port: number }> {
+ * taken, an ephemeral port is used.
+ *
+ * `portRequired` marks the port as configured rather than remembered. A configured
+ * `oauth.callbackPort` names the redirect_uri the IdP has registered, so quietly
+ * binding a different one sends the user to an opaque redirect_uri mismatch at the
+ * IdP; the bind failure is reported here instead, where it can name the real cause. */
+export async function startCallbackServer(preferredPort?: number, portRequired = false): Promise<{ server: http.Server; port: number }> {
   const server = http.createServer()
   const listen = (port: number, host: string): Promise<void> => new Promise((resolve, reject) => server.listen(port, host, resolve).once('error', reject))
   try {
     await listen(preferredPort ?? 0, '127.0.0.1')
-  } catch {
+  } catch (error) {
+    if (portRequired) throw new Error(`oauth.callbackPort ${preferredPort} is in use, so the registered redirect URI cannot be served: free that port or change oauth.callbackPort (${errorMessage(error)})`)
     await listen(0, '127.0.0.1')
   }
   const port = (server.address() as { port: number }).port

package/extensions/internal/path-rules.ts

@@ -188,7 +188,6 @@ function resolveRule(rule: string, anchors: PathAnchors): string {
  * root-relative path. */
 export interface CompiledGlob {
   regex: RegExp
-  matchesBasename: boolean
 }
 
 let globsCompiled = 0
@@ -219,7 +218,7 @@ export function compileGlobs(globs: string[]): CompiledGlob[] {
     // would compile to `^docs/$` and match nothing.
     if (glob.endsWith('/')) glob += '**'
     globsCompiled += 1
-    compiled.push({ regex: new RegExp(`^${globToRegExpSource(glob)}$`), matchesBasename: !glob.includes('/') })
+    compiled.push({ regex: new RegExp(`^${globToRegExpSource(glob)}$`) })
   }
   return compiled
 }
@@ -229,8 +228,7 @@ export function compileGlobs(globs: string[]): CompiledGlob[] {
 export function matchesCompiledGlobs(relPath: string, globs: CompiledGlob[]): boolean {
   globsEvaluated += 1
   const posix = relPath.split(path.sep).join('/')
-  const base = posix.split('/').pop() ?? posix
-  return globs.some((glob) => glob.regex.test(glob.matchesBasename ? base : posix))
+  return globs.some((glob) => glob.regex.test(posix))
 }
 
 /** Whether the accessed file matches at least one rule. No rules means no match:
@@ -245,6 +243,23 @@ const toPosix = (target: string): string => {
   return withSlashes.replace(/^\/?[A-Za-z]:\//, '/')
 }
 
+/**
+ * Drop a drive from a RESOLVED rule so it can meet a target that toPosix has already
+ * stripped. Claude documents `//path` as an absolute path from the filesystem root,
+ * and on Windows its own example names the drive as the first segment (`//c/` then a
+ * recursive glob), where `c` is the drive; that resolved to `/c/...` while every target
+ * resolved to `/...`, so the rule could never match anything.
+ *
+ * Windows only, and that is the whole point of the flag: on POSIX `/c/foo` is an
+ * ordinary absolute path and stripping its first segment would widen the rule to
+ * everything under the root. Exported and platform-parameterized rather than reading
+ * process.platform inline, so both branches are assertable from either host.
+ */
+export function stripRuleDrive(rule: string, windows: boolean): string {
+  if (!windows) return rule
+  return rule.replace(/^([A-Za-z]):\//, '/').replace(/^\/[A-Za-z]\//, '/')
+}
+
 export function matchesPathRules(filePath: string, rules: string[], anchors: PathAnchors): boolean {
   const target = toPosix(path.resolve(anchors.cwd, filePath))
   return rules.some((rule) => {
@@ -252,7 +267,7 @@ export function matchesPathRules(filePath: string, rules: string[], anchors: Pat
     // An empty specifier (`Read()`) matches nothing, so the tool stays blocked
     // rather than falling open, mirroring `Bash()`.
     if (trimmed === '') return false
-    const resolved = toPosix(resolveRule(trimmed, anchors))
+    const resolved = stripRuleDrive(toPosix(resolveRule(trimmed, anchors)), path.sep === '\\')
     return new RegExp(`^${globToRegExpSource(resolved)}$`).test(target)
   })
 }

package/extensions/internal/plugins.ts

@@ -215,6 +215,17 @@ export function installedPlugins(home: string, extraSettingsFiles: string[] = []
   return plugins
 }
 
+/** The plugins a managed `enabledPlugins` entry force-enables. Claude exempts their
+ * hooks from `allowManagedHooksOnly`: an administrator who turned a plugin on meant its
+ * hooks to run. Keys are matched the way pluginEnabled matches them, by the qualified
+ * `name@marketplace` or the bare directory name, so the two cannot drift apart. */
+export function managedForceEnabled(plugins: InstalledPlugin[]): InstalledPlugin[] {
+  const managedEntry = readManagedSettings().enabledPlugins
+  if (managedEntry === null || typeof managedEntry !== 'object') return []
+  const entries = managedEntry as Record<string, unknown>
+  return plugins.filter((plugin) => Object.entries(entries).some(([key, value]) => value === true && (key === plugin.name || key.startsWith(`${plugin.name}@`))))
+}
+
 /** The plugin's effective enablement per Claude's precedence: a managed
  * enabledPlugins entry force-enables or blocks, then the user's setting, then the
  * manifest's defaultEnabled, which defaults to true ("starts in an enabled state

package/extensions/internal/project-approval.ts

@@ -18,6 +18,7 @@
  */
 
 import * as fs from 'node:fs'
+import * as os from 'node:os'
 import * as path from 'node:path'
 import { getAgentDir, hasTrustRequiringProjectResources, ProjectTrustStore } from '@earendil-works/pi-coding-agent'
 
@@ -46,11 +47,15 @@ const CLAUDE_SHAPED = [
  * The walk matters: agent discovery already searches upward, so starting pi in a
  * subdirectory of a repository whose `.claude/agents` sits at the root found those
  * agents while a cwd-only check reported nothing to gate, and the short-circuit
- * approved the project without ever asking. The bound is the repository root, so a
- * directory outside any repository never inherits a parent's config. */
-export function hasClaudeShapedConfig(cwd: string): boolean {
+ * approved the project without ever asking. The bound is the repository root and the home
+ * directory, because `~/.claude` is the user's own configuration: a directory under
+ * home that is in no repository would otherwise walk up into it and report the user's
+ * own settings as a project waiting to be approved. */
+export function hasClaudeShapedConfig(cwd: string, home: string = os.homedir()): boolean {
   let currentDir = cwd
   while (true) {
+    // The home check comes first: at home itself the .claude found is the user's own.
+    if (currentDir === home) return false
     if (CLAUDE_SHAPED.some((entry) => fs.existsSync(path.join(currentDir, entry)))) return true
     if (ROOT_MARKERS.some((marker) => fs.existsSync(path.join(currentDir, marker)))) return false
     const parentDir = path.dirname(currentDir)

package/extensions/internal/project-root.ts

@@ -13,18 +13,21 @@
 import * as fs from 'node:fs'
 import * as path from 'node:path'
 
-/** Project root markers ending the walk. `.git` is a file in worktrees and submodules. */
-export const ROOT_MARKERS = ['.git', 'package.json']
+/** The project root marker. `.git` is a file in worktrees and submodules, a directory
+ * in an ordinary clone.
+ *
+ * `package.json` used to count too, which made every package of a monorepo its own
+ * project: its own memory directory, its own settings.local.json, its own
+ * CLAUDE_PROJECT_DIR, its own trust decision. Claude's project is the repository, and
+ * a repository can add a package.json wherever it likes, so a marker it controls was
+ * also a marker it could move. */
+export const ROOT_MARKERS = ['.git']
 
-/** Project root at or above `from`, or undefined when no marker is found. */
+/** Project root at or above `from`, or undefined outside a repository. */
 export function repoRoot(from: string): string | undefined {
-  let currentDir = from
-  while (true) {
-    if (ROOT_MARKERS.some((marker) => fs.existsSync(path.join(currentDir, marker)))) return currentDir
-    const parentDir = path.dirname(currentDir)
-    if (parentDir === currentDir) return undefined
-    currentDir = parentDir
-  }
+  const root = gitRoot(from)
+  if (root === undefined) return undefined
+  return mainCheckout(root)
 }
 
 /** The git checkout at or above `from`, or undefined outside one.
@@ -45,6 +48,38 @@ export function gitRoot(from: string): string | undefined {
   }
 }
 
+/** The main checkout for a git directory.
+ *
+ * A worktree carries a `.git` FILE holding `gitdir: <main>/.git/worktrees/<name>`, so
+ * resolving it gives the checkout the repository's state actually belongs to. Claude
+ * reads settings.local.json from "the file at the main checkout's root" and shares one
+ * auto memory directory across "all worktrees and subdirectories within the same repo",
+ * so a worktree is not its own project. An unreadable or unexpected `.git` file leaves
+ * the directory as its own root, which is the safe direction. */
+function mainCheckout(root: string): string {
+  const dotGit = path.join(root, '.git')
+  let pointer: string
+  try {
+    if (!fs.statSync(dotGit).isFile()) return root
+    pointer = fs.readFileSync(dotGit, 'utf-8')
+  } catch {
+    return root
+  }
+  // Parsed rather than matched: the file is one `gitdir: <path>` line, and a regex
+  // over an arbitrary-length path is a backtracking cost for nothing.
+  const [firstLine = ''] = pointer.split('\n')
+  const prefix = 'gitdir:'
+  if (!firstLine.startsWith(prefix)) return root
+  const target = firstLine.slice(prefix.length).trim()
+  if (!target) return root
+  // <main>/.git/worktrees/<name> -> <main>
+  const worktreeDir = path.resolve(root, target)
+  const marker = `${path.sep}.git${path.sep}worktrees${path.sep}`
+  const cut = worktreeDir.lastIndexOf(marker)
+  if (cut === -1) return root
+  return worktreeDir.slice(0, cut)
+}
+
 function statOf(target: string): fs.Stats | null {
   try {
     return fs.statSync(target)

package/extensions/internal/scope-rules.ts

@@ -0,0 +1,117 @@
+/**
+ * Claude's argument scopes for the two tools whose specifier is neither a bash
+ * command nor a file path: `WebFetch(domain:host)` and `Agent(AgentName)`.
+ *
+ * pi's active-tool set has no argument dimension, so commands.ts grants the base
+ * tool and checks each call here, the way it already does for `Bash(...)` scopes.
+ * Both matchers fail closed: a scope this module cannot interpret matches nothing
+ * rather than reading as the unscoped grant the author did not write.
+ *
+ * Claude's parameter form `Tool(param:value)` is deliberately absent. The
+ * permissions reference restricts it to deny and ask rules ("An allow rule for one
+ * parameter value wouldn't establish that the call is safe overall, so allow rules
+ * continue to use each tool's own specifier syntax"), and every scope reaching this
+ * module comes from an allow surface: a command's `allowed-tools`.
+ */
+
+/** Regex specials except `*`, which carries the rule's own wildcard meaning. */
+const escapeExceptStar = (text: string): string => text.replaceAll(/[.+?^${}()|[\]\\]/g, String.raw`\$&`)
+
+/** A hostname pattern segment: `*` matches any text that does not cross a dot. */
+const hostPattern = (pattern: string): string => escapeExceptStar(pattern).replaceAll('*', '[^.]*')
+
+/** Lowercased, with the trailing `.` the reference strips from both sides removed. */
+const canonicalHost = (host: string): string => host.trim().toLowerCase().replace(/\.$/, '')
+
+/** The hostname of a fetch target, or '' when the url does not parse. */
+function hostnameOf(url: string): string {
+  try {
+    return canonicalHost(new URL(url).hostname)
+  } catch {
+    return ''
+  }
+}
+
+/** The host pattern of one `domain:` scope, or undefined for any other spelling.
+ * WebFetch has exactly one documented specifier syntax, so an unrecognized scope is
+ * not a wider grant, it is a rule that matches nothing. */
+function domainPattern(rule: string): string | undefined {
+  const trimmed = rule.trim()
+  const colon = trimmed.indexOf(':')
+  if (colon === -1 || trimmed.slice(0, colon).trim().toLowerCase() !== 'domain') return undefined
+  const pattern = canonicalHost(trimmed.slice(colon + 1))
+  return pattern === '' ? undefined : pattern
+}
+
+function matchesDomainRule(host: string, rule: string): boolean {
+  const pattern = domainPattern(rule)
+  if (pattern === undefined) return false
+  if (pattern === '*') return true
+  // A leading `*.` is the one wildcard that crosses dots: it stands for one or more
+  // whole labels, so it covers `a.b.example.com` while leaving the apex unmatched.
+  if (pattern.startsWith('*.')) return new RegExp(String.raw`^(?:[^.]+\.)+${hostPattern(pattern.slice(2))}$`).test(host)
+  return new RegExp(`^${hostPattern(pattern)}$`).test(host)
+}
+
+/**
+ * Claude: "WebFetch rules use a `domain:` prefix and match against the hostname of
+ * the requested URL. Matching is case-insensitive, supports `*` wildcards, and strips
+ * a trailing `.` from both the rule and the hostname."
+ */
+export function matchesDomainRules(url: string, rules: string[]): boolean {
+  const host = hostnameOf(url)
+  if (host === '') return false
+  return rules.some((rule) => matchesDomainRule(host, rule))
+}
+
+/**
+ * Claude: "Permission syntax: `Skill(name)` for exact match, `Skill(name *)` for
+ * prefix match with any arguments."
+ *
+ * The invocation is the skill name and its arguments as one string, the shape pi's
+ * `slash_command` tool takes; a leading `/` is optional there, so it is stripped
+ * before matching. Only the two documented forms are interpreted. A rule spelled any
+ * other way, `commit:*` included, matches nothing rather than widening the grant.
+ */
+export function matchesSkillRules(invocation: string, rules: string[]): boolean {
+  const call = invocation.trim().replace(/^\//, '').trim()
+  if (call === '') return false
+  return rules.some((raw) => {
+    const rule = raw.trim()
+    if (rule === '') return false
+    if (!rule.endsWith(' *')) return rule === call
+    // The space before the trailing `*` is part of the rule, so `review-pr *` covers
+    // `review-pr` and `review-pr 123` but never the longer name `review-pretend`.
+    const prefix = rule.slice(0, -2).trimEnd()
+    return prefix !== '' && (call === prefix || call.startsWith(`${prefix} `))
+  })
+}
+
+/** The `agent` of one call or task entry, when it has one. */
+const agentNameOf = (value: unknown): string | undefined => {
+  const record = value !== null && typeof value === 'object' ? (value as Record<string, unknown>) : undefined
+  return typeof record?.agent === 'string' ? record.agent : undefined
+}
+
+/** Every agent name one subagent call names, across all three modes: `agent` for
+ * single, and the `agent` of each entry in `tasks` (parallel) or `chain` (sequential).
+ * One collector, so a rule checked against single mode cannot be quietly skipped for
+ * the two modes that carry their names in an array. */
+export function agentNamesIn(input: unknown): string[] {
+  const raw = input !== null && typeof input === 'object' ? (input as Record<string, unknown>) : {}
+  const listed = ['tasks', 'chain'].flatMap((key) => (Array.isArray(raw[key]) ? (raw[key] as unknown[]) : []))
+  return [input, ...listed].map(agentNameOf).filter((name): name is string => name !== undefined)
+}
+
+/**
+ * Claude: "Use `Agent(AgentName)` rules to control which subagents Claude can use."
+ *
+ * Every agent the call names must match, not just the first. A subagent call carries
+ * names in `agent`, `tasks[].agent` and `chain[].agent`; gating one field would let
+ * parallel or chain mode route around the rule. A call naming no agent cannot be
+ * checked against the scope, so it fails closed too.
+ */
+export function matchesAgentRules(names: string[], rules: string[]): boolean {
+  if (names.length === 0) return false
+  return names.every((name) => rules.some((rule) => rule.trim() !== '' && rule.trim() === name.trim()))
+}

package/extensions/internal/settings-chain.ts

@@ -13,19 +13,46 @@ import { claudeConfigDir } from './config-dir.js'
 import { repoRoot } from './project-root.js'
 import { isRecord } from './values.js'
 
+/** Whether every path given exists and belongs to the user running this process.
+ * A path that is absent is not someone else's, so it does not disqualify the root. */
+function ownedByUser(paths: string[]): boolean {
+  const uid = process.getuid?.()
+  if (uid === undefined) return true
+  return paths.every((target) => {
+    try {
+      return fs.statSync(target).uid === uid
+    } catch {
+      return true
+    }
+  })
+}
+
+/** Where `settings.local.json` lives, per Claude's four exceptions: it sits at the
+ * repository root, except outside a repository, when that root is the home directory,
+ * on Windows, or when the root or its `.git` or `.claude` entry belongs to someone
+ * else. In each of those it stays beside `.claude/settings.json` in the working
+ * directory instead. In a worktree the root is the main checkout, which repoRoot
+ * resolves. */
+function localSettingsDir(cwd: string, home: string, platform: NodeJS.Platform, owned: (paths: string[]) => boolean): string {
+  const root = repoRoot(cwd)
+  if (root === undefined || root === home) return cwd
+  if (platform === 'win32') return cwd
+  if (!owned([root, path.join(root, '.git'), path.join(root, '.claude')])) return cwd
+  return root
+}
+
 /** The user settings.json, then (only when `includeProject`) the project files by
  * Claude's placement rules: the shared `.claude/settings.json` is read from the
  * session's primary working directory (never an ancestor; "to use a file committed
  * at the repository root, start Claude Code there"), while `settings.local.json`
- * lives at the repository root, falling back to the primary directory outside a
- * repository or when the root is the home directory. A legacy local file at the
- * primary directory is still read, with the root's values winning. Later files win. */
-export function claudeSettingsChain(cwd: string, home: string, includeProject: boolean): string[] {
+ * lives at the repository root, subject to the exceptions in localSettingsDir. A
+ * legacy local file at the primary directory is still read, with the root's values
+ * winning. Later files win. */
+export function claudeSettingsChain(cwd: string, home: string, includeProject: boolean, platform: NodeJS.Platform = process.platform, owned: (paths: string[]) => boolean = ownedByUser): string[] {
   const files = [path.join(claudeConfigDir(home), 'settings.json')]
   if (!includeProject) return files
   files.push(path.join(cwd, '.claude', 'settings.json'))
-  const root = repoRoot(cwd)
-  const localDir = root !== undefined && root !== home ? root : cwd
+  const localDir = localSettingsDir(cwd, home, platform, owned)
   if (localDir !== cwd) files.push(path.join(cwd, '.claude', 'settings.local.json'))
   files.push(path.join(localDir, '.claude', 'settings.local.json'))
   return files

package/extensions/internal/web-transport.ts

@@ -52,6 +52,13 @@ export function httpFetch(url: URL, opts: TransportOptions): Promise<Response> {
           // (204/205/304) and for status 0. That throw fires here, off the Promise
           // executor, so without this guard it escapes as an uncaughtException and pi
           // exits. Give those statuses a null body; reject anything else that throws.
+          //
+          // The catch below has no test and cannot get one through this function: the
+          // only two throw sources are the null-body statuses, which the line under this
+          // comment handles, and a status outside 200-599, which never reaches this
+          // callback at all (node routes 1xx to the `information` event and rejects a
+          // malformed status line in the parser). It stays as depth, not dead code, but
+          // do not chase its coverage with a test that reaches it some other way.
           const body = NULL_BODY_STATUSES.has(status) ? null : (Readable.toWeb(res) as ReadableStream<Uint8Array>)
           resolve(new Response(body, { status, headers }))
         } catch (err) {

package/extensions/mcp/config.ts

@@ -27,6 +27,8 @@ export interface StdioServerConfig {
   baseName?: string
   /** Root of the plugin that supplied this server; exported as CLAUDE_PLUGIN_ROOT. */
   pluginRoot?: string
+  /** ${CLAUDE_PLUGIN_DATA} for a plugin's server, exported alongside the root. */
+  pluginDataDir?: string
   /** Loaded from the project scope, whose helpers run credential-stripped. */
   projectScope?: boolean
 }
@@ -52,6 +54,8 @@ export interface HttpServerConfig {
   baseName?: string
   /** Root of the plugin that supplied this server; exported as CLAUDE_PLUGIN_ROOT. */
   pluginRoot?: string
+  /** ${CLAUDE_PLUGIN_DATA} for a plugin's server, exported alongside the root. */
+  pluginDataDir?: string
   /** Loaded from the project scope, whose helpers run credential-stripped. */
   projectScope?: boolean
 }
@@ -225,7 +229,7 @@ export function loadPluginServers(plugins: InstalledPlugin[], projectDir?: strin
       // plugin:<plugin-name>:<server-name>", which is what an mcp_tool hook names and what
       // keeps a same-named user server from replacing a plugin's. The tool alias keeps its
       // own flat spelling, mcp__plugin_<plugin>_<server>__<tool>.
-      if (substituted) servers[`plugin:${plugin.name}:${name}`] = { ...substituted, aliasPrefix: `mcp__plugin_${fold(plugin.name)}_${fold(name)}__`, baseName: name, pluginRoot: plugin.root }
+      if (substituted) servers[`plugin:${plugin.name}:${name}`] = { ...substituted, aliasPrefix: `mcp__plugin_${fold(plugin.name)}_${fold(name)}__`, baseName: name, pluginRoot: plugin.root, pluginDataDir: plugin.dataDir }
     }
   }
   return servers

package/extensions/mcp/index.ts

@@ -85,6 +85,10 @@ function authUiFor(ctx: ExtensionContext): AuthUi | undefined {
 
 export default async function mcpExtension(pi: ExtensionAPI) {
   const clients = new Map<string, Client>()
+  // The session's OAuth UI seams, captured at session_start. The reconnect paths below
+  // run outside that handler, and passing undefined there made an INTERACTIVE session
+  // report the headless "cannot log in" advice on a re-auth it could actually perform.
+  let sessionAuthUi: AuthUi | undefined
   const status = new Map<string, { state: string; tools: number }>()
   // Config per server name, kept for call-time timeout tuning: the idle tier follows
   // the transport kind, and a declared per-server timeout governs the wall budget.
@@ -178,14 +182,15 @@ export default async function mcpExtension(pi: ExtensionAPI) {
   /** Claude's mid-session reconnect for a dropped remote server: five attempts with
    * a delay doubling from one second. connectServers redoes the full bring-up
    * (tools, prompts, subscriptions, a fresh onclose) and its duplicate guard skips
-   * out if another path already reconnected the name. Runs without authUi: a server
-   * that now needs a login ends failed, and after the fifth failure the last
-   * attempt's failed status stands, with a session restart as the manual retry. */
+   * out if another path already reconnected the name. Uses the session's authUi, so a
+   * server that now needs a login can prompt for it in an interactive session; headless
+   * still ends failed, and after the fifth failure the last attempt's failed status
+   * stands, with a session restart as the manual retry. */
   async function reconnectWithBackoff(name: string, config: ServerConfig): Promise<void> {
     for (let attempt = 0; attempt < 5; attempt++) {
       await new Promise((resolve) => setTimeout(resolve, 1000 * 2 ** attempt))
       if (shuttingDown || clients.has(name)) return
-      await connectServers({ [name]: config }, undefined, true)
+      await connectServers({ [name]: config }, sessionAuthUi, true)
       if (clients.has(name)) return
     }
   }
@@ -200,7 +205,7 @@ export default async function mcpExtension(pi: ExtensionAPI) {
       clients.delete(name)
       await withTimeout(old.close(), 3000, 'close').catch(() => {})
     }
-    await connectServers({ [name]: config }, undefined, true)
+    await connectServers({ [name]: config }, sessionAuthUi, true)
   }
 
   /** A tool call with the auth retry: on a 401/403 rejection, reconnect once and
@@ -576,6 +581,7 @@ export default async function mcpExtension(pi: ExtensionAPI) {
     // project root as CLAUDE_PROJECT_DIR to stdio servers; both derive from ctx.cwd.
     sessionDirs = { projectDir: repoRoot(ctx.cwd) ?? ctx.cwd, launchDir: ctx.cwd }
     const authUi = authUiFor(ctx)
+    sessionAuthUi = authUi
     // The allow/deny lists filter every scope, including a managed-mcp.json set. They
     // merge from managed settings plus the trust-gated settings chain, as Claude
     // documents (a repo's file counts only once the project is approved).