@gitkraken/agent-tools 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/) and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-12
+
+### Added
+
+- OpenCode MCP layout selection (core-tools#164). `McpInstallRequest.openCode` and `generateConfigEntry`/`clientJSONPath` options take an `OpenCodeMcpPolicy`: `{ mode: 'authoritative', layout: 'v1' | 'v2' }` writes and prunes the other layout, `{ mode: 'infer-existing' }` follows the layout the config already uses (v1 when both exist, the entry OpenCode launches) and never prunes. Omitting it keeps the 0.1.1 behavior (v2, v1 pruned). `inspectMcpInstall` results and `installMcp` results report the selected `openCodeLayout`.
+- `inspectMcpInstall` reports `missing` with the new reason `layout-unknown` when `infer-existing` finds no GitKraken entry in either OpenCode layout (including a missing or blank file), the cases where `installMcp` would throw `OpenCodeMcpLayoutUnknownError`. `McpInstallStatus.openCodeDuplicateLocation` is the JSON pointer of the GitKraken entry in the OpenCode layout that was not compared, present whenever both layouts hold one; it is reported only and never pruned by `infer-existing`.
+- `OpenCodeMcpLayoutUnknownError` for `infer-existing` with no GitKraken entry to follow, or in a read-free helper; `OpenCodeMcpCleanupError`, carrying the committed `result`, when the selected entry was written but removing the other layout's entry failed. Cancellation (`AbortError`) is rethrown as-is.
+
+### Changed
+
+- OpenCode migration is two writes: the selected entry first with the other layout retained, then the removal, after re-reading to confirm the file is unchanged. A v2 write refuses a flat server named `servers` and a non-object `mcp` or `mcp.servers`.
+- `inspectMcpInstall` reports a prunable OpenCode duplicate with the selected entry and location (previously the duplicate's), and an entry only in the other layout as `legacy-location` in either direction.
+- `inspectMcpInstall` reports an OpenCode config that `installMcp` refuses (a non-object root, `mcp` or `mcp.servers`, or a flat server named `servers` under a v2 policy) as `missing` with the new reason `unsafe-config`, instead of `no-entry`.
+- Safe OpenCode migration needs the host `FileSystemPort.writeFile` to leave the previous file intact when it rejects. Custom fields inside a replaced GitKraken entry are not carried across layouts.
+
+### Fixed
+
+- `uninstallMcp` and `getClientInstallation` no longer treat a `GitKraken` key on a flat OpenCode server named `servers` as a v2 entry, so uninstall leaves it intact.
+
+## [0.1.1] - 2026-10-02
+
+### Added
+
+- Initial scaffold of `@gitkraken/agent-tools` (P6, gkcli#1726): `AgentHostConfig`, `joinPath`, and the `./testing` subpath with an in-memory `FileSystemPort`.
+- The 16-id MCP client registry (`gemini` retained as legacy, uninstall-only), path resolution over `AgentHostConfig.paths`, `installMcp`/`uninstallMcp` (comment-preserving JSONC via `jsonc-parser`, comment-preserving TOML splicing for Codex), `inspectMcpInstall`, `detectClient`/`getClientInstallation`, and `getMcpCliInstallCommand`.
+- `installMcp` and `uninstallMcp` report each file they touched (created, updated or unchanged), the locations written or removed and why nothing was removed; a re-run of `installMcp` writes nothing. `inspectMcpInstall` reports why an entry is missing or drifted, `detectClient` reports how a client was found, and `getClientInstallation` lists the files that carry an entry. The shared `FileChange` type records per-file changes.
+- OpenCode is installed in its v2 shape; a v1 entry is pruned on install, reported as a legacy location by `inspectMcpInstall`, and still removed by `uninstallMcp`.
+- Per-host hook install/uninstall (`installHooks`, `uninstallHooks`): JSON hook writers, the Claude Code marketplace plugin, and opencode/pi relay plugins, plus the `eventManifest` each host is registered against.
+- `installHooks` and `uninstallHooks` report the hooks file, the events installed, removed or still hooked, and each file created, updated, unchanged or removed, with a `reason` when nothing was removed. Refusals throw `HookConfigError`, carrying a kebab-case `code` and the `path` involved.
+- `listAgents` reports how each MCP row was detected (`detection`) and which config files carry a GitKraken entry (`mcpConfigPaths`).
+- `inspectSkillStatus`/`installSkill`/`uninstallSkill` and per-agent skill directory resolution, with skill ownership recorded in `.gk-skill.json`. Results report the skill directory, each file created, updated, unchanged or removed, and machine-readable status reasons; conflicts throw errors carrying a `code`, the `operation` and the `path`.

package/LICENSE

@@ -0,0 +1,19 @@
+Core Tools License
+
+Copyright (c) 2025-2026 Axosoft, LLC dba GitKraken ("GitKraken")
+
+This software and associated documentation files (the "Software") may be compiled as part of GitKraken software products, including the gitkraken/vscode-gitlens open source project (collectively, the "GitKraken Products"), to the extent the Software is a required component of the GitKraken Products; provided, however, that the Software and its functionality may only be used if you (and any entity that you represent) have agreed to, and are in compliance with, the GitKraken End User License Agreement, available at https://gitkraken.com/eula (the "EULA"), or other agreement governing the use of the Software, as agreed by you and GitKraken, and otherwise have a valid subscription for the correct number of user seats for the applicable version of the Software (e.g., GitLens Free+, GitLens Pro, GitLens Teams, and GitLens Enterprise).
+
+The Software is licensed, not sold. This license only gives you some rights to use the Software. GitKraken reserves all other rights. Unless applicable law gives you more rights despite this limitation, you may use the Software only as expressly permitted in this license. In doing so, you must comply with any technical limitations in the Software that only allow you to use it in certain ways. You may not (i) work around any technical limitations in the Software, (ii) reverse engineer, decompile or disassemble the Software, or otherwise attempt to derive the source code for the Software, except and to the extent required by third party licensing terms governing use of certain open source components that may be included with the Software, (iii) remove, minimize, block or modify any notices of GitKraken or its suppliers in the Software, (iv) use the software in any way that is against the law, (v) host, share, publish, rent or lease the Software; (vi) distribute the Software as a stand-alone or integrated offering or combine it with any of your applications for others to use, (vii) use the Software other than in connection with validly licensed GitKraken Products or (viii) use any portion of the Software to create software with the same or similar functionality.
+
+You agree that GitKraken and/or its licensors (as applicable) retain all right, title and interest in and to the Software and all modifications and/or patches thereto. You are not granted any other rights beyond what is expressly stated herein. Except as set forth above, it is forbidden to copy, merge, publish, distribute, sublicense, modify and/or sell the Software.
+
+If you give feedback about the Software to GitKraken, you give to GitKraken, without charge, the right to use, share and commercialize your feedback in any way and for any purpose. You will not give feedback that is subject to a license that requires GitKraken to license its software or documentation to third parties because we include your feedback in them. These rights survive this License.
+
+The full text of this Core Tools License shall be included in all copies or substantial portions of the Software.
+
+This License and the EULA, if applicable, are the entire agreement for the Software. You must comply with all domestic and international export laws and regulations that apply to the Software, which include restrictions on destinations, end users and end use. This License is governed and construed by the laws of the State of Arizona, United States without regard to any choice or conflict of law principles or rules.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL GITKRAKEN, THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+For all third party components incorporated into the Software, those components are licensed under the original license provided by the owner of the applicable component.

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# @gitkraken/agent-tools
 
-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 current scaffold exports `AgentHostConfig`, `AgentHostPaths`, `AgentOrigin`, `joinPath`, and a testing `MemoryFileSystem`. Client detection, MCP and skill configuration, and hook configuration are planned for later layers.
+
+The package is **ports & adapters**: it never touches the real filesystem, the environment, or a child process directly. `AgentHostConfig` describes the host-provided platform, paths, filesystem port, and optional process facts. `joinPath` joins path segments using `/` without importing `node:path`.
+
+```ts
+import { joinPath } from '@gitkraken/agent-tools';
+
+const settingsPath = joinPath('/Users/me', '.config', 'settings.json');
+```
+
+## Install
+
+```sh
+pnpm add @gitkraken/agent-tools
+```
+
+## Host configuration types
+
+Import the configuration types when implementing a host adapter:
+
+```ts
+import type { AgentHostConfig } from '@gitkraken/agent-tools';
+
+const config: AgentHostConfig = {
+	platform: 'darwin', // 'darwin' | 'linux' | 'win32'
+	paths: {
+		home: '/Users/me',
+		configHome: '/Users/me/.config', // resolved $XDG_CONFIG_HOME
+		appSupport: '/Users/me/Library/Application Support',
+		// claudeConfigDir, copilotHome, grokHome, piAgentDir: resolved env overrides, when set
+	},
+	fs: myFileSystemPort, // @gitkraken/shared-tools FileSystemPort
+	resolveExecutable: (command) => myPathLookup(command), // optional: a client's binary on PATH
+	openCodeMajor: 2, // optional: the installed OpenCode major version (0/undefined = unknown); does not select the MCP layout
+};
+```
+
+## MCP install/uninstall
+
+```ts
+import { getMcpCliInstallCommand, inspectMcpInstall, installMcp, uninstallMcp } from '@gitkraken/agent-tools';
+
+// 1. Try the client's own CLI first, when it has one. `undefined` means go straight to step 2.
+const request = { client: 'vscode', executablePath: '/usr/local/bin/gk', args: ['mcp', '--host=vscode'] } as const;
+const argv = await getMcpCliInstallCommand(request, config);
+if (argv) {
+	const ok = await myHost.run(argv); // your own process spawn
+	if (ok) return;
+}
+
+// 2. Fall back to a direct, comment-preserving config-file write.
+const installed = await installMcp(request, config);
+// { client, path, change: 'created' | 'updated' | 'unchanged', format, location, entry, removedLocations }
+
+// Drift check, e.g. for a status command:
+const status = await inspectMcpInstall(request, config);
+// { state: 'missing' | 'drifted' | 'current', reason?, key?, entry?, path, location }
+
+const removal = await uninstallMcp({ client: 'vscode' }, config);
+// { client, removed, files: [{ path, change, removedLocations, reason? }] }
+```
+
+`installMcp`/`uninstallMcp`/`inspectMcpInstall` accept an optional `configPath` to target a specific file directly instead of the client's resolved config path.
+
+`getMcpCliInstallCommand` returns `undefined` when a shortcut cannot do the job: the client has none, a `configPath` is set, the client is Cursor (its config file is always written directly), or Codex's config still holds the legacy `['mcp_servers.GitKraken']` table. `installMcp` and `uninstallMcp` throw `unsupported client` for an unknown id (`installMcp` also for the uninstall-only `gemini`), and throw without writing when a config file does not parse (`inspectMcpInstall` reports `invalid-config` instead). A leading UTF-8 BOM is accepted and kept.
+
+Re-running `installMcp` when the entry is already in place writes nothing and reports `change: 'unchanged'`. `inspectMcpInstall` says why an entry is not current (`reason`, and the drifting `key`) and exposes the on-disk `entry`, so a host can carry user-added args forward before reinstalling.
+
+### OpenCode layouts
+
+OpenCode reads MCP servers from `/mcp/<name>` (v1) or `/mcp/servers/<name>` (v2). Omitting `openCode` writes v2 and prunes a v1 entry, as in 0.1.1. A host that probed the installed OpenCode should pass a policy on every OpenCode call (inspect before and after repair, and install). The library never runs the probe or compares versions:
+
+```ts
+// Verified earlier-v1 OpenCode -> v1; verified >= 1.18.24, or a v2 client -> v2.
+const policy = { mode: 'authoritative', layout: 'v1' } as const;
+// Probe failed or unparseable: follow what the config already uses, never prune.
+const unknown = { mode: 'infer-existing' } as const;
+
+await installMcp({ ...request, openCode: policy }, config);
+generateConfigEntry('opencode', '/usr/local/bin/gk', ['mcp'], { openCode: policy });
+// { type: 'local', command: ['/usr/local/bin/gk', 'mcp'], enabled: true }   (v2 uses `disabled: false`)
+clientJSONPath('opencode', { openCode: policy }); // '/mcp/GitKraken'
+```
+
+- `authoritative` writes the selected layout and removes the other layout's GitKraken entry. `infer-existing` follows the layout the config already uses and repairs that entry in place; with both layouts present it selects v1, because OpenCode's compatibility reader retains it over the native entry. It leaves the duplicate alone. It never authorizes pruning, even if you copy the reported `openCodeLayout` elsewhere; pass `infer-existing` unchanged through both inspections and the install.
+- `infer-existing` throws `OpenCodeMcpLayoutUnknownError` when there is no entry to follow, and in the read-free helpers (`generateConfigEntry`, `clientJSONPath`), which cannot read the config. To generate an entry without a probe result, choose a documented fallback yourself, e.g. `{ mode: 'authoritative', layout: 'v1' }`; generating performs no write or cleanup. A non-object GitKraken entry is treated as corruption and refused, not skipped. A malformed policy throws `TypeError`.
+- `inspectMcpInstall` compares the selected layout; an entry found only in the other layout is `drifted` / `legacy-location` with that entry exposed for argv repair, and a current entry with a prunable duplicate is `drifted` / `legacy-location` with the selected entry. With `infer-existing` the compared entry is the v1 one when both layouts are present. `openCodeDuplicateLocation` reports the pointer of the other layout's entry whenever both hold one, in either mode; it is never pruned by `infer-existing`. `infer-existing` with no entry in either layout (including a missing or blank file) is `missing` / `layout-unknown`, the case where `installMcp` would throw `OpenCodeMcpLayoutUnknownError`. Argv merging stays in the host: re-run `inspectMcpInstall` with the effective argv before `installMcp`.
+- A migration writes the selected entry first and the removal second. If the removal fails (or the file changed in between), `installMcp` throws `OpenCodeMcpCleanupError`; `error.result` describes what was committed, with no `removedLocations`. This is not success, since an older reader can still reject a leftover native `servers` object. Run the install again to finish. `AbortError` is rethrown unchanged.
+- Refused without writing: a non-object root, `mcp` or `mcp.servers`; a v2 write where `mcp.servers` is a flat server named `servers` (an object whose `type` or `enabled` is a scalar, array or null). `inspectMcpInstall` reports these same files as `missing` / `unsafe-config`, so a host can tell before installing. Custom fields inside a replaced GitKraken entry are not carried across layouts.
+- Safe migration needs your `FileSystemPort.writeFile` to leave the previous file intact when it rejects (write a temp file, then rename). Your `readFile` must also return exactly the bytes `writeFile` was given (no newline normalization, appended trailing newline, or BOM changes): the migration compares the re-read file against what it wrote before the destructive second write, and a port that does not round-trip turns the migration into `OpenCodeMcpCleanupError` (retrying completes it). The library cannot check this and holds no lock against concurrent writers.
+- `uninstallMcp` ignores the policy and removes both pointers, except that a `GitKraken` key on a flat server named `servers` is not a v2 entry and is left alone; `configPath` confines every read and write to that file.
+
+Codex TOML edits preserve surrounding text and comments by splicing table blocks. When an entry needs to change but its valid TOML representation cannot be edited safely this way (for example, a drifted inline or dotted `mcp_servers.GitKraken` assignment), install or uninstall throws an error naming the config path and leaves the file untouched. A semantically current entry remains a no-op even when it uses an unusual representation.
+
+JSON/JSONC config files are edited losslessly via `jsonc-parser` (comments and formatting outside the edited range survive); Codex's TOML config is edited by splicing raw text, the same way gkcli does, because a full parse/marshal round trip drops comments and reorders sibling tables.
+
+## Hook install/uninstall
+
+```ts
+import { HookConfigError, installHooks, uninstallHooks } from '@gitkraken/agent-tools';
+
+try {
+	const installed = await installHooks({ host: 'codex', executablePath: '/usr/local/bin/gk' }, config);
+	// { host, path, events, blockingEvents, files: [{ path, change: 'created' | 'updated' | 'unchanged' | 'removed' }] }
+
+	const removed = await uninstallHooks('codex', config, ['PreToolUse']);
+	// { host, path, removedEvents, remainingEvents, files, reason?: 'file-missing' | 'not-installed' }
+} catch (error) {
+	if (error instanceof HookConfigError) {
+		console.error(error.code, error.path); // e.g. 'invalid-json', 'wrong-shape', 'unmanaged-file'
+	}
+}
+```
+
+Only GitKraken-owned hooks are added or removed; other entries and keys in the hooks file are preserved, and a file that is not valid JSON (or, for the OpenCode and Pi relays, not written by GitKraken) is refused without being modified.
+
+## Client detection
+
+```ts
+import { allClients, clientDisplayName, detectClient, getClientInstallation } from '@gitkraken/agent-tools';
+
+for (const client of allClients()) {
+	// 15 installable clients; 'gemini' is retained separately as legacy, uninstall-only.
+	const detection = await detectClient(client, config); // { detected, source?: 'executable' | 'config-file' | 'config-dir', reason?, checkedPaths, ... }
+	const installation = await getClientInstallation(client, config); // { installed, paths }: the files that carry a GitKraken entry
+	console.log(clientDisplayName(client), detection.detected, installation.installed);
+}
+```
+
+## Skills
+
+```ts
+import { installSkill, SkillConflictError, uninstallSkill } from '@gitkraken/agent-tools';
+
+const request = { agent: 'cursor', name: 'commit-composer', files: { 'SKILL.md': skillMarkdown } } as const;
+
+// action: 'create' | 'replace' | 'unchanged'. path is the skill directory; files lists each content file
+// and the .gk-skill.json manifest as created, updated or unchanged (empty when nothing needed writing).
+const { action, path, files, status } = await installSkill(request, config);
+
+try {
+	// action: 'remove' | 'absent'. files lists what was removed, including the directory once it was left empty.
+	await uninstallSkill(request, config);
+} catch (error) {
+	// Modified or foreign content requires `force`. Errors carry `code`, `operation` and `path`.
+	if (error instanceof SkillConflictError && error.code === 'modified') {
+		await uninstallSkill(request, config, { force: true });
+	}
+}
+```
+
+`status` is the skill's state before the action: `state` is `'missing' | 'current' | 'older-release' | 'modified'`, `reason` is a kebab-case code (for example `'content-changed'` or `'unowned'`) and is absent when the skill is current and clean, and `path` is the skill directory.
+
+The host supplies bundled skill content. The library records ownership in `.gk-skill.json` through the injected filesystem port and protects modified files during install and uninstall; see `ARCHITECTURE.md`.
+
+## Testing
+
+```ts
+import { MemoryFileSystem } from '@gitkraken/agent-tools/testing';
+
+const fs = new MemoryFileSystem({ '/Users/me/.cursor/mcp.json': '{}' });
+```

package/dist/agents.d.ts

@@ -0,0 +1,52 @@
+import { AgentHostConfig } from "./config.js";
+import { HookHost } from "./hooks/events.js";
+import { Client, ClientDetection, ClientType } from "./mcp/clients.js";
+
+//#region src/agents.d.ts
+/**
+ * A hook client's reported capability, supplied by the host. The host computes
+ * it from this package's hook writers and passes it to {@link listAgents}, which
+ * merges it with the MCP client registry.
+ */
+interface HookCapability {
+  /**
+   * The MCP client id(s) this hook capability's row(s) should be merged
+   * into (gkcli's `MCPNamesForHook`). A capability reported under more than
+   * one id — e.g. Antigravity's shared IDE/CLI hooks.json — does not let
+   * either row's `detected`/`executable` clobber the other's.
+   */
+  mcpNames: readonly string[];
+  displayName: string;
+  clientType?: ClientType;
+  detected: boolean;
+  executable?: string;
+  installed: boolean;
+}
+interface Agent {
+  name: string;
+  type: ClientType | 'unknown';
+  displayName: string;
+  /** Merged across MCP and hook detection; `detection` holds the MCP-registry result alone. */
+  detected: boolean;
+  executable?: string;
+  /** How the MCP registry found, or failed to find, the client. Absent on hook-only rows. */
+  detection?: ClientDetection;
+  mcpSupported: boolean;
+  mcpInstalled: boolean;
+  /** The config files that carry a GitKraken MCP entry; empty on hook-only rows. */
+  mcpConfigPaths: string[];
+  hooksSupported: boolean;
+  hooksInstalled: boolean;
+}
+/**
+ * The unified list of agents, sorted by name: every MCP client, plus any
+ * hook capability the host passes in (see {@link HookCapability}). Mirrors
+ * gkcli's `internal/agents.List`.
+ */
+declare function listAgents(config: AgentHostConfig, hookCapabilities?: readonly HookCapability[]): Promise<Agent[]>;
+/** MCP row ids that report one hook host's capability. */
+declare function mcpNamesForHook(host: HookHost): string[];
+/** Resolve aliases accepted by `gk ai hook` to the backing hook registry id. */
+declare function resolveHookClient(client: string): string;
+//#endregion
+export { Agent, type Client, HookCapability, listAgents, mcpNamesForHook, resolveHookClient };

package/dist/agents.js

@@ -0,0 +1 @@
+import{allClients as e,clientDisplayName as t,clientType as n,clientsForHost as r,detectClient as i,getClientInstallation as a}from"./mcp/clients.js";async function o(r,o=[]){let s=new Map;for(let o of e()){let e=await i(o,r),c=await a(o,r);s.set(o,{name:o,type:n(o),displayName:t(o),detected:e.detected,executable:e.executablePath,detection:e,mcpSupported:!0,mcpInstalled:c.installed,mcpConfigPaths:c.paths,hooksSupported:!1,hooksInstalled:!1})}for(let e of o)for(let t of e.mcpNames){let n=s.get(t);n||(n={name:t,type:e.clientType??`unknown`,displayName:e.displayName,detected:!1,mcpSupported:!1,mcpInstalled:!1,mcpConfigPaths:[],hooksSupported:!1,hooksInstalled:!1},s.set(t,n)),n.hooksSupported=!0,n.hooksInstalled=e.installed,!(e.mcpNames.length>1)&&(n.detected=n.detected||e.detected,n.executable||=e.executable)}return[...s.values()].sort((e,t)=>e.name.localeCompare(t.name))}function s(e){if(e===`claude-code`)return[`claude-cli`];let t=r(e);return t.length?t:[e]}function c(e){for(let t of[`claude-code`,`opencode`,`cursor`,`codex`,`copilot`,`antigravity`,`pi`,`augment`,`grok`])if(s(t).includes(e))return t;return e}export{o as listAgents,s as mcpNamesForHook,c as resolveHookClient};

package/dist/config.d.ts

@@ -0,0 +1,69 @@
+import { FileSystemPort } from "@gitkraken/shared-tools";
+
+//#region src/config.d.ts
+/** Origin metadata for the process driving this library, mirroring gkcli's `GITKRAKEN_AGENT_*` env vars. */
+interface AgentOrigin {
+  client?: string;
+  kind?: string;
+  clientRunId?: string;
+  id?: string;
+}
+/**
+ * Host-resolved filesystem locations this library joins segments onto. The
+ * host resolves these (env vars, `os.homedir()`, platform APIs); the library
+ * never reads the environment or the real filesystem directly.
+ */
+interface AgentHostPaths {
+  /** The user's home directory. */
+  home: string;
+  /** Resolved `$XDG_CONFIG_HOME`, or its per-platform default (e.g. `~/.config`). */
+  configHome: string;
+  /** Per-platform "app support" root: `%APPDATA%` on Windows, `~/Library/Application Support` on macOS, and `configHome` on Linux. */
+  appSupport: string;
+  /** Windows `%LOCALAPPDATA%` (distinct from `appSupport`, which is `%APPDATA%`/Roaming). Only JetBrains Copilot's Windows path uses it; falls back to `home/AppData/Local` when omitted. */
+  localAppData?: string;
+  /** Resolved `$CLAUDE_CONFIG_DIR`, when set. */
+  claudeConfigDir?: string;
+  /** Resolved `$COPILOT_HOME`, when set. */
+  copilotHome?: string;
+  /** Resolved `$GROK_HOME`, when set. */
+  grokHome?: string;
+  /** Resolved, tilde-expanded `$PI_CODING_AGENT_DIR`, when set. */
+  piAgentDir?: string;
+}
+/**
+ * Shared configuration for every function in `@gitkraken/agent-tools`. The
+ * host injects the filesystem, all paths, and any process/environment facts
+ * (origin, insights, the installed OpenCode major) the Go implementation read
+ * directly; this library never touches `process.env`, `os.homedir()`, spawns
+ * a child process, or writes to stdout.
+ */
+interface AgentHostConfig {
+  platform: 'darwin' | 'linux' | 'win32';
+  paths: AgentHostPaths;
+  fs: FileSystemPort;
+  /** Was `GITKRAKEN_AGENT_ORIGIN_CLIENT`/`ORIGIN_KIND`/`CLIENT_RUN_ID`/`ORIGIN_ID`. */
+  origin?: AgentOrigin;
+  /** Was `GK_CC_INSIGHTS`. */
+  insights?: boolean;
+  /**
+   * The installed OpenCode major version, or `undefined`/`0` when unknown —
+   * the same sentinel Go's `OpenCodeMajor()` returns. Go probes `opencode
+   * --version`; this library never spawns a process, so the host resolves
+   * the probe (or reads its own cache) and injects the result. It does not
+   * select an MCP layout; pass `McpInstallRequest.openCode` for that.
+   */
+  openCodeMajor?: number;
+  /**
+   * Resolves a command name to its absolute path on `PATH`, or `undefined`
+   * when it is not found. Go's client detection calls `exec.LookPath`
+   * directly; this library never reads `PATH` itself, so the host injects
+   * the lookup (not part of the plan's original `AgentHostConfig` sketch —
+   * added because client detection has no other way to learn this).
+   */
+  resolveExecutable?: (command: string) => string | undefined;
+}
+/** Joins path segments with `/`, matching D7: libraries never use `node:path`. */
+declare function joinPath(...segments: string[]): string;
+//#endregion
+export { AgentHostConfig, AgentHostPaths, AgentOrigin, joinPath };

package/dist/config.js

@@ -0,0 +1 @@
+function e(...e){let t=[];for(let n of e){if(!n)continue;let e=n.replace(/^\/+/,``).replace(/\/+$/,``);e&&t.push(e)}let n=e[0]??``;return(n.startsWith(`//`)?`//`:n.startsWith(`/`)?`/`:``)+t.join(`/`)}export{e as joinPath};

package/dist/file-change.d.ts

@@ -0,0 +1,28 @@
+import { FileSystemPort } from "@gitkraken/shared-tools";
+
+//#region src/file-change.d.ts
+/** What one operation did to one file or directory. */
+type FileChangeKind = 'created' | 'updated' | 'unchanged' | 'removed';
+/** One file or directory an install or uninstall touched, and what happened to it. */
+interface FileChange {
+  path: string;
+  change: FileChangeKind;
+}
+/**
+ * Writes `content` to `path` unless it already holds exactly that, and records
+ * the outcome in `changes`. `options.mode` is applied only when the file did
+ * not exist, so an existing file keeps the permissions its owner chose.
+ */
+declare function writeFileTracked(fs: FileSystemPort, path: string, content: string, changes: FileChange[], options?: {
+  mode?: number;
+}): Promise<Exclude<FileChangeKind, 'removed'>>;
+/**
+ * Removes `path` and records `'removed'` in `changes`, or records nothing when
+ * it was already absent. A directory (`options.recursive`) is probed with
+ * `readDir` rather than `readFile`.
+ */
+declare function removeTracked(fs: FileSystemPort, path: string, changes: FileChange[], options?: {
+  recursive?: boolean;
+}): Promise<void>;
+//#endregion
+export { FileChange, FileChangeKind, removeTracked, writeFileTracked };

package/dist/file-change.js

@@ -0,0 +1 @@
+async function e(e,t,n,r,i){let a=await e.readFile(t);if(a===n)return r.push({path:t,change:`unchanged`}),`unchanged`;await e.writeFile(t,n,a===null?i:void 0);let o=a===null?`created`:`updated`;return r.push({path:t,change:o}),o}async function t(e,t,n,r){let i=r?.recursive?await e.readDir(t)!==null:await e.readFile(t)!==null;await e.remove(t,r),i&&n.push({path:t,change:`removed`})}export{t as removeTracked,e as writeFileTracked};

package/dist/hooks/claude.d.ts

@@ -0,0 +1,16 @@
+import { AgentHostConfig } from "../config.js";
+import { HookInstallResult, HookUninstallResult } from "./results.js";
+
+//#region src/hooks/claude.d.ts
+interface ClaudeHookRequest {
+  executablePath: string;
+  events?: readonly string[];
+  blockingEvents?: readonly string[];
+  version?: string;
+  /** Host-supplied timestamp for reproducible installs and tests. */
+  now?: string;
+}
+declare function installClaudeHooks(request: ClaudeHookRequest, config: AgentHostConfig): Promise<HookInstallResult>;
+declare function uninstallClaudeHooks(events: readonly string[] | undefined, config: AgentHostConfig): Promise<HookUninstallResult>;
+//#endregion
+export { ClaudeHookRequest, installClaudeHooks, uninstallClaudeHooks };

package/dist/hooks/claude.js

@@ -0,0 +1,3 @@
+import{joinPath as e}from"../config.js";import{addAtPointer as t,removeAtPointer as n}from"../mcp/jsonc-edit.js";import{removeTracked as r,writeFileTracked as i}from"../file-change.js";import{HookConfigError as a}from"./errors.js";import{eventManifest as o}from"./events.js";import{command as s}from"./writers.js";import{parse as c}from"jsonc-parser";const l=`gitkraken`,u=`gitkraken-hooks`,d=`${u}@${l}`,f=`Live AI session tracking for GitKraken products. See what Claude is doing in real time — current tool, active prompt, subagents — and optionally approve or deny tool calls from the UI.`,p=[`gitkraken@local`,`gk@gitkraken`];function m(e){return e&&typeof e==`object`&&!Array.isArray(e)?e:{}}function h(e,t){if(e===null||e.trim()===``)return{};let n=[],r=c(e,n,{allowTrailingComma:!0});if(n.length||!r||typeof r!=`object`||Array.isArray(r))throw new a(`invalid-json`,`${t} is not valid JSON; refusing to overwrite shared configuration`,t);return r}function g(e,t){if(e.hooks===void 0)return{};if(!e.hooks||typeof e.hooks!=`object`||Array.isArray(e.hooks))throw new a(`wrong-shape`,`${t} has an invalid hooks wrapper`,t);let n=e.hooks;for(let[e,r]of Object.entries(n))if(!Array.isArray(r)||!r.every(e=>{if(!e||typeof e!=`object`||Array.isArray(e))return!1;let t=e.hooks;return t===void 0||Array.isArray(t)&&t.every(e=>!!e&&typeof e==`object`&&!Array.isArray(e))}))throw new a(`wrong-shape`,`${t} has an invalid ${e} hook group`,t);return n}function _(e,t){for(let n of[`enabledPlugins`,`extraKnownMarketplaces`]){let r=e[n];if(r!==void 0&&(!r||typeof r!=`object`||Array.isArray(r)))throw new a(`wrong-shape`,`${t} has an invalid ${n} map`,t)}}function v(t){return t.paths.claudeConfigDir||e(t.paths.home,`.claude`)}function y(t,n){let r=v(t),i=e(r,`plugins`,`marketplaces`,l);return{base:r,marketplace:i,source:e(i,`plugins`,u),cache:e(r,`plugins`,`cache`,l,u,n),settings:e(r,`settings.json`),known:e(r,`plugins`,`known_marketplaces.json`)}}function b(){return{name:l,description:`Plugins from GitKraken to enhance AI coding workflows in GitKraken Desktop, GitLens, and other GitKraken products.`,owner:{name:`GitKraken`},plugins:[{name:u,source:`./plugins/${u}`,description:f}]}}function x(e){return typeof m(e).command==`string`&&m(e).command.includes(`ai hook run`)}function S(e,t,n,r){C(e,[t]);let i=Array.isArray(e[t])?[...e[t]]:[],a=i.findIndex(e=>(typeof e.matcher!=`string`||e.matcher===``)&&Array.isArray(e.hooks)&&e.hooks.length>0);a<0&&(a=i.length,i.push({matcher:``,hooks:[]}));let o={...i[a]};o.hooks=[...(Array.isArray(o.hooks)?o.hooks:[]).filter(e=>!x(e)),{type:`command`,command:r?`${n} --blocking`:n,...r?{timeout:86400}:{}}],i[a]=o,e[t]=i}function C(e,t){for(let n of t){let t=Array.isArray(e[n])?e[n]:[],r=!1,i=t.flatMap(e=>{if(!Array.isArray(e.hooks))return[e];let t=e.hooks.filter(e=>!x(e));return t.length===e.hooks.length?[e]:(r=!0,t.length?[{...e,hooks:t}]:[])});r&&(i.length?e[n]=i:delete e[n])}}function w(e){return Object.keys(e).filter(t=>{let n=e[t];return Array.isArray(n)&&n.some(e=>Array.isArray(m(e).hooks)&&m(e).hooks.some(x))})}function T(e,t){let n=e.hooks;if(!n||typeof n!=`object`||Array.isArray(n))return;let r={...n};return C(r,t),Object.keys(n).every(e=>r[e]===n[e])?void 0:r}function E(e,r,i,a){let o=T(r,i);if(!o)return e;for(let[i,s]of Object.entries(r.hooks)){if(o[i]===s)continue;let r=`/hooks/${i.replace(/~/g,`~0`).replace(/\//g,`~1`)}`;e=o[i]===void 0?n(e,r,a).text:t(e,r,o[i],a)}return e}async function D(e,t,n,r){await i(n.fs,e,`${JSON.stringify(t,null,2)}\n`,r,{mode:384})}async function O(e,r,a,o,s,c){let u=await s.fs.readFile(e),f=h(u,e);_(f,e);let g={...m(f.enabledPlugins)};for(let e of p)delete g[e];a?g[d]=!0:delete g[d];let v={...m(f.extraKnownMarketplaces)};if(a?v[l]={...m(v[l]),source:{source:`directory`,path:r}}:delete v[l],!a&&u===null)return;let y=u===null||u.trim()===``;if(!a&&y){c.push({path:e,change:`unchanged`});return}let b=y?`{}`:E(u,f,o,e);for(let[r,i]of[[`enabledPlugins`,g],[`extraKnownMarketplaces`,v]])b=Object.keys(i).length?t(b,`/${r}`,i,e):n(b,`/${r}`,e).text;b===u?c.push({path:e,change:`unchanged`}):await i(s.fs,e,b.endsWith(`
+`)?b:`${b}\n`,c,{mode:384})}async function k(e,r,a,o){let s=await a.fs.readFile(e);if(s===null)return;let c=h(s,e);_(c,e);let l={...m(c.enabledPlugins)};for(let e of[...p,d])delete l[e];if(s.trim()===``){o.push({path:e,change:`unchanged`});return}let u=E(s,c,r,e),f=Object.keys(l).length?t(u,`/enabledPlugins`,l,e):n(u,`/enabledPlugins`,e).text;f===s?o.push({path:e,change:`unchanged`}):await i(a.fs,e,f.endsWith(`
+`)?f:`${f}\n`,o,{mode:384})}function A(t){return e(t,`plugins`,`installed_plugins.json`)}function j(e,t){return t===e||t.startsWith(`${e}/`)}function M(e,t){let n=e.replaceAll(`\\`,`/`);return t===`win32`?n.toLowerCase():n}function N(e,t,n,r=``){let i=t.filter(t=>t in e).map(e=>`/${e}`),a=m(e.plugins),o=M(r,n),s=o.slice(0,o.lastIndexOf(`/`));for(let e of t){if(!(e in a))continue;if(e!==d||!o){i.push(`/plugins/${e}`);continue}let t=a[e];if(!Array.isArray(t))continue;let r=t.flatMap((e,t)=>{let r=m(e).installPath;if(typeof r!=`string`)return[];let i=M(r,n);return i!==s&&j(s,i)&&!j(o,i)?[t]:[]});r.length&&r.length===t.length?i.push(`/plugins/${e}`):i.push(...r.reverse().map(t=>`/plugins/${e}/${t}`))}return i}async function P(e,t){let n=A(e),r=await t.fs.readFile(n);if(r!==null)try{return[r,h(r,n)]}catch{return}}async function F(e,t,r,a){let o=await P(t,e);if(!o)return;let s=A(t),[c,l]=o,u=c;for(let t of N(l,[...p,d],e.platform,a))u=n(u,t,s).text;u!==c&&await i(e.fs,s,u,r,{mode:384})}async function I(t,n){for(let r of[e(n,`.claude-plugin`,`plugin.json`),e(n,`plugin.json`)]){let e=await t.fs.readFile(r);if(e!==null)try{let t=m(JSON.parse(e)).name;return t===u||t===`gk`}catch{return!1}}return!1}async function L(t,n,i,a){let o=e(n,`plugins`,`cache`,l,u);for(let n of await t.fs.readDir(o)??[]){let s=e(o,n);n!==i&&await I(t,s)&&await r(t.fs,s,a,{recursive:!0})}}async function R(t,n,i,a=!1){let o=[e(n.source,`.claude-plugin`,`plugin.json`),e(n.source,`hooks`,`hooks.json`)];for(let e of o)await r(t.fs,e,i);for(let a of[e(n.source,`.claude-plugin`),e(n.source,`hooks`)])(await t.fs.readDir(a))?.length||await r(t.fs,a,i,{recursive:!0});(await t.fs.readDir(n.source))?.length||await r(t.fs,n.source,i,{recursive:!0});let s=e(n.marketplace,`plugins`);(await t.fs.readDir(s))?.length||await r(t.fs,s,i,{recursive:!0});let c=e(n.base,`plugins`,`cache`,l,u);for(let n of await t.fs.readDir(c)??[]){let a=e(c,n);await r(t.fs,e(a,`.claude-plugin`,`plugin.json`),i),await r(t.fs,e(a,`hooks`,`hooks.json`),i);for(let n of[e(a,`.claude-plugin`),e(a,`hooks`)])(await t.fs.readDir(n))?.length||await r(t.fs,n,i,{recursive:!0});(await t.fs.readDir(a))?.length||await r(t.fs,a,i,{recursive:!0})}(await t.fs.readDir(c))?.length||await r(t.fs,c,i,{recursive:!0});let d=e(n.marketplace,`.claude-plugin`,`marketplace.json`),f=await t.fs.readFile(d);!a&&f?.trimEnd()===JSON.stringify(b(),null,2)&&await r(t.fs,d,i);let p=e(n.marketplace,`.claude-plugin`);!a&&!(await t.fs.readDir(p))?.length&&await r(t.fs,p,i,{recursive:!0});let m=await t.fs.readDir(n.marketplace);!a&&!m?.length&&(m===null&&i.some(e=>e.path.startsWith(`${n.marketplace}/`))?(await t.fs.remove(n.marketplace,{recursive:!0}),i.push({path:n.marketplace,change:`removed`})):await r(t.fs,n.marketplace,i,{recursive:!0}))}async function z(t,n){return(await t.fs.readDir(e(n.marketplace,`plugins`))??[]).some(e=>e!==u)}function B(e,t){return Object.keys(e).some(e=>e!==`hooks`)||Object.values(t).some(Array.isArray)}async function V(t,n){let i=[],a=t.version||`0.0.0-dev`,c=y(n,a),d=e(c.source,`hooks`,`hooks.json`),p=h(await n.fs.readFile(d),d),v=g(p,d),x=h(await n.fs.readFile(c.known),c.known),C=c.settings;_(h(await n.fs.readFile(C),C),C);let w=s(t.executablePath,`claude-code`,n,!1);for(let e of t.events??[])S(v,e,w,!1);for(let e of t.blockingEvents??[])S(v,e,w,!0);p.hooks=v,await D(e(c.marketplace,`.claude-plugin`,`marketplace.json`),b(),n,i);for(let t of[c.source,c.cache])await D(e(t,`.claude-plugin`,`plugin.json`),{name:u,version:a,description:f},n,i),await D(e(t,`hooks`,`hooks.json`),p,n,i);return x[l]={...m(x[l]),source:{source:`directory`,path:c.marketplace},installLocation:c.marketplace,lastUpdated:t.now??new Date().toISOString().replace(/\.\d{3}Z$/,`Z`)},await D(c.known,x,n,i),await O(c.settings,c.marketplace,!0,o[`claude-code`].events,n,i),await F(n,c.base,i,c.cache),await r(n.fs,e(c.marketplace,`plugins`,`gk`),i,{recursive:!0}),await r(n.fs,e(c.base,`plugins`,`cache`,l,`gk`),i,{recursive:!0}),await L(n,c.base,a,i),{host:`claude-code`,path:d,events:[...t.events??[]],blockingEvents:[...t.blockingEvents??[]],files:i}}async function H(t,n){let i=[],a=y(n,`0.0.0-dev`),s=e(a.source,`hooks`,`hooks.json`),c=await n.fs.readFile(s),f=h(c,s),v=g(f,s),b=h(await n.fs.readFile(a.settings),a.settings);_(b,a.settings);let x=await n.fs.readFile(a.known),S={};try{x!==null&&(S=h(x,a.known))}catch{}let E=t??Object.keys(v),A=t??o[`claude-code`].events,j=w(v).filter(e=>E.includes(e));C(v,E),f.hooks=v;let M=w(v),I={host:`claude-code`,path:s,removedEvents:j,remainingEvents:M,files:i};j.length||(I.reason=c===null?`file-missing`:`not-installed`);let L=B(f,v);if(!j.length){if(t!==void 0||L)return I;let r=await P(a.base,n),i=!!r&&N(r[1],p,n.platform).length>0,o=e(a.base,`plugins`,`cache`,l,u);if(!(d in m(b.enabledPlugins)||l in S||i||T(b,A)||(await n.fs.readDir(o))?.length))return I}else if(M.length||L){await D(s,f,n,i);let t=e(a.base,`plugins`,`cache`,l,u);for(let r of await n.fs.readDir(t)??[])await D(e(t,r,`hooks`,`hooks.json`),f,n,i);return I}let V=await z(n,a);return V?await k(a.settings,A,n,i):await O(a.settings,a.marketplace,!1,A,n,i),l in S&&!V&&(delete S[l],Object.keys(S).length?await D(a.known,S,n,i):await r(n.fs,a.known,i)),await R(n,a,i,V),await F(n,a.base,i),I}export{V as installClaudeHooks,H as uninstallClaudeHooks};

package/dist/hooks/errors.d.ts

@@ -0,0 +1,10 @@
+//#region src/hooks/errors.d.ts
+type HookConfigErrorCode = 'invalid-json' | 'wrong-shape' | 'invalid-event' | 'unsupported-host' | 'blocking-unsupported' | 'unmanaged-file';
+/** A hook install or uninstall was refused; `path` names the file involved, when there is one. An existing file is left untouched. */
+declare class HookConfigError extends Error {
+  readonly code: HookConfigErrorCode;
+  readonly path?: string | undefined;
+  constructor(code: HookConfigErrorCode, message: string, path?: string | undefined);
+}
+//#endregion
+export { HookConfigError, HookConfigErrorCode };

package/dist/hooks/errors.js

@@ -0,0 +1 @@
+var e=class extends Error{constructor(e,t,n){super(t),this.code=e,this.path=n,this.name=`HookConfigError`}};export{e as HookConfigError};

package/dist/hooks/events.d.ts

@@ -0,0 +1,73 @@
+//#region src/hooks/events.d.ts
+declare const eventManifest: {
+  readonly 'claude-code': {
+    readonly events: readonly ["SessionStart", "Setup", "InstructionsLoaded", "UserPromptSubmit", "UserPromptExpansion", "MessageDisplay", "PreToolUse", "PermissionRequest", "PermissionDenied", "PostToolUse", "PostToolUseFailure", "PostToolBatch", "Notification", "SubagentStart", "SubagentStop", "TaskCreated", "TaskCompleted", "Stop", "StopFailure", "TeammateIdle", "ConfigChange", "CwdChanged", "DirectoryAdded", "FileChanged", "WorktreeCreate", "WorktreeRemove", "PreCompact", "PostCompact", "PreModelSwitch", "PostModelSwitch", "Elicitation", "ElicitationResult", "SessionEnd"];
+    readonly skippedDefaultEvents: readonly ["Setup", "MessageDisplay", "FileChanged", "WorktreeCreate", "WorktreeRemove"];
+    readonly backfillEvents: readonly ["PostModelSwitch"];
+    readonly sessionEndEvent: "SessionEnd";
+    readonly sessionStartEvent: "SessionStart";
+  };
+  readonly opencode: {
+    readonly events: readonly ["session.created", "session.updated", "session.deleted", "session.idle", "session.error", "session.status", "session.diff", "session.execution.failed", "session.compacted", "permission.asked", "permission.updated", "permission.replied", "message.updated", "message.part.updated", "tool.execute.before", "tool.execute.after", "file.edited", "todo.updated", "command.executed", "vcs.branch.updated", "installation.updated"];
+    readonly v1OnlyEvents: readonly ["session.updated", "session.error"];
+    readonly v2EventAliases: {
+      readonly 'session.status': readonly ["session.updated"];
+      readonly 'session.execution.failed': readonly ["session.error"];
+    };
+    readonly skippedDefaultEvents: readonly ["message.updated", "message.part.updated", "installation.updated"];
+    readonly sessionEndEvent: "session.deleted";
+    readonly sessionStartEvent: "session.created";
+  };
+  readonly cursor: {
+    readonly events: readonly ["sessionStart", "sessionEnd", "preToolUse", "postToolUse", "postToolUseFailure", "subagentStart", "subagentStop", "beforeShellExecution", "afterShellExecution", "beforeMCPExecution", "afterMCPExecution", "beforeReadFile", "afterFileEdit", "beforeSubmitPrompt", "preCompact", "stop", "afterAgentResponse", "afterAgentThought", "beforeTabFileRead", "afterTabFileEdit", "workspaceOpen"];
+    readonly skippedDefaultEvents: readonly ["beforeTabFileRead", "afterTabFileEdit", "workspaceOpen"];
+    readonly sessionEndEvent: "sessionEnd";
+    readonly sessionStartEvent: "sessionStart";
+  };
+  readonly codex: {
+    readonly events: readonly ["SessionStart", "UserPromptSubmit", "PreToolUse", "PermissionRequest", "PostToolUse", "PreCompact", "PostCompact", "SubagentStart", "SubagentStop", "Stop", "Interrupt", "SessionEnd"];
+    readonly skippedDefaultEvents: readonly [];
+    readonly backfillEvents: readonly ["SessionEnd", "Interrupt"];
+    readonly sessionEndEvent: "SessionEnd";
+    readonly sessionStartEvent: "SessionStart";
+    readonly windowsShell: "powershell";
+  };
+  readonly copilot: {
+    readonly events: readonly ["SessionStart", "SessionEnd", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "Stop", "SubagentStop", "ErrorOccurred", "PreCompact", "Notification", "PermissionRequest"];
+    readonly legacyEvents: readonly ["sessionStart", "sessionEnd", "userPromptSubmitted", "preToolUse", "postToolUse", "postToolUseFailure", "agentStop", "subagentStart", "subagentStop", "errorOccurred", "preCompact", "notification", "permissionRequest"];
+    readonly skippedDefaultEvents: readonly [];
+    readonly sessionEndEvent: "SessionEnd";
+    readonly sessionStartEvent: "SessionStart";
+    readonly windowsShell: "powershell";
+  };
+  readonly antigravity: {
+    readonly events: readonly ["PreToolUse", "PostToolUse", "PreInvocation", "PostInvocation", "Stop"];
+    readonly skippedDefaultEvents: readonly [];
+    readonly sessionEndEvent: "Stop";
+    readonly sessionStartEvent: "";
+  };
+  readonly pi: {
+    readonly events: readonly ["project_trust", "resources_discover", "session_start", "session_info_changed", "session_before_switch", "session_before_fork", "session_before_compact", "session_compact", "session_compact_failed", "session_before_tree", "session_tree", "session_shutdown", "before_agent_start", "agent_start", "agent_end", "agent_settled", "ui_prompt_start", "ui_prompt_end", "turn_start", "turn_end", "message_start", "message_update", "message_end", "tool_call", "tool_result", "tool_execution_start", "tool_execution_update", "tool_execution_end", "context", "before_provider_headers", "before_provider_request", "after_provider_response", "model_select", "thinking_level_select", "user_bash", "input"];
+    readonly skippedDefaultEvents: readonly ["resources_discover", "message_start", "message_update", "message_end", "tool_execution_start", "tool_execution_update", "tool_execution_end", "context", "before_provider_headers", "before_provider_request", "after_provider_response", "input"];
+    readonly sessionEndEvent: "session_shutdown";
+    readonly sessionStartEvent: "session_start";
+  };
+  readonly augment: {
+    readonly events: readonly ["SessionStart", "SessionEnd", "PreToolUse", "PostToolUse", "Stop", "Notification", "PromptSubmit"];
+    readonly skippedDefaultEvents: readonly [];
+    readonly sessionEndEvent: "SessionEnd";
+    readonly sessionStartEvent: "SessionStart";
+    readonly blockingTimeoutMultiplier: 1000;
+    readonly promptSubmitEvent: "PromptSubmit";
+  };
+  readonly grok: {
+    readonly events: readonly ["SessionStart", "SessionEnd", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "PermissionDenied", "Stop", "StopFailure", "StopCancelled", "Notification", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact"];
+    readonly skippedDefaultEvents: readonly [];
+    readonly sessionEndEvent: "SessionEnd";
+    readonly sessionStartEvent: "SessionStart";
+    readonly windowsShell: "powershell";
+  };
+};
+type HookHost = keyof typeof eventManifest;
+//#endregion
+export { HookHost, eventManifest };

package/dist/hooks/events.js

@@ -0,0 +1 @@
+const e={"claude-code":{events:`SessionStart.Setup.InstructionsLoaded.UserPromptSubmit.UserPromptExpansion.MessageDisplay.PreToolUse.PermissionRequest.PermissionDenied.PostToolUse.PostToolUseFailure.PostToolBatch.Notification.SubagentStart.SubagentStop.TaskCreated.TaskCompleted.Stop.StopFailure.TeammateIdle.ConfigChange.CwdChanged.DirectoryAdded.FileChanged.WorktreeCreate.WorktreeRemove.PreCompact.PostCompact.PreModelSwitch.PostModelSwitch.Elicitation.ElicitationResult.SessionEnd`.split(`.`),skippedDefaultEvents:[`Setup`,`MessageDisplay`,`FileChanged`,`WorktreeCreate`,`WorktreeRemove`],backfillEvents:[`PostModelSwitch`],sessionEndEvent:`SessionEnd`,sessionStartEvent:`SessionStart`},opencode:{events:[`session.created`,`session.updated`,`session.deleted`,`session.idle`,`session.error`,`session.status`,`session.diff`,`session.execution.failed`,`session.compacted`,`permission.asked`,`permission.updated`,`permission.replied`,`message.updated`,`message.part.updated`,`tool.execute.before`,`tool.execute.after`,`file.edited`,`todo.updated`,`command.executed`,`vcs.branch.updated`,`installation.updated`],v1OnlyEvents:[`session.updated`,`session.error`],v2EventAliases:{"session.status":[`session.updated`],"session.execution.failed":[`session.error`]},skippedDefaultEvents:[`message.updated`,`message.part.updated`,`installation.updated`],sessionEndEvent:`session.deleted`,sessionStartEvent:`session.created`},cursor:{events:[`sessionStart`,`sessionEnd`,`preToolUse`,`postToolUse`,`postToolUseFailure`,`subagentStart`,`subagentStop`,`beforeShellExecution`,`afterShellExecution`,`beforeMCPExecution`,`afterMCPExecution`,`beforeReadFile`,`afterFileEdit`,`beforeSubmitPrompt`,`preCompact`,`stop`,`afterAgentResponse`,`afterAgentThought`,`beforeTabFileRead`,`afterTabFileEdit`,`workspaceOpen`],skippedDefaultEvents:[`beforeTabFileRead`,`afterTabFileEdit`,`workspaceOpen`],sessionEndEvent:`sessionEnd`,sessionStartEvent:`sessionStart`},codex:{events:[`SessionStart`,`UserPromptSubmit`,`PreToolUse`,`PermissionRequest`,`PostToolUse`,`PreCompact`,`PostCompact`,`SubagentStart`,`SubagentStop`,`Stop`,`Interrupt`,`SessionEnd`],skippedDefaultEvents:[],backfillEvents:[`SessionEnd`,`Interrupt`],sessionEndEvent:`SessionEnd`,sessionStartEvent:`SessionStart`,windowsShell:`powershell`},copilot:{events:[`SessionStart`,`SessionEnd`,`UserPromptSubmit`,`PreToolUse`,`PostToolUse`,`PostToolUseFailure`,`Stop`,`SubagentStop`,`ErrorOccurred`,`PreCompact`,`Notification`,`PermissionRequest`],legacyEvents:[`sessionStart`,`sessionEnd`,`userPromptSubmitted`,`preToolUse`,`postToolUse`,`postToolUseFailure`,`agentStop`,`subagentStart`,`subagentStop`,`errorOccurred`,`preCompact`,`notification`,`permissionRequest`],skippedDefaultEvents:[],sessionEndEvent:`SessionEnd`,sessionStartEvent:`SessionStart`,windowsShell:`powershell`},antigravity:{events:[`PreToolUse`,`PostToolUse`,`PreInvocation`,`PostInvocation`,`Stop`],skippedDefaultEvents:[],sessionEndEvent:`Stop`,sessionStartEvent:``},pi:{events:`project_trust.resources_discover.session_start.session_info_changed.session_before_switch.session_before_fork.session_before_compact.session_compact.session_compact_failed.session_before_tree.session_tree.session_shutdown.before_agent_start.agent_start.agent_end.agent_settled.ui_prompt_start.ui_prompt_end.turn_start.turn_end.message_start.message_update.message_end.tool_call.tool_result.tool_execution_start.tool_execution_update.tool_execution_end.context.before_provider_headers.before_provider_request.after_provider_response.model_select.thinking_level_select.user_bash.input`.split(`.`),skippedDefaultEvents:[`resources_discover`,`message_start`,`message_update`,`message_end`,`tool_execution_start`,`tool_execution_update`,`tool_execution_end`,`context`,`before_provider_headers`,`before_provider_request`,`after_provider_response`,`input`],sessionEndEvent:`session_shutdown`,sessionStartEvent:`session_start`},augment:{events:[`SessionStart`,`SessionEnd`,`PreToolUse`,`PostToolUse`,`Stop`,`Notification`,`PromptSubmit`],skippedDefaultEvents:[],sessionEndEvent:`SessionEnd`,sessionStartEvent:`SessionStart`,blockingTimeoutMultiplier:1e3,promptSubmitEvent:`PromptSubmit`},grok:{events:[`SessionStart`,`SessionEnd`,`UserPromptSubmit`,`PreToolUse`,`PostToolUse`,`PostToolUseFailure`,`PermissionDenied`,`Stop`,`StopFailure`,`StopCancelled`,`Notification`,`SubagentStart`,`SubagentStop`,`PreCompact`,`PostCompact`],skippedDefaultEvents:[],sessionEndEvent:`SessionEnd`,sessionStartEvent:`SessionStart`,windowsShell:`powershell`}};export{e as eventManifest};

package/dist/hooks/install.d.ts

@@ -0,0 +1,15 @@
+import { AgentHostConfig } from "../config.js";
+import { HookHost } from "./events.js";
+import { HookInstallResult, HookUninstallResult } from "./results.js";
+import { HookWriteRequest } from "./writers.js";
+
+//#region src/hooks/install.d.ts
+interface InstallHooksRequest extends HookWriteRequest {
+  /** Host-supplied build version for Claude's cache directory. */
+  version?: string;
+}
+/** Dispatches hook config writes for all supported agent hosts. The host supplies the stable launcher path. */
+declare function installHooks(request: InstallHooksRequest, config: AgentHostConfig): Promise<HookInstallResult>;
+declare function uninstallHooks(host: HookHost, config: AgentHostConfig, events?: readonly string[]): Promise<HookUninstallResult>;
+//#endregion
+export { InstallHooksRequest, installHooks, uninstallHooks };

package/dist/hooks/install.js

@@ -0,0 +1 @@
+import{HookConfigError as e}from"./errors.js";import{eventManifest as t}from"./events.js";import{installJsonHooks as n,uninstallJsonHooks as r}from"./writers.js";import{installClaudeHooks as i,uninstallClaudeHooks as a}from"./claude.js";import{installMarkerHooks as o,uninstallMarkerHooks as s}from"./templates.js";function c(n){let r=t[n.host],i=n.events?.length||n.blockingEvents?.length?[...n.events??[]]:r.events.filter(e=>!r.skippedDefaultEvents.includes(e)),a=[...n.blockingEvents??[]];for(let t of[...i,...a])if(!r.events.includes(t))throw new e(`invalid-event`,`${t} is not valid for ${n.host}`);return{events:i,blockingEvents:a}}async function l(e,t){let{events:r,blockingEvents:a}=c(e);return e.host===`claude-code`?i({executablePath:e.executablePath,events:r,blockingEvents:a,version:e.version},t):e.host===`opencode`||e.host===`pi`?o({host:e.host,executablePath:e.executablePath,events:r,blockingEvents:a},t):n({...e,events:r,blockingEvents:a},t)}async function u(n,i,o){if(o){for(let r of o)if(!t[n].events.includes(r))throw new e(`invalid-event`,`${r} is not valid for ${n}`)}let c=o?.length?o:t[n].events;return n===`claude-code`?a(o?.length?c:void 0,i):n===`opencode`||n===`pi`?s(n,c,i):r(n,i,c)}export{l as installHooks,u as uninstallHooks};

package/dist/hooks/results.d.ts

@@ -0,0 +1,30 @@
+import { HookHost } from "./events.js";
+import { FileChange } from "../file-change.js";
+
+//#region src/hooks/results.d.ts
+interface HookInstallResult {
+  host: HookHost;
+  /** The hooks file the agent reads. */
+  path: string;
+  /** The non-blocking events this call installed. */
+  events: string[];
+  /** The blocking events this call installed. */
+  blockingEvents: string[];
+  /** Every file written or removed, in order. */
+  files: FileChange[];
+}
+interface HookUninstallResult {
+  host: HookHost;
+  /** The hooks file the agent reads. */
+  path: string;
+  /** Events whose GitKraken hooks this call removed. */
+  removedEvents: string[];
+  /** Events that still carry a GitKraken hook after this call, as after a partial uninstall. */
+  remainingEvents: string[];
+  /** Every file written or removed, in order. */
+  files: FileChange[];
+  /** Set when no GitKraken hook was removed: the hooks file does not exist, or holds none for the requested events. */
+  reason?: 'file-missing' | 'not-installed';
+}
+//#endregion
+export { HookInstallResult, HookUninstallResult };

package/dist/hooks/results.js

@@ -0,0 +1 @@
+export{};

package/dist/hooks/templates.d.ts

@@ -0,0 +1,15 @@
+import { AgentHostConfig } from "../config.js";
+import { HookInstallResult, HookUninstallResult } from "./results.js";
+
+//#region src/hooks/templates.d.ts
+type MarkerHost = 'opencode' | 'pi';
+interface MarkerHookRequest {
+  host: MarkerHost;
+  executablePath: string;
+  events?: readonly string[];
+  blockingEvents?: readonly string[];
+}
+declare function installMarkerHooks(request: MarkerHookRequest, config: AgentHostConfig): Promise<HookInstallResult>;
+declare function uninstallMarkerHooks(host: MarkerHost, events: readonly string[] | undefined, config: AgentHostConfig): Promise<HookUninstallResult>;
+//#endregion
+export { MarkerHookRequest, MarkerHost, installMarkerHooks, uninstallMarkerHooks };