lockage 0.0.0-stage → 0.9.1

package/dist/hook/clients.js

@@ -0,0 +1,258 @@
+/**
+ * Per-client adapters. They call the pure logic in repo.ts / context.ts / guard.ts, parse each
+ * client's input (claude / antigravity / kiro), and build the response. Only the input/output
+ * shapes are client-specific; the decision logic itself stays inside the pure logic.
+ *
+ * The final control of exit codes and stdout/stderr is handled by the outermost shell in
+ * dispatch.ts. Here we decide "what to output", and dispatch.ts handles "how to output it" (write
+ * the JSON to stdout / set the exit code). Rather than returning both side effects (record, stderr
+ * log) and an "output payload", each adapter function returns a value natural to its client.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { buildContext, DEFAULT_HEADER } from './context.js';
+import { decide, record } from './guard.js';
+import { log, mainTreeRoot, repoState } from './repo.js';
+/** The heading used by the kiro session (the kiro version of HEADER). */
+const KIRO_HEADER = '## lockage coordinated development (lockage Kiro Power)\n';
+/** Parse a JSON string. Unparseable / non-JSON is treated as an empty object. */
+function parsePayload(stdin) {
+    try {
+        const v = JSON.parse(stdin);
+        return v && typeof v === 'object' ? v : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Result of the claude guard. Returns the JSON to write to stdout (null if none). record is already
+ * performed as a side effect. For PreToolUse, if decide returns a reason, an ask JSON, otherwise no
+ * output. For PostToolUse, record and output nothing.
+ */
+export function claudeGuard(stdin) {
+    const payload = parsePayload(stdin);
+    if (payload.hook_event_name === 'PostToolUse') {
+        record(payload);
+        return null;
+    }
+    const reason = decide(payload);
+    if (reason === null)
+        return null;
+    return {
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'ask',
+            permissionDecisionReason: reason,
+        },
+    };
+}
+/**
+ * Build the fixed text for lockage-worker.
+ * Distinct from buildContext: even if the worker is started outside git, pass at least the location
+ * of the canonical rules.
+ */
+function buildWorkerContext(agentsMd, mainRoot) {
+    let context = DEFAULT_HEADER + `- canonical coordination rules: ${agentsMd} (read it with Read before starting work)\n`;
+    if (mainRoot !== null) {
+        context += `- repository of the launch location: ${mainRoot}\n`;
+    }
+    return context;
+}
+/**
+ * Result of the claude session. Returns the JSON to write to stdout (null if none).
+ * For SessionStart, no output if repoState(cwd) is null, otherwise buildContext as
+ * additionalContext. For SubagentStart, no output unless agent_type includes lockage-worker, in
+ * which case buildWorkerContext as additionalContext. The output JSON's hookEventName echoes the
+ * input event name.
+ */
+export function claudeSession(stdin, agentsMd) {
+    const payload = parsePayload(stdin);
+    const event = payload.hook_event_name || 'SessionStart';
+    // Add nothing for subagents unrelated to lockage. Decide this before calling git
+    if (event === 'SubagentStart' && !(payload.agent_type || '').includes('lockage-worker')) {
+        return null;
+    }
+    const st = repoState(payload.cwd || process.cwd());
+    let context;
+    if (event === 'SubagentStart') {
+        context = buildWorkerContext(agentsMd, st === null ? null : st.mainRoot);
+    }
+    else {
+        if (st === null)
+            return null; // inject nothing outside a git repository
+        context = buildContext(st, { agentsMd, readTool: 'Read' });
+    }
+    return { hookSpecificOutput: { hookEventName: event, additionalContext: context } };
+}
+/** Normalize antigravity input into the claude-shaped guard payload. */
+function toGuardPayload(payload) {
+    const args = payload.toolCall?.args ?? {};
+    const workspaces = payload.workspacePaths ?? [];
+    return {
+        tool_input: { file_path: args.TargetFile ?? null },
+        // Resolve relative paths from the workspace (the hook's working directory depends on the caller)
+        cwd: workspaces.length > 0 ? workspaces[0] : null,
+        session_id: payload.conversationId ?? null,
+    };
+}
+/** The default response when the antigravity guard "passes" (built each time). */
+function antigravityPass() {
+    return { decision: 'ask' };
+}
+/**
+ * Result of the antigravity guard. Always returns an output JSON (returning nothing is treated as
+ * deny, so always return a decision).
+ * pre: decide null→{decision:'ask'}, with a reason→{decision:'force_ask',reason}.
+ * post: record only when there is no error, always {}.
+ */
+export function antigravityGuard(stdin, event) {
+    const payload = parsePayload(stdin);
+    if (event === 'pre') {
+        const reason = decide(toGuardPayload(payload));
+        if (reason === null)
+            return antigravityPass();
+        return { decision: 'force_ask', reason };
+    }
+    // post: do not record when the tool failed (there is an error)
+    if (!payload.error) {
+        record(toGuardPayload(payload));
+    }
+    return {};
+}
+/** Whether a transcript line is an EPHEMERAL_MESSAGE we injected. */
+function isOurMessage(line) {
+    // To avoid parsing every line even for a large transcript, narrow by string first, then parse
+    if (!line.includes('EPHEMERAL_MESSAGE'))
+        return false;
+    let step;
+    try {
+        step = JSON.parse(line);
+    }
+    catch {
+        return false;
+    }
+    return step.type === 'EPHEMERAL_MESSAGE' && String(step.content ?? '').startsWith(DEFAULT_HEADER);
+}
+/** Expand a `~`-prefixed path with homedir (minimal version). */
+function expandUser(path) {
+    if (path === '~')
+        return homedir();
+    if (path.startsWith('~/'))
+        return join(homedir(), path.slice(2));
+    return path;
+}
+/** Whether the text has already been injected into the conversation. Unreadable/not-yet-created is false. */
+function alreadyInjected(transcriptPath) {
+    if (!transcriptPath)
+        return false;
+    let content;
+    try {
+        content = readFileSync(expandUser(transcriptPath), { encoding: 'utf8' });
+    }
+    catch {
+        // The transcript is not written yet (first call) or unreadable. Prefer injecting again over missing it
+        return false;
+    }
+    return content.split('\n').some((line) => isOurMessage(line));
+}
+/**
+ * Result of the antigravity session. Returns the JSON to inject (injectSteps or {}).
+ * If invocationNum!==0 or already injected, {}; otherwise concatenate buildContext over
+ * workspacePaths in order, deduplicating by repoState→mainRoot??toplevel.
+ */
+export function antigravitySession(stdin, agentsMd) {
+    const payload = parsePayload(stdin);
+    const message = buildAntigravityMessage(payload, agentsMd);
+    return message ? { injectSteps: [{ ephemeralMessage: message }] } : {};
+}
+function buildAntigravityMessage(payload, agentsMd) {
+    // Read the transcript only when invocationNum is 0 (do not re-read every time)
+    if (payload.invocationNum !== 0)
+        return null;
+    if (alreadyInjected(payload.transcriptPath))
+        return null;
+    const contexts = [];
+    const seen = new Set();
+    const opts = { agentsMd, readTool: 'view_file' };
+    for (const workspace of payload.workspacePaths ?? []) {
+        const st = repoState(workspace);
+        if (st === null)
+            continue; // outside a git repository
+        const key = st.mainRoot ?? st.toplevel;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        contexts.push(buildContext(st, opts));
+    }
+    return contexts.length > 0 ? contexts.join('\n') : null;
+}
+// --- kiro ---------------------------------------------------------------------
+// Exit codes for the kiro guard. PreToolUse is fail-closed.
+export const KIRO_EXIT_ALLOW = 0;
+export const KIRO_EXIT_DENY = 2;
+/**
+ * Decision result of the kiro guard. Returns an exit code. Messages to stderr are emitted inside
+ * this function.
+ * - PostToolUse → exit 0 (a defensive contract; not called by the generated hook)
+ * - path unavailable → exit 0 + stderr warning (the list of tool_input keys)
+ * - mainTreeRoot !== null → exit 2 + stderr message
+ * - otherwise → exit 0
+ * Exceptions (e.g. a git parse error) are made fail-closed (exit 2) by the outermost shell in
+ * dispatch.ts.
+ */
+export function kiroGuard(stdin) {
+    const payload = parsePayload(stdin);
+    // In Kiro, PostToolUse is only a post-hoc notification; this Power keeps no memory of allowances, so it does not decide (always allow)
+    if (payload.hook_event_name === 'PostToolUse')
+        return KIRO_EXIT_ALLOW;
+    const toolInput = payload.tool_input ?? {};
+    const path = toolInput.file_path || toolInput.path;
+    if (!path) {
+        const keys = Object.keys(payload.tool_input ?? {}).sort();
+        log(`Could not extract the edit target path from ${payload.tool_name}'s tool_input, so allowed without deciding` +
+            ` (tool_input keys: [${keys.join(', ')}]; expected via file_path or path).`);
+        return KIRO_EXIT_ALLOW;
+    }
+    if (mainTreeRoot(path, payload.cwd ?? undefined) === null) {
+        return KIRO_EXIT_ALLOW;
+    }
+    process.stderr.write('This edit target is the main working tree of a repository operating under lockage. ' +
+        'If you are working as a lockage task, edit inside the worktree_path returned by assign_worktree. ' +
+        'If you must edit the main working tree directly, set the environment variable LOCKAGE_GUARD_DISABLE=1 to disable the guard.\n');
+    return KIRO_EXIT_DENY;
+}
+/**
+ * Result of the kiro session. Returns the text to write to stdout (null if none).
+ * No output if repoState(cwd) is null, otherwise buildContext (KIRO_HEADER) as stdout text.
+ * Appends a self-diagnostic at the end inside the kiro adapter.
+ */
+export function kiroSession(stdin, agentsMd) {
+    const payload = parsePayload(stdin);
+    const st = repoState(payload.cwd || process.cwd());
+    if (st === null)
+        return null; // inject nothing outside a git repository
+    let text = buildContext(st, { agentsMd, readTool: 'Read', header: KIRO_HEADER });
+    text += kiroGuardDiagnostic(st.mainRoot ?? st.toplevel);
+    return text;
+}
+/**
+ * Self-diagnostic for a missing guard hook. Looks at .kiro/hooks/lockage-guard.json directly under
+ * the main repository, and returns a one-line warning if it is missing. Returns an empty string
+ * (appends nothing) if present or on exception. This does not pollute buildContext itself; it is
+ * done only inside the kiro adapter.
+ */
+function kiroGuardDiagnostic(base) {
+    try {
+        const guardPath = join(base, '.kiro', 'hooks', 'lockage-guard.json');
+        if (!existsSync(guardPath)) {
+            return '- The guard hook is not installed. Run npx -y lockage setup kiro to install the guard hook.\n';
+        }
+    }
+    catch {
+        // Swallow a diagnostic failure and append nothing (injection-only; never deny)
+    }
+    return '';
+}
+//# sourceMappingURL=clients.js.map

package/dist/hook/context.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The text passed to the model at the start of a session (the repository state, and the location
+ * of the canonical coordination rules).
+ *
+ * How it is delivered (claude's SessionStart, antigravity's PreInvocation, kiro's SessionStart) is
+ * handled by each client's adapter (clients.ts).
+ *
+ * The body of AGENTS.md is not passed (it would exceed the client's additionalContext limit, so we
+ * pass only the path and have the model read it).
+ */
+import type { RepoState } from './repo.js';
+export declare const DEFAULT_HEADER = "## lockage coordinated development (lockage plugin)\n";
+/** Per-client parameters for buildContext. */
+export interface BuildContextOptions {
+    agentsMd: string;
+    readTool: string;
+    header?: string;
+}
+/**
+ * Build the injected text.
+ */
+export declare function buildContext(st: RepoState, opts: BuildContextOptions): string;

package/dist/hook/context.js

@@ -0,0 +1,40 @@
+/**
+ * The text passed to the model at the start of a session (the repository state, and the location
+ * of the canonical coordination rules).
+ *
+ * How it is delivered (claude's SessionStart, antigravity's PreInvocation, kiro's SessionStart) is
+ * handled by each client's adapter (clients.ts).
+ *
+ * The body of AGENTS.md is not passed (it would exceed the client's additionalContext limit, so we
+ * pass only the path and have the model read it).
+ */
+import { inUse } from './repo.js';
+// Default HEADER. Clients replace it (kiro overrides it with the "lockage Kiro Power" version).
+// Keep it identical across clients (so the injected content does not change).
+export const DEFAULT_HEADER = '## lockage coordinated development (lockage plugin)\n';
+/**
+ * Build the injected text.
+ */
+export function buildContext(st, opts) {
+    const { agentsMd, readTool, header = DEFAULT_HEADER } = opts;
+    const tree = st.isLinked ? 'worktree' : 'main working tree';
+    const repoPath = st.mainRoot ?? 'cannot be determined (a layout such as --separate-git-dir; check and pass the location of the main repository)';
+    // lockage matches repos by path string, so passing just a name or a worktree path drops it from listings and checks
+    const head = header +
+        `- value to pass as repo_path: ${repoPath}\n` +
+        '- pass the same absolute path as repo_path to open_ticket\'s repos, create_task\'s repo, and lockage-publish\'s --repo-path as well\n' +
+        `- current working tree: ${st.toplevel} (${tree})\n`;
+    if (inUse(st)) {
+        return (head +
+            '- this repository is operating under lockage. Before starting work that changes files, or work ' +
+            `that handles lockage tickets/tasks, read the canonical coordination rules ${agentsMd} with ${readTool} and follow the lockage-workflow skill\'s steps.\n` +
+            '- do all editing only inside the worktree returned by assign_worktree, and do not edit the main working tree directly' +
+            ' (the only exception is "when the user instructs you not to use lockage" at the top of AGENTS.md).\n' +
+            '- if the repository\'s AGENTS.md has a lockage section, treat it as that repository\'s specific rules and prefer it over the bundled canonical rules.\n');
+    }
+    // For a repository not operating under lockage, pass only the entry point to keep per-session overhead small
+    return (head +
+        '- this repository does not use lockage yet. If the user instructs you to proceed with lockage, ' +
+        `read the canonical coordination rules ${agentsMd} with ${readTool} and follow the lockage-workflow skill\'s steps.\n`);
+}
+//# sourceMappingURL=context.js.map

package/dist/hook/dispatch.d.ts

@@ -0,0 +1,21 @@
+/**
+ * CLI dispatcher for `lockage hook <guard|session>` / `lockage setup kiro`.
+ *
+ * The entry section of src/index.ts dynamically imports and calls here only when argv[2]==='hook'
+ * || 'setup'. With no args or an unknown argv[2], index.ts starts the MCP server (main) as before,
+ * so we never reach here.
+ *
+ * design.md §1/§3 is authoritative. CLI forms:
+ *   lockage hook guard   --client <claude|antigravity|kiro> [--event pre|post] [--agents-md <path>]
+ *   lockage hook session --client <claude|antigravity|kiro> [--agents-md <path>]
+ *   lockage setup kiro   [--repo <path>] [--force]
+ *
+ * The per-client exit-code/stdout control (claude/antigravity return a passing response + exit 0 on
+ * exception; kiro guard is fail-closed exit 2 on exception; kiro session is exit 0 on exception) is
+ * branched by this outermost shell according to --client and the subcommand type (the layer that
+ * owns the invariant "only kiro guard is fail-closed").
+ */
+/**
+ * CLI entry point. argv is process.argv.slice(2) (first element is 'hook' or 'setup').
+ */
+export declare function dispatchCli(argv: string[]): Promise<void>;

package/dist/hook/dispatch.js

@@ -0,0 +1,212 @@
+/**
+ * CLI dispatcher for `lockage hook <guard|session>` / `lockage setup kiro`.
+ *
+ * The entry section of src/index.ts dynamically imports and calls here only when argv[2]==='hook'
+ * || 'setup'. With no args or an unknown argv[2], index.ts starts the MCP server (main) as before,
+ * so we never reach here.
+ *
+ * design.md §1/§3 is authoritative. CLI forms:
+ *   lockage hook guard   --client <claude|antigravity|kiro> [--event pre|post] [--agents-md <path>]
+ *   lockage hook session --client <claude|antigravity|kiro> [--agents-md <path>]
+ *   lockage setup kiro   [--repo <path>] [--force]
+ *
+ * The per-client exit-code/stdout control (claude/antigravity return a passing response + exit 0 on
+ * exception; kiro guard is fail-closed exit 2 on exception; kiro session is exit 0 on exception) is
+ * branched by this outermost shell according to --client and the subcommand type (the layer that
+ * owns the invariant "only kiro guard is fail-closed").
+ */
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { antigravityGuard, antigravitySession, claudeGuard, claudeSession, KIRO_EXIT_ALLOW, KIRO_EXIT_DENY, kiroGuard, kiroSession, } from './clients.js';
+import { log } from './repo.js';
+import { setupKiro } from './setup-kiro.js';
+const USAGE = `lockage hook <guard|session> --client <claude|antigravity|kiro> [--event pre|post] [--agents-md <path>]\n` +
+    `lockage setup kiro [--repo <path>] [--force]\n\n` +
+    `hook:\n` +
+    `  guard    Guard for editing the main working tree. Pass the hook payload JSON on stdin.\n` +
+    `  session  Context injection at session start. Pass the hook payload JSON on stdin.\n` +
+    `  --client   claude | antigravity | kiro (required)\n` +
+    `  --event    pre | post (required for antigravity guard; claude/kiro use the input's hook_event_name)\n` +
+    `  --agents-md  path to the canonical coordination rules (AGENTS.md) (only placed in the text)\n\n` +
+    `setup kiro:\n` +
+    `  --repo <path>  the target repository root (default cwd)\n` +
+    `  --force        overwrite an existing hook definition without confirmation\n`;
+/** Write usage to stderr and exit non-zero (does not fall back to MCP). */
+function usageError(msg) {
+    process.stderr.write(`lockage: ${msg}\n\n${USAGE}`);
+    process.exit(2);
+}
+/** Read all of stdin (called only by hook guard/session). Empty becomes an empty string. */
+function readStdin() {
+    try {
+        return readFileSync(0, { encoding: 'utf8' });
+    }
+    catch {
+        // When there is no stdin / it cannot be read, treat it as an empty payload (clients.ts handles empty safely)
+        return '';
+    }
+}
+/** Validate the --client value. */
+function requireClient(value) {
+    if (value === 'claude' || value === 'antigravity' || value === 'kiro')
+        return value;
+    usageError(`--client must be one of claude|antigravity|kiro (received: ${value ?? '(none)'})`);
+}
+/**
+ * CLI entry point. argv is process.argv.slice(2) (first element is 'hook' or 'setup').
+ */
+export async function dispatchCli(argv) {
+    const [group, sub, ...rest] = argv;
+    if (group === 'hook') {
+        return dispatchHook(sub, rest);
+    }
+    if (group === 'setup') {
+        return dispatchSetup(sub, rest);
+    }
+    // The entry section of index.ts calls here only for hook/setup, so we normally never reach here
+    usageError(`unknown subcommand: ${group ?? '(none)'}`);
+}
+/** Handle `lockage hook <guard|session> ...`. */
+function dispatchHook(sub, rest) {
+    if (sub !== 'guard' && sub !== 'session') {
+        usageError(`the hook subcommand must be guard|session (received: ${sub ?? '(none)'})`);
+    }
+    const { values } = parseArgs({
+        args: rest,
+        options: {
+            client: { type: 'string' },
+            event: { type: 'string' },
+            'agents-md': { type: 'string' },
+            help: { type: 'boolean', short: 'h' },
+        },
+        allowPositionals: false,
+    });
+    if (values.help) {
+        process.stdout.write(USAGE);
+        return;
+    }
+    const client = requireClient(values.client);
+    const agentsMd = values['agents-md'] ?? '';
+    if (sub === 'guard') {
+        dispatchGuard(client, values.event, agentsMd);
+        return;
+    }
+    dispatchSession(client, agentsMd);
+}
+/** Handle the guard subcommand per client. The outermost shell controls exit code and stdout. */
+function dispatchGuard(client, event, _agentsMd) {
+    // Disable switch. Returns a path-dependent "pass" response and does not even read stdin (design.md §3)
+    const disabled = process.env.LOCKAGE_GUARD_DISABLE === '1';
+    if (client === 'claude') {
+        try {
+            if (disabled)
+                return; // no output, no record, exit immediately
+            const out = claudeGuard(readStdin());
+            if (out !== null)
+                process.stdout.write(JSON.stringify(out));
+        }
+        catch (e) {
+            // When it cannot decide, pass (do not stop the edit itself due to a hook defect). No output + exit 0
+            log(`guard(claude) failed, so passed without deciding: ${String(e)}`);
+        }
+        return;
+    }
+    if (client === 'antigravity') {
+        if (event !== 'pre' && event !== 'post') {
+            usageError('antigravity guard requires --event pre|post');
+        }
+        try {
+            if (disabled) {
+                // pre→{decision:'ask'}, post→{} (mode-dependent, no record, does not read stdin)
+                process.stdout.write(JSON.stringify(event === 'pre' ? { decision: 'ask' } : {}));
+                return;
+            }
+            const out = antigravityGuard(readStdin(), event);
+            process.stdout.write(JSON.stringify(out));
+        }
+        catch (e) {
+            // When it cannot decide, leave it to the usual permission check (pre=ask / post={}) + exit 0
+            log(`guard(antigravity) failed, so passed without deciding: ${String(e)}`);
+            process.stdout.write(JSON.stringify(event === 'pre' ? { decision: 'ask' } : {}));
+        }
+        return;
+    }
+    // kiro: decide via exit code (fail-closed). Does not read stdin if disabled either
+    try {
+        if (disabled) {
+            process.exit(KIRO_EXIT_ALLOW);
+        }
+        process.exit(kiroGuard(readStdin()));
+    }
+    catch (e) {
+        // On exception, fail safe and deny (exit 2)
+        log(`guard(kiro) failed, so failed safe and denied: ${String(e)}`);
+        process.exit(KIRO_EXIT_DENY);
+    }
+}
+/** Handle the session subcommand per client. On exception, all inject nothing + exit 0. */
+function dispatchSession(client, agentsMd) {
+    if (client === 'claude') {
+        try {
+            const out = claudeSession(readStdin(), agentsMd);
+            if (out !== null)
+                process.stdout.write(JSON.stringify(out));
+        }
+        catch (e) {
+            log(`session(claude) failed, so injected nothing: ${String(e)}`);
+        }
+        return;
+    }
+    if (client === 'antigravity') {
+        try {
+            const out = antigravitySession(readStdin(), agentsMd);
+            process.stdout.write(JSON.stringify(out));
+        }
+        catch (e) {
+            // Do not hinder the model invocation (emit {})
+            log(`session(antigravity) failed, so injected nothing: ${String(e)}`);
+            process.stdout.write(JSON.stringify({}));
+        }
+        return;
+    }
+    // kiro: text to stdout (not JSON). On exception, no output, exit 0
+    try {
+        const text = kiroSession(readStdin(), agentsMd);
+        if (text !== null)
+            process.stdout.write(text);
+    }
+    catch (e) {
+        log(`session(kiro) failed, so injected nothing: ${String(e)}`);
+    }
+}
+/** Handle `lockage setup kiro ...`. */
+function dispatchSetup(sub, rest) {
+    if (sub !== 'kiro') {
+        usageError(`the setup subcommand must be kiro (received: ${sub ?? '(none)'})`);
+    }
+    const { values } = parseArgs({
+        args: rest,
+        options: {
+            repo: { type: 'string' },
+            force: { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' },
+        },
+        allowPositionals: false,
+    });
+    if (values.help) {
+        process.stdout.write(USAGE);
+        return;
+    }
+    try {
+        const result = setupKiro({ repo: values.repo, force: values.force });
+        for (const line of result.lines)
+            process.stdout.write(line + '\n');
+        process.exitCode = result.exitCode;
+    }
+    catch (e) {
+        // A mkdir/write failure or a --repo pointing to a nonexistent directory is fatal (stderr + non-zero exit)
+        process.stderr.write(`lockage setup kiro: ${e instanceof Error ? e.message : String(e)}\n`);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/hook/guard.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Decision for the main-working-tree edit guard. The input/output is normalized to the claude shape
+ * { tool_input, cwd, session_id } by each client's adapter (clients.ts) before being passed in.
+ *
+ * In a repository operating under lockage, if an edit targets a file in the main working tree rather
+ * than a worktree, interpose a confirmation. We use a confirmation instead of deny so as not to
+ * block the case where a person works on the main tree without using lockage (Kiro, which cannot
+ * show a confirmation, falls back to deny).
+ *
+ * The confirmation keeps appearing until it is allowed. Once allowed and the edit actually happens
+ * (PostToolUse), we no longer ask for that session and that repository. An operating repository
+ * always leaves traces such as a lockage/ branch or .lockage/, so asking every time would cause
+ * confirmation fatigue — leading to always allowing it, or disabling the guard entirely so it
+ * becomes a mere formality. We do not place the mark at PreToolUse time because the hook cannot
+ * distinguish allow from deny, which would let even a post-deny edit slip through.
+ */
+export declare const STATE_DIR: string;
+/** The claude-shaped hook payload. antigravity / kiro inputs are normalized to this shape by the adapters. */
+export interface GuardPayload {
+    tool_input?: {
+        file_path?: string | null;
+        notebook_path?: string | null;
+    } | null;
+    cwd?: string | null;
+    session_id?: string | null;
+}
+/**
+ * PreToolUse: returns the reason string if a confirmation should be interposed, or null if not.
+ */
+export declare function decide(payload: GuardPayload, stateDir?: string): string | null;
+/**
+ * PostToolUse: record that an edit to the main working tree actually happened (= was allowed).
+ */
+export declare function record(payload: GuardPayload, stateDir?: string): void;