praxis-agent 0.60.1 → 0.61.0

package/README.md

@@ -215,8 +215,10 @@ troubleshooting. Run `praxis --help` for the authoritative command surface.
   tool, memory, first-turn, and resume behavior. Agent execution uses one
   durable lifecycle vocabulary with bounded cancellation and drain,
   continuation, notifications, and single-owner orphan recovery. Isolated
-  Workflow turns use ownership-recorded repo-local temporary worktrees and
-  retain dirty or committed results for inspection. Experimental
+  Workflow turns use ownership-recorded repo-local temporary worktrees, run
+  trust-admitted synchronous lifecycle hooks, safely roll back blocked
+  creation, and retain dirty, committed, unsafe, or removal-blocked results
+  for inspection. Experimental
   local Teams (`PRAXIS_ENABLE_TEAMS=true`) stay absent from ordinary startup by
   default and add durable task ownership plus one ordered mailbox with stable
   identities, fixed broadcast recipients, durable cursors, bounded retention,

package/dist/application/managed-worktree.d.ts

@@ -6,6 +6,23 @@ export interface ManagedWorktree {
     cwd: string;
     cleanup(): Promise<ManagedWorktreeCleanup>;
 }
+export interface ManagedWorktreeHookInput {
+    readonly worktreePath: string;
+    readonly worktreeKind: 'workflow' | 'agent' | 'team';
+    readonly worktreeId: string;
+    readonly ownerId: string;
+    readonly baseCommit: string;
+}
+export interface ManagedWorktreeRemoveHookInput extends ManagedWorktreeHookInput {
+    readonly reason: 'normal' | 'reconcile';
+}
+export interface ManagedWorktreeHookOutcome {
+    blockedReason?: string;
+}
+export interface ManagedWorktreeHooks {
+    afterCreate(input: ManagedWorktreeHookInput): Promise<ManagedWorktreeHookOutcome>;
+    beforeRemove(input: ManagedWorktreeRemoveHookInput): Promise<ManagedWorktreeHookOutcome>;
+}
 export interface OwnedManagedWorktreeOptions {
     cwd: string;
     stateRoot: string;
@@ -14,6 +31,7 @@ export interface OwnedManagedWorktreeOptions {
     label: 'Agent' | 'Workflow' | 'Team';
     kind: 'workflow' | 'agent' | 'team';
     policy: 'ephemeral' | 'durable';
+    hooks?: ManagedWorktreeHooks;
 }
 export declare function createOwnedManagedWorktree(options: OwnedManagedWorktreeOptions): Promise<ManagedWorktree>;
 export declare function createManagedWorktree(options: {

package/dist/application/managed-worktree.js

@@ -360,6 +360,24 @@ export async function createOwnedManagedWorktree(options) {
         gitCreated = true;
         await writeMarker(worktreePath, record);
         markerCreated = true;
+        if (options.hooks) {
+            let outcome;
+            try {
+                outcome = await options.hooks.afterCreate({
+                    worktreePath,
+                    worktreeKind: record.kind,
+                    worktreeId: record.worktreeId,
+                    ownerId: record.ownerId,
+                    baseCommit: record.baseCommit,
+                });
+            }
+            catch (error) {
+                throw new Error(`WorktreeCreate hook failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+            }
+            if (outcome.blockedReason) {
+                throw new Error(`WorktreeCreate hook blocked: ${outcome.blockedReason}`);
+            }
+        }
         await store.update(nextRecord(record, 'active'));
         created = true;
     }
@@ -537,6 +555,38 @@ async function cleanupOwnedManagedWorktree(store, options, original, heldLease)
             const reason = `${options.label} worktree has commits and was retained at ${record.worktreePath}`;
             return retain(store, releasing, reason);
         }
+        if (options.hooks) {
+            let outcome;
+            try {
+                outcome = await options.hooks.beforeRemove({
+                    worktreePath: record.worktreePath,
+                    worktreeKind: record.kind,
+                    worktreeId: record.worktreeId,
+                    ownerId: record.ownerId,
+                    baseCommit: record.baseCommit,
+                    reason: 'normal',
+                });
+            }
+            catch (error) {
+                return retain(store, releasing, `WorktreeRemove hook failed for ${record.worktreePath}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (outcome.blockedReason) {
+                return retain(store, releasing, `WorktreeRemove hook blocked for ${record.worktreePath}: ${outcome.blockedReason}`);
+            }
+            try {
+                const postHookRegistered = await registeredWorktrees(record.repositoryRoot);
+                const postHookInspection = await inspectOwnedCheckout(record, postHookRegistered);
+                if (postHookInspection.status.length > 0) {
+                    return retain(store, releasing, `WorktreeRemove hook left uncommitted changes in ${record.worktreePath}; worktree was retained at ${record.worktreePath}`);
+                }
+                if (postHookInspection.head !== record.baseCommit) {
+                    return retain(store, releasing, `WorktreeRemove hook created commits in ${record.worktreePath}; worktree was retained at ${record.worktreePath}`);
+                }
+            }
+            catch (error) {
+                return retain(store, releasing, `WorktreeRemove hook left worktree unsafe at ${record.worktreePath}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
         try {
             await git(record.repositoryRoot, [
                 'worktree',

package/dist/application/subagent-service.js

@@ -1393,6 +1393,17 @@ export class ClaudeSubagentExecutor {
                 praxisRoot: sessionPaths.praxisRoot,
                 runId: options.runId,
                 agentId: options.agentId,
+                ...(this.options.hooks
+                    ? {
+                        hookContext: {
+                            runner: this.options.hooks,
+                            sessionId: options.sessionId,
+                            transcriptPath: paths.transcriptFile,
+                            permissionMode: 'default',
+                            ...(options.signal ? { signal: options.signal } : {}),
+                        },
+                    }
+                    : {}),
             })
             : null;
         const agentCwd = isolation?.cwd ?? this.cwd();

package/dist/application/workflow-worktree.d.ts

@@ -1,9 +1,18 @@
 import { type ManagedWorktree } from './managed-worktree.js';
+import type { ClaudeHookRunner } from '../hooks/claude-hooks.js';
 export type WorkflowWorktree = ManagedWorktree;
+export interface WorkflowWorktreeHookContext {
+    runner: ClaudeHookRunner;
+    sessionId: string;
+    transcriptPath: string;
+    permissionMode: string;
+    signal?: AbortSignal;
+}
 export declare function createWorkflowWorktree(options: {
     cwd: string;
     praxisRoot: string;
     runId: string;
     agentId: string;
+    hookContext?: WorkflowWorktreeHookContext;
 }): Promise<WorkflowWorktree>;
 //# sourceMappingURL=workflow-worktree.d.ts.map

package/dist/application/workflow-worktree.js

@@ -1,4 +1,26 @@
 import { createOwnedManagedWorktree, } from './managed-worktree.js';
+function lifecycleHookInput(input, context, event) {
+    const reason = 'reason' in input ? input.reason : undefined;
+    return {
+        session_id: context.sessionId,
+        transcript_path: context.transcriptPath,
+        cwd: input.worktreePath,
+        permission_mode: context.permissionMode,
+        hook_event_name: event,
+        worktree_path: input.worktreePath,
+        worktree_kind: input.worktreeKind,
+        worktree_id: input.worktreeId,
+        owner_id: input.ownerId,
+        base_commit: input.baseCommit,
+        ...(event === 'WorktreeRemove' && reason !== undefined ? { reason } : {}),
+    };
+}
+function lifecycleHooks(context) {
+    return {
+        afterCreate: async (input) => context.runner.run(lifecycleHookInput(input, context, 'WorktreeCreate'), input.worktreeKind, context.signal),
+        beforeRemove: async (input) => context.runner.run(lifecycleHookInput(input, context, 'WorktreeRemove'), input.worktreeKind, context.signal),
+    };
+}
 export async function createWorkflowWorktree(options) {
     return createOwnedManagedWorktree({
         cwd: options.cwd,
@@ -8,6 +30,9 @@ export async function createWorkflowWorktree(options) {
         label: 'Workflow',
         kind: 'workflow',
         policy: 'ephemeral',
+        ...(options.hookContext
+            ? { hooks: lifecycleHooks(options.hookContext) }
+            : {}),
     });
 }
 //# sourceMappingURL=workflow-worktree.js.map

package/dist/hooks/claude-hooks.js

@@ -28,7 +28,14 @@ export const HOOK_EVENTS = [
     'FileChanged',
     'SessionEnd',
 ];
-const EXECUTABLE_HOOK_EVENTS = new Set(HOOK_EVENTS);
+const LIFECYCLE_HOOK_EVENTS = [
+    'WorktreeCreate',
+    'WorktreeRemove',
+];
+const EXECUTABLE_HOOK_EVENTS = new Set([
+    ...HOOK_EVENTS,
+    ...LIFECYCLE_HOOK_EVENTS,
+]);
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -91,6 +98,9 @@ function eventSettings(settings, event, maxTimeoutMs) {
                 if (hook.async !== undefined && typeof hook.async !== 'boolean') {
                     throw new Error(`Invalid Claude ${event} hook async: ${resource.path}`);
                 }
+                if (LIFECYCLE_HOOK_EVENTS.includes(event) && hook.async === true) {
+                    throw new Error(`Invalid Claude ${event} hook async: ${resource.path}`);
+                }
                 return [
                     {
                         command,
@@ -145,8 +155,9 @@ export function validateClaudeHooks(settings, maxTimeoutMs = DEFAULT_TIMEOUT_MS)
         !Number.isInteger(maxTimeoutMs)) {
         throw new Error('Hook max timeout must be a positive integer');
     }
-    for (const event of HOOK_EVENTS)
+    for (const event of [...HOOK_EVENTS, ...LIFECYCLE_HOOK_EVENTS]) {
         eventSettings(settings, event, maxTimeoutMs);
+    }
 }
 function outputRecord(stdout) {
     const trimmed = stdout.trim();
@@ -204,6 +215,9 @@ function hookMatcherValue(input) {
             return basename(optionalString(input.file_path) ?? '');
         case 'SessionEnd':
             return optionalString(input.reason) ?? '';
+        case 'WorktreeCreate':
+        case 'WorktreeRemove':
+            return optionalString(input.worktree_kind) ?? '';
         default:
             return '';
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis-agent",
-  "version": "0.60.1",
+  "version": "0.61.0",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",