@hasna/hooks 0.12.6 → 0.12.8
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/README.md +10 -4
- package/bin/hooks-mcp.js +3666 -1268
- package/bin/index.js +4104 -1723
- package/bin/native-safety-entry.js +25 -20
- package/bin/native-safety-worker.cjs +25 -20
- package/bin/serve.js +2 -2
- package/dist/index.js +3936 -1522
- package/dist/lib/claude-skills-coordination.d.ts +16 -2
- package/dist/lib/codex-safety-check.d.ts +1 -1
- package/dist/lib/installer.d.ts +11 -0
- package/dist/lib/native-safety-registration.d.ts +8 -3
- package/hooks/hook-trash-guard/README.md +49 -15
- package/hooks/hook-trash-guard/src/hook.ts +741 -125
- package/hooks/hook-workspace-repos-guard/src/hook.ts +274 -79
- package/hooks/shell-words.ts +368 -0
- package/package.json +2 -2
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { planClaudeHookEventsUpdate } from "@hasna/skills";
|
|
1
2
|
/** A definite refusal raised before any Claude settings byte is written.
|
|
2
3
|
* `settings_unreadable` (raised by the installer's writer, also for Gemini
|
|
3
4
|
* settings): the file exists but was not read and parsed as a JSON object. */
|
|
@@ -12,17 +13,30 @@ export declare class ClaudeSettingsRefusal extends Error {
|
|
|
12
13
|
* as any file type. A lookup error other than ENOENT/ENOTDIR counts as present.
|
|
13
14
|
* Returns the evidence found; an empty list means Skills is genuinely absent. */
|
|
14
15
|
export declare function claudeSkillsUsage(before: string | null, home: string): string[];
|
|
15
|
-
/** Every location the bundled Skills package (@hasna/skills 0.10.
|
|
16
|
+
/** Every location the bundled Skills package (@hasna/skills 0.10.53, `getDataRoot`)
|
|
16
17
|
* considers for `agent-policy.json`, in its resolution order, with the outcome
|
|
17
18
|
* at each. Only called after Skills found no policy at the selected location. */
|
|
18
19
|
export declare function skillsPolicyLocations(dataDir?: string): string[];
|
|
20
|
+
/** The read-only half of the coordinated write: the owning Skills writer parses
|
|
21
|
+
* its agent policy and plans the Claude settings and discovery update exactly as
|
|
22
|
+
* the write does, and writes nothing. Returns the Skills plan, or `null` while
|
|
23
|
+
* Skills is genuinely absent (`claudeSkillsUsage`), which permits the standalone
|
|
24
|
+
* writer. When Skills is in use but its policy cannot be resolved, it refuses
|
|
25
|
+
* with `skills_policy_unresolved`. Any other Skills refusal (an invalid policy,
|
|
26
|
+
* drift, an unsupported change) propagates unchanged.
|
|
27
|
+
*/
|
|
28
|
+
export declare function planCoordinatedClaudeSettings(before: string | null, replacement: string, options: {
|
|
29
|
+
home: string;
|
|
30
|
+
dataDir?: string;
|
|
31
|
+
}): ReturnType<typeof planClaudeHookEventsUpdate>;
|
|
19
32
|
/** The owning Skills writer commits Claude settings and discovery together.
|
|
20
33
|
* A missing policy permits ordinary standalone installation only while Skills is
|
|
21
34
|
* genuinely absent (`claudeSkillsUsage`). When Skills is in use but its policy
|
|
22
35
|
* cannot be resolved, it refuses with `skills_policy_unresolved` and writes
|
|
23
36
|
* nothing. Any other refusal propagates before settings are written; it never
|
|
24
37
|
* selects a fallback writer. `beforeWrite` runs once, immediately before the
|
|
25
|
-
* coordinated write starts.
|
|
38
|
+
* coordinated write starts. The planning is `planCoordinatedClaudeSettings`, so
|
|
39
|
+
* a caller can run the same checks first without writing.
|
|
26
40
|
*/
|
|
27
41
|
export declare function coordinateClaudeSettings(before: string | null, replacement: string, options: {
|
|
28
42
|
home: string;
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { verifyNativeSafetyCommand } from "../native-safety.js";
|
|
2
2
|
/** Exact `codex --version` outputs whose app-server protocol was measured
|
|
3
3
|
* against the real native binary. Anything else refuses as native_unsupported. */
|
|
4
|
-
export declare const SUPPORTED_CODEX_SAFETY_VERSIONS: readonly ["codex-cli 0.153.0", "codex-cli 0.154.0", "codex-cli 0.154.0-alpha.6.1", "codex-cli 0.155.0", "codex-cli 0.155.1", "codex-cli 0.156.1", "codex-cli 0.157.0", "codex-cli 0.157.1", "codex-cli 0.158.0", "codex-cli 0.159.0", "codex-cli 0.159.2", "codex-cli 0.159.3", "codex-cli 0.160.0", "codex-cli 0.160.1"];
|
|
4
|
+
export declare const SUPPORTED_CODEX_SAFETY_VERSIONS: readonly ["codex-cli 0.153.0", "codex-cli 0.154.0", "codex-cli 0.154.0-alpha.6.1", "codex-cli 0.155.0", "codex-cli 0.155.1", "codex-cli 0.156.1", "codex-cli 0.157.0", "codex-cli 0.157.1", "codex-cli 0.158.0", "codex-cli 0.159.0", "codex-cli 0.159.2", "codex-cli 0.159.3", "codex-cli 0.160.0", "codex-cli 0.160.1", "codex-cli 0.161.0"];
|
|
5
5
|
export type CodexSafetyCode = "native_unavailable" | "native_unsafe_executable" | "native_executable_required" | "native_unsupported" | "native_failed" | "native_discovery_failed" | "hooks_disabled" | "guard_missing" | "guard_ambiguous" | "guard_definition_invalid" | "guard_disabled" | "guard_untrusted" | "guard_changed" | "guard_failed";
|
|
6
6
|
export declare class CodexSafetyError extends Error {
|
|
7
7
|
readonly code: CodexSafetyCode;
|
package/dist/lib/installer.d.ts
CHANGED
|
@@ -58,6 +58,17 @@ export interface InstallOptions {
|
|
|
58
58
|
export declare function getSettingsPath(scope?: Scope, target?: SingleTarget, codewithConfigPath?: string): string;
|
|
59
59
|
export declare function getHookPath(name: string): string;
|
|
60
60
|
export declare function hookExists(name: string): boolean;
|
|
61
|
+
/** The read-only twin of the Claude write `writeSettings` performs for `after`:
|
|
62
|
+
* when that write goes through the Skills coordinated writer, run the writer's
|
|
63
|
+
* own policy parsing and update planning and throw exactly what that write
|
|
64
|
+
* throws before writing. Nothing is written. Returns quietly when the write
|
|
65
|
+
* would not be refused there, including when Skills does not coordinate the file. */
|
|
66
|
+
export declare function planClaudeSettingsWrite(before: string | null, after: string, scope?: Scope): void;
|
|
67
|
+
/** How `installHook` reports an error thrown while writing settings. */
|
|
68
|
+
export declare function writerRefusal(error: unknown): {
|
|
69
|
+
error: string;
|
|
70
|
+
code?: string;
|
|
71
|
+
};
|
|
61
72
|
/** Whether a hook's event can be registered for the given target */
|
|
62
73
|
export declare function isEventSupported(internalEvent: HookEvent, target: SingleTarget): boolean;
|
|
63
74
|
export declare function buildCodewithTomlFragment(name: string, profile?: string, mementos?: MementosRegistration): string;
|
|
@@ -1,14 +1,19 @@
|
|
|
1
1
|
import { verifyNativeSafetyCommand } from "../native-safety.js";
|
|
2
|
-
/** The definite cause of
|
|
2
|
+
/** The definite cause of a refusal by the owning settings writer, before it could change the target. */
|
|
3
3
|
export interface RegistrationRefusal {
|
|
4
4
|
code: string;
|
|
5
5
|
message: string;
|
|
6
6
|
}
|
|
7
|
+
/** `writer_refused`: the owning settings writer's read-only planning refused the
|
|
8
|
+
* exact planned change (for Claude, the Skills coordinated writer, for example an
|
|
9
|
+
* agent policy it cannot accept). Plan and apply both return it, with the same
|
|
10
|
+
* `refusal`, before anything is written or journaled. `apply_refused`: a journaled
|
|
11
|
+
* apply stopped before its writer may have started, for example on a writer lock. */
|
|
7
12
|
export declare class NativeRegistrationError extends Error {
|
|
8
|
-
readonly code: "input_invalid" | "settings_unsafe" | "settings_invalid" | "settings_changed" | "hooks_disabled" | "registration_conflict" | "guard_failed" | "apply_refused" | "apply_outcome_uncertain";
|
|
13
|
+
readonly code: "input_invalid" | "settings_unsafe" | "settings_invalid" | "settings_changed" | "hooks_disabled" | "registration_conflict" | "guard_failed" | "writer_refused" | "apply_refused" | "apply_outcome_uncertain";
|
|
9
14
|
readonly operationId?: string | undefined;
|
|
10
15
|
readonly refusal?: RegistrationRefusal | undefined;
|
|
11
|
-
constructor(code: "input_invalid" | "settings_unsafe" | "settings_invalid" | "settings_changed" | "hooks_disabled" | "registration_conflict" | "guard_failed" | "apply_refused" | "apply_outcome_uncertain", operationId?: string | undefined, refusal?: RegistrationRefusal | undefined);
|
|
16
|
+
constructor(code: "input_invalid" | "settings_unsafe" | "settings_invalid" | "settings_changed" | "hooks_disabled" | "registration_conflict" | "guard_failed" | "writer_refused" | "apply_refused" | "apply_outcome_uncertain", operationId?: string | undefined, refusal?: RegistrationRefusal | undefined);
|
|
12
17
|
}
|
|
13
18
|
export interface NativeRegistrationOptions {
|
|
14
19
|
target: "codex" | "claude";
|
|
@@ -34,25 +34,51 @@ and one handed to another guard is refused rather than partially rewritten.
|
|
|
34
34
|
|
|
35
35
|
Only `rm`'s own grammar, and only in **command position**: the verb must be the
|
|
36
36
|
command, after any assignment prefixes (`FOO=1 rm …`), shell keywords, and
|
|
37
|
-
recognized wrappers (`sudo`, `doas`, `env`, `nice`, `ionice`,
|
|
38
|
-
`timeout`, `nohup`, `setsid`, `command`, `builtin`, `exec`).
|
|
39
|
-
`$HOME` and `${HOME}` spellings, `--`, redirections and every
|
|
40
|
-
command are preserved.
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
37
|
+
recognized wrappers (`sudo`, `doas`, `flock`, `env`, `nice`, `ionice`,
|
|
38
|
+
`stdbuf`, `time`, `timeout`, `nohup`, `setsid`, `command`, `builtin`, `exec`).
|
|
39
|
+
Quoting, `~`, `$HOME` and `${HOME}` spellings, `--`, redirections and every
|
|
40
|
+
other byte of the command are preserved.
|
|
41
|
+
|
|
42
|
+
Each command is read twice: by the shared command-position walk, and by the
|
|
43
|
+
strict wrapper model in `hooks/shell-words.ts` (shared with
|
|
44
|
+
`workspace-repos-guard`), which reads wrapper options the way GNU coreutils,
|
|
45
|
+
util-linux, sudo and bash do: option clusters (`timeout -vk 5 30 rm`),
|
|
46
|
+
attached values (`nice -n5`), unique long-option abbreviations
|
|
47
|
+
(`nice --adj 5`, `env --uns VAR`, `stdbuf --out L`) and positional
|
|
48
|
+
arguments (`timeout 5 rm` rewrites the `rm`, not the duration; `flock <file>
|
|
49
|
+
rm` rewrites the `rm`, not the lock file). A delete either reading finds
|
|
50
|
+
counts, and the rewrite replaces only the verb, behind its wrappers.
|
|
44
51
|
|
|
45
52
|
## What it refuses
|
|
46
53
|
|
|
47
54
|
- `rmdir`, `unlink`, `shred` — their flags and semantics are not `rm`'s.
|
|
48
55
|
- `git rm` (without `--cached`), `git clean` — they delete outside `rm`.
|
|
49
|
-
- `find -delete`, `find -exec rm …`, `xargs rm`
|
|
50
|
-
through a verb this hook can swap.
|
|
51
|
-
- A delete inside a command substitution
|
|
56
|
+
- `find -delete`, `find -exec|-execdir|-ok|-okdir rm …`, `xargs rm` (also
|
|
57
|
+
`/bin/rm`) — the delete does not run through a verb this hook can swap.
|
|
58
|
+
- A delete inside a command substitution, wherever bash runs one: `$( )` and
|
|
59
|
+
backticks, unquoted or inside double quotes, nested (`"$(echo "$(rm …)")"`,
|
|
60
|
+
escaped backticks inside backticks), and in a here-document body whose
|
|
61
|
+
delimiter is unquoted. Single-quoted text and a quoted here-document body are
|
|
62
|
+
data.
|
|
52
63
|
- `busybox rm` / `toybox rm` — a different applet, not GNU `rm`.
|
|
53
|
-
- Shells and opaque command strings (`sh -c 'rm …'`, `eval`, `su -c
|
|
54
|
-
|
|
55
|
-
|
|
64
|
+
- Shells and opaque command strings (`sh -c 'rm …'`, `eval`, `su -c …`,
|
|
65
|
+
`flock <file> -c '…'`), and a here-document a shell reads as its script:
|
|
66
|
+
one on the shell's own command (`bash <<'EOF'`), or any in the command when
|
|
67
|
+
the shell reads standard input (`cat <<'EOF' | bash`).
|
|
68
|
+
- A command whose command word or wrapper arguments cannot be read before it
|
|
69
|
+
runs: an expansion bash can turn into other words (`$X`, `$(…)`, a brace
|
|
70
|
+
pattern such as `{X,rm}`, a glob, `~user`, `$'…'`), an option the model does
|
|
71
|
+
not know or does not model (`env -C`, `time -o`, `sudo -D`) or a non-decimal
|
|
72
|
+
duration (`timeout 1e3`). Such a command is refused when any of its words
|
|
73
|
+
could run a delete, or could become one (`${RM:-rm}`, `r{m,}`).
|
|
74
|
+
- A brace operand (`rm -rf ~/{.ssh,x}`) is expanded and each path checked: one
|
|
75
|
+
in the protected class, or one under a protected repo-checkout root that the
|
|
76
|
+
written word does not show, is refused.
|
|
77
|
+
- An unparseable command (unterminated quote or substitution, or an extended
|
|
78
|
+
glob such as `@(a|b)`) that mentions a delete verb. A here-document is read
|
|
79
|
+
as bash reads it: the rest of its operator's line is still the command
|
|
80
|
+
(`cat <<EOF && rm x`), `<<-` strips tabs, and a body with no terminator runs
|
|
81
|
+
to the end of the command.
|
|
56
82
|
- The protected class, below.
|
|
57
83
|
|
|
58
84
|
Each refusal carries a reason and a way forward: re-run the delete as
|
|
@@ -89,7 +115,11 @@ Deletes under the protected repo-checkout roots `$HOME/.hasna/repos/clones` and
|
|
|
89
115
|
every delete under them at any depth. This hook does not restate that policy:
|
|
90
116
|
it recognizes the boundary and abstains, so the other hook's decision stands.
|
|
91
117
|
A command that mixes a delete inside those roots with one outside is refused,
|
|
92
|
-
because a partial rewrite would leave one of them unredirected.
|
|
118
|
+
because a partial rewrite would leave one of them unredirected. A delete run
|
|
119
|
+
from inside a checkout that names only literal paths outside the roots is
|
|
120
|
+
refused too: `workspace-repos-guard` does not own those paths, so abstaining
|
|
121
|
+
would let the raw delete run where the two hooks are registered on their own.
|
|
122
|
+
The native safety entry already refused it.
|
|
93
123
|
|
|
94
124
|
## Conflict discipline
|
|
95
125
|
|
|
@@ -124,7 +154,11 @@ The guard is a best-effort **text** classifier, not an execution sandbox.
|
|
|
124
154
|
- **Nested and generated commands escape it.** `bash -c`, `eval`, `make`,
|
|
125
155
|
`npm run`, a `Dockerfile`, a heredoc-fed interpreter: the hook can only see
|
|
126
156
|
that a shell string mentions a delete verb and refuse it, never redirect
|
|
127
|
-
inside it.
|
|
157
|
+
inside it. A verb assembled at run time (`X=rm; $X …`, `bash -c "$(printf
|
|
158
|
+
'r''m …')"`), a delete made by an interpreter (`python3 -c`, `perl -e`) or by
|
|
159
|
+
another tool (`rsync --delete`, `find -exec sh -c '…'`), and runners not
|
|
160
|
+
modelled (`coproc`, `chroot`, `nsenter`, `unshare`, `taskset`, `chrt`,
|
|
161
|
+
`systemd-run`) are not seen.
|
|
128
162
|
- **Threat model: accident, not adversary.** A hostile same-user agent can
|
|
129
163
|
remove the hook, edit the store, or call `unlink(2)` directly; nothing here
|
|
130
164
|
holds against that.
|