@hasna/hooks 0.12.6 → 0.12.7

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.
@@ -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.28, `getDataRoot`)
16
+ /** Every location the bundled Skills package (@hasna/skills 0.10.47, `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;
@@ -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 an apply that stopped before its writer could change the target. */
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`, `stdbuf`, `time`,
38
- `timeout`, `nohup`, `setsid`, `command`, `builtin`, `exec`). Quoting, `~`,
39
- `$HOME` and `${HOME}` spellings, `--`, redirections and every other byte of the
40
- command are preserved.
41
-
42
- Wrappers that take positional arguments are handled (`timeout 5 rm -rf x`
43
- rewrites the `rm`, not the duration).
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` — the delete does not run
50
- through a verb this hook can swap.
51
- - A delete inside a command substitution (`$(rm …)`, backticks).
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
- - An unparseable command (unterminated quote, substitution or here-document)
55
- that mentions a delete verb.
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.