docks-kit 0.22.28 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/AGENTS.md +42 -89
  2. package/README.md +35 -72
  3. package/cli/docs/command-guards.md +233 -197
  4. package/cli/docs/flags.md +17 -65
  5. package/cli/docs/install.md +2 -3
  6. package/cli/docs/omp-context.md +79 -7
  7. package/cli/docs/omp-models.md +27 -12
  8. package/cli/docs/overview.md +7 -18
  9. package/cli/docs/platforms.md +2 -2
  10. package/cli/docs/sync-layers.md +14 -60
  11. package/cli/docs/toolchain.md +12 -81
  12. package/cli/src/argv.ts +0 -12
  13. package/cli/src/argvValidate.ts +3 -54
  14. package/cli/src/commands/docs.ts +3 -15
  15. package/cli/src/commands/omp.ts +1 -1
  16. package/cli/src/commands/scratch.ts +1 -1
  17. package/cli/src/commands/sync.ts +5 -120
  18. package/cli/src/commands/tidy.ts +1 -1
  19. package/cli/src/commands/toolchain.ts +4 -12
  20. package/cli/src/engine-native/DESIGN.md +69 -100
  21. package/cli/src/engine-native/deps.ts +7 -92
  22. package/cli/src/engine-native/engineCtx.ts +9 -103
  23. package/cli/src/engine-native/exec.ts +1 -18
  24. package/cli/src/engine-native/index.ts +6 -8
  25. package/cli/src/engine-native/jq.ts +4 -37
  26. package/cli/src/engine-native/kitDb.ts +21 -37
  27. package/cli/src/engine-native/modes.ts +3 -132
  28. package/cli/src/engine-native/ompFastMode.ts +1 -1
  29. package/cli/src/engine-native/ompOverlay.ts +1 -1
  30. package/cli/src/engine-native/ompRemovals.ts +24 -3
  31. package/cli/src/engine-native/ompSession.ts +67 -0
  32. package/cli/src/engine-native/ompSync.ts +1 -1
  33. package/cli/src/engine-native/os/darwin.ts +0 -4
  34. package/cli/src/engine-native/os/index.ts +1 -2
  35. package/cli/src/engine-native/os/linux.ts +0 -3
  36. package/cli/src/engine-native/os/posix.ts +2 -47
  37. package/cli/src/engine-native/os/types.ts +1 -36
  38. package/cli/src/engine-native/os/windows.ts +0 -50
  39. package/cli/src/engine-native/parseArgs.ts +7 -180
  40. package/cli/src/engine-native/parseHelp.ts +4 -44
  41. package/cli/src/engine-native/scratch.ts +1 -1
  42. package/cli/src/engine-native/services.ts +1 -2
  43. package/cli/src/engine-native/sharedTypes.d.ts +1 -41
  44. package/cli/src/engine-native/syncConcurrency.ts +3 -15
  45. package/cli/src/engine-native/syncDispatch.ts +30 -143
  46. package/cli/src/engine-native/toolchain.ts +6 -45
  47. package/cli/src/engine.ts +0 -75
  48. package/cli/src/generated/sotPayload.ts +14 -43
  49. package/cli/src/main.ts +8 -24
  50. package/cli/src/payload.ts +2 -8
  51. package/cli/tsconfig.json +1 -3
  52. package/package.json +3 -5
  53. package/cli/docs/models.md +0 -58
  54. package/cli/docs/modifiers.md +0 -52
  55. package/cli/docs/plugins.md +0 -70
  56. package/cli/src/checklistPrompt.ts +0 -464
  57. package/cli/src/commands/harnesses.ts +0 -80
  58. package/cli/src/commands/model.ts +0 -68
  59. package/cli/src/commands/models.ts +0 -75
  60. package/cli/src/commands/plugins.ts +0 -35
  61. package/cli/src/commands/skills.ts +0 -40
  62. package/cli/src/commands/status.ts +0 -206
  63. package/cli/src/efforts.ts +0 -89
  64. package/cli/src/engine-native/claudeLsp.ts +0 -301
  65. package/cli/src/engine-native/claudeOptionalPlugins.ts +0 -126
  66. package/cli/src/engine-native/claudePluginPasses.ts +0 -426
  67. package/cli/src/engine-native/claudeRemovals.ts +0 -383
  68. package/cli/src/engine-native/claudeRetired.ts +0 -165
  69. package/cli/src/engine-native/claudeRuntime.ts +0 -157
  70. package/cli/src/engine-native/claudeSettings.ts +0 -201
  71. package/cli/src/engine-native/claudeSettingsModifiers.ts +0 -115
  72. package/cli/src/engine-native/claudeSync.ts +0 -312
  73. package/cli/src/engine-native/codexConfig.ts +0 -214
  74. package/cli/src/engine-native/codexHooks.ts +0 -91
  75. package/cli/src/engine-native/codexPaths.ts +0 -14
  76. package/cli/src/engine-native/codexPlugins.ts +0 -315
  77. package/cli/src/engine-native/codexStatus.ts +0 -25
  78. package/cli/src/engine-native/codexSync.ts +0 -314
  79. package/cli/src/engine-native/codexToml.ts +0 -303
  80. package/cli/src/engine-native/harnesses.ts +0 -138
  81. package/cli/src/engine-native/liveModels.ts +0 -264
  82. package/cli/src/engine-native/models.ts +0 -101
  83. package/cli/src/engine-native/parseModifiers.ts +0 -225
  84. package/cli/src/engine-native/settings.ts +0 -42
  85. package/cli/src/engine-native/skillsInstall.ts +0 -135
  86. package/cli/src/engine-native/skillsLinks.ts +0 -216
  87. package/cli/src/engine-native/skillsManifest.ts +0 -36
  88. package/cli/src/engine-native/skillsPrune.ts +0 -117
  89. package/cli/src/engine-native/skillsRecords.ts +0 -138
  90. package/cli/src/engine-native/skillsSync.ts +0 -57
  91. package/cli/src/engine-native/tomlLines.ts +0 -92
  92. package/cli/src/manifests.ts +0 -145
  93. package/cli/src/terminalCells.ts +0 -191
@@ -1,20 +1,16 @@
1
1
  # Command guards
2
2
 
3
- The kit ships one destructive-command policy to omp, Claude Code, and Codex.
3
+ The kit ships one destructive-command policy to omp.
4
4
  The short rule for agents: **to remove, use the trash**. Run
5
- `gio trash -- <path>` on Linux or `trash <path>` on macOS. In omp, remove a
5
+ `gio trash -- <path>` on Linux or `trash <path>` on macOS. Remove a
6
6
  temporary file or directory with `docks-kit scratch remove <path>` instead.
7
7
  To remove a path from the git index, run `git rm -- <path>`.
8
8
 
9
- Claude Code and Codex follow one principle: **fail closed**. A command is
10
- allowed only in a canonical form that is safe by construction, and every other
11
- form that could force, empty, or delete asks. omp keeps only the deny part of
12
- that principle. Where omp's critical-command check acts, the form is denied
13
- instead of asked. omp also denies a `$` or a backtick after `git push`,
14
- because the agent can always write the ref literally. A false positive in the
15
- ask tier is accepted.
9
+ The policy keeps only deny rules. Where omp's critical-command check acts,
10
+ the form is denied. omp also denies a `$` or a backtick after `git push`,
11
+ because the agent can always write the ref literally.
16
12
 
17
- omp is the exception: by owner decision (0.22.8, #126), the kit ships no omp
13
+ By owner decision (0.22.8, #126), the kit ships no omp
18
14
  prompt rule. The kit's `bash.patterns` holds only deny rules and the `trash *`
19
15
  allow. Under omp's default `tools.approvalMode: yolo`, omp runs every
20
16
  command that no deny matches without a question, in the main session and in
@@ -33,49 +29,44 @@ A subagent does not run a bulk discard and names it in its report. The omp
33
29
  agent prompt lists a force push as a step that needs `ask`. The section
34
30
  "omp trigger rules" below describes these rules.
35
31
 
36
- The policy sorts shell commands into three tiers. omp uses two of them: deny
37
- and allow.
32
+ The policy sorts shell commands into two tiers.
38
33
 
39
34
  - **Deny**: the command never runs, and nobody can approve it in the session.
40
- - **Ask**: the command needs approval before it runs. The kit ships no omp
41
- rule in this tier.
42
- - Claude Code asks a person, even in auto mode.
43
- - Codex sends the prompt to the approvals reviewer in the kit's
44
- `config.toml`. That reviewer is `auto_review`, a reviewer subagent, so a
45
- Codex ask can be approved without a person.
46
- - **Allow**: the agent may run the command alone. In omp, a command that no
47
- rule matches runs too. The table below calls this `run`.
35
+ - **Allow**: the agent may run the command alone. A command that no rule
36
+ matches runs too. The table below calls this `run`.
37
+
38
+ A prompt rule that the user adds asks a person in the main session, and a
39
+ subagent rejects it.
48
40
 
49
41
  The omp `eval` tool stays unrestricted: `bash.patterns` does not gate a shell
50
42
  that `eval` starts.
51
43
 
52
- ## Tiers per tool
53
-
54
- | Command | omp `bash.patterns` | Claude Code `permissions` | Codex `docks.rules` |
55
- | --- | --- | --- | --- |
56
- | `rm` of `/`, `~`, `~/`, `$HOME`, `${HOME}`, quoted or with a trailing `/` | deny | deny, also through `/bin/rm` and other `*/rm` paths | deny `/` as argv; deny the exact scripts listed in `docks.rules` |
57
- | `rm` of `/*` | deny with an `r` or `f` option; plain `rm /*` runs | deny | deny the exact scripts listed |
58
- | `HOME=...`, `export HOME=...`, `env HOME=...` | deny | deny `export`, `env`, and a bare `HOME=...` line; `HOME=... cmd` goes to the classifier | deny `export HOME=$(mktemp -d)` and three spellings; `env` asks |
59
- | `sudo` before `rm`, plain or by path (`/usr/bin/sudo`) | deny | deny (`sudo *`, `*/sudo *`) | deny (`sudo`, resolved by path) |
60
- | `git push --force` or `-f` to `origin main` or `origin master` | deny | deny | deny |
61
- | Recursive `rm` (`-r`, `-R`, `-rf`, `-fr`, `-rfv`, `-ri`, `-ir`, `-Ri`, `-iR`, `--recursive`, other listed clusters) | deny, also behind any prefix (`env`, `xargs`, `nice`, `find -exec`, `git rm -r`) | ask | ask (every `rm` asks) |
62
- | `rm` with an `r` or `f` option before an absolute path, `--no-preserve-root` | deny | ask if recursive, else classifier | ask |
63
- | Any other `rm`: one file, several files, a glob, `-f` | run | glob asks; the rest goes to the classifier | ask |
64
- | `find ... -delete`, `find ... -exec rm` (also `-execdir`, `-ok`, `-okdir`), `xargs rm` | deny, in every position and by path | ask for `-delete`, `-exec rm` and `-execdir rm`; `-ok`/`-okdir rm` and a non-recursive `xargs rm` go to the classifier | ask (every `find` asks) |
65
- | `git clean`, `git reset --hard` | run | ask | ask |
66
- | `git push` that could force: see below | run, unless a deny above matches | ask | ask (every `git push` asks) |
67
- | A `$` or a backtick anywhere after `git push` in the same command | deny, also after a shell keyword, a wrapper, or a path before `git`: see below | ask for a word that starts with `$` or a backtick | ask (every `git push` asks) |
68
- | A git command that skips the repository's hooks: see below | run | no rule; the classifier decides | ask for each `git push`, `git merge`, and `git rebase` that starts the command; no rule for `git commit`, `git am`, or `git pull` |
69
- | `git rm -- <path>`, `git worktree remove -- <path>` | run | ask | ask |
70
- | `git worktree remove --force -- <path>` | run; the omp `file-removal.md` trigger rule fires on each `--force`, `-f`, or `--f` form and permits it once, after the commits are on the remote | ask | ask |
71
- | `docks-kit scratch remove <path>` | run; the command removes only a path inside the scratch root, the system temporary directory, or `/var/tmp` | no rule | no rule |
72
- | Any other non-recursive `git rm` or `git worktree remove` | run | ask | ask |
73
- | `gio trash -- <path>` | run | allow | ask |
74
- | Any other `gio trash` | run | ask with `--empty` or `--restore`; the rest goes to the classifier | ask |
75
- | `trash <path>` (macOS) | allow | allow | allow |
76
-
77
- In Claude Code, a `git push` asks when it holds any of these words. Codex
78
- asks for every `git push`. omp runs each of these forms. Its force-push deny
44
+ ## Tiers
45
+
46
+ | Command | omp `bash.patterns` |
47
+ | --- | --- |
48
+ | `rm` of `/`, `~`, `~/`, `$HOME`, `${HOME}`, quoted or with a trailing `/` | deny |
49
+ | `rm` of `/*` | deny with an `r` or `f` option; plain `rm /*` runs |
50
+ | `HOME=...`, `export HOME=...`, `env HOME=...` | deny |
51
+ | `sudo` before `rm`, plain or by path (`/usr/bin/sudo`) | deny |
52
+ | `git push --force` or `-f` to `origin main` or `origin master` | deny |
53
+ | Recursive `rm` (`-r`, `-R`, `-rf`, `-fr`, `-rfv`, `-ri`, `-ir`, `-Ri`, `-iR`, `--recursive`, other listed clusters) | deny, also behind any prefix (`env`, `xargs`, `nice`, `find -exec`, `git rm -r`) |
54
+ | `rm` with an `r` or `f` option before an absolute path, `--no-preserve-root` | deny |
55
+ | Any other `rm`: one file, several files, a glob, `-f` | run |
56
+ | `find ... -delete`, `find ... -exec rm` (also `-execdir`, `-ok`, `-okdir`), `xargs rm` | deny, in every position and by path |
57
+ | `git clean`, `git reset --hard` | run |
58
+ | `git push` that could force: see below | run, unless a deny above matches |
59
+ | A `$` or a backtick anywhere after `git push` in the same command | deny, also after a shell keyword, a wrapper, or a path before `git`: see below |
60
+ | A git command that skips the repository's hooks: see below | run |
61
+ | `git rm -- <path>`, `git worktree remove -- <path>` | run |
62
+ | `git worktree remove --force -- <path>` | run; the omp `file-removal.md` trigger rule fires on each `--force`, `-f`, or `--f` form and permits it once, after the commits are on the remote |
63
+ | `docks-kit scratch remove <path>` | run; the command removes only a path inside the scratch root, the system temporary directory, or `/var/tmp` |
64
+ | Any other non-recursive `git rm` or `git worktree remove` | run |
65
+ | `gio trash -- <path>` | run |
66
+ | Any other `gio trash` | run |
67
+ | `trash <path>` (macOS) | allow |
68
+
69
+ omp runs each of these `git push` forms, which can force. Its force-push deny
79
70
  matches only `git push --force` or `git push -f` directly before
80
71
  `origin main` or `origin master`:
81
72
 
@@ -90,8 +81,7 @@ matches only `git push --force` or `git push -f` directly before
90
81
  denies a `$` or a backtick anywhere after `git push`.
91
82
 
92
83
  Each of these must begin a word: `feat/cache-vf` is a branch name, not an
93
- option. In Claude Code, `--follow-tags` also asks. This is an accepted false
94
- positive, because it shares the `--f` prefix.
84
+ option.
95
85
 
96
86
  A `$` or a backtick hides the ref until the shell expands it, so the matcher
97
87
  cannot tell `$b` from `+main` or `--force`. An unquoted value inside a word
@@ -116,52 +106,33 @@ A git command can skip the repository's hooks, for example with
116
106
  `--no-verify`, `git commit -n`, `git am -n`, or a `core.hooksPath` change.
117
107
  The kit ships no omp `bash.patterns` rule for these commands, so omp does not
118
108
  block them. The omp `git-safety.md` trigger rule forbids each hook skip.
119
- Claude Code has no rule either, so its classifier decides. Codex asks for each
120
- `git push`, `git merge`, and `git rebase` that starts the command. Codex has
121
- no rule for `git commit`, `git am`, or `git pull`.
122
-
123
- ## Why the tools differ
124
-
125
- | Topic | omp | Claude Code | Codex |
126
- | --- | --- | --- | --- |
127
- | Rule order | First match wins | Deny, then ask, then allow, whatever the order | Strictest matching rule wins |
128
- | Exception for one form | The kit ships no omp prompt rule, so it needs no exception | An allow never beats a matching ask, so every `git rm` asks | An allow never beats a matching prompt, so every `gio trash` asks |
129
- | Pattern | Glob on the whole line and on each quote-stripped segment; `*` crosses spaces; no literal `*` | Glob on each subcommand as written, quotes included; `\*` is a literal `*` | Exact argv tokens from the start, with alternatives |
130
- | `rm` by path (`/bin/rm`) | Matched by `*/rm` forms | Matched by `*/rm` forms | Resolved to the `rm` rules |
131
- | Leading assignment `X=1 cmd` | Part of the line | Stripped before deny and ask rules | A script with it is not split |
132
- | What an ask means | The kit ships no ask; a user prompt rule asks a person in the main session, and a subagent rejects it | A person | The `auto_review` reviewer subagent |
133
- | Critical-command check | Turns a prompt into an allow under yolo, so the kit denies those shapes | Asks or denies for an `rm` of a critical path | Prompts for a forced `rm` that no rule matches |
134
109
 
135
110
  ## How an agent removes files
136
111
 
137
- 1. In omp, remove a temporary file or directory with the `scratch_remove`
138
- tool or `docks-kit scratch remove <path>`. The command removes only a path
139
- inside the scratch root, the system temporary directory, or `/var/tmp`.
112
+ 1. Remove a temporary file or directory with the `scratch_remove` tool or
113
+ `docks-kit scratch remove <path>`. The command removes only a path inside
114
+ the scratch root, the system temporary directory, or `/var/tmp`.
140
115
  `gio trash` does not trash on a system internal mount, such as a `tmpfs`
141
116
  `/tmp`.
142
117
  2. Move every other file or directory to the trash with `gio trash -- <path>`
143
118
  on Linux or `trash <path>` on macOS. The `--` ends option parsing, so `gio`
144
119
  reads every later argument as a path, and a path such as `--empty` cannot
145
- empty the trash. In Claude Code and Codex, leave a temporary file in
146
- `/tmp`; the system clears it.
120
+ empty the trash.
147
121
  3. To remove a path from the git index, run `git rm -- <path>`. To remove a
148
- worktree, run `git worktree remove -- <path>`. In omp, when git refuses
149
- because the worktree has changes, the agent may pass `--force` once, after
150
- each commit is on the remote and `git status --porcelain` lists only
151
- generated files. Never pass `--force` two times.
152
- 4. In omp, do not use `rm`. omp denies a recursive `rm`, `find -delete`,
122
+ worktree, run `git worktree remove -- <path>`. When git refuses because the
123
+ worktree has changes, the agent may pass `--force` once, after each commit
124
+ is on the remote and `git status --porcelain` lists only generated files.
125
+ Never pass `--force` two times.
126
+ 4. Do not use `rm`. omp denies a recursive `rm`, `find -delete`,
153
127
  `find -exec rm`, and `xargs rm`. It runs any other `rm` without a prompt.
154
- 5. In Claude Code and Codex, use `rm <file>` without flags only for one file
155
- that the agent created.
156
- 6. For a recursive or bulk deletion, ask the user in the main session. A
157
- subagent lists the paths in its final report. In omp, the user runs a
158
- recursive deletion by hand.
159
- 7. Write literal absolute paths. Never use `~` or `$HOME`, and never set or
128
+ 5. For a recursive or bulk deletion, ask the user in the main session. A
129
+ subagent lists the paths in its final report. The user runs a recursive
130
+ deletion by hand.
131
+ 6. Write literal absolute paths. Never use `~` or `$HOME`, and never set or
160
132
  export `HOME`.
161
133
 
162
- In omp, the kit plugin trigger rules `file-removal.md` and `literal-paths.md`
163
- carry these rules. `~/.claude/CLAUDE.md` and the Codex `AGENTS.md` carry the
164
- same rules.
134
+ The kit plugin trigger rules `file-removal.md` and `literal-paths.md` carry
135
+ these rules.
165
136
 
166
137
  ### What the git removals keep
167
138
 
@@ -233,20 +204,102 @@ command before they decide, because `-n` or `--staged` can come last.
233
204
  The buffer is the argument JSON text, and omp's schema puts the intent field
234
205
  `i` before `command`. A call can also put `i` after `command`, and a provider
235
206
  can stream JSON with white space, such as `{"command": "ls"}`. Each condition
236
- has the lookbehind `(?<="(?:command|code)"\s*:\s*"(?:\\.|[^"\\])*)` before
237
- its first command token, so a match starts only inside the `command` or
238
- `code` string, with or without JSON white space around the colon. omp 18.21.0
239
- accepts this variable-length lookbehind. A scan reads an escape pair, such as
240
- `\"` or `\\`, as one unit. It stops at an unescaped `"`, which ends the
241
- command string, and at a newline (`\n`), which ends the command line. So the
242
- intent text and the next line do not fire a rule. A tab in a command is `\t`
243
- in the buffer, so each condition reads `\t` as shell white space, as it reads
244
- a space. A scan that looks for an option also stops at a ` -- ` word, also
245
- with a tab, because each later word is a path. So `git clean -fd -- -n`
246
- fires, and `git rm -- -f` stays quiet. In the `git push` conditions for `$`,
247
- a backtick, and a chain, a scan also stops at `)` and at a backtick, which end
248
- a JavaScript `` sh`…` `` or `sh("…")` call. A backtick counts as a command
207
+ starts its match with the forward key prefix, after an optional inline flag
208
+ group:
209
+
210
+ ```text
211
+ "(?:command|code)"\s*:\s*"[^"\\]*?(?:\\.[^"\\]*?\\.[^"\\]*?\\.[^"\\]*?\\.[^"\\]*?\\.[^"\\]*?\\.[^"\\]*?\\.[^"\\]*?\\.[^"\\]*?)*?(?:\\.[^"\\]*?){0,7}?
212
+ ```
213
+
214
+ The prefix matches the `command` or `code` key, with or without JSON white
215
+ space around the colon. Then it walks the string body forward and steps over
216
+ one escape pair, such as `\"` or `\\`, as one unit. Each loop step takes up to
217
+ 8 escape pairs. So the JavaScriptCore regex JIT handles about 8 times more
218
+ escapes before it falls back to its slower interpreter. The walk never passes
219
+ an unescaped `"`, so the key prefix starts at the key and stays inside that
220
+ string. Only the prefix gives this guarantee. A scan stops at an unescaped
221
+ `"`, which ends the command string, and at a newline (`\n`), which ends the
222
+ command line. So the intent text and the next line do not fire a rule. A
223
+ known limit: a part of a condition that is not such a scan, such as
224
+ `[^)]*`, can cross the closing quote, and the match then continues into a
225
+ later field. For example, the `Bun.file` condition of `file-removal.md`
226
+ matches `{"code":"Bun.file(","i":").delete("}`. A tab in a command is `\t` in
227
+ the buffer, so each condition reads `\t` as shell white space, as it reads a
228
+ space. A scan that looks for an option also stops at a ` -- ` word, also with
229
+ a tab, because each later word is a path. So `git clean -fd -- -n` fires, and
230
+ `git rm -- -f` stays quiet. In the `git push` conditions for `$`, a backtick,
231
+ and a chain, a scan also stops at `)` and at a backtick, which end a
232
+ JavaScript `` sh`…` `` or `sh("…")` call. A backtick counts as a command
249
233
  substitution only when a word follows it.
234
+ omp's `Matched:` excerpt is a bounded window around the match start, not the
235
+ full match (`packages/coding-agent/src/export/ttsr.ts` in omp 19.0.0). The
236
+ window starts up to 60 characters before the match start, so it can show the
237
+ end of the intent field. omp keeps at most 120 characters of the match and
238
+ up to 60 characters after them. So a long match is cut at 180 characters from
239
+ its start. omp replaces each white space run with one space and marks a cut
240
+ end with `…`. In a long call, the trigger can be more than 180 characters
241
+ after the key, and then the trigger is outside the excerpt.
242
+
243
+ omp 19.0.0 tests every condition on the whole buffer at each streamed delta,
244
+ on its main thread, in JavaScriptCore. From 0.22.24 to 0.22.29, each
245
+ condition started with a variable-length lookbehind over the key and the
246
+ string body. A leading unbounded lookbehind walks back over the buffer from
247
+ every position. On a 20 KB tool call, one scan took seconds and froze the omp
248
+ session. Past JavaScriptCore's match limit, the scan also reported no match,
249
+ so the rule did not fire.
250
+
251
+ A forward key prefix alone does not make a condition linear. Three input
252
+ families can still make a scan slow:
253
+
254
+ - A dense line: one long line that repeats a command start, such as
255
+ `git restore `. If the scan of each command start runs to the end of the
256
+ line, the time grows with the square of the line length.
257
+ - A head and a run: one command start, such as `aws `, and then one long run,
258
+ such as `x x x`. A group loop inside a lookaround makes JavaScriptCore keep
259
+ each loop step until the match attempt ends. The regex then drops out of
260
+ the JIT. One `remote-cleanup.md` condition took 0.9 ms at 16 KB and 82 ms at
261
+ 64 KB.
262
+ - An open buffer: the buffer stops before the closing quote of the command.
263
+ omp tests the buffer after each streamed delta, so most real scans see no
264
+ closing quote, and a scan cannot use it as a stop.
265
+
266
+ A command start inside the option region of an earlier command start, and
267
+ text with many escapes, need care too. So each condition has this form:
268
+
269
+ - The match starts at the forward key prefix.
270
+ - Each scan after a command start is one lazy walk that stops at its first
271
+ event: `(?=(?<w>[\s\S]*?)(?=EVENT)BOUNDARY)\k<w>`. The events are the flag
272
+ that the condition looks for, a terminator, the end of the run, and the
273
+ next command start. A lookahead in JavaScript does not backtrack after it
274
+ matches, so `\k<w>` consumes the walk as one frozen piece.
275
+ - An event counts only at a real token boundary: no odd run of backslashes
276
+ comes before it.
277
+ - A scan stops at a later command start, because the scan of that command
278
+ start reads the same remaining text. So two scans never read the same
279
+ text, and a dense line costs linear time.
280
+ - Some conditions find the flag first and then walk back once to the head of
281
+ the command. Their head allows wrapper words, such as `sudo` or `env`, or
282
+ `KEY=value` words before the command, as in `LC_ALL=C rm`.
283
+
284
+ The rewrite gives the same result as the rules of 0.22.29 on each input that
285
+ the checks tried. The checks are the 2697 rows of the test table, a fuzz run
286
+ of 5 times 310,825 buffers on all 69 conditions, and an enumeration of every
287
+ token sequence of up to 6 or 7 tokens for each condition. The enumeration
288
+ used closed and open buffers. No result changed, and no match was lost or
289
+ added.
290
+
291
+ Write each new condition by these rules:
292
+
293
+ - Start the match with the forward key prefix. Never start a condition with
294
+ an unbounded lookbehind.
295
+ - Make each scan one frozen walk that stops at its first event and at the
296
+ next command start.
297
+ - Never put a group loop inside a lookaround over text of unbounded length.
298
+ - Run `bunx vitest run cli/test/unit/ompTriggerRules.test.ts`. It runs the
299
+ shape guard and the Bun backstop.
300
+ - When you rewrite a condition, run the old and the new condition on each
301
+ buffer of the test table, and make sure that both give the same result.
302
+
250
303
  `cli/test/unit/ompTriggerRules.test.ts` runs each shell row through bash,
251
304
  Python `sh("…")`, JavaScript `` sh`…` ``, and JavaScript `sh("…");`. It runs
252
305
  every row in the compact JSON layout (`{"command":"ls"}`) and in the spaced
@@ -256,6 +309,35 @@ before or after the command, or put a tab in the command. The test checks
256
309
  that each correct form stays quiet on each prefix, that each condition has a
257
310
  wrong row that fires it, and that each rule has `repeatMode: always`.
258
311
 
312
+ Its shape guard checks only what a static check can prove. Each condition
313
+ must start with the forward key prefix, and this rejects the leading
314
+ lookbehind that froze omp. No `|` can stand outside every group, because the
315
+ alternative after it needs no key prefix. The shape guard cannot prove
316
+ linear time. The backstop tests the measured input families for linear
317
+ time: the test runs `cli/test/lib/ompTriggerBackstop.ts` under Bun, because
318
+ the unit tests run on V8, which does not show the JavaScriptCore cost. A
319
+ condition can still backtrack on a run that no generator holds, so a new
320
+ condition needs a new family when its shape is new. The backstop has these
321
+ checks:
322
+
323
+ - Time budget, with the regex JIT on: one pass of all conditions over a
324
+ 20 KB Python cell, a 20 KB bash command, and a 30 KB `KEY=value` chain
325
+ stays under 250 ms for each buffer.
326
+ - Fire, with the regex JIT on: `git reset --hard` at the end of the 20 KB
327
+ cell fires `git-safety.md`.
328
+ - Scaling, with the regex JIT off: each condition alone, on each adversarial
329
+ input shape, at 16 KB and 64 KB.
330
+ - Dense and head-and-run scaling, with the regex JIT on: each condition
331
+ alone, on the two families above, at 16 KB and 64 KB. Each line goes into a
332
+ bash command, an open bash command without its closing quote, and a Python
333
+ `sh("…")` cell.
334
+
335
+ In each scaling check, the 64 KB time must stay at most 8 times the 16 KB
336
+ time plus 15 ms, and at most 100 ms. The backstop times the pairs in parallel
337
+ child processes first. Each pair that fails there gets a second, serial run,
338
+ and it fails only when it fails there too. A call of 1000 ms or more fails at
339
+ once.
340
+
259
341
  ## Why omp denies instead of asking
260
342
 
261
343
  omp has a built-in check for critical commands. For example, it flags:
@@ -263,11 +345,14 @@ omp has a built-in check for critical commands. For example, it flags:
263
345
  - an `rm` with an `r` or `f` option before an absolute path;
264
346
  - `sudo rm`, also when `sudo` is called by its path.
265
347
 
266
- For a critical command, omp returns a bare safety override before it returns
267
- a matching prompt rule. Under omp's default `tools.approvalMode: yolo`,
268
- omp ignores a bare override, so the command runs. This applies in subagents
269
- too.
270
- Only a deny rule stops a critical command (`omp://approval-mode.md`).
348
+ omp 19.0.0 checks deny and prompt rules first, then its critical patterns, then
349
+ allow rules. A critical command that no deny or prompt rule matches gets a bare
350
+ safety override, which also replaces a matching allow. Under omp's default
351
+ `tools.approvalMode: yolo`, omp ignores a bare override, so the command runs.
352
+ This applies in subagents too. A prompt rule would ask a person in the main
353
+ session, but a subagent rejects every prompt, so the kit ships none. Only a
354
+ deny rule stops a critical command in every session (`BashTool.approval` in
355
+ the v19.0.0 source).
271
356
 
272
357
  The kit therefore denies every `rm` shape that the check can flag:
273
358
 
@@ -281,33 +366,21 @@ The kit also denies bulk removal through `find -delete`, `find -exec rm`, and
281
366
  the home directory, and no glob can express "inside the temporary directory".
282
367
  `docks-kit scratch remove` checks the path in code instead.
283
368
 
284
- ## Matching rules per tool
285
-
286
- - **omp**:
287
- - The rules are ordered, and the first match wins.
288
- - `*` matches any text, spaces included, and no escape spells a literal `*`.
289
- - Deny rules test the whole line and each segment between `;`, `&&`, `|`,
290
- and similar operators, with quotes and escapes removed. So
291
- `rm -rf "$HOME"` matches `rm * $HOME`.
292
- - Allow rules apply only to a simple command.
293
- - The kit ships no prompt rule. It lists rules as deny, then the `trash *`
294
- allow.
295
- - **Claude Code**:
296
- - Deny beats ask, and ask beats allow, whatever the order.
297
- - The rules match the command text as written, quotes included, so the kit
298
- lists each quoted spelling. `\*` is a literal `*`.
299
- - Claude Code strips wrappers such as `timeout` and bare `xargs`. It matches
300
- deny and ask rules past a leading variable assignment, and it applies them
301
- to every subcommand.
302
- - A rule for `rm` does not match `/bin/rm`, so the kit adds `*/rm` forms.
303
- - **Codex**:
304
- - A rule matches argv tokens from the start, and the strictest matching rule
305
- wins.
306
- - Codex splits a `bash -lc` script into argv only when every word is a plain
307
- literal. A script with `~`, `$HOME`, a glob, or a substitution stays one
308
- `[shell, -lc, script]` invocation, so a rule can match only that exact
309
- script.
310
- - Codex resolves `/bin/rm` and `/usr/bin/sudo` to the `rm` and `sudo` rules.
369
+ ## Matching rules
370
+
371
+ - For a simple command, the rules are ordered, and the first match wins.
372
+ - `*` matches any text, spaces included, and no escape spells a literal `*`.
373
+ - Deny rules test the whole line and each segment between `;`, `&&`, `|`,
374
+ and similar operators, with quotes and escapes removed. So
375
+ `rm -rf "$HOME"` matches `rm * $HOME`. A segment also matches without its
376
+ leading `NAME=value` words.
377
+ - For a line with shell control, each segment takes its first matching deny
378
+ or prompt rule. A deny chosen for one segment wins over a prompt chosen
379
+ for another segment; within one segment, a prompt rule that comes first
380
+ wins over a later deny.
381
+ - Allow rules apply only to a simple command.
382
+ - The kit ships no prompt rule. It lists rules as deny, then the `trash *`
383
+ allow.
311
384
 
312
385
  ## Gaps
313
386
 
@@ -334,15 +407,13 @@ the home directory, and no glob can express "inside the temporary directory".
334
407
  - **omp, bulk-removal text**: the `* find *-delete*`, `*-exec rm *`, and
335
408
  `*xargs rm` rules also match text, so a line such as
336
409
  `echo use find with -delete` is denied. Write such text to a file instead.
337
- - **Recursive `rm` clusters**: omp and Claude Code match only the listed
338
- recursive-`rm` clusters. In omp, these are `r` or `R` alone or with `f` and
339
- `v`, plus `-ri`, `-ir`, `-Ri`, and `-iR`. In Claude Code, they are `r` or `R`
340
- alone or with `f` and `v`. Another cluster falls back to the tool's next
341
- tier. In omp, the command runs. In Claude Code, the classifier decides.
410
+ - **omp, recursive `rm` clusters**: omp matches only the listed
411
+ recursive-`rm` clusters: `r` or `R` alone or with `f` and `v`, plus `-ri`,
412
+ `-ir`, `-Ri`, and `-iR`. Another cluster runs.
342
413
  - **`git push` beyond the listed words**: a configured `+` refspec in
343
414
  `remote.<name>.push` makes a plain `git push` force. No rule sees git
344
415
  configuration. `git push --delete` and `git push --prune` remove remote
345
- branches without force; they ask only in Codex.
416
+ branches without force; no kit rule asks for them.
346
417
  - **omp, force push to `main` in another spelling**: the force-push deny
347
418
  rules match only `git push --force` or `git push -f`, then
348
419
  `origin main` or `origin master`. Every other force push to `main` runs
@@ -355,27 +426,11 @@ the home directory, and no glob can express "inside the temporary directory".
355
426
  a wrapper, or a path runs without a check, such as
356
427
  `for r in a; do git push --force origin main; done`,
357
428
  `env git push --force origin main`, or `/usr/bin/git push --force origin main`.
358
- - **`git -C`**: no tool matches a git subcommand that does not follow `git`
429
+ - **`git -C`**: no rule matches a git subcommand that does not follow `git`
359
430
  directly, such as `git -C . push --force origin main` or
360
431
  `git -C . push origin $b`.
361
- - **Claude Code, `HOME=` before a command**: Claude Code matches deny rules
362
- past a leading assignment. So `HOME=/tmp/x cmd` reaches the classifier.
363
- `export HOME=...`, `env HOME=...`, a bare `HOME=...` line, and any `rm` of
364
- `$HOME` stay denied.
365
- - **Claude Code, unlisted `rm` forms**: a multi-file `rm` and an `rm -f` of
366
- one file go to the auto-mode classifier. Claude Code does not strip `env`, so
367
- `env X=1 rm -rf ~` also goes to the classifier.
368
- - **Claude Code, `gio trash`**: a `gio trash` form other than `-- <path>` that
369
- holds neither `--empty` nor `--restore` goes to the classifier. GLib's
370
- `gio trash` supports no abbreviated long options.
371
- - **Codex, scripts**: a home or root deletion inside a longer script, such as
372
- `cd x && rm -rf ~`, falls to Codex's built-in forced-`rm` prompt and to the
373
- sandbox. Codex matches `HOME=` reassignment only as an exact script, and
374
- `export HOME=/tmp` runs sandboxed. Each Codex command runs in a new shell.
375
- - **Codex, prompt reviewer**: a Codex prompt reaches the `auto_review`
376
- reviewer subagent, not always a person.
377
- - **All tools**: no rule covers a program that removes files itself, such as a
378
- Python or Node script, or a shell started by omp `eval`.
432
+ - **Programs that remove files**: no rule covers a program that removes files
433
+ itself, such as a Python or Node script, or a shell started by omp `eval`.
379
434
 
380
435
  ### How `gio trash` empties the trash
381
436
 
@@ -384,61 +439,42 @@ or restores the paths, and `--empty` has no effect. Without a path, it empties
384
439
  the trash when `--empty` is set. `-f` can repeat. So `gio trash -ff --empty`
385
440
  empties the trash, while `gio trash build --empty` only trashes `build`.
386
441
 
387
- In Codex, every `gio trash` asks, because a prefix rule cannot tell
388
- `-ff --empty` from `-- <path>`. In omp, every `gio trash` runs without a
389
- prompt. In Claude Code, any form with `--empty` or `--restore` asks.
442
+ omp runs every `gio trash` without a prompt.
390
443
 
391
444
  ## Sync behavior
392
445
 
393
- - **omp**:
394
- - The config merge keeps user `bash.patterns` rules and groups all rules in
395
- this order:
396
- 1. kit deny;
397
- 2. user deny;
398
- 3. user prompt;
399
- 4. kit prompt (the kit ships none since 0.22.8);
400
- 5. the other user rules;
401
- 6. kit allow.
402
- - A user deny or prompt thus precedes every kit allow, and no allow can
403
- loosen a deny or a prompt.
404
- - A repeat sync changes nothing.
405
- - After the merge, `ompRemovals.ts syncOmpRemovals, retired bash-rule
406
- inventory` removes the retired kit rules in `OMP_RETIRED_BASH_RULES` from
407
- the deployed `bash.patterns` on every sync. The inventory also holds the
408
- 492 prompt rules that the kit retired in 0.22.8. It removes a rule only
409
- when its `match` and `approval` equal a retired pair, so a different user
410
- rule stays.
411
- - **Claude Code**: sync unions each permissions array with the deployed one,
412
- so user rules stay. `--reconcile` replaces the arrays with the SoT arrays.
413
- - **Codex**: sync writes `~/.codex/rules/docks.rules` whole. Keep your own
414
- rules in another `.rules` file, such as `default.rules`. Codex applies the
415
- strictest rule across all files. Sync records each kit rules file in
416
- `~/.codex/.kit-managed-rules`. When the SoT drops a kit rules file, sync
417
- removes the deployed copy while it holds the kit bytes. A dropped file that
418
- you edited stays, and each sync warns about it. Sync never removes a file
419
- that it did not write, such as `default.rules`.
446
+ - The config merge keeps user `bash.patterns` rules and groups all rules in
447
+ this order:
448
+ 1. kit deny;
449
+ 2. user deny;
450
+ 3. user prompt;
451
+ 4. kit prompt (the kit ships none since 0.22.8);
452
+ 5. the other user rules;
453
+ 6. kit allow.
454
+ - A user deny or prompt thus precedes every kit allow, and no allow can
455
+ loosen a deny or a prompt.
456
+ - A repeat sync changes nothing.
457
+ - After the merge, `ompRemovals.ts syncOmpRemovals, retired bash-rule
458
+ inventory` removes the retired kit rules in `OMP_RETIRED_BASH_RULES` from
459
+ the deployed `bash.patterns` on every sync. The inventory also holds the
460
+ 492 prompt rules that the kit retired in 0.22.8. It removes a rule only
461
+ when its `match` and `approval` equal a retired pair, so a different user
462
+ rule stays.
420
463
 
421
464
  ## Check the deployed rules
422
465
 
423
- Each check below is safe, because the shell never reaches `rm`.
466
+ The check below is safe, because the shell never reaches `rm`.
424
467
 
425
- - **Codex**: run
426
- `codex execpolicy check --pretty --rules ~/.codex/rules/docks.rules -- rm -rf /`.
427
- It prints the decision and runs nothing.
428
- - **omp and Claude Code**: ask the agent to run `true || rm -rf "$HOME"`. The
429
- `true ||` short-circuit stops the shell before `rm`. omp reports
430
- `Blocked by bash pattern: rm * $HOME`, and Claude Code reports a denial.
468
+ Ask the agent to run `true || rm -rf "$HOME"`. The `true ||` short-circuit
469
+ stops the shell before `rm`. omp reports
470
+ `Blocked by bash pattern: rm * $HOME`.
431
471
 
432
472
  ## Sources
433
473
 
434
474
  - omp: `omp://tools/bash.md`, `omp://approval-mode.md`, and the
435
- `@oh-my-pi/pi-coding-agent` 18.17.0 source `src/tools/bash.ts`
436
- (`CRITICAL_BASH_PATTERNS`, `BashTool.approval`).
437
- - Claude Code: https://code.claude.com/docs/en/permissions and
438
- https://code.claude.com/docs/en/permission-modes
439
- - Codex: https://learn.chatgpt.com/docs/agent-configuration/rules,
440
- https://github.com/openai/codex/blob/main/codex-rs/execpolicy/README.md, and
441
- https://learn.chatgpt.com/docs/config-file/config-reference (`approvals_reviewer`).
475
+ `@oh-my-pi/pi-coding-agent` 19.0.0 source `src/tools/bash.ts`
476
+ (`CRITICAL_BASH_PATTERNS`, `BashTool.approval`). `omp://approval-mode.md`
477
+ still describes the 18.17.0 order; the source is what runs.
442
478
  - GLib `gio trash`: https://github.com/GNOME/glib/blob/main/gio/gio-tool-trash.c
443
479
  - Git: https://git-scm.com/docs/gitcli (abbreviated and clustered options),
444
480
  https://git-scm.com/docs/git-rm, https://git-scm.com/docs/git-worktree,