@arnilo/prism-coding-agent 0.0.26 → 0.0.27

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.0.27] - 2026-08-07
+
+### Added
+- `createCodingLifecycleEmitter(options?)` — consumer-gated coding lifecycle events (Phase 10): ships `process_*` (reuses `CodingProcessEvent`) plus `file_changed`, `worktree_changed`, `permission_denied`, `configuration_changed`; synchronous bounded `emit`/`on`; drops unknown/oversized events without breaking producer paths; invalid limits fail closed with `CodingLifecycleError` (`ERR_PRISM_LIFECYCLE_LIMIT`); frozen `DEFAULT_LIFECYCLE_MAX_*` / `HARD_LIFECYCLE_MAX_*` caps.
+- `onEvent` option on `createWriteTool` / `createEditTool` / `createMoveTool` / `createDeleteTool` / `createGitWorktreeTool` — tools emit `file_changed` (write/edit/move/delete) and `worktree_changed` (add/remove) after successful mutation, and `permission_denied` via the shared `enforceExecutionPolicy` deny hook (never raw tool arguments).
+- `enforceExecutionPolicy(..., onDenied?)` — optional callback invoked once per policy denial (additive; existing callers unaffected).
+
 ## [0.0.26] - 2026-08-06
 
 ### Added

package/dist/delete.d.ts

@@ -1,4 +1,5 @@
 import type { ExecutionPolicy, ToolDefinition } from "@arnilo/prism";
+import type { CodingLifecycleEvent } from "./lifecycle.js";
 export interface MutationStat {
     isFile(): boolean;
     isDirectory(): boolean;
@@ -22,5 +23,7 @@ export interface DeleteOperations {
 export interface DeleteToolOptions {
     executionPolicy?: ExecutionPolicy;
     operations?: DeleteOperations;
+    /** Optional consumer-gated lifecycle listener (file_changed / permission_denied). */
+    onEvent?: (event: CodingLifecycleEvent) => void;
 }
 export declare function createDeleteTool(cwd: string, options?: DeleteToolOptions): ToolDefinition;

package/dist/delete.js

@@ -62,7 +62,7 @@ export function createDeleteTool(cwd, options) {
                     paths: [absolutePath],
                     risk: "high",
                     metadata: { sessionId: context.sessionId, runId: context.runId, signal: context.signal },
-                }, toolCallId, "delete");
+                }, toolCallId, "delete", (denied) => options?.onEvent?.({ type: "permission_denied", ...denied }));
                 if (!policyCheck.allowed)
                     return policyCheck.result;
                 const allowedPath = policyCheck.action.paths?.[0] ?? absolutePath;
@@ -84,6 +84,7 @@ export function createDeleteTool(cwd, options) {
                         return errorResult(toolCallId, "Operation aborted");
                     if (st.isFile() || st.isSymbolicLink()) {
                         await ops.unlink(allowedPath, { signal: context.signal });
+                        options?.onEvent?.({ type: "file_changed", path: allowedPath, op: "delete", toolCallId });
                         return {
                             toolCallId,
                             name: "delete",
@@ -97,6 +98,7 @@ export function createDeleteTool(cwd, options) {
                             return errorResult(toolCallId, `Directory is not empty: ${path}. Recursive delete is not supported.`);
                         }
                         await ops.rmdir(allowedPath, { signal: context.signal });
+                        options?.onEvent?.({ type: "file_changed", path: allowedPath, op: "delete", toolCallId });
                         return {
                             toolCallId,
                             name: "delete",

package/dist/edit.d.ts

@@ -21,6 +21,7 @@
  */
 import { Buffer } from "node:buffer";
 import type { ExecutionPolicy, ToolDefinition } from "@arnilo/prism";
+import type { CodingLifecycleEvent } from "./lifecycle.js";
 import { type ReadBeforeWriteOptions } from "./read-path-set.js";
 export interface Edit {
     oldText: string;
@@ -71,5 +72,7 @@ export interface EditToolOptions extends ReadBeforeWriteOptions {
     maxInputBytes?: number;
     /** Maximum replacements per call (default 100). */
     maxEdits?: number;
+    /** Optional consumer-gated lifecycle listener (file_changed / permission_denied). */
+    onEvent?: (event: CodingLifecycleEvent) => void;
 }
 export declare function createEditTool(cwd: string, options?: EditToolOptions): ToolDefinition;

package/dist/edit.js

@@ -149,7 +149,7 @@ export function createEditTool(cwd, options) {
                     paths: [absolutePath],
                     risk: "medium",
                     metadata: { editCount: edits.length, sessionId: context.sessionId, runId: context.runId, signal: context.signal },
-                }, toolCallId, "edit");
+                }, toolCallId, "edit", (denied) => options?.onEvent?.({ type: "permission_denied", ...denied }));
                 if (!policyCheck.allowed)
                     return policyCheck.result;
                 const allowedPath = policyCheck.action.paths?.[0] ?? absolutePath;
@@ -203,6 +203,7 @@ export function createEditTool(cwd, options) {
                         return errorResult(toolCallId, "Operation aborted");
                     const finalContent = bom + restoreLineEndings(newContent, originalEnding);
                     await ops.writeFile(allowedPath, finalContent, { signal: context.signal });
+                    options?.onEvent?.({ type: "file_changed", path: allowedPath, op: "edit", toolCallId });
                     const diffResult = generateDiffString(baseContent, newContent);
                     const patch = generateUnifiedPatch(prepared.path, baseContent, newContent);
                     return {

package/dist/execution-policy.d.ts

@@ -1,5 +1,11 @@
 import type { ExecutionAction, ExecutionPolicy, ToolResult } from "@arnilo/prism";
-export declare function enforceExecutionPolicy(policy: ExecutionPolicy | undefined, action: ExecutionAction, toolCallId: string, toolName: string): Promise<{
+export declare function enforceExecutionPolicy(policy: ExecutionPolicy | undefined, action: ExecutionAction, toolCallId: string, toolName: string, 
+/** Called once on policy denial so one site emits lifecycle permission_denied for every tool. */
+onDenied?: (input: {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly reason: string;
+}) => void): Promise<{
     allowed: true;
     action: ExecutionAction;
 } | {

package/dist/execution-policy.js

@@ -1,5 +1,7 @@
 import { assertExecutionAllowed, ExecutionDeniedError } from "@arnilo/prism";
-export async function enforceExecutionPolicy(policy, action, toolCallId, toolName) {
+export async function enforceExecutionPolicy(policy, action, toolCallId, toolName, 
+/** Called once on policy denial so one site emits lifecycle permission_denied for every tool. */
+onDenied) {
     if (!policy)
         return { allowed: true, action };
     try {
@@ -12,6 +14,7 @@ export async function enforceExecutionPolicy(policy, action, toolCallId, toolNam
             : error instanceof Error
                 ? error.message
                 : String(error);
+        onDenied?.({ toolCallId, toolName, reason: message });
         return {
             allowed: false,
             result: {

package/dist/git-tools.d.ts

@@ -6,6 +6,7 @@
  */
 import type { ExecutionPolicy, ToolDefinition } from "@arnilo/prism";
 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;
@@ -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

@@ -243,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 {
@@ -254,6 +254,9 @@ 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)"
                     : `ok action=${action} path=${result.path ?? ""}`;

package/dist/index.d.ts

@@ -5,6 +5,8 @@ export type { CodingCheckToolOptions, NamedCheckDefinition } from "./checks.js";
 export { createCodingCheckTool } from "./checks.js";
 export type { DeleteOperations, DeleteToolOptions, MutationStat } from "./delete.js";
 export { createDeleteTool } from "./delete.js";
+export type { CodingLifecycleEvent, CodingLifecycleLimits, CodingLifecycleEmitter, CreateCodingLifecycleEmitterOptions, FileChangeOp, FileChangedEvent, WorktreeChangedEvent, PermissionDeniedEvent, ConfigurationChangedEvent, ResolvedCodingLifecycleLimits, } from "./lifecycle.js";
+export { createCodingLifecycleEmitter, CodingLifecycleError, resolveCodingLifecycleLimits, } from "./lifecycle.js";
 export type { CodingArtifactKind, CodingArtifactRef, CodingCheckpointLimitOptions, CodingCheckpointMetadata, CodingCheckSummary, CodingFingerprints, CodingHandoffSummary, CodingTaskStatus, CodingTodoItem, ResolvedCodingCheckpointLimits, } from "./coding-checkpoint.js";
 export { assertCodingResumeAllowed, buildCodingCheckpointMetadata, CODING_CHECKPOINT_SCHEMA_VERSION, CODING_STATE_KEY, CodingCheckpointError, codingCheckpointStatePatch, codingPlanPathForTask, createCodingArtifactRef, createCodingPlanMarkdown, fingerprintJson, parseCodingPlanTodos, readCodingCheckpointFromState, readCodingPlanFile, resolveCodingCheckpointLimits, validateCodingCheckpointMetadata, verifyCodingArtifactBytes, writeCodingPlanFile, } from "./coding-checkpoint.js";
 export type { Edit, EditOperations, EditToolDetails, EditToolOptions } from "./edit.js";

package/dist/index.js

@@ -8,6 +8,7 @@ export { createDirectoryArtifactWriter, createTempArtifactWriter, sha256Hex } fr
 export { ASK_USER_DECISION_RATIONALE_COUNT, ASK_USER_DECISION_SUSPEND_REASON, ASK_USER_DECISION_TOOL_NAME, askUserDecisionResumeSchema, createAskUserDecisionResumeValidator, createAskUserDecisionTool, DEFAULT_MAX_ASK_USER_DECISION_BULLET_BYTES, DEFAULT_MAX_ASK_USER_DECISION_CUSTOM_BYTES, DEFAULT_MAX_ASK_USER_DECISION_LABEL_BYTES, DEFAULT_MAX_ASK_USER_DECISION_OPTIONS, DEFAULT_MAX_ASK_USER_DECISION_QUESTION_BYTES, HARD_MAX_ASK_USER_DECISION_BULLET_BYTES, HARD_MAX_ASK_USER_DECISION_CUSTOM_BYTES, HARD_MAX_ASK_USER_DECISION_LABEL_BYTES, HARD_MAX_ASK_USER_DECISION_OPTIONS, HARD_MAX_ASK_USER_DECISION_QUESTION_BYTES, parseAskUserDecisionArgs, resolveAskUserDecisionAnswer, resolveAskUserDecisionLimits, suspendAskUserDecision, toAskUserDecisionSuspendData, validateAskUserDecisionAgentResume, validateAskUserDecisionResume, } from "./ask-user-decision.js";
 export { createCodingCheckTool } from "./checks.js";
 export { createDeleteTool } from "./delete.js";
+export { createCodingLifecycleEmitter, CodingLifecycleError, resolveCodingLifecycleLimits, } from "./lifecycle.js";
 export { assertCodingResumeAllowed, buildCodingCheckpointMetadata, CODING_CHECKPOINT_SCHEMA_VERSION, CODING_STATE_KEY, CodingCheckpointError, codingCheckpointStatePatch, codingPlanPathForTask, createCodingArtifactRef, createCodingPlanMarkdown, fingerprintJson, parseCodingPlanTodos, readCodingCheckpointFromState, readCodingPlanFile, resolveCodingCheckpointLimits, validateCodingCheckpointMetadata, verifyCodingArtifactBytes, writeCodingPlanFile, } from "./coding-checkpoint.js";
 export { createEditTool } from "./edit.js";
 export { classifyGitApplyEffect, classifyGitBranchEffect, classifyGitWorktreeEffect, CODING_LOCAL_EFFECT, CODING_OBSERVATION_EFFECT, CODING_UNSUPPORTED_EFFECT, reconcileCodingToolEffect, } from "./effects.js";

package/dist/lifecycle.d.ts

@@ -0,0 +1,75 @@
+import type { CodingProcessEvent } from "./process/types.js";
+export type FileChangeOp = "write" | "edit" | "delete" | "move";
+export interface FileChangedEvent {
+    readonly type: "file_changed";
+    /** Workspace-relative or policy-checked absolute path. Never a raw file body. */
+    readonly path: string;
+    readonly op: FileChangeOp;
+    readonly toolCallId?: string;
+}
+export interface WorktreeChangedEvent {
+    readonly type: "worktree_changed";
+    readonly action: "add" | "remove";
+    readonly path: string;
+    readonly toolCallId?: string;
+}
+export interface PermissionDeniedEvent {
+    readonly type: "permission_denied";
+    /** Policy decision reason. Never includes raw tool arguments. */
+    readonly reason: string;
+    readonly toolName: string;
+    readonly toolCallId?: string;
+    readonly approvalId?: string;
+}
+export interface ConfigurationChangedEvent {
+    readonly type: "configuration_changed";
+    /** Changed config keys only; values never travel in the event. */
+    readonly keys: readonly string[];
+}
+export type CodingLifecycleEvent = CodingProcessEvent | FileChangedEvent | WorktreeChangedEvent | PermissionDeniedEvent | ConfigurationChangedEvent;
+export declare const DEFAULT_LIFECYCLE_MAX_EVENT_BYTES = 16384;
+export declare const HARD_LIFECYCLE_MAX_EVENT_BYTES = 65536;
+export declare const DEFAULT_LIFECYCLE_MAX_PATH_BYTES = 4096;
+export declare const HARD_LIFECYCLE_MAX_PATH_BYTES = 16384;
+export declare const DEFAULT_LIFECYCLE_MAX_REASON_BYTES = 1024;
+export declare const HARD_LIFECYCLE_MAX_REASON_BYTES = 16384;
+export declare const DEFAULT_LIFECYCLE_MAX_TOOL_NAME_BYTES = 256;
+export declare const HARD_LIFECYCLE_MAX_TOOL_NAME_BYTES = 4096;
+export declare const DEFAULT_LIFECYCLE_MAX_CONFIG_KEYS = 64;
+export declare const HARD_LIFECYCLE_MAX_CONFIG_KEYS = 256;
+export interface CodingLifecycleLimits {
+    readonly maxEventBytes?: number;
+    readonly maxPathBytes?: number;
+    readonly maxReasonBytes?: number;
+    readonly maxToolNameBytes?: number;
+    readonly maxConfigKeys?: number;
+}
+export interface ResolvedCodingLifecycleLimits {
+    readonly maxEventBytes: number;
+    readonly maxPathBytes: number;
+    readonly maxReasonBytes: number;
+    readonly maxToolNameBytes: number;
+    readonly maxConfigKeys: number;
+}
+export declare class CodingLifecycleError extends Error {
+    readonly code = "ERR_PRISM_LIFECYCLE_LIMIT";
+    constructor(message: string);
+}
+export declare function resolveCodingLifecycleLimits(limits?: CodingLifecycleLimits): ResolvedCodingLifecycleLimits;
+export interface CodingLifecycleEmitter {
+    /**
+     * Delivers the event to every registered listener. Returns true when at least one
+     * listener received it. Drops (returns false) without throwing for unknown kinds,
+     * oversized events, or when no listener is registered, so producer success paths
+     * never break on telemetry.
+     */
+    emit(event: CodingLifecycleEvent): boolean;
+    /** Registers a listener; the returned function unregisters it. */
+    on(listener: (event: CodingLifecycleEvent) => void): () => void;
+}
+export interface CreateCodingLifecycleEmitterOptions {
+    readonly limits?: CodingLifecycleLimits;
+    /** Convenience initial listener, equivalent to `on`. */
+    readonly onEvent?: (event: CodingLifecycleEvent) => void;
+}
+export declare function createCodingLifecycleEmitter(options?: CreateCodingLifecycleEmitterOptions): CodingLifecycleEmitter;

package/dist/lifecycle.js

@@ -0,0 +1,102 @@
+/**
+ * Consumer-gated coding lifecycle events (Phase 10 Task 1 freeze).
+ *
+ * Ships only event kinds with a consumer in 0.0.27 (ACP mapper and/or host
+ * `CodingLifecycleEmitter` callback). Deferred kinds — check_started/finished,
+ * task_created/completed, compaction_started/finished, subagent_started/stopped —
+ * MUST NOT be added here until a consumer exists
+ * (scripts/phase10-freeze-manifest.json lifecycle.deferredEvents).
+ */
+import { validateCodingLimit } from "./limits.js";
+export const DEFAULT_LIFECYCLE_MAX_EVENT_BYTES = 16_384;
+export const HARD_LIFECYCLE_MAX_EVENT_BYTES = 65_536;
+export const DEFAULT_LIFECYCLE_MAX_PATH_BYTES = 4_096;
+export const HARD_LIFECYCLE_MAX_PATH_BYTES = 16_384;
+export const DEFAULT_LIFECYCLE_MAX_REASON_BYTES = 1_024;
+export const HARD_LIFECYCLE_MAX_REASON_BYTES = 16_384;
+export const DEFAULT_LIFECYCLE_MAX_TOOL_NAME_BYTES = 256;
+export const HARD_LIFECYCLE_MAX_TOOL_NAME_BYTES = 4_096;
+export const DEFAULT_LIFECYCLE_MAX_CONFIG_KEYS = 64;
+export const HARD_LIFECYCLE_MAX_CONFIG_KEYS = 256;
+export class CodingLifecycleError extends Error {
+    code = "ERR_PRISM_LIFECYCLE_LIMIT";
+    constructor(message) {
+        super(message);
+        this.name = "CodingLifecycleError";
+    }
+}
+function validate(name, value, hard) {
+    try {
+        return validateCodingLimit(name, value, hard);
+    }
+    catch (error) {
+        throw new CodingLifecycleError(error instanceof Error ? error.message : String(error));
+    }
+}
+export function resolveCodingLifecycleLimits(limits) {
+    return {
+        maxEventBytes: validate("maxEventBytes", limits?.maxEventBytes ?? DEFAULT_LIFECYCLE_MAX_EVENT_BYTES, HARD_LIFECYCLE_MAX_EVENT_BYTES),
+        maxPathBytes: validate("maxPathBytes", limits?.maxPathBytes ?? DEFAULT_LIFECYCLE_MAX_PATH_BYTES, HARD_LIFECYCLE_MAX_PATH_BYTES),
+        maxReasonBytes: validate("maxReasonBytes", limits?.maxReasonBytes ?? DEFAULT_LIFECYCLE_MAX_REASON_BYTES, HARD_LIFECYCLE_MAX_REASON_BYTES),
+        maxToolNameBytes: validate("maxToolNameBytes", limits?.maxToolNameBytes ?? DEFAULT_LIFECYCLE_MAX_TOOL_NAME_BYTES, HARD_LIFECYCLE_MAX_TOOL_NAME_BYTES),
+        maxConfigKeys: validate("maxConfigKeys", limits?.maxConfigKeys ?? DEFAULT_LIFECYCLE_MAX_CONFIG_KEYS, HARD_LIFECYCLE_MAX_CONFIG_KEYS),
+    };
+}
+/** Frozen shipped kinds: the six CodingProcessEvent kinds plus the four new kinds. */
+const FROZEN_EVENT_TYPES = new Set([
+    "process_started",
+    "process_exited",
+    "process_killed",
+    "process_released",
+    "process_expired",
+    "process_unknown",
+    "file_changed",
+    "worktree_changed",
+    "permission_denied",
+    "configuration_changed",
+]);
+export function createCodingLifecycleEmitter(options = {}) {
+    const limits = resolveCodingLifecycleLimits(options.limits);
+    const listeners = new Set();
+    if (options.onEvent)
+        listeners.add(options.onEvent);
+    return {
+        emit(event) {
+            if (!event || typeof event !== "object" || !FROZEN_EVENT_TYPES.has(event.type))
+                return false;
+            if (Buffer.byteLength(JSON.stringify(event), "utf8") > limits.maxEventBytes)
+                return false;
+            switch (event.type) {
+                case "file_changed":
+                case "worktree_changed":
+                    if (Buffer.byteLength(event.path, "utf8") > limits.maxPathBytes)
+                        return false;
+                    break;
+                case "permission_denied":
+                    if (Buffer.byteLength(event.reason, "utf8") > limits.maxReasonBytes)
+                        return false;
+                    if (Buffer.byteLength(event.toolName, "utf8") > limits.maxToolNameBytes)
+                        return false;
+                    break;
+                case "configuration_changed":
+                    if (event.keys.length > limits.maxConfigKeys)
+                        return false;
+                    break;
+                default:
+                    break;
+            }
+            if (listeners.size === 0)
+                return false;
+            for (const listener of [...listeners])
+                listener(event);
+            return true;
+        },
+        on(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/move.d.ts

@@ -1,5 +1,6 @@
 import type { ExecutionPolicy, ToolDefinition } from "@arnilo/prism";
 import type { MutationStat } from "./delete.js";
+import type { CodingLifecycleEvent } from "./lifecycle.js";
 export interface MoveOperations {
     lstat: (absolutePath: string, options?: {
         signal?: AbortSignal;
@@ -17,5 +18,7 @@ export interface MoveOperations {
 export interface MoveToolOptions {
     executionPolicy?: ExecutionPolicy;
     operations?: MoveOperations;
+    /** Optional consumer-gated lifecycle listener (file_changed / permission_denied). */
+    onEvent?: (event: CodingLifecycleEvent) => void;
 }
 export declare function createMoveTool(cwd: string, options?: MoveToolOptions): ToolDefinition;

package/dist/move.js

@@ -79,7 +79,7 @@ export function createMoveTool(cwd, options) {
                     paths: [fromPath, toPath],
                     risk: "high",
                     metadata: { overwrite, sessionId: context.sessionId, runId: context.runId, signal: context.signal },
-                }, toolCallId, "move");
+                }, toolCallId, "move", (denied) => options?.onEvent?.({ type: "permission_denied", ...denied }));
                 if (!policyCheck.allowed)
                     return policyCheck.result;
                 const allowedFrom = policyCheck.action.paths?.[0] ?? fromPath;
@@ -126,6 +126,7 @@ export function createMoveTool(cwd, options) {
                     if (context.signal?.aborted)
                         return errorResult(toolCallId, "Operation aborted");
                     await ops.rename(allowedFrom, allowedTo, { signal: context.signal });
+                    options?.onEvent?.({ type: "file_changed", path: allowedTo, op: "move", toolCallId });
                     return {
                         toolCallId,
                         name: "move",

package/dist/write.d.ts

@@ -1,4 +1,5 @@
 import type { ExecutionPolicy, ToolDefinition } from "@arnilo/prism";
+import type { CodingLifecycleEvent } from "./lifecycle.js";
 import { type ReadBeforeWriteOptions } from "./read-path-set.js";
 /**
  * Pluggable operations for the write tool. Override to delegate file writing to remote systems
@@ -22,5 +23,7 @@ export interface WriteToolOptions extends ReadBeforeWriteOptions {
     operations?: WriteOperations;
     /** Maximum UTF-8 input bytes accepted before any filesystem mutation (default 8 MiB). */
     maxInputBytes?: number;
+    /** Optional consumer-gated lifecycle listener (file_changed / permission_denied). */
+    onEvent?: (event: CodingLifecycleEvent) => void;
 }
 export declare function createWriteTool(cwd: string, options?: WriteToolOptions): ToolDefinition;

package/dist/write.js

@@ -84,7 +84,7 @@ export function createWriteTool(cwd, options) {
                     paths: [absolutePath],
                     risk: "medium",
                     metadata: { bytes, sessionId: context.sessionId, runId: context.runId, signal: context.signal },
-                }, toolCallId, "write");
+                }, toolCallId, "write", (denied) => options?.onEvent?.({ type: "permission_denied", ...denied }));
                 if (!policyCheck.allowed)
                     return policyCheck.result;
                 const allowedPath = policyCheck.action.paths?.[0] ?? absolutePath;
@@ -101,6 +101,7 @@ export function createWriteTool(cwd, options) {
                     if (context.signal?.aborted)
                         return errorResult(toolCallId, "Operation aborted");
                     await ops.writeFile(allowedPath, content, { maxBytes: maxInputBytes, signal: context.signal });
+                    options?.onEvent?.({ type: "file_changed", path: allowedPath, op: "write", toolCallId });
                     const lines = countLines(content);
                     return {
                         toolCallId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism-coding-agent",
-  "version": "0.0.26",
+  "version": "0.0.27",
   "description": "Optional coding-agent tools (shell, read, write, edit, repo_list, repo_search, glob, delete, move, opt-in Git/check/ask-user-decision, and durable plan/checkpoint helpers) package for Prism.",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,8 +28,8 @@
     "diff": "^9.0.0"
   },
   "peerDependencies": {
-    "@arnilo/prism": "0.0.26",
-    "@arnilo/prism-workflows": "0.0.26"
+    "@arnilo/prism": "0.0.27",
+    "@arnilo/prism-workflows": "0.0.27"
   },
   "devDependencies": {
     "@arnilo/prism": "file:../..",