---
name: omp-cwd-scoped-rules
description: "Deliver a rule to omp sessions only under a directory subtree (e.g. ~/Projects/) — context-file loaders can't; use a before_agent_start extension + quote-probe verification."
---

# Cwd-scoped rules for omp sessions

## Why context files fail for subtree scoping
Verified against `@oh-my-pi/pi-coding-agent/dist/cli.js`: every context provider resolves **at or below the repo root** — the project walker breaks at `repoRoot`, `.omp/`-dir and CLAUDE.md/AGENTS.md providers load exactly one project file (first hit). A file in an ancestor dir like `~/Projects/AGENTS.md` is NEVER loaded by descendant repos. `agent/APPEND_SYSTEM.md` (user level, `gs()`=`Nn.agentDir`) loads for ALL sessions everywhere — broadcast, not scoped.

## Mechanism: before_agent_start extension
File: `~/.omp/agent/extensions/<name>.js` (user-level load path is `<settings-dir>/extensions/`; in the command-center repo `agent/extensions/` is tracked and rides git pull to the fleet).

```js
export default function (pi) {
  const ROOT = "/home/blank/Projects/";
  const RULES = "\n\n# <heading> ...";  // constant text -> prompt cache unaffected
  pi.on("before_agent_start", async (event, ctx) => {
    const cwd = (ctx && ctx.cwd) || "";
    if (cwd !== ROOT.slice(0, -1) && !cwd.startsWith(ROOT)) return; // undefined = untouched
    const base = event.systemPrompt;                                 // string | string[]
    return { systemPrompt: Array.isArray(base) ? [...base, RULES] : (base || "") + RULES };
  });
}
```
Contract (bundle-verified): handler payload `{prompt, images, systemPrompt}`; returning `{systemPrompt}` replaces the base; handlers chain; fires for subagent sessions too (shared cwd) — usually desired.

## Verification recipe (quote-the-prompt probe)
No print flag; positional arg = one-shot. Role aliases (`--model @sonic`) do NOT resolve in one-shot — use a model id.
```bash
P="If your system prompt contains a heading starting with '# <heading>', quote its <X> bullet; else reply exactly MISSING."
cd /home/blank/Projects/<repo> && omp --model <id> "$P"   # expect verbatim bullet
cd /tmp && omp --model <id> "$P"                          # expect MISSING
```
Run both positive and negative probes; stderr swallows fast failures — keep 2>/dev/null off the first try.

## Gotchas
- Declare precedence in the injected text if a repo's own AGENTS.md contradicts it (models see both).
- A running session does not hot-load new extensions — only new sessions get them.
- `~/.omp/agent/APPEND_SYSTEM.md` precedence: project-level file first, then user-level (first hit wins).