@hasna/hooks 0.11.6 → 0.12.0

package/bin/serve.js

@@ -131,6 +131,7 @@ function getExplicitDbPath(env = process.env) {
 }
 
 // src/lib/registry.ts
+var CLAUDE_TRASH_GUARD_MATCHER = "^(Bash|Monitor|apply_patch|ApplyPatch|functions\\.apply_patch)$";
 var HOOKS = [
   {
     name: "gitguard",
@@ -181,6 +182,8 @@ var HOOKS = [
     category: "Git Safety",
     event: "PreToolUse",
     matcher: "^(Bash|Write|Edit|MultiEdit|NotebookEdit|apply_patch|ApplyPatch|functions\\.apply_patch)$",
+    targetMatchers: { claude: "^(Bash|Monitor|Write|Edit|MultiEdit|NotebookEdit|apply_patch|ApplyPatch|functions\\.apply_patch)$" },
+    legacyMatchers: ["^(Bash|Write|Edit|MultiEdit|NotebookEdit|apply_patch|ApplyPatch|functions\\.apply_patch)$"],
     tags: ["workspace", "repos", "structure", "guard", "safety", "orgs", "multi-agent"]
   },
   {
@@ -191,6 +194,8 @@ var HOOKS = [
     category: "Git Safety",
     event: "PreToolUse",
     matcher: "^(Bash|apply_patch|ApplyPatch|functions\\.apply_patch)$",
+    targetMatchers: { claude: CLAUDE_TRASH_GUARD_MATCHER },
+    legacyMatchers: ["^(Bash|apply_patch|ApplyPatch|functions\\.apply_patch)$"],
     tags: ["rm", "delete", "trash", "recoverable", "guard", "safety", "bash"],
     rewritesInput: true,
     timeoutSeconds: 10
@@ -295,6 +300,28 @@ var HOOKS = [
     matcher: "Bash",
     tags: ["security", "credentials", "secrets", "detection", "audit"]
   },
+  {
+    name: "signed-link-guard",
+    displayName: "Signed Link Guard",
+    description: "Refuses gh reads that would print composite GitHub content (bodies, comments, reviews, commit messages, check links and details, raw issue/PR/check API objects) where signed action links appear; bounded scalar projections, diffs, lists and writes pass",
+    version: "0.1.0",
+    category: "Security",
+    event: "PreToolUse",
+    matcher: "^(Bash|Monitor)$",
+    tags: ["github", "gh", "signed-links", "capabilities", "transcript", "guard", "security"],
+    timeoutSeconds: 10
+  },
+  {
+    name: "signed-link-output",
+    displayName: "Signed Link Output",
+    description: "Claude PostToolUse backstop: replaces signed-link URLs in tool output with a redaction marker (updatedToolOutput, where the running Claude Code supports it) and tells the model not to repeat or store the link. It runs after the tool, so it cannot undo display or other persistence",
+    version: "0.1.0",
+    category: "Security",
+    event: "PostToolUse",
+    matcher: "^(Bash|WebFetch|mcp__.*)$",
+    tags: ["github", "signed-links", "capabilities", "redaction", "transcript", "security"],
+    timeoutSeconds: 10
+  },
   {
     name: "phonenotify",
     displayName: "Phone Notify",

package/dist/index.js

@@ -6979,6 +6979,10 @@ var HOOK_EVENTS = [
   "UserPromptSubmit",
   "SubagentStart"
 ];
+var CLAUDE_TRASH_GUARD_MATCHER = "^(Bash|Monitor|apply_patch|ApplyPatch|functions\\.apply_patch)$";
+function matcherFor(meta, target) {
+  return meta.targetMatchers?.[target] ?? meta.matcher;
+}
 var CATEGORIES = [
   "Git Safety",
   "Code Quality",
@@ -7041,6 +7045,8 @@ var HOOKS = [
     category: "Git Safety",
     event: "PreToolUse",
     matcher: "^(Bash|Write|Edit|MultiEdit|NotebookEdit|apply_patch|ApplyPatch|functions\\.apply_patch)$",
+    targetMatchers: { claude: "^(Bash|Monitor|Write|Edit|MultiEdit|NotebookEdit|apply_patch|ApplyPatch|functions\\.apply_patch)$" },
+    legacyMatchers: ["^(Bash|Write|Edit|MultiEdit|NotebookEdit|apply_patch|ApplyPatch|functions\\.apply_patch)$"],
     tags: ["workspace", "repos", "structure", "guard", "safety", "orgs", "multi-agent"]
   },
   {
@@ -7051,6 +7057,8 @@ var HOOKS = [
     category: "Git Safety",
     event: "PreToolUse",
     matcher: "^(Bash|apply_patch|ApplyPatch|functions\\.apply_patch)$",
+    targetMatchers: { claude: CLAUDE_TRASH_GUARD_MATCHER },
+    legacyMatchers: ["^(Bash|apply_patch|ApplyPatch|functions\\.apply_patch)$"],
     tags: ["rm", "delete", "trash", "recoverable", "guard", "safety", "bash"],
     rewritesInput: true,
     timeoutSeconds: 10
@@ -7155,6 +7163,28 @@ var HOOKS = [
     matcher: "Bash",
     tags: ["security", "credentials", "secrets", "detection", "audit"]
   },
+  {
+    name: "signed-link-guard",
+    displayName: "Signed Link Guard",
+    description: "Refuses gh reads that would print composite GitHub content (bodies, comments, reviews, commit messages, check links and details, raw issue/PR/check API objects) where signed action links appear; bounded scalar projections, diffs, lists and writes pass",
+    version: "0.1.0",
+    category: "Security",
+    event: "PreToolUse",
+    matcher: "^(Bash|Monitor)$",
+    tags: ["github", "gh", "signed-links", "capabilities", "transcript", "guard", "security"],
+    timeoutSeconds: 10
+  },
+  {
+    name: "signed-link-output",
+    displayName: "Signed Link Output",
+    description: "Claude PostToolUse backstop: replaces signed-link URLs in tool output with a redaction marker (updatedToolOutput, where the running Claude Code supports it) and tells the model not to repeat or store the link. It runs after the tool, so it cannot undo display or other persistence",
+    version: "0.1.0",
+    category: "Security",
+    event: "PostToolUse",
+    matcher: "^(Bash|WebFetch|mcp__.*)$",
+    tags: ["github", "signed-links", "capabilities", "redaction", "transcript", "security"],
+    timeoutSeconds: 10
+  },
   {
     name: "phonenotify",
     displayName: "Phone Notify",
@@ -39789,6 +39819,7 @@ function registerHook(name, scope = "global", target = "claude", profile, mement
   if (uniqueEventKeys.length === 0) {
     throw new Error(`Hook '${name}' has no installable events for target '${target}'`);
   }
+  const matcher = matcherFor(meta3, target);
   const settings = readSettings2(scope, target);
   if (!settings.hooks)
     settings.hooks = {};
@@ -39823,10 +39854,12 @@ function registerHook(name, scope = "global", target = "claude", profile, mement
       }
     }
     if (positions.length) {
-      if (positions.length !== uniqueEventKeys.length || uniqueEventKeys.some((event) => positions.filter((position) => position.event === event).length !== 1) || positions.some((position) => (position.entry.matcher ?? "") !== (meta3.matcher ?? ""))) {
+      if (positions.length !== uniqueEventKeys.length || uniqueEventKeys.some((event) => positions.filter((position) => position.event === event).length !== 1) || positions.some((position) => (position.entry.matcher ?? "") !== matcher && !(meta3.legacyMatchers ?? []).includes(position.entry.matcher ?? ""))) {
         throw new Error("Codex hook events, matchers or duplicate registrations require explicit reconciliation; no settings were changed.");
       }
       for (const { entry, index } of positions) {
+        if (matcher)
+          entry.matcher = matcher;
         entry.hooks[index] = { ...entry.hooks[index], type: "command", command: hookCommand };
         if (typeof meta3.timeoutSeconds === "number" && meta3.timeoutSeconds > 0)
           entry.hooks[index].timeout = meta3.timeoutSeconds;
@@ -39846,8 +39879,8 @@ function registerHook(name, scope = "global", target = "claude", profile, mement
     const entry = {
       hooks: [hookEntry]
     };
-    if (meta3.matcher) {
-      entry.matcher = meta3.matcher;
+    if (matcher) {
+      entry.matcher = matcher;
     }
     settings.hooks[eventKey].push(entry);
   }
@@ -41351,7 +41384,7 @@ async function verifyNativeSafetyCommand(command, home = homedir7()) {
 }
 
 // src/lib/codex-safety-check.ts
-var versions = new Set(["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"]);
+var versions = new Set(["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"]);
 var matcher = "^(Bash|apply_patch|ApplyPatch|functions\\.apply_patch)$";
 
 class CodexSafetyError extends Error {
@@ -41896,7 +41929,7 @@ async function verifyClaudeSafetyConfiguration(options = {}, dependencies = {})
           need8(!/^(?:hooks run trash-guard|hook-trash-guard)(?:\s|$)/.test(handler.command.trim()), "guard_definition_invalid");
           if (binding?.name !== "trash-guard")
             continue;
-          need8(binding.home === home && event === "PreToolUse" && handler.type === "command" && group.matcher === "^(Bash|apply_patch|ApplyPatch|functions\\.apply_patch)$" && handler.timeout === 10 && (handler.async === undefined || handler.async === false) && handler.asyncRewake !== true, "guard_definition_invalid");
+          need8(binding.home === home && event === "PreToolUse" && handler.type === "command" && group.matcher === CLAUDE_TRASH_GUARD_MATCHER && handler.timeout === 10 && (handler.async === undefined || handler.async === false) && handler.asyncRewake !== true, "guard_definition_invalid");
           guards.push({ command: handler.command, path: file2.path });
         }
       }

package/dist/lib/native-safety-registration.d.ts

@@ -7,9 +7,12 @@ export declare class NativeRegistrationError extends Error {
 export interface NativeRegistrationOptions {
     target: "codex" | "claude";
 }
+export interface NativeReadinessRegistrationOptions {
+    target: "codex" | "claude" | "sumi";
+}
 export interface NativeRegistrationPlan {
     schema: "hasna.hooks.native-safety-registration/v1" | "hasna.hooks.native-readiness-registration/v1";
-    target: "codex" | "claude";
+    target: "codex" | "claude" | "sumi";
     settingsPath: string;
     resolvedPath: string;
     beforeSHA256: string;
@@ -24,6 +27,21 @@ export interface NativeRegistrationPlan {
 interface Dependencies {
     verify?: typeof verifyNativeSafetyCommand;
 }
+/** Sumi observes startup inside its own process through the bundled
+ * `@hasna/hooks/native-readiness` SDK, enabled by Sumi's own
+ * `experimental.trash_readiness` setting, so there is no startup command to
+ * write into a harness settings file. The Hooks-owned Sumi registration is the
+ * native guard record `~/.hasna/hooks/native/sumi-trash-guard.json`: it pins a
+ * Hooks runtime and worker, and Sumi's startup check requires it (Trash runs
+ * `hooks safety verify --target sumi --execution`). Planning re-points that
+ * record at this installed package without writing. Applying requires the exact
+ * plan digest, keeps the previous record as `<path>.before-<sha256>` and journals
+ * the operation. Sumi's own configuration is never read or written here. */
+export interface SumiRegistrationDependencies {
+    home?: string;
+    command?: string;
+    verify?: typeof verifyNativeSafetyCommand;
+}
 export declare const planNativeSafetyRegistration: (options: NativeRegistrationOptions, dependencies?: Dependencies) => Promise<NativeRegistrationPlan>;
 export declare const applyNativeSafetyRegistration: (options: NativeRegistrationOptions & {
     expectedPlanDigest: string;
@@ -38,7 +56,7 @@ export declare const applyNativeSafetyRegistration: (options: NativeRegistration
     guardVerified: boolean;
 } | {
     schema: "hasna.hooks.native-safety-registration/v1" | "hasna.hooks.native-readiness-registration/v1";
-    target: "codex" | "claude";
+    target: "codex" | "claude" | "sumi";
     settingsPath: string;
     resolvedPath: string;
     beforeSHA256: string;
@@ -52,10 +70,11 @@ export declare const applyNativeSafetyRegistration: (options: NativeRegistration
     ok: boolean;
     changed: boolean;
 }>;
-export declare const planNativeReadinessRegistration: (options: NativeRegistrationOptions) => Promise<NativeRegistrationPlan>;
-export declare const applyNativeReadinessRegistration: (options: NativeRegistrationOptions & {
+/** `sumiDependencies` is a test seam for the Sumi target only. */
+export declare const planNativeReadinessRegistration: (options: NativeReadinessRegistrationOptions, sumiDependencies?: SumiRegistrationDependencies) => Promise<NativeRegistrationPlan>;
+export declare const applyNativeReadinessRegistration: (options: NativeReadinessRegistrationOptions & {
     expectedPlanDigest: string;
-}) => Promise<{
+}, sumiDependencies?: SumiRegistrationDependencies) => Promise<{
     nativeAdoptionVerified: boolean;
     readinessRunnerVerified?: boolean | undefined;
     ok: boolean;
@@ -66,7 +85,31 @@ export declare const applyNativeReadinessRegistration: (options: NativeRegistrat
     guardVerified: boolean;
 } | {
     schema: "hasna.hooks.native-safety-registration/v1" | "hasna.hooks.native-readiness-registration/v1";
-    target: "codex" | "claude";
+    target: "codex" | "claude" | "sumi";
+    settingsPath: string;
+    resolvedPath: string;
+    beforeSHA256: string;
+    desiredSHA256: string;
+    commandSHA256: string;
+    action: "unchanged" | "register";
+    planDigest: string;
+    guardVerified: boolean;
+    readinessRunnerVerified?: true;
+    nativeAdoptionVerified: false;
+    ok: boolean;
+    changed: boolean;
+}> | Promise<{
+    nativeAdoptionVerified: boolean;
+    backup?: string | undefined;
+    ok: boolean;
+    changed: boolean;
+    operationId: `${string}-${string}-${string}-${string}-${string}`;
+    planDigest: string;
+    settingsSHA256: string;
+    guardVerified: boolean;
+} | {
+    schema: "hasna.hooks.native-safety-registration/v1" | "hasna.hooks.native-readiness-registration/v1";
+    target: "codex" | "claude" | "sumi";
     settingsPath: string;
     resolvedPath: string;
     beforeSHA256: string;

package/dist/lib/registry.d.ts

@@ -21,6 +21,17 @@ export interface HookMeta {
      * reports it.
      */
     rewritesInput?: boolean;
+    /**
+     * A different matcher for one harness. Claude Code's `Monitor` tool runs a
+     * shell command and streams its stdout to the model, so the bundled guards
+     * add it on Claude; Codex has no such tool and keeps its verified matcher.
+     */
+    targetMatchers?: Partial<Record<"claude" | "codex", string>>;
+    /**
+     * Earlier matchers of an installed native registration that an in-place
+     * update may replace with the current one.
+     */
+    legacyMatchers?: string[];
     /**
      * Timeout (seconds) written into the agent's settings entry for this hook.
      * The harness default is 600s, and a TIMED-OUT HOOK DOES NOT BLOCK: a guard
@@ -28,6 +39,10 @@ export interface HookMeta {
      */
     timeoutSeconds?: number;
 }
+/** The Claude Code matcher of the bundled Trash guard registration (Bash, Monitor and patch tools). */
+export declare const CLAUDE_TRASH_GUARD_MATCHER = "^(Bash|Monitor|apply_patch|ApplyPatch|functions\\.apply_patch)$";
+/** The matcher a hook is registered with for one harness. */
+export declare function matcherFor(meta: HookMeta, target: string): string;
 export declare const CATEGORIES: readonly ["Git Safety", "Code Quality", "Security", "Notifications", "Context Management", "Workflow Automation", "Environment", "Permissions", "Observability", "Agent Teams"];
 export type Category = (typeof CATEGORIES)[number];
 export declare const HOOKS: HookMeta[];

package/dist/native-safety.d.ts

@@ -38,10 +38,14 @@ export type NativeSafetyRecord = {
     harness: "sumi";
     command: string;
 };
+/** The exact bytes every writer stores for a Sumi guard record. Planners use
+ * the same bytes to compute a desired digest before any write. */
+export declare function nativeSafetyRecordText(command: string): string;
 export declare function readNativeSafetyRegistration(home?: string): {
     record: NativeSafetyRecord;
     sha256: string;
     path: string;
+    text: string;
 };
 /** Bounded, non-leaking explanation for a refused binding: which integrity
  * property the saved record fails. A binding that a third party could rewrite

package/dist/native-safety.js

@@ -199,11 +199,16 @@ function syncDirectory(path) {
     closeSync2(fd);
   }
 }
+function nativeSafetyRecordText(command) {
+  const record = { schema: "hasna.hooks.native-safety.v1", harness: "sumi", command };
+  return JSON.stringify(record) + `
+`;
+}
 function readNativeSafetyRegistration(home = homedir2()) {
   try {
     home = canonicalHome(home);
     const path = join2(home, ".hasna/hooks/native", filename), text = readOwned(path);
-    return { record: parseRecord(text, home), sha256: hash(text), path };
+    return { record: parseRecord(text, home), sha256: hash(text), path, text };
   } catch (error) {
     if (error instanceof NativeSafetyError)
       throw error;
@@ -229,9 +234,7 @@ function nativeSafetyBindingIntegrityReason(home = homedir2()) {
 }
 function registerNativeSafety(options = {}) {
   const home = canonicalHome(options.home ?? homedir2());
-  const record = { schema: "hasna.hooks.native-safety.v1", harness: "sumi", command: options.command ?? installedNativeSafetyCommand("trash-guard") };
-  const text = JSON.stringify(record) + `
-`;
+  const text = nativeSafetyRecordText(options.command ?? installedNativeSafetyCommand("trash-guard"));
   parseRecord(text, home);
   for (const dir of [join2(home, ".hasna"), join2(home, ".hasna/hooks"), join2(home, ".hasna/hooks/native")]) {
     try {
@@ -412,6 +415,7 @@ export {
   verifyNativeSafetyCommand,
   registerNativeSafety,
   readNativeSafetyRegistration,
+  nativeSafetyRecordText,
   nativeSafetyBindingIntegrityReason,
   evaluateNativeSafetyForExecution,
   evaluateNativeSafety,

package/hooks/hook-signed-link-guard/README.md

@@ -0,0 +1,228 @@
+# signed-link-guard
+
+PreToolUse guard for shell commands, installed as `hooks run signed-link-guard`
+with the matcher `^(Bash|Monitor)$`. It judges Claude Code's `Bash` tool and its
+`Monitor` tool (Monitor runs a shell command and streams each stdout line to the
+model), and Codex's `Bash`. The bundled native safety entry
+(`hooks safety install trash-guard`) also evaluates it for every Bash and
+Monitor command, whatever capability name the registration uses.
+
+Composite GitHub content (bodies, comments, reviews, commit messages, check
+links and check details) carries third-party signed action links: URLs with a
+signature parameter, a multi-week expiry and no revoke path. A tool result stays
+in the agent's transcript, so a printed link is an exposed capability. This
+guard refuses a command before it runs when any `gh` invocation in it would
+print that content. The refusal reason is always exactly:
+
+```
+composite output withheld: signed-link shape; use bounded scalar projections per class disposition 799310
+```
+
+## What it refuses
+
+1. `gh pr view`, `gh issue view`, `gh release view`, `gh discussion view`:
+   - without `--json` (the human view prints the body), so a plain
+     `gh pr view <n>` is refused;
+   - with `--comments` / `-c`;
+   - with a `--json` field outside the scalar list below, unless a `--jq`
+     projection provably prints only bounded scalars.
+   `--web` / `-w` is allowed: it opens a browser and prints nothing. A flag's
+   last occurrence wins and `--web=false`, `-w=false` or `--web=0` is not set,
+   as gh's own flag parser reads them.
+2. `gh pr checks` without `--json` (the table prints check links, and so does
+   `--watch`), or with a `--json` field other than `bucket, completedAt, event,
+   name, startedAt, state, workflow` (`link` and `description` are refused)
+   unless a scalar `--jq` projection selects from them.
+3. `gh api` on REST endpoints that return bodies, comments, reviews, commit
+   messages, check runs or suites, statuses, events, deployment payloads or
+   issue and pull request objects:
+   - `repos/<o>/<r>/{pulls,issues,commits,check-runs,check-suites,statuses,
+     comments,releases,compare,events,discussions,deployments,milestones}`
+     (issue labels excepted);
+   - a single branch `repos/<o>/<r>/branches/<b>` (it carries the head
+     commit's message; the branch list, protection and rename endpoints do
+     not);
+   - `…/git/{commits,tags}`, `…/actions/{runs,jobs}` (logs excepted, see
+     below), `…/actions/workflows/<id>/runs`, webhook deliveries;
+   - `issues`, `user/issues`, `orgs/<o>/issues`, `search/{issues,commits}`,
+     user, org and network events, project items and cards, team
+     discussions.
+
+   The endpoint is normalised as the request reaches GitHub first: an
+   `https://api.github.com/` or GHES `/api/v3/` origin, the query string and
+   fragment are stripped, `%2F` and other escapes are decoded, `.` and `..`
+   are resolved and letters are lower-cased. Any other absolute URL (a
+   github.com page, a raw `.patch`) cannot be classified and is refused.
+4. `gh api graphql` queries selecting `body`, `bodyText`, `bodyHTML`,
+   `comments`, `reviews`, `reviewThreads`, commit `message*`,
+   `autoMergeRequest { commitBody commitHeadline }`, `summary`, `text`,
+   `description`, `annotations`, `payload`, `url` or any `*Url` / `*HTML`
+   field, and a check run's or status context's `title`. The query is read
+   with a GraphQL tokenizer, so strings, block strings and `#` comments are
+   not selections; an unbalanced query counts as sensitive.
+5. `gh api` writes whose response echoes the object: `PATCH` of an issue,
+   pull request, review or comment, and other writes on the families above.
+   Writes whose documented response is empty or scalar pass (GitHub REST
+   OpenAPI description 1.1.4): deleting a comment, reaction, label, release,
+   asset, run, deployment or milestone; re-running, cancelling or approving a
+   run or job; `PUT pulls/<n>/merge` (it returns `sha`, `merged` and a GitHub
+   status message) and `update-branch`; setting, adding or removing issue
+   labels; locking an issue. For the others use `--silent` or a scalar `--jq`.
+6. `gh api` reads of a sensitive family without `--silent` or a `--jq` / `-q`
+   projection the guard can prove prints only bounded scalars (see below).
+7. Other composite reads: `gh status` (it prints comment and mention
+   excerpts), `gh pr diff --patch` (each commit's full message), `gh project
+   item-list --format json` without a scalar `--jq`, and `--json` lists with a
+   composite field on `gh pr list`, `gh issue list`, `gh pr status`,
+   `gh issue status`, `gh search prs|issues|commits`, `gh release list` and
+   `gh discussion list`.
+8. Traffic logging. `GH_DEBUG` (any value except empty, `0`, `false` and `no`;
+   gh's legacy `DEBUG` for `1`, `true`, `yes` and `api`) and `gh api
+   --verbose` make gh log the raw HTTP responses whatever `--jq` or `--silent`
+   print. Under them a call passes only when it provably fetches no link field:
+   a view, list, status or search whose `--json` fields are all scalar, or a
+   `gh api` call on an endpoint outside the families above (logs endpoints
+   excepted). Every other gh command is refused under `GH_DEBUG`, writes and
+   `gh run` included; `gh pr checks` is always refused under it, because its
+   query fetches every check's `detailsUrl` whatever `--json` selects. The
+   variable is read from assignments in the command (`GH_DEBUG=api gh …`,
+   `export GH_DEBUG=1; gh …`, `env GH_DEBUG=1 gh …`).
+9. Fail closed: an endpoint, field list or query built from an expansion
+   (`$VAR`, `$( )`, a glob or brace list), a GraphQL query read from a file or
+   stdin, an unknown `gh` command (it may be an alias for a read above), an
+   unknown subcommand of `pr`, `issue`, `release`, `discussion` or `search`, a
+   read whose arguments `xargs` appends from stdin (`… | xargs gh pr view`),
+   and a command that cannot be parsed to its end while it mentions `gh`.
+
+## Scalar `--json` fields
+
+- Pull requests: `additions, assignees, author, baseRefName, baseRefOid,
+  changedFiles, closed, closedAt, createdAt, deletions, files, fullDatabaseId,
+  headRefName, headRefOid, headRepository, headRepositoryOwner, id,
+  isCrossRepository, isDraft, labels, maintainerCanModify, mergeCommit,
+  mergeStateStatus, mergeable, mergedAt, mergedBy, number,
+  potentialMergeCommit, reactionGroups, reviewDecision, reviewRequests, state,
+  title, updatedAt, url`.
+- Issues: `assignees, author, closed, closedAt, createdAt, id, isPinned,
+  labels, number, reactionGroups, state, stateReason, subIssuesSummary, title,
+  updatedAt, url`.
+- Releases: `apiUrl, author, createdAt, databaseId, id, isDraft, isImmutable,
+  isLatest, isPrerelease, name, publishedAt, tagName, tarballUrl,
+  targetCommitish, uploadUrl, url, zipballUrl`.
+
+The object's own `url` is allowed: GitHub generates it from the owner,
+repository and number, and it has no query string that could carry a
+signature. Labels are allowed because a label description is a repository
+setting capped at 100 characters. Refused composite fields include `body,
+comments, reviews, latestReviews, statusCheckRollup, commits,
+autoMergeRequest, closingIssuesReferences, closedByPullRequestsReferences,
+blockedBy, blocking, parent, subIssues, milestone, projectCards,
+projectItems, issueType, category, assets`, and any field a future gh adds.
+
+## `--jq` projections
+
+A `--jq` / `-q` filter admits a command when every output provably ends at a
+scalar, non-free-text field. This applies to `gh api`, to `gh project
+item-list --format json`, and to the `--json` commands above, where it admits
+a composite field: `gh pr view 12 --json body --jq '.body | length'` passes.
+Accepted examples: `.head.sha`, `.[] | .name`, `[.number, .title]`,
+`{number, state}`, `"\(.number) \(.title)"`, `.check_runs[] | [.name,
+.conclusion] | @tsv`, `.body | length`, `map(.name) | join(",")`,
+`.[] | select(.user.login == "x") | .id`, and on a single pull request or
+issue the counts `.commits`, `.comments` and `.review_comments`.
+
+Scalar leaves are identifiers, numbers, counts, booleans, enums, refs, object
+ids, timestamps and short names (`id`, `number`, `state`, `conclusion`,
+`name`, `login`, `sha`, `title`, `created_at`, `digest`, `size_in_bytes`,
+`run_started_at`, `date`, `wait_timer`, `ahead_by`, `behind_by`,
+`total_commits`, …) and `html_url`. `html_url` is admitted because in every
+response the guard refuses it is a GitHub-generated `github.com/<owner>/<repo>/…`
+page address with at most an anchor or a GitHub filter query; the schemas where
+someone else sets it (license, Pages site, dependency-snapshot job) are not
+among them. Other URL fields (`url`, `details_url`, `target_url`) stay refused.
+
+Refused: anything outside the supported jq subset (`..`, `if`, `reduce`,
+variables, `$ENV`, `input`, dynamic object keys, regular-expression functions
+with a non-literal pattern, `#` comments, which gojq continues across a
+backslash-newline), any whole object (`.`, `.head`, `.[]`), any free-text leaf
+(`.body`, `.output.summary`), anything projected out of a free-form container
+(`payload`, `inputs`, check `output`, `config`, …), and anything projected out
+of an object or array the filter built from a composite field
+(`{name: .body} | .name`, `[.body] | .[0]`). `--verbose` and `--template` void
+a projection.
+
+## Where commands can hide
+
+Command position is honoured (only a `gh` word in command position counts,
+after assignments, keywords and `env`, `sudo`, `timeout`, `nice`, `command`,
+`exec`, `nohup`, `time` and similar wrappers), and the guard follows:
+
+- pipelines, `&&`, `||`, `;`, subshells, `{ …; }` groups and `function`
+  bodies;
+- `$( … )` and backticks, also inside double quotes and unquoted
+  here-documents; a here-document body inside `$( )` is data, so the default
+  write spelling `gh pr comment 1 --body "$(cat <<'EOF' … EOF)"` passes
+  whatever the body says (apostrophes, an unbalanced `)`, nested quotes, or
+  the text of a refused command);
+- `bash|sh|zsh -c`, also when the string is built by `$(cat <<EOF …)` or
+  `$(echo …)`, `eval`, `env -S`, `su|runuser|script|flock -c`, `ssh <host>
+  <command>`, `gh codespace ssh … -- <command>` and `watch`;
+- text a shell reads as its script: literal `echo`, `printf` or `cat <<EOF`
+  output piped into `bash` or `sh`, here-documents and here-strings fed to a
+  shell, `source <(…)`, `. <(…)` and `. /dev/stdin`;
+- `xargs … gh …` and `find … -exec gh … ;`;
+- runners that pass a bare `gh` word on (`secrets exec … -- gh`, `op run --
+  gh`, `unbuffer gh`, `npx`, `bun x`, `docker`, …).
+
+A command word built by expansion is judged by its literal basename when it
+has one: `"$HOME/.bun/bin/tool" status` is not gh, `"$HOME/bin/gh" pr view 1`
+is. A word with no readable name (`$GH`, `"$(command -v gh)"`) is judged as gh.
+Any other program's `gh` argument is data: `node x.js gh pr view 1` is not a
+gh call.
+
+## Always allowed
+
+`gh pr diff` (without `--patch`), `gh pr list` / `gh issue list` tables,
+`gh pr view --json` with scalar fields, every `gh` write subcommand (`create`,
+`comment`, `edit`, `merge`, `review`, …; `--body` and `--body-file` are input,
+not output), `gh run`, `gh repo`, `gh workflow`, `gh release download`, `gh
+api` on other endpoints, `--help`, and every command that does not run `gh`.
+
+Workflow logs are allowed: `gh run view --log`, `--log-failed` and `gh api
+…/actions/runs/<id>/logs` or `…/actions/jobs/<id>/logs` print the
+repository's own step output, not the composite objects of this class, and
+the two routes are treated the same. They are downloads through a redirect to
+a signed storage URL that gh follows without printing; `--verbose` and
+`GH_DEBUG` print that redirect, so under them the logs endpoints are refused.
+
+## Scalar alternatives
+
+| Instead of | Use |
+|---|---|
+| `gh pr view 12` | `gh pr view 12 --json number,title,state,headRefOid,url` |
+| reading a body | `gh pr view 12 --json body --jq '.body \| length'`, or `gh pr view 12 --web` |
+| `gh pr checks 12` | `gh pr checks 12 --json name,state,bucket` |
+| failing checks | `gh pr checks 12 --json name,bucket --jq '.[] \| select(.bucket == "fail") \| .name'` |
+| `gh pr checks 12 --watch` | `gh run watch <run-id> --exit-status`, or poll `gh pr checks 12 --json bucket --jq '[.[] \| select(.bucket == "pending")] \| length'` |
+| `gh api repos/o/r/pulls/12` | `gh api repos/o/r/pulls/12 --jq .head.sha` |
+| `gh api -X PATCH repos/o/r/issues/12 -f state=closed` | the same with `--silent` |
+
+gh refuses `--watch` together with `--json`, so a scalar watch is a polling
+loop or `gh run watch`.
+
+## Limits
+
+- It judges the command text. A script file, a shell alias or function
+  defined in an earlier command or a startup file, a program that runs `gh`
+  itself (Python, Node, Perl, awk, `make`, a git alias) and a `gh` extension's
+  own output are not visible to it.
+- `GH_DEBUG` set in the harness's own environment, rather than in the
+  command, is not visible to it.
+- `curl`, `wget` and other HTTP clients calling `api.github.com` directly,
+  and `git log` or `git show` of a commit message, are outside its scope.
+- It is not the only exposure path: workflow logs, `gh pr diff`, file
+  contents and other tools can print a link that someone wrote there. The
+  optional `signed-link-output` PostToolUse hook is the backstop for output.
+- Codex's interactive terminal input (`write_stdin` into a running unified
+  exec session) has not been verified to pass through PreToolUse; a command
+  typed into a running shell that way may not be judged.

package/hooks/hook-signed-link-guard/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "signed-link-guard",
+  "version": "0.1.0",
+  "description": "PreToolUse Signed Link Guard hook for @hasna/hooks",
+  "type": "module",
+  "main": "./src/hook.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Hasna",
+  "license": "Apache-2.0"
+}