@arnilo/prism-coding-agent 0.0.96 → 0.1.0

package/dist/forge/types.d.ts

@@ -0,0 +1,150 @@
+import type { AgentIdentity, ExecutionPolicy, OwnershipScope, ToolEffectStore } from "@arnilo/prism";
+import type { BoundGitRunner, CreateGitRunnerOptions } from "../git-exec.js";
+/** Read-only context for one GitHub issue, bounded by payload caps. */
+export interface ForgeIssueContext {
+    readonly number: number;
+    readonly title: string;
+    readonly state: "open" | "closed";
+    readonly body: string;
+    readonly labels: readonly string[];
+    readonly author: string;
+    readonly updatedAt: string;
+    readonly url: string;
+}
+/** Pull-request state as seen through the forge. */
+export interface ForgePullRequest {
+    readonly number: number;
+    readonly state: "open" | "closed";
+    readonly merged: boolean;
+    readonly head: string;
+    readonly base: string;
+    readonly title: string;
+    readonly body: string;
+    readonly url: string;
+}
+/** One check run or commit status, normalized. */
+export interface ForgeCheck {
+    readonly name: string;
+    readonly status: "queued" | "in_progress" | "completed";
+    readonly conclusion?: string;
+    readonly detailsUrl?: string;
+}
+/** Bounded handoff reconciliation: push/PR/check state, never auto-merged. */
+export interface ForgeHandoffReport {
+    readonly base: string;
+    readonly head: string;
+    /** Whether the head ref exists on the remote. */
+    readonly pushed: boolean;
+    readonly aheadBy: number;
+    readonly behindBy: number;
+    /** No commits ahead and no divergence: nothing to push. */
+    readonly alreadyUpToDate: boolean;
+    readonly alreadyMerged: boolean;
+    readonly pullRequest?: ForgePullRequest;
+    readonly checks: readonly ForgeCheck[];
+    /** Bounded commit list (sha + subject), present only when pushed. */
+    readonly commits: readonly {
+        sha: string;
+        subject: string;
+    }[];
+    /** Bounded changed paths, present only when pushed. */
+    readonly changedPaths: readonly string[];
+    readonly diffstat: string;
+    readonly warnings: readonly string[];
+}
+export type ForgeErrorCode = "ERR_PRISM_FORGE_AUTH" | "ERR_PRISM_FORGE_API" | "ERR_PRISM_FORGE_STALE" | "ERR_PRISM_FORGE_RATE_LIMIT" | "ERR_PRISM_FORGE_LIMIT" | "ERR_PRISM_FORGE_OWNERSHIP";
+export declare class ForgeError extends Error {
+    readonly code: ForgeErrorCode;
+    constructor(code: ForgeErrorCode, message: string);
+}
+export interface ForgeLimits {
+    readonly pagesPerOperation?: number;
+    readonly payloadBytes?: number;
+    readonly commentsPerReview?: number;
+    readonly requestConcurrency?: number;
+    readonly requestTimeoutMs?: number;
+}
+export interface ResolvedForgeLimits {
+    readonly pagesPerOperation: number;
+    readonly payloadBytes: number;
+    readonly commentsPerReview: number;
+    readonly requestConcurrency: number;
+    readonly requestTimeoutMs: number;
+}
+export declare function resolveForgeLimits(options?: ForgeLimits): ResolvedForgeLimits;
+export interface ForgeOperations {
+    issueContext(input: {
+        number: number;
+    }): Promise<ForgeIssueContext>;
+    push(input: {
+        refspec?: string;
+    }): Promise<{
+        remoteRef: string;
+    }>;
+    createPullRequest(input: {
+        head: string;
+        base: string;
+        title: string;
+        body: string;
+    }): Promise<ForgePullRequest>;
+    updatePullRequest(input: {
+        number: number;
+        title?: string;
+        body?: string;
+        state?: "open" | "closed";
+    }): Promise<ForgePullRequest>;
+    createReviewComment(input: {
+        number: number;
+        path: string;
+        line: number;
+        body: string;
+    }): Promise<{
+        id: number;
+    }>;
+    checks(input: {
+        ref: string;
+    }): Promise<readonly ForgeCheck[]>;
+    reconcileHandoff(input: {
+        base: string;
+        head: string;
+    }): Promise<ForgeHandoffReport>;
+}
+/** Structural mirror of the core `CredentialResolverSource` (not barrel-exported). */
+export interface ForgeCredential {
+    readonly type: "bearer" | "api_key" | "basic" | "custom";
+    readonly value: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface ForgeCredentialResolver {
+    resolve(request: {
+        readonly name: string;
+        readonly provider?: string;
+        readonly metadata?: Readonly<Record<string, unknown>>;
+    }): Promise<ForgeCredential | undefined> | ForgeCredential | undefined;
+}
+export interface ForgeCredentialResolverSource {
+    readonly name: string;
+    readonly resolver: ForgeCredentialResolver;
+}
+export interface CreateGitHubForgeOptions {
+    /** Credential resolver — resolved with provider "github" per call. */
+    readonly credentials: ForgeCredentialResolverSource;
+    /** "owner/repo", bound per instance. */
+    readonly repository: string;
+    /** Local checkout the adapter pushes from. */
+    readonly cwd: string;
+    /** Git runner reused for authenticated push. */
+    readonly git: CreateGitRunnerOptions | BoundGitRunner;
+    /** Mutations are gated through this policy before any request. */
+    readonly policy?: ExecutionPolicy;
+    /** REQUIRED: idempotency + unknown-outcome recovery for mutations. */
+    readonly effectStore: ToolEffectStore;
+    /** Durable context for effect keys; required for mutations. */
+    readonly identity?: AgentIdentity;
+    readonly ownership?: OwnershipScope;
+    readonly sessionId?: string;
+    readonly runId?: string;
+    readonly limits?: ForgeLimits;
+    /** Host-injectable fetch (e.g. routed through an egress proxy); defaults to globalThis.fetch. */
+    readonly fetch?: typeof fetch;
+}

package/dist/forge/types.js

@@ -0,0 +1,19 @@
+import { DEFAULT_MAX_FORGE_COMMENTS_PER_REVIEW, DEFAULT_MAX_FORGE_PAGES_PER_OPERATION, DEFAULT_MAX_FORGE_PAYLOAD_BYTES, DEFAULT_MAX_FORGE_REQUEST_CONCURRENCY, DEFAULT_MAX_FORGE_REQUEST_TIMEOUT_MS, HARD_MAX_FORGE_COMMENTS_PER_REVIEW, HARD_MAX_FORGE_PAGES_PER_OPERATION, HARD_MAX_FORGE_PAYLOAD_BYTES, HARD_MAX_FORGE_REQUEST_CONCURRENCY, HARD_MAX_FORGE_REQUEST_TIMEOUT_MS, validateCodingLimit, } from "../limits.js";
+export class ForgeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ForgeError";
+        this.code = code;
+    }
+}
+export function resolveForgeLimits(options) {
+    return {
+        pagesPerOperation: validateCodingLimit("forge.pagesPerOperation", options?.pagesPerOperation ?? DEFAULT_MAX_FORGE_PAGES_PER_OPERATION, HARD_MAX_FORGE_PAGES_PER_OPERATION),
+        payloadBytes: validateCodingLimit("forge.payloadBytes", options?.payloadBytes ?? DEFAULT_MAX_FORGE_PAYLOAD_BYTES, HARD_MAX_FORGE_PAYLOAD_BYTES),
+        commentsPerReview: validateCodingLimit("forge.commentsPerReview", options?.commentsPerReview ?? DEFAULT_MAX_FORGE_COMMENTS_PER_REVIEW, HARD_MAX_FORGE_COMMENTS_PER_REVIEW),
+        requestConcurrency: validateCodingLimit("forge.requestConcurrency", options?.requestConcurrency ?? DEFAULT_MAX_FORGE_REQUEST_CONCURRENCY, HARD_MAX_FORGE_REQUEST_CONCURRENCY),
+        requestTimeoutMs: validateCodingLimit("forge.requestTimeoutMs", options?.requestTimeoutMs ?? DEFAULT_MAX_FORGE_REQUEST_TIMEOUT_MS, HARD_MAX_FORGE_REQUEST_TIMEOUT_MS),
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/git-aware-repository.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Git-aware repository enumeration over `git ls-files`.
+ *
+ * Detection: `git rev-parse --is-inside-work-tree` (cached per instance).
+ * Non-Git / detection failure → native fallback. Post-detection Git failure → fail closed.
+ * No hand-rolled `.gitignore` parser; argv is fixed host-side only.
+ */
+import { type BoundGitRunner, type CreateGitRunnerOptions } from "./git-exec.js";
+import { type RepositoryLimitOptions, type RepositoryOperations } from "./repository.js";
+export interface GitAwareRepositoryOptions {
+    readonly git?: CreateGitRunnerOptions | BoundGitRunner;
+    readonly fallback?: RepositoryOperations;
+    /** Host-config only, never model-settable. Default false: ignored paths stay excluded. */
+    readonly includeIgnored?: boolean;
+    readonly limits?: RepositoryLimitOptions;
+    /** Override freeze default/hard `ls-files` stdout cap. */
+    readonly maxLsFilesOutputBytes?: number;
+}
+/** Parse NUL-delimited `git ls-files -z` stdout. */
+export declare function parseGitLsFilesZ(buffer: Buffer): string[];
+/**
+ * Repository operations that prefer Git tracked/unignored enumeration.
+ * Outside a Git work tree (or when detection fails), delegates to `fallback`.
+ */
+export declare function createGitAwareRepositoryOperations(cwd: string, options?: GitAwareRepositoryOptions): RepositoryOperations;

package/dist/git-aware-repository.js

@@ -0,0 +1,268 @@
+/**
+ * Git-aware repository enumeration over `git ls-files`.
+ *
+ * Detection: `git rev-parse --is-inside-work-tree` (cached per instance).
+ * Non-Git / detection failure → native fallback. Post-detection Git failure → fail closed.
+ * No hand-rolled `.gitignore` parser; argv is fixed host-side only.
+ */
+import { lstat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { createBoundGitRunner, gitText, GitError } from "./git-exec.js";
+import { DEFAULT_MAX_LS_FILES_OUTPUT_BYTES, HARD_MAX_LS_FILES_OUTPUT_BYTES, validateCodingLimit } from "./limits.js";
+import { createLocalRepositoryOperations, RepositoryError, toRepoRelative, } from "./repository.js";
+function isBoundGitRunner(value) {
+    return typeof value.exec === "function" && typeof value.gitPath === "string";
+}
+function shouldSkipName(name, includeHidden, exclude) {
+    if (name === "." || name === "..")
+        return true;
+    if (exclude.has(name))
+        return true;
+    if (!includeHidden && name.startsWith("."))
+        return true;
+    return false;
+}
+function pathHasSkippedComponent(relativePath, includeHidden, exclude) {
+    for (const part of relativePath.split("/")) {
+        if (shouldSkipName(part, includeHidden, exclude))
+            return true;
+    }
+    return false;
+}
+/** Parse NUL-delimited `git ls-files -z` stdout. */
+export function parseGitLsFilesZ(buffer) {
+    const out = [];
+    let start = 0;
+    for (let i = 0; i < buffer.length; i++) {
+        if (buffer[i] === 0) {
+            if (i > start)
+                out.push(buffer.subarray(start, i).toString("utf8"));
+            start = i + 1;
+        }
+    }
+    if (start < buffer.length)
+        out.push(buffer.subarray(start).toString("utf8"));
+    return out;
+}
+function depthFromStart(relativePath, startRel) {
+    const rel = startRel === "."
+        ? relativePath
+        : relativePath === startRel
+            ? ""
+            : relativePath.startsWith(`${startRel}/`)
+                ? relativePath.slice(startRel.length + 1)
+                : relativePath;
+    if (rel === "" || rel === ".")
+        return 0;
+    return rel.split("/").length - 1;
+}
+function isUnderStart(relativePath, startRel) {
+    if (startRel === "." || startRel === "")
+        return true;
+    return relativePath === startRel || relativePath.startsWith(`${startRel}/`);
+}
+async function* walkGitFiles(rootReal, startAbsolute, limits, files) {
+    const startRel = toRepoRelative(rootReal, startAbsolute);
+    const dirSeen = new Set();
+    const planned = [];
+    for (const relativePath of files) {
+        if (limits.signal?.aborted)
+            throw new RepositoryError("Operation aborted");
+        if (limits.deadlineAt !== undefined && Date.now() >= limits.deadlineAt) {
+            throw new RepositoryError("Repository operation exceeded time limit");
+        }
+        if (!relativePath || relativePath.includes("\0"))
+            continue;
+        if (relativePath === ".git" || relativePath.startsWith(".git/"))
+            continue;
+        if (!isUnderStart(relativePath, startRel))
+            continue;
+        if (pathHasSkippedComponent(relativePath, limits.includeHidden, limits.exclude))
+            continue;
+        const fileDepth = depthFromStart(relativePath, startRel);
+        if (fileDepth > limits.maxDepth)
+            continue;
+        // Synthesize parent directories within the start scope (native walker emits dirs too).
+        const parts = relativePath.split("/");
+        let acc = "";
+        for (let i = 0; i < parts.length - 1; i++) {
+            acc = acc ? `${acc}/${parts[i]}` : parts[i];
+            if (!isUnderStart(acc, startRel))
+                continue;
+            if (pathHasSkippedComponent(acc, limits.includeHidden, limits.exclude))
+                break;
+            const dirDepth = depthFromStart(acc, startRel);
+            if (dirDepth > limits.maxDepth)
+                break;
+            if (!dirSeen.has(acc)) {
+                dirSeen.add(acc);
+                planned.push({ path: acc, kind: "directory", depth: dirDepth });
+            }
+        }
+        planned.push({ path: relativePath, kind: "file", depth: fileDepth });
+    }
+    planned.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    let scannedEntries = 0;
+    let scannedFiles = 0;
+    for (const item of planned) {
+        if (limits.signal?.aborted)
+            throw new RepositoryError("Operation aborted");
+        if (limits.deadlineAt !== undefined && Date.now() >= limits.deadlineAt) {
+            throw new RepositoryError("Repository operation exceeded time limit");
+        }
+        if (scannedEntries >= limits.maxEntries) {
+            yield { type: "limit", truncatedBy: "entries" };
+            return;
+        }
+        const absolutePath = join(rootReal, item.path);
+        const rootResolved = resolve(rootReal);
+        const absResolved = resolve(absolutePath);
+        if (absResolved !== rootResolved && !absResolved.startsWith(rootResolved + "/"))
+            continue;
+        let kind = item.kind;
+        let size;
+        try {
+            const st = await lstat(absolutePath);
+            if (st.isSymbolicLink())
+                kind = "symlink";
+            else if (st.isDirectory())
+                kind = "directory";
+            else if (st.isFile()) {
+                kind = "file";
+                size = st.size;
+            }
+            else
+                kind = "other";
+        }
+        catch {
+            // Missing after ls-files (race) — skip.
+            continue;
+        }
+        if (kind === "file") {
+            if (scannedFiles >= limits.maxFiles) {
+                yield { type: "limit", truncatedBy: "files" };
+                return;
+            }
+            scannedFiles++;
+        }
+        scannedEntries++;
+        const entry = size === undefined ? { path: item.path, kind } : { path: item.path, kind, size };
+        yield { type: "entry", entry, absolutePath, depth: item.depth };
+    }
+}
+/**
+ * Repository operations that prefer Git tracked/unignored enumeration.
+ * Outside a Git work tree (or when detection fails), delegates to `fallback`.
+ */
+export function createGitAwareRepositoryOperations(cwd, options) {
+    const fallback = options?.fallback ?? createLocalRepositoryOperations(options?.limits);
+    const includeIgnored = options?.includeIgnored === true;
+    const maxLsBytes = validateCodingLimit("maxLsFilesOutputBytes", options?.maxLsFilesOutputBytes ?? DEFAULT_MAX_LS_FILES_OUTPUT_BYTES, HARD_MAX_LS_FILES_OUTPUT_BYTES);
+    let detected;
+    let runnerPromise;
+    let gitOps;
+    function getRunner() {
+        if (!runnerPromise) {
+            const git = options?.git;
+            runnerPromise =
+                git && isBoundGitRunner(git)
+                    ? Promise.resolve(git)
+                    : createBoundGitRunner({
+                        ...git,
+                        maxOutputBytes: maxLsBytes,
+                    });
+        }
+        return runnerPromise;
+    }
+    async function detect(signal) {
+        if (detected !== undefined)
+            return detected;
+        try {
+            const result = await (await getRunner()).exec({
+                args: ["rev-parse", "--is-inside-work-tree"],
+                cwd,
+                signal,
+                maxOutputBytes: 64,
+            });
+            detected = result.exitCode === 0 && gitText(result).trim() === "true";
+        }
+        catch {
+            detected = false;
+        }
+        return detected;
+    }
+    async function listGitPaths(signal) {
+        const runner = await getRunner();
+        // Fixed argv only — never model-supplied flags (Task 0 freeze).
+        const primary = await runner.exec({
+            args: ["ls-files", "--cached", "--others", "--exclude-standard", "-z"],
+            cwd,
+            signal,
+            maxOutputBytes: maxLsBytes,
+        });
+        if (primary.timedOut)
+            throw new RepositoryError("Repository operation exceeded time limit");
+        if (primary.aborted)
+            throw new RepositoryError("Operation aborted");
+        if (primary.exitCode !== 0) {
+            throw new RepositoryError(`git ls-files failed (exit ${primary.exitCode})`);
+        }
+        const paths = new Set(parseGitLsFilesZ(primary.stdout));
+        if (includeIgnored) {
+            // Second invocation only when host opts into ignored paths (≤ 2 total per freeze).
+            const ignored = await runner.exec({
+                args: ["ls-files", "-o", "-i", "--exclude-standard", "-z"],
+                cwd,
+                signal,
+                maxOutputBytes: maxLsBytes,
+            });
+            if (ignored.timedOut)
+                throw new RepositoryError("Repository operation exceeded time limit");
+            if (ignored.aborted)
+                throw new RepositoryError("Operation aborted");
+            if (ignored.exitCode !== 0) {
+                throw new RepositoryError(`git ls-files (ignored) failed (exit ${ignored.exitCode})`);
+            }
+            for (const p of parseGitLsFilesZ(ignored.stdout))
+                paths.add(p);
+        }
+        return [...paths].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    }
+    function getGitOps() {
+        if (!gitOps) {
+            const walk = async function* (rootReal, startAbsolute, limits) {
+                let files;
+                try {
+                    files = await listGitPaths(limits.signal);
+                }
+                catch (error) {
+                    if (error instanceof RepositoryError)
+                        throw error;
+                    if (error instanceof GitError) {
+                        if (/abort/i.test(error.message))
+                            throw new RepositoryError("Operation aborted");
+                        if (/time|exceeded/i.test(error.message)) {
+                            throw new RepositoryError("Repository operation exceeded time limit");
+                        }
+                        throw new RepositoryError(error.message);
+                    }
+                    throw new RepositoryError(error instanceof Error ? error.message : String(error));
+                }
+                yield* walkGitFiles(rootReal, startAbsolute, limits, files);
+            };
+            gitOps = createLocalRepositoryOperations(options?.limits, walk);
+        }
+        return gitOps;
+    }
+    async function route(signal, gitCall, nativeCall) {
+        if (!(await detect(signal)))
+            return nativeCall();
+        return gitCall();
+    }
+    return {
+        list: (request) => route(request.signal, () => getGitOps().list(request), () => fallback.list(request)),
+        search: (request) => route(request.signal, () => getGitOps().search(request), () => fallback.search(request)),
+        glob: (request) => route(request.signal, () => getGitOps().glob(request), () => fallback.glob(request)),
+    };
+}
+//# sourceMappingURL=git-aware-repository.js.map

package/dist/git-exec.js

@@ -6,8 +6,8 @@
  * runner (for example a sandbox `execFile` adapter) without changing tool code.
  */
 import { spawn } from "node:child_process";
-import { access } from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
+import { access } from "node:fs/promises";
 import { isAbsolute } from "node:path";
 import { DEFAULT_GIT_TIMEOUT_MS, DEFAULT_MAX_GIT_OUTPUT_BYTES, HARD_GIT_TIMEOUT_MS, HARD_MAX_GIT_OUTPUT_BYTES, validateCodingLimit, } from "./limits.js";
 export class GitError extends Error {

package/dist/git-tools.d.ts

@@ -5,8 +5,9 @@
  * Shell is never used internally; all Git invocations go through typed arg arrays.
  */
 import type { ExecutionPolicy, ToolDefinition } from "@arnilo/prism";
-import { type ArtifactWriter, type CreateGitOperationsOptions, type GitOperations } from "./git.js";
 import { type CodingCheckToolOptions, type NamedCheckDefinition } from "./checks.js";
+import type { CodingLifecycleEvent } from "./lifecycle.js";
+import { type ArtifactWriter, type CreateGitOperationsOptions, type GitOperations } from "./git.js";
 export interface GitToolsOptions {
     readonly executionPolicy?: ExecutionPolicy;
     readonly gitPath?: string;
@@ -19,6 +20,8 @@ export interface GitToolsOptions {
     /** Optional named checks included by `createGitTools` when provided. */
     readonly checks?: Readonly<Record<string, NamedCheckDefinition>>;
     readonly checkOptions?: Omit<CodingCheckToolOptions, "checks" | "executionPolicy">;
+    /** Optional consumer-gated lifecycle listener (worktree_changed / permission_denied). */
+    readonly onEvent?: (event: CodingLifecycleEvent) => void;
 }
 export declare function createGitStatusTool(cwd: string, options?: GitToolsOptions): ToolDefinition;
 export declare function createGitDiffTool(cwd: string, options?: GitToolsOptions): ToolDefinition;

package/dist/git-tools.js

@@ -1,6 +1,7 @@
+import { createCodingCheckTool } from "./checks.js";
+import { classifyGitApplyEffect, classifyGitBranchEffect, classifyGitWorktreeEffect, CODING_LOCAL_EFFECT, CODING_OBSERVATION_EFFECT, CODING_UNSUPPORTED_EFFECT, } from "./effects.js";
 import { enforceExecutionPolicy } from "./execution-policy.js";
 import { createGitOperations, GitError, } from "./git.js";
-import { createCodingCheckTool } from "./checks.js";
 function errorResult(toolName, toolCallId, message) {
     return {
         toolCallId,
@@ -39,6 +40,7 @@ export function createGitStatusTool(cwd, options) {
     const getOps = opsFactory(cwd, options);
     return {
         name: "git_status",
+        effect: CODING_OBSERVATION_EFFECT,
         description: "Return structured Git status (porcelain v2) including branch metadata and dirty-state. Does not follow shell; paths are repository-relative.",
         parameters: {
             type: "object",
@@ -84,6 +86,7 @@ export function createGitDiffTool(cwd, options) {
     const getOps = opsFactory(cwd, options);
     return {
         name: "git_diff",
+        effect: CODING_OBSERVATION_EFFECT,
         description: "Return a bounded unified diff (--no-ext-diff --no-textconv). Large diffs truncate inline and may spill through the host artifact writer.",
         parameters: {
             type: "object",
@@ -138,6 +141,7 @@ export function createGitBranchTool(cwd, options) {
     const getOps = opsFactory(cwd, options);
     return {
         name: "git_branch",
+        effect: classifyGitBranchEffect,
         description: "Validate, list, create, or switch branches. Switch refuses a dirty worktree unless createCheckpoint=true.",
         exclusive: true,
         parameters: {
@@ -208,6 +212,7 @@ export function createGitWorktreeTool(cwd, options) {
     const getOps = opsFactory(cwd, options);
     return {
         name: "git_worktree",
+        effect: classifyGitWorktreeEffect,
         description: "List, add, or remove Git worktrees within finite caps. Prefer disposable worktrees for mutating transactions.",
         exclusive: true,
         parameters: {
@@ -238,7 +243,7 @@ export function createGitWorktreeTool(cwd, options) {
                 paths: path ? [path] : [cwd],
                 risk: action === "list" ? "low" : "high",
                 metadata: { branch, force, sessionId: context.sessionId, runId: context.runId },
-            }, toolCallId, "git_worktree");
+            }, toolCallId, "git_worktree", (denied) => options?.onEvent?.({ type: "permission_denied", ...denied }));
             if (!policy.allowed)
                 return policy.result;
             try {
@@ -249,9 +254,11 @@ export function createGitWorktreeTool(cwd, options) {
                     force,
                     signal: context.signal,
                 });
+                if (action !== "list") {
+                    options?.onEvent?.({ type: "worktree_changed", action, path: result.path ?? path ?? "", toolCallId });
+                }
                 const text = action === "list"
-                    ? result.worktrees.map((w) => `${w.path}\t${w.branch ?? ""}\t${w.head ?? ""}`).join("\n") ||
-                        "(no worktrees)"
+                    ? result.worktrees.map((w) => `${w.path}\t${w.branch ?? ""}\t${w.head ?? ""}`).join("\n") || "(no worktrees)"
                     : `ok action=${action} path=${result.path ?? ""}`;
                 return {
                     toolCallId,
@@ -270,6 +277,7 @@ export function createGitApplyTool(cwd, options) {
     const getOps = opsFactory(cwd, options);
     return {
         name: "git_apply",
+        effect: classifyGitApplyEffect,
         description: "Check, apply, or reverse a unified patch. Always runs apply --check first for apply/reverse. Dirty trees require createCheckpoint=true; failures restore the checkpoint or clean tree.",
         exclusive: true,
         parameters: {
@@ -337,6 +345,7 @@ export function createGitCommitTool(cwd, options) {
     const getOps = opsFactory(cwd, options);
     return {
         name: "git_commit",
+        effect: CODING_LOCAL_EFFECT,
         description: "Stage and commit explicit paths only (never `git add -A`). Refuses dirty unrelated worktrees unless createCheckpoint=true. Uses --no-verify and a temp message file; never pushes.",
         exclusive: true,
         parameters: {
@@ -396,6 +405,7 @@ export function createGitPrHandoffTool(cwd, options) {
     const getOps = opsFactory(cwd, options);
     return {
         name: "git_pr_handoff",
+        effect: CODING_UNSUPPORTED_EFFECT,
         description: "Build a bounded host-owned PR handoff payload (base/head/commits/paths/diffstat/checks/artifact). Never pushes, authenticates, or opens a PR.",
         exclusive: true,
         parameters: {
@@ -430,9 +440,7 @@ export function createGitPrHandoffTool(cwd, options) {
             const base = typeof args.base === "string" ? args.base : "";
             const head = typeof args.head === "string" ? args.head : undefined;
             const includeBundle = args.includeBundle === true;
-            const checks = Array.isArray(args.checks)
-                ? args.checks
-                : undefined;
+            const checks = Array.isArray(args.checks) ? args.checks : undefined;
             const policy = await enforceExecutionPolicy(options?.executionPolicy, {
                 kind: "git",
                 operation: "pr_handoff",

package/dist/git.d.ts

@@ -133,7 +133,7 @@ export interface CreateGitOperationsOptions extends CreateGitRunnerOptions, GitL
     };
 }
 export declare function createGitOperations(options: CreateGitOperationsOptions): Promise<GitOperations>;
+export type { BoundGitRunner, CreateGitRunnerOptions, GitExecRequest, GitExecResult, GitRunner } from "./git-exec.js";
+export { createBoundGitRunner, GitError, runGitCli, SAFE_GIT_CONFIG_ARGS, SAFE_GIT_ENV, } from "./git-exec.js";
+export type { GitStatusBranch, GitStatusEntry, GitStatusEntryKind, GitStatusResult } from "./git-status.js";
 export { parsePorcelainV2 } from "./git-status.js";
-export type { GitStatusResult, GitStatusEntry, GitStatusBranch, GitStatusEntryKind } from "./git-status.js";
-export { GitError, SAFE_GIT_ENV, SAFE_GIT_CONFIG_ARGS, createBoundGitRunner, runGitCli, } from "./git-exec.js";
-export type { GitRunner, GitExecRequest, GitExecResult, BoundGitRunner, CreateGitRunnerOptions } from "./git-exec.js";