docks-kit 0.22.28 → 0.23.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.
- package/AGENTS.md +31 -77
- package/README.md +31 -58
- package/cli/docs/command-guards.md +231 -197
- package/cli/docs/flags.md +25 -55
- package/cli/docs/install.md +2 -3
- package/cli/docs/omp-models.md +9 -0
- package/cli/docs/overview.md +4 -12
- package/cli/docs/platforms.md +2 -2
- package/cli/docs/sync-layers.md +10 -57
- package/cli/docs/toolchain.md +9 -78
- package/cli/src/argv.ts +0 -8
- package/cli/src/argvValidate.ts +2 -46
- package/cli/src/commands/docs.ts +2 -14
- package/cli/src/commands/harnesses.ts +6 -9
- package/cli/src/commands/sync.ts +5 -99
- package/cli/src/commands/toolchain.ts +4 -12
- package/cli/src/engine-native/DESIGN.md +67 -88
- package/cli/src/engine-native/deps.ts +6 -86
- package/cli/src/engine-native/engineCtx.ts +7 -76
- package/cli/src/engine-native/exec.ts +1 -18
- package/cli/src/engine-native/harnesses.ts +6 -6
- package/cli/src/engine-native/index.ts +4 -6
- package/cli/src/engine-native/jq.ts +4 -37
- package/cli/src/engine-native/modes.ts +3 -132
- package/cli/src/engine-native/os/darwin.ts +0 -4
- package/cli/src/engine-native/os/index.ts +1 -2
- package/cli/src/engine-native/os/linux.ts +0 -3
- package/cli/src/engine-native/os/posix.ts +2 -46
- package/cli/src/engine-native/os/types.ts +1 -32
- package/cli/src/engine-native/os/windows.ts +0 -49
- package/cli/src/engine-native/parseArgs.ts +11 -124
- package/cli/src/engine-native/parseHelp.ts +5 -40
- package/cli/src/engine-native/scratch.ts +1 -1
- package/cli/src/engine-native/services.ts +1 -2
- package/cli/src/engine-native/sharedTypes.d.ts +0 -40
- package/cli/src/engine-native/skillsSync.ts +1 -1
- package/cli/src/engine-native/syncConcurrency.ts +3 -15
- package/cli/src/engine-native/syncDispatch.ts +10 -57
- package/cli/src/engine-native/toolchain.ts +5 -40
- package/cli/src/engine.ts +0 -75
- package/cli/src/generated/sotPayload.ts +12 -39
- package/cli/src/main.ts +7 -19
- package/cli/src/manifests.ts +1 -93
- package/cli/src/payload.ts +2 -8
- package/cli/tsconfig.json +1 -3
- package/package.json +3 -5
- package/cli/docs/models.md +0 -58
- package/cli/docs/modifiers.md +0 -52
- package/cli/docs/plugins.md +0 -70
- package/cli/src/commands/model.ts +0 -68
- package/cli/src/commands/models.ts +0 -75
- package/cli/src/commands/plugins.ts +0 -35
- package/cli/src/commands/status.ts +0 -206
- package/cli/src/efforts.ts +0 -89
- package/cli/src/engine-native/claudeLsp.ts +0 -301
- package/cli/src/engine-native/claudeOptionalPlugins.ts +0 -126
- package/cli/src/engine-native/claudePluginPasses.ts +0 -426
- package/cli/src/engine-native/claudeRemovals.ts +0 -383
- package/cli/src/engine-native/claudeRetired.ts +0 -165
- package/cli/src/engine-native/claudeRuntime.ts +0 -157
- package/cli/src/engine-native/claudeSettings.ts +0 -201
- package/cli/src/engine-native/claudeSettingsModifiers.ts +0 -115
- package/cli/src/engine-native/claudeSync.ts +0 -312
- package/cli/src/engine-native/codexConfig.ts +0 -214
- package/cli/src/engine-native/codexHooks.ts +0 -91
- package/cli/src/engine-native/codexPaths.ts +0 -14
- package/cli/src/engine-native/codexPlugins.ts +0 -315
- package/cli/src/engine-native/codexStatus.ts +0 -25
- package/cli/src/engine-native/codexSync.ts +0 -314
- package/cli/src/engine-native/codexToml.ts +0 -303
- package/cli/src/engine-native/liveModels.ts +0 -264
- package/cli/src/engine-native/models.ts +0 -101
- package/cli/src/engine-native/parseModifiers.ts +0 -225
- package/cli/src/engine-native/settings.ts +0 -42
- package/cli/src/engine-native/tomlLines.ts +0 -92
|
@@ -1,20 +1,16 @@
|
|
|
1
1
|
# Command guards
|
|
2
2
|
|
|
3
|
-
The kit ships one destructive-command policy to omp
|
|
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.
|
|
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
|
-
|
|
10
|
-
|
|
11
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
- **
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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
|
|
53
|
-
|
|
54
|
-
| Command | omp `bash.patterns` |
|
|
55
|
-
| --- | --- |
|
|
56
|
-
| `rm` of `/`, `~`, `~/`, `$HOME`, `${HOME}`, quoted or with a trailing `/` | deny |
|
|
57
|
-
| `rm` of `/*` | deny with an `r` or `f` option; plain `rm /*` runs |
|
|
58
|
-
| `HOME=...`, `export HOME=...`, `env HOME=...` | deny |
|
|
59
|
-
| `sudo` before `rm`, plain or by path (`/usr/bin/sudo`) | deny |
|
|
60
|
-
| `git push --force` or `-f` to `origin main` or `origin master` | 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`) |
|
|
62
|
-
| `rm` with an `r` or `f` option before an absolute path, `--no-preserve-root` | deny |
|
|
63
|
-
| Any other `rm`: one file, several files, a glob, `-f` | run |
|
|
64
|
-
| `find ... -delete`, `find ... -exec rm` (also `-execdir`, `-ok`, `-okdir`), `xargs rm` | deny, in every position and by path |
|
|
65
|
-
| `git clean`, `git reset --hard` | run |
|
|
66
|
-
| `git push` that could force: see below | run, unless a deny above matches |
|
|
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 |
|
|
68
|
-
| A git command that skips the repository's hooks: see below | run |
|
|
69
|
-
| `git rm -- <path>`, `git worktree remove -- <path>` | run |
|
|
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 |
|
|
71
|
-
| `docks-kit scratch remove <path>` | run; the command removes only a path inside the scratch root, the system temporary directory, or `/var/tmp` |
|
|
72
|
-
| Any other non-recursive `git rm` or `git worktree remove` | run |
|
|
73
|
-
| `gio trash -- <path>` | run |
|
|
74
|
-
| Any other `gio trash` | run |
|
|
75
|
-
| `trash <path>` (macOS) | allow |
|
|
76
|
-
|
|
77
|
-
|
|
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.
|
|
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.
|
|
138
|
-
|
|
139
|
-
|
|
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.
|
|
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>`.
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
4.
|
|
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.
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
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
|
-
|
|
163
|
-
|
|
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
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
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,33 @@ 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 proves it by measurement: the test runs
|
|
317
|
+
`cli/test/lib/ompTriggerBackstop.ts` under Bun, because the unit tests run on
|
|
318
|
+
V8, which does not show the JavaScriptCore cost. The backstop has these
|
|
319
|
+
checks:
|
|
320
|
+
|
|
321
|
+
- Time budget, with the regex JIT on: one pass of all conditions over a
|
|
322
|
+
20 KB Python cell, a 20 KB bash command, and a 30 KB `KEY=value` chain
|
|
323
|
+
stays under 250 ms for each buffer.
|
|
324
|
+
- Fire, with the regex JIT on: `git reset --hard` at the end of the 20 KB
|
|
325
|
+
cell fires `git-safety.md`.
|
|
326
|
+
- Scaling, with the regex JIT off: each condition alone, on each adversarial
|
|
327
|
+
input shape, at 16 KB and 64 KB.
|
|
328
|
+
- Dense and head-and-run scaling, with the regex JIT on: each condition
|
|
329
|
+
alone, on the two families above, at 16 KB and 64 KB. Each line goes into a
|
|
330
|
+
bash command, an open bash command without its closing quote, and a Python
|
|
331
|
+
`sh("…")` cell.
|
|
332
|
+
|
|
333
|
+
In each scaling check, the 64 KB time must stay at most 8 times the 16 KB
|
|
334
|
+
time plus 15 ms, and at most 100 ms. The backstop times the pairs in parallel
|
|
335
|
+
child processes first. Each pair that fails there gets a second, serial run,
|
|
336
|
+
and it fails only when it fails there too. A call of 1000 ms or more fails at
|
|
337
|
+
once.
|
|
338
|
+
|
|
259
339
|
## Why omp denies instead of asking
|
|
260
340
|
|
|
261
341
|
omp has a built-in check for critical commands. For example, it flags:
|
|
@@ -263,11 +343,14 @@ omp has a built-in check for critical commands. For example, it flags:
|
|
|
263
343
|
- an `rm` with an `r` or `f` option before an absolute path;
|
|
264
344
|
- `sudo rm`, also when `sudo` is called by its path.
|
|
265
345
|
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
346
|
+
omp 19.0.0 checks deny and prompt rules first, then its critical patterns, then
|
|
347
|
+
allow rules. A critical command that no deny or prompt rule matches gets a bare
|
|
348
|
+
safety override, which also replaces a matching allow. Under omp's default
|
|
349
|
+
`tools.approvalMode: yolo`, omp ignores a bare override, so the command runs.
|
|
350
|
+
This applies in subagents too. A prompt rule would ask a person in the main
|
|
351
|
+
session, but a subagent rejects every prompt, so the kit ships none. Only a
|
|
352
|
+
deny rule stops a critical command in every session (`BashTool.approval` in
|
|
353
|
+
the v19.0.0 source).
|
|
271
354
|
|
|
272
355
|
The kit therefore denies every `rm` shape that the check can flag:
|
|
273
356
|
|
|
@@ -281,33 +364,21 @@ The kit also denies bulk removal through `find -delete`, `find -exec rm`, and
|
|
|
281
364
|
the home directory, and no glob can express "inside the temporary directory".
|
|
282
365
|
`docks-kit scratch remove` checks the path in code instead.
|
|
283
366
|
|
|
284
|
-
## Matching rules
|
|
285
|
-
|
|
286
|
-
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
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.
|
|
367
|
+
## Matching rules
|
|
368
|
+
|
|
369
|
+
- For a simple command, the rules are ordered, and the first match wins.
|
|
370
|
+
- `*` matches any text, spaces included, and no escape spells a literal `*`.
|
|
371
|
+
- Deny rules test the whole line and each segment between `;`, `&&`, `|`,
|
|
372
|
+
and similar operators, with quotes and escapes removed. So
|
|
373
|
+
`rm -rf "$HOME"` matches `rm * $HOME`. A segment also matches without its
|
|
374
|
+
leading `NAME=value` words.
|
|
375
|
+
- For a line with shell control, each segment takes its first matching deny
|
|
376
|
+
or prompt rule. A deny chosen for one segment wins over a prompt chosen
|
|
377
|
+
for another segment; within one segment, a prompt rule that comes first
|
|
378
|
+
wins over a later deny.
|
|
379
|
+
- Allow rules apply only to a simple command.
|
|
380
|
+
- The kit ships no prompt rule. It lists rules as deny, then the `trash *`
|
|
381
|
+
allow.
|
|
311
382
|
|
|
312
383
|
## Gaps
|
|
313
384
|
|
|
@@ -334,15 +405,13 @@ the home directory, and no glob can express "inside the temporary directory".
|
|
|
334
405
|
- **omp, bulk-removal text**: the `* find *-delete*`, `*-exec rm *`, and
|
|
335
406
|
`*xargs rm` rules also match text, so a line such as
|
|
336
407
|
`echo use find with -delete` is denied. Write such text to a file instead.
|
|
337
|
-
- **
|
|
338
|
-
recursive-`rm` clusters
|
|
339
|
-
|
|
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.
|
|
408
|
+
- **omp, recursive `rm` clusters**: omp matches only the listed
|
|
409
|
+
recursive-`rm` clusters: `r` or `R` alone or with `f` and `v`, plus `-ri`,
|
|
410
|
+
`-ir`, `-Ri`, and `-iR`. Another cluster runs.
|
|
342
411
|
- **`git push` beyond the listed words**: a configured `+` refspec in
|
|
343
412
|
`remote.<name>.push` makes a plain `git push` force. No rule sees git
|
|
344
413
|
configuration. `git push --delete` and `git push --prune` remove remote
|
|
345
|
-
branches without force;
|
|
414
|
+
branches without force; no kit rule asks for them.
|
|
346
415
|
- **omp, force push to `main` in another spelling**: the force-push deny
|
|
347
416
|
rules match only `git push --force` or `git push -f`, then
|
|
348
417
|
`origin main` or `origin master`. Every other force push to `main` runs
|
|
@@ -355,27 +424,11 @@ the home directory, and no glob can express "inside the temporary directory".
|
|
|
355
424
|
a wrapper, or a path runs without a check, such as
|
|
356
425
|
`for r in a; do git push --force origin main; done`,
|
|
357
426
|
`env git push --force origin main`, or `/usr/bin/git push --force origin main`.
|
|
358
|
-
- **`git -C`**: no
|
|
427
|
+
- **`git -C`**: no rule matches a git subcommand that does not follow `git`
|
|
359
428
|
directly, such as `git -C . push --force origin main` or
|
|
360
429
|
`git -C . push origin $b`.
|
|
361
|
-
- **
|
|
362
|
-
|
|
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`.
|
|
430
|
+
- **Programs that remove files**: no rule covers a program that removes files
|
|
431
|
+
itself, such as a Python or Node script, or a shell started by omp `eval`.
|
|
379
432
|
|
|
380
433
|
### How `gio trash` empties the trash
|
|
381
434
|
|
|
@@ -384,61 +437,42 @@ or restores the paths, and `--empty` has no effect. Without a path, it empties
|
|
|
384
437
|
the trash when `--empty` is set. `-f` can repeat. So `gio trash -ff --empty`
|
|
385
438
|
empties the trash, while `gio trash build --empty` only trashes `build`.
|
|
386
439
|
|
|
387
|
-
|
|
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.
|
|
440
|
+
omp runs every `gio trash` without a prompt.
|
|
390
441
|
|
|
391
442
|
## Sync behavior
|
|
392
443
|
|
|
393
|
-
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
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`.
|
|
444
|
+
- The config merge keeps user `bash.patterns` rules and groups all rules in
|
|
445
|
+
this order:
|
|
446
|
+
1. kit deny;
|
|
447
|
+
2. user deny;
|
|
448
|
+
3. user prompt;
|
|
449
|
+
4. kit prompt (the kit ships none since 0.22.8);
|
|
450
|
+
5. the other user rules;
|
|
451
|
+
6. kit allow.
|
|
452
|
+
- A user deny or prompt thus precedes every kit allow, and no allow can
|
|
453
|
+
loosen a deny or a prompt.
|
|
454
|
+
- A repeat sync changes nothing.
|
|
455
|
+
- After the merge, `ompRemovals.ts syncOmpRemovals, retired bash-rule
|
|
456
|
+
inventory` removes the retired kit rules in `OMP_RETIRED_BASH_RULES` from
|
|
457
|
+
the deployed `bash.patterns` on every sync. The inventory also holds the
|
|
458
|
+
492 prompt rules that the kit retired in 0.22.8. It removes a rule only
|
|
459
|
+
when its `match` and `approval` equal a retired pair, so a different user
|
|
460
|
+
rule stays.
|
|
420
461
|
|
|
421
462
|
## Check the deployed rules
|
|
422
463
|
|
|
423
|
-
|
|
464
|
+
The check below is safe, because the shell never reaches `rm`.
|
|
424
465
|
|
|
425
|
-
-
|
|
426
|
-
|
|
427
|
-
|
|
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.
|
|
466
|
+
Ask the agent to run `true || rm -rf "$HOME"`. The `true ||` short-circuit
|
|
467
|
+
stops the shell before `rm`. omp reports
|
|
468
|
+
`Blocked by bash pattern: rm * $HOME`.
|
|
431
469
|
|
|
432
470
|
## Sources
|
|
433
471
|
|
|
434
472
|
- omp: `omp://tools/bash.md`, `omp://approval-mode.md`, and the
|
|
435
|
-
`@oh-my-pi/pi-coding-agent`
|
|
436
|
-
(`CRITICAL_BASH_PATTERNS`, `BashTool.approval`).
|
|
437
|
-
|
|
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`).
|
|
473
|
+
`@oh-my-pi/pi-coding-agent` 19.0.0 source `src/tools/bash.ts`
|
|
474
|
+
(`CRITICAL_BASH_PATTERNS`, `BashTool.approval`). `omp://approval-mode.md`
|
|
475
|
+
still describes the 18.17.0 order; the source is what runs.
|
|
442
476
|
- GLib `gio trash`: https://github.com/GNOME/glib/blob/main/gio/gio-tool-trash.c
|
|
443
477
|
- Git: https://git-scm.com/docs/gitcli (abbreviated and clustered options),
|
|
444
478
|
https://git-scm.com/docs/git-rm, https://git-scm.com/docs/git-worktree,
|