@openagentsy/hooks 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @openagentsy/hooks
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The deterministic guardrails: the rule registry, the default rules, the output
+checks, the shell environment policy, the redaction wrapper and the approval
+gate. It is a library. The adapter (the OpenCode plugin) calls it; OpenCode
+never loads it.
+
+## What it guards
+
+- **Git hooks cannot be skipped.** `--no-verify`, `git commit -n` and
+  `HUSKY=0` are refused.
+- **The package manager is Bun.** `pnpm`, `yarn`, `npx` and `npm install` are
+  refused.
+- **Writes stay in the workspace** and in the OpenAgentsy worktrees.
+- **Policy files are a person's**: `roles.yaml`, the model lock,
+  `opencode.json`, the build config, the lockfile, the hooks, the workflows,
+  the templates, the lessons and the waivers.
+- **Decisions are a person's**: a lesson, a waiver and a memory promotion are
+  decided by a person, never by an agent.
+- **Secrets do not get written.** A credential in the content is refused.
+- **Destructive commands need an approval**: `rm -rf`, a forced push, a hard
+  reset and a dropped table. The escape hatch is `/oa approve <callID>`, and
+  a grant passes once.
+
+The human-only guarantee rides the permission map (`roles.yaml`), not this
+package: the map denies the three decision tools to every agent role, and
+this package is the second layer. The output checks flag, they never block.
+
+## The known gap
+
+The entropy guard in the redaction helper is strictly `> 4.0` bits per
+character, so a pure-hex value of 32 characters is never flagged. The helper
+is core's, and 2f owns the fix; this package does not widen it.

package/dist/accountability.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The counts the Accountability block shows.
+ *
+ * The block itself is the sidebar's (plan §7.4) and it is phase 2e's. What
+ * lives here is the data the block renders: the count of the waivers a
+ * person recorded, and the line the block shows for it. A block that has to
+ * reach into a file to count a thing is a block that has to know where the
+ * file is, so the reading is done here and the block only renders.
+ */
+/** The counts. */
+export type AccountabilityCounts = {
+    /** The waivers a person recorded. */
+    waivers: number;
+};
+/**
+ * The counts, read from the state root.
+ *
+ * A state root with no waivers file holds no waivers, and that is a count
+ * of zero and not a failure.
+ */
+export declare function accountabilityCounts(root: string): Promise<AccountabilityCounts>;
+/**
+ * The line the block shows.
+ *
+ * The plan's example reads "2 waivers", so the count comes first and the
+ * word follows it.
+ */
+export declare function formatAccountability(counts: AccountabilityCounts): string;
+//# sourceMappingURL=accountability.d.ts.map

package/dist/accountability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accountability.d.ts","sourceRoot":"","sources":["../src/accountability.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,kBAAkB;AAClB,MAAM,MAAM,oBAAoB,GAAG;IACjC,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAEtF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAGzE"}

package/dist/accountability.js

@@ -0,0 +1,21 @@
+import { createWaiverStore } from './quality/waivers.js';
+/**
+ * The counts, read from the state root.
+ *
+ * A state root with no waivers file holds no waivers, and that is a count
+ * of zero and not a failure.
+ */
+export async function accountabilityCounts(root) {
+    return { waivers: await createWaiverStore(root).count() };
+}
+/**
+ * The line the block shows.
+ *
+ * The plan's example reads "2 waivers", so the count comes first and the
+ * word follows it.
+ */
+export function formatAccountability(counts) {
+    const waivers = counts.waivers;
+    return `${waivers} ${waivers === 1 ? 'waiver' : 'waivers'}`;
+}
+//# sourceMappingURL=accountability.js.map

package/dist/accountability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accountability.js","sourceRoot":"","sources":["../src/accountability.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAkBzD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,IAAY;IACrD,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;AAC5D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAA4B;IAC/D,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,OAAO,GAAG,OAAO,IAAI,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;AAC9D,CAAC"}

package/dist/accountability.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=accountability.test.d.ts.map

package/dist/accountability.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accountability.test.d.ts","sourceRoot":"","sources":["../src/accountability.test.ts"],"names":[],"mappings":""}

package/dist/accountability.test.js

@@ -0,0 +1,42 @@
+import { mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { accountabilityCounts, formatAccountability } from './accountability.js';
+import { createWaiverStore } from './quality/waivers.js';
+/** A state root the test reads. */
+async function scratch() {
+    return await mkdtemp(join(tmpdir(), 'openagentsy-accountability-'));
+}
+/** A waiver, as a person recorded it. */
+function waiver(over = {}) {
+    return {
+        ruleId: 'css/no-transition-all',
+        path: 'src/app.css',
+        reason: 'The file is a fixture, not a page.',
+        decidedBy: 'human',
+        ts: '2026-10-27T10:00:00.000Z',
+        ...over,
+    };
+}
+describe('the accountability counts', () => {
+    it('counts no waiver in a project that has none', async () => {
+        const root = await scratch();
+        const counts = await accountabilityCounts(root);
+        expect(counts.waivers).toBe(0);
+        expect(formatAccountability(counts)).toBe('0 waivers');
+    });
+    it('counts the waivers a person recorded', async () => {
+        const root = await scratch();
+        const store = createWaiverStore(root);
+        await store.add(waiver());
+        await store.add(waiver({ path: 'src/other.css' }));
+        const counts = await accountabilityCounts(root);
+        expect(counts.waivers).toBe(2);
+        expect(formatAccountability(counts)).toBe('2 waivers');
+    });
+    it('says one waiver in the singular', () => {
+        expect(formatAccountability({ waivers: 1 })).toBe('1 waiver');
+    });
+});
+//# sourceMappingURL=accountability.test.js.map

package/dist/accountability.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accountability.test.js","sourceRoot":"","sources":["../src/accountability.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAE,iBAAiB,EAAe,MAAM,sBAAsB,CAAC;AAEtE,mCAAmC;AACnC,KAAK,UAAU,OAAO;IACpB,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,6BAA6B,CAAC,CAAC,CAAC;AACtE,CAAC;AAED,yCAAyC;AACzC,SAAS,MAAM,CAAC,OAAwB,EAAE;IACxC,OAAO;QACL,MAAM,EAAE,uBAAuB;QAC/B,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE,oCAAoC;QAC5C,SAAS,EAAE,OAAO;QAClB,EAAE,EAAE,0BAA0B;QAC9B,GAAG,IAAI;KACR,CAAC;AACJ,CAAC;AAED,QAAQ,CAAC,2BAA2B,EAAE,GAAG,EAAE;IACzC,EAAE,CAAC,6CAA6C,EAAE,KAAK,IAAI,EAAE;QAC3D,MAAM,IAAI,GAAG,MAAM,OAAO,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,IAAI,CAAC,CAAC;QAChD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC/B,MAAM,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,KAAK,IAAI,EAAE;QACpD,MAAM,IAAI,GAAG,MAAM,OAAO,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACtC,MAAM,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QAC1B,MAAM,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC;QACnD,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,IAAI,CAAC,CAAC;QAChD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC/B,MAAM,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACzC,MAAM,CAAC,oBAAoB,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAChE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/approvals.d.ts

@@ -0,0 +1,110 @@
+import type { HandlerResult } from './registry.js';
+/**
+ * The approval gate.
+ *
+ * A destructive command needs a person. OpenCode's own permission prompt
+ * cannot be answered from inside a plugin, so an approval is a grant on
+ * disk: a person runs `/oa approve <callID>`, the grant is written down,
+ * and the call it names goes through once.
+ */
+/** One grant. */
+export interface ApprovalEntry {
+    /** The call the grant covers. */
+    callID: string;
+    /** When the grant stops being valid, in milliseconds since the epoch. */
+    expiresAt: number;
+}
+/** How long a grant lives when no other time is given. */
+export declare const DEFAULT_APPROVAL_TTL_MS: number;
+/**
+ * The timings of the store.
+ *
+ * They are the defaults of a store; a test can shorten them.
+ */
+export interface ApprovalTiming {
+    /** How long a writer waits for the lock. */
+    timeoutMs?: number;
+    /** How old a lock must be before it is presumed abandoned. */
+    staleMs?: number;
+    /** How often the lock is refreshed while the action runs. */
+    heartbeatMs?: number;
+}
+/** The timings a store runs with. */
+export type ResolvedTiming = Required<ApprovalTiming>;
+/**
+ * Where the grants live.
+ *
+ * The file sits in the state root next to the board, so every session of
+ * the project reads the same grants. The path is a protected one: the file
+ * is written by a person and by the gate, never by an agent.
+ */
+export declare function approvalsPath(stateRoot: string): string;
+/** The grants, and the gate that spends them. */
+export interface ApprovalStore {
+    /** Where the grants live. */
+    readonly path: string;
+    /** Whether a grant covers the call now. */
+    isApproved(callID: string, now: number): Promise<boolean>;
+    /** Grant the call, unless it is granted already. */
+    approve(callID: string, now: number, ttlMs?: number): Promise<ApprovalGrant>;
+    /** Spend the grant: it passes once and is gone, and the use is audited. */
+    consumeApproval(callID: string, now: number, actor?: string): Promise<boolean>;
+    /** Take a grant back: the call is not approved after it. */
+    revokeApproval(callID: string, now: number): Promise<boolean>;
+}
+/**
+ * A grant, and whether this call wrote it.
+ *
+ * The store holds the lock while it decides, so it knows whether the grant
+ * was there already. The caller needs that: a grant that was written is
+ * audited, and a grant that was found is not.
+ */
+export interface ApprovalGrant {
+    /** The grant that is on file now. */
+    entry: ApprovalEntry;
+    /** Whether this call wrote it, as opposed to finding it there. */
+    created: boolean;
+}
+/**
+ * The lock that serialises a claim.
+ *
+ * Two calls that spend the same grant at the same time must not both pass,
+ * so the read and the write of the store are one step under a lock file
+ * that is created exclusively. The second caller waits and then finds the
+ * grant gone.
+ */
+export declare function withLock<T>(path: string, timing: ResolvedTiming, action: () => Promise<T>): Promise<T>;
+/**
+ * The lock is given back.
+ *
+ * The lock is moved to a private path with a rename, which is one atomic
+ * step, and the token is read there: a lock that was taken away from this
+ * writer and given to another one is not removed by mistake, and the lock
+ * of the other writer is put back.
+ */
+export declare function releaseLock(lockPath: string, token: string): Promise<void>;
+/**
+ * A lock that was moved aside goes back where it was.
+ *
+ * It is not put over a lock that is held now: the writer that holds that
+ * one would lose it. The link is one atomic step, so a lock that is taken
+ * in the window between the move and the restore is not lost either.
+ */
+export declare function restoreLock(privatePath: string, lockPath: string): Promise<void>;
+/**
+ * The store of grants for one project.
+ */
+export declare function createApprovalStore(stateRoot: string, timing?: ApprovalTiming): ApprovalStore;
+/**
+ * The rule handler that asks for an approval.
+ *
+ * A command that matches needs a grant. A pattern is enough for a single
+ * shape, and a matcher is enough for the shapes a pattern cannot say: the
+ * flags of `rm` in any order, for example.
+ *
+ * A store that cannot be read passes nothing: the command is refused, and
+ * the reason names the failure. A refusal is the safe answer, and the
+ * failure is not swallowed: it is in the reason.
+ */
+export declare function approvalGate(matcher: RegExp | ((command: string) => boolean), store: ApprovalStore, now?: () => number): (event: unknown) => Promise<HandlerResult>;
+//# sourceMappingURL=approvals.d.ts.map

package/dist/approvals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.d.ts","sourceRoot":"","sources":["../src/approvals.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD;;;;;;;GAOG;AAEH,iBAAiB;AACjB,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,0DAA0D;AAC1D,eAAO,MAAM,uBAAuB,QAAiB,CAAC;AA8CtD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qCAAqC;AACrC,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC,cAAc,CAAC,CAAC;AAEtD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,iDAAiD;AACjD,MAAM,WAAW,aAAa;IAC5B,6BAA6B;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2CAA2C;IAC3C,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,oDAAoD;IACpD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC7E,2EAA2E;IAC3E,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/E,4DAA4D;IAC5D,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,KAAK,EAAE,aAAa,CAAC;IACrB,kEAAkE;IAClE,OAAO,EAAE,OAAO,CAAC;CAClB;AA4BD;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CAgBZ;AAsDD;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBhF;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUtF;AAoHD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,GAAE,cAAmB,GAAG,aAAa,CAqFjG;AASD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,EAChD,KAAK,EAAE,aAAa,EACpB,GAAG,GAAE,MAAM,MAAiB,GAC3B,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,aAAa,CAAC,CA4B5C"}