fuli-context 0.8.0 → 0.8.2

package/src/agent-tools/employee-definitions.js

@@ -3,6 +3,7 @@ import { booleanSchema, objectSchema, stringSchema } from './schema.js';
 const id = { ...stringSchema(), minLength: 1, maxLength: 256 };
 const projectPath = { ...stringSchema(), minLength: 1, maxLength: 4096 };
 const target = { projectPath, templateId: id };
+const workbenchTarget = { ...target, personalProjectId: id };
 
 export const EMPLOYEE_TOOL_DEFINITIONS = [
   {
@@ -29,15 +30,15 @@ export const EMPLOYEE_TOOL_DEFINITIONS = [
   },
   {
     name: 'list_employee_tools', title: 'READ · Employee workbench tools',
-    description: 'Discover the exact input schemas and permissions for a recruited employee in the current project. Read these schemas before calling a tool; a workbench has to be installed first.',
-    inputSchema: objectSchema(target, ['projectPath', 'templateId'])
+    description: 'Discover complete input schemas and permitted tools for a recruited employee. Supply projectPath, or a previously resolved personalProjectId without projectPath when directory resolution is unavailable. If both are supplied they must resolve to the same project. Existing project and employee authorization always apply. Use includeSchemas=false for a compact name list, then toolName to read one exact schema. Oversized contracts fail explicitly, never return partial schemas. Read the schema before calling; a workbench has to be installed first.',
+    inputSchema: objectSchema({ ...workbenchTarget, toolName: id, includeSchemas: booleanSchema() }, ['templateId'])
   },
   {
     name: 'call_employee_tool', title: 'WRITE · Call an employee workbench tool',
-    description: 'Call a discovered employee tool inside the exact assigned project. May read or change data according to the tool schema. Preserve optimistic concurrency and idempotency keys. Does not grant cross-project access, execute an external model, or confirm task completion for the human.',
+    description: 'Call a discovered employee tool inside the exact assigned project. Supply projectPath or a previously resolved personalProjectId; omit projectPath if directory resolution is unavailable. If both are supplied they must resolve to the same project. May read or change data according to the tool schema. Preserve optimistic concurrency and idempotency keys. Does not grant cross-project access, execute an external model, or confirm task completion for the human.',
     inputSchema: objectSchema({
-      ...target, tool: id,
+      ...workbenchTarget, tool: id,
       arguments: { type: 'object', additionalProperties: true }
-    }, ['projectPath', 'templateId', 'tool', 'arguments'])
+    }, ['templateId', 'tool', 'arguments'])
   }
 ];

package/src/agent-tools/graph-definitions.js

@@ -1,3 +1,6 @@
+import { projectRelationDefinitions } from './project-relation-definitions.js';
+import { AGENT_COLLABORATION_DEFINITIONS } from './agent-collaboration-definitions.js';
+import { AGENT_CONVERSATION_DEFINITIONS } from './agent-conversation-definitions.js';
 import {
   arraySchema,
   booleanSchema,
@@ -670,6 +673,10 @@ export const GRAPH_TOOL_DEFINITIONS = [
     description: 'Resolve the exact local project from projectPath and return its lightweight Agent directory. Optionally filter active/inactive/archived records or find Agents whose capabilities or responsibility match a capability query. This never loads another Agent\'s private memory.',
     inputSchema: objectSchema({
       projectPath: boundedString(4096),
+      personalProjectId: {
+        ...nullableStringSchema(), minLength: 1, maxLength: 128,
+        description: 'Explicit existing project ID when the directory has no exact match. A conflicting exact path match is rejected.'
+      },
       status: nullableProjectAgentStatus,
       capability: nullableStringSchema()
     }, ['projectPath'])
@@ -680,6 +687,10 @@ export const GRAPH_TOOL_DEFINITIONS = [
     description: 'Resolve one active project Agent and assemble only the context needed for the task: personal-global rules, exact and authorized inherited project knowledge, this Agent\'s preferences and memory, and focused query results. It excludes every other project Agent. Fuli remains a control layer; the calling host Agent performs reasoning and execution.',
     inputSchema: objectSchema({
       projectPath: boundedString(4096),
+      personalProjectId: {
+        ...nullableStringSchema(), minLength: 1, maxLength: 128,
+        description: 'Explicit existing project ID when the directory has no exact match. A conflicting exact path match is rejected.'
+      },
       agentId: boundedString(128),
       queries: arraySchema(shortText, { minItems: 1, maxItems: 10 }),
       limitPerQuery: integerSchema({ minimum: 1, maximum: 50 }),
@@ -697,6 +708,8 @@ export const GRAPH_TOOL_DEFINITIONS = [
     }, ['personalSpaceId', 'agentId'])
   },
   ...PROJECT_AGENT_MEMORY_DEFINITIONS,
+  ...AGENT_CONVERSATION_DEFINITIONS,
+  ...AGENT_COLLABORATION_DEFINITIONS,
   {
     name: 'delete_project_agent',
     title: 'WRITE · Archive one Agent identity',
@@ -710,7 +723,7 @@ export const GRAPH_TOOL_DEFINITIONS = [
   {
     name: 'cleanup_test_project_agents',
     title: 'WRITE · Archive test Agent roles',
-    description: 'Archive only test-marked Project Agents for one explicit test source through the Provider. Durable production identities are not touched; the result reports the number archived for cleanup verification.',
+    description: 'TEST-ONLY. Archive only test-marked Project Agents for one explicit test source through the Provider. Disabled on default MCP/HTTP surfaces unless FULI_ENABLE_TEST_TOOLS=1. Durable production identities are not touched; the result reports the number archived for cleanup verification.',
     inputSchema: objectSchema({
       personalSpaceId: id,
       testSource: boundedString(256)
@@ -748,7 +761,7 @@ export const GRAPH_TOOL_DEFINITIONS = [
   {
     name: 'coordinate_project_agent_task',
     title: 'WRITE · Prepare a host-executed Agent team',
-    description: 'Resolve the exact local project, let the Provider coordinator route one durable task, and assemble an isolated context bundle for every selected lead/collaborator. Pass the current taskContextToken so a newly recruited lead can claim an initially unassigned task, including its blocked work. The result is a truthful host execution plan: Fuli persists identity, staffing, and memory scope, while the calling host must start real workers, report their concrete worker/executor evidence, and finish their lifecycle. This tool never claims that a selected Agent is online or that a worker was started.',
+    description: 'Resolve the exact local project, let the Provider coordinator route one durable task, and assemble an isolated context bundle for every selected lead/collaborator. Pass the current taskContextToken so a newly recruited lead can claim an initially unassigned task, including its blocked work. When recruiting, HR should set recruitmentProfile.character from the role responsibilities and preserve user expectations; configured traits must never be presented as proven growth. The result is a truthful host execution plan: Fuli persists identity, staffing, and memory scope, while the calling host must start real workers, report their concrete worker/executor evidence, and finish their lifecycle. This tool never claims that a selected Agent is online or that a worker was started.',
     inputSchema: projectAgentTaskCoordinateInput
   },
   {
@@ -776,7 +789,7 @@ export const GRAPH_TOOL_DEFINITIONS = [
   {
     name: 'submit_project_agent_task',
     title: 'WRITE · Submit a routed Agent task',
-    description: 'Submit one durable task to the FULI control plane. Existing matching durable Agents are preferred; no anonymous temporary Agent is created. The Agent locked executor policy outranks task, assignment, project, and space rules; explicit user priority is never lowered for token savings. The space coordinator, complexity, model strategy, routing decision, boundaries, actual executor/model/rule/fallback audit fields, and any HR disclosure are persisted by the Provider.',
+    description: 'Submit one durable task to the FULI control plane. Every new task requires a passed quality gate for its exact artifact revision before completion; use record_agent_verification with actual run evidence. Existing matching durable Agents are preferred; no anonymous temporary Agent is created. The Agent locked executor policy outranks task, assignment, project, and space rules; explicit user priority is never lowered for token savings. The space coordinator, complexity, model strategy, routing decision, boundaries, actual executor/model/rule/fallback audit fields, and any HR disclosure are persisted by the Provider. HR should fill recruitmentProfile.character from role responsibilities, preserve user expectations, and distinguish configured traits from demonstrated growth; never invent past achievements.',
     inputSchema: projectAgentTaskSubmitInput
   },
   {
@@ -793,7 +806,7 @@ export const GRAPH_TOOL_DEFINITIONS = [
   {
     name: 'record_project_agent_task_activity',
     title: 'WRITE · Record task activity',
-    description: 'Record one explicit task event, including real terminal activity, actual executor/model/client attribution, and an optional source-labelled cumulative token snapshot for the concrete worker. Never estimate missing usage. Terminal activity is the only source for per-Agent activity summaries.',
+    description: 'Record real task/worker activity and optional source-labelled cumulative token usage; never estimate. workerStatus requires workerId and agentId. Report actualExecutorId, actualModelProvider and actualModel together only with matching authorized preflight evidence. Otherwise omit all three, report observed workerRuntime and explain the mismatch in summary. A terminal activity with valid actual execution automatically records its routing outcome.',
     inputSchema: projectAgentTaskActivityInput
   },
   {
@@ -1003,7 +1016,7 @@ export const GRAPH_TOOL_DEFINITIONS = [
   {
     name: 'record_project_agent_task_outcome',
     title: 'WRITE · Record explicit routing outcome evidence',
-    description: 'Record only explicit acceptance/satisfaction evidence such as rework_requested, repeated_negative_feedback, explicit_praise, test/acceptance pass or fail, or an explicit rating. Natural-language text is never used to infer satisfaction.',
+    description: 'Record explicit user/test outcome evidence against a matching recorded execution. Use the task workKind and effective modelStrategy plus real referenceIds; a CLI session ID alone is not a recorded run. Terminal routing outcomes are already derived from valid task activity; do not submit them again. Never infer satisfaction or fabricate execution evidence to clear a validation error.',
     inputSchema: projectAgentTaskOutcomeInput
   },
   {
@@ -1194,36 +1207,7 @@ export const GRAPH_TOOL_DEFINITIONS = [
       providerUrl: shortText
     }, ['projectId', 'providerUrl'])
   },
-  {
-    name: 'create_project_relation',
-    description: 'Create a canonical relationship between two public projects. PART_OF waits for target/parent Maintainer confirmation; other relation types become active immediately. This never subscribes either project.',
-    inputSchema: objectSchema({
-      sourceProjectId: id,
-      targetProjectId: id,
-      providerUrl: shortText,
-      relationType: projectRelationType,
-      note: nullableStringSchema()
-    }, ['sourceProjectId', 'targetProjectId', 'providerUrl', 'relationType'])
-  },
-  {
-    name: 'list_project_relations',
-    description: 'List canonical incoming and outgoing project relationships. Related projects are suggestions only and never expand the active subscription set.',
-    inputSchema: objectSchema({
-      projectId: id,
-      providerUrl: shortText
-    }, ['projectId', 'providerUrl'])
-  },
-  {
-    name: 'review_project_relation',
-    description: 'Confirm or reject a pending PART_OF relationship as a Maintainer of the target parent project.',
-    inputSchema: objectSchema({
-      targetProjectId: id,
-      relationId: id,
-      providerUrl: shortText,
-      decision: enumSchema(['confirm', 'reject']),
-      note: nullableStringSchema()
-    }, ['targetProjectId', 'relationId', 'providerUrl', 'decision'])
-  },
+  ...projectRelationDefinitions({ id, shortText, projectRelationType }),
   {
     name: 'list_personal_review_queue',
     description: 'List full structured knowledge drafts waiting in the local personal pre-review queue before any public submission.',

package/src/agent-tools/graph-handlers.js

@@ -1,7 +1,20 @@
 import { ApplicationError } from '../app/application-error.js';
+import { assertTestToolsEnabled } from '../app/test-tools.js';
+import { activeTestToolsEnabled } from '../app/agent-request-context.js';
 import { agentInterfaceCatalog } from './interface-catalog.js';
 
 const HANDLERS = Object.freeze({
+  get_agent_quality_gate: (app, input) => app.agentVerification('query', input),
+  record_agent_verification: (app, input) => app.agentVerification('record', input),
+  plan_agent_collaboration: (app, input) => app.planAgentCollaboration(input),
+  request_agent_loan: (app, input) => app.agentLoan('request', input),
+  decide_agent_loan: (app, input) => app.agentLoan('decide', input),
+  list_agent_loans: (app, input) => app.agentLoan('query', input),
+  list_agent_conversations: (app, input) => app.queryAgentConversations({ ...input, mode: 'list' }),
+  read_agent_conversation: (app, input) => app.queryAgentConversations({ ...input, mode: 'events' }),
+  resume_agent_conversation: (app, input) => app.resumeAgentConversation(input),
+  get_agent_conversation_policy: (app, input) => app.queryAgentConversations({ ...input, mode: 'policy' }),
+  update_agent_conversation_policy: (app, input) => app.updateAgentConversationPolicy(input),
   list_project_agent_tasks: (app, input) => app.listProjectAgentTasks(input),
   request_agent_attention: (app, input) => app.requestAgentAttention(input),
   list_agent_attention: (app, input) => app.listAgentAttention(input),
@@ -107,7 +120,10 @@ const HANDLERS = Object.freeze({
   list_project_agents: (app, input) => app.listCurrentProjectAgents(input),
   get_project_agent: (app, input) => app.getProjectAgent(input),
   delete_project_agent: (app, input) => app.deleteProjectAgent(input),
-  cleanup_test_project_agents: (app, input) => app.cleanupProjectAgentTestRoles(input),
+  cleanup_test_project_agents: (app, input) => {
+    assertTestToolsEnabled({ FULI_ENABLE_TEST_TOOLS: activeTestToolsEnabled() ? '1' : '0' });
+    return app.cleanupProjectAgentTestRoles(input);
+  },
   create_project_agent_assignment: (app, input) =>
     app.createProjectAgentAssignment(input),
   list_project_agent_assignments: (app, input) =>

package/src/agent-tools/interface-catalog.js

@@ -1,4 +1,6 @@
 const UI_MUTATION_PARITY = Object.freeze([
+  agent('POST /api/agent-conversations/query', 'list_agent_conversations', 'read_agent_conversation', 'get_agent_conversation_policy'),
+  agent('PUT /api/agent-conversations/policy', 'update_agent_conversation_policy'),
   agent('POST /api/agent-attention', 'request_agent_attention'),
   agent('POST /api/agent-attention/cancel', 'cancel_agent_attention'),
   local('POST /api/agent-attention/respond', 'Only a local person may respond to an Agent request. A response records a decision, but never executes permissions or task acceptance.'),

package/src/agent-tools/project-agent-definitions.js

@@ -4,6 +4,7 @@ import {
   enumSchema,
   integerSchema,
   nullableStringSchema,
+  numberSchema,
   objectSchema,
   stringSchema
 } from './schema.js';
@@ -54,6 +55,18 @@ export const projectAgentProfile = objectSchema({
   name: boundedString(160),
   displayName: boundedString(160),
   responsibility: boundedString(4096),
+  character: {
+    ...objectSchema({
+      judgment: { type: 'string', maxLength: 2048, default: '' },
+      taste: { type: 'string', maxLength: 2048, default: '' },
+      personality: { type: 'string', maxLength: 2048, default: '' }
+    }),
+    description: 'HR-configured judgment, taste and personality based on role responsibilities. These are intended working traits, not evidence of observed growth or performance.'
+  },
+  expectations: {
+    type: 'string', maxLength: 4096, default: '',
+    description: 'User expectations for this Agent. Preserve the user’s wording and leave empty when none were provided.'
+  },
   occupationEmoji: { ...nullableStringSchema(), minLength: 1, maxLength: 32 },
   agentType: enumSchema(['coordinator', 'durable', 'hr', 'temporary']),
   workKinds: arraySchema(boundedString(512), { maxItems: 32 }),
@@ -156,6 +169,10 @@ export const projectAgentTaskSubmitInput = objectSchema({
 export const projectAgentTaskCoordinateInput = objectSchema({
   taskContextToken: id,
   projectPath: boundedString(4096),
+  personalProjectId: {
+    ...nullableStringSchema(), minLength: 1, maxLength: 128,
+    description: 'Explicit existing project ID when the directory has no exact match. A conflicting exact path match is rejected.'
+  },
   idempotencyKey,
   title: boundedString(160),
   objective: boundedString(4096),
@@ -181,6 +198,7 @@ export const projectAgentTaskCoordinateInput = objectSchema({
   'routingReason', 'contextQueries'
 ]);
 export const projectAgentTaskActivityInput = objectSchema({
+  artifactRevision: { ...stringSchema(), minLength: 1, maxLength: 160 },
   personalSpaceId: id,
   personalProjectId: id,
   taskId: id,
@@ -235,6 +253,8 @@ const executorActualModelStrategySource = enumSchema([
   'task', 'assignment', 'agent', 'routing_rule', 'coordinator'
 ]);
 export const executorModel = objectSchema({
+  capabilityTier: integerSchema({ minimum: 1, maximum: 3 }),
+  costRank: numberSchema({ minimum: 0 }),
   provider: boundedString(128),
   model: boundedString(256),
   capabilities: arraySchema(boundedString(512), { maxItems: 32 }),
@@ -276,6 +296,7 @@ export const executorRoutingRuleInput = objectSchema({
   idempotencyKey
 }, ['scope', 'workKind', 'reason', 'idempotencyKey']);
 export const executorActualReportInput = objectSchema({
+  artifactRevision: { ...stringSchema(), minLength: 1, maxLength: 160 },
   personalSpaceId: id,
   personalProjectId: id,
   taskId: id,

package/src/agent-tools/project-relation-definitions.js

@@ -0,0 +1,36 @@
+import { enumSchema, nullableStringSchema, objectSchema } from './schema.js';
+
+export function projectRelationDefinitions({ id, shortText, projectRelationType }) {
+  return [
+  {
+    name: 'create_project_relation',
+    description: 'Create a canonical relationship between two public projects. PART_OF waits for target/parent Maintainer confirmation; other relation types become active immediately. This never subscribes either project.',
+    inputSchema: objectSchema({
+      sourceProjectId: id,
+      targetProjectId: id,
+      providerUrl: shortText,
+      relationType: projectRelationType,
+      note: nullableStringSchema()
+    }, ['sourceProjectId', 'targetProjectId', 'providerUrl', 'relationType'])
+  },
+  {
+    name: 'list_project_relations',
+    description: 'List canonical incoming and outgoing project relationships. Related projects are suggestions only and never expand the active subscription set.',
+    inputSchema: objectSchema({
+      projectId: id,
+      providerUrl: shortText
+    }, ['projectId', 'providerUrl'])
+  },
+  {
+    name: 'review_project_relation',
+    description: 'Confirm or reject a pending PART_OF relationship as a Maintainer of the target parent project.',
+    inputSchema: objectSchema({
+      targetProjectId: id,
+      relationId: id,
+      providerUrl: shortText,
+      decision: enumSchema(['confirm', 'reject']),
+      note: nullableStringSchema()
+    }, ['targetProjectId', 'relationId', 'providerUrl', 'decision'])
+  },
+  ];
+}

package/src/agents/claude-code/conversation-transcript.js

@@ -0,0 +1,20 @@
+// Claude JSONL v1; thinking/redacted_thinking are intentionally never persisted.
+export function normalizeClaudeRecord(record, sessionId) {
+  if (record?.sessionId !== sessionId || !['user', 'assistant'].includes(record.type)) return [];
+  const content = record.message?.content;
+  if (typeof content === 'string') return content ? [{ role: record.type, kind: 'message', content }] : [];
+  if (!Array.isArray(content)) return [];
+  return content.flatMap(block => {
+    if (block.type === 'text' && block.text) return [{ role: record.type, kind: 'message', content: block.text }];
+    if (block.type === 'tool_use') return [{ role: 'assistant', kind: 'tool_call', content: JSON.stringify({
+      call_id: block.id, name: block.name, input: block.input
+    }) }];
+    if (block.type === 'tool_result') return [{ role: 'tool', kind: 'tool_result', content: JSON.stringify({
+      call_id: block.tool_use_id, output: block.content, is_error: block.is_error ?? false
+    }) }];
+    return [];
+  });
+}
+export function verifyClaudeTranscript(firstRecord, sessionId) {
+  return firstRecord?.sessionId === sessionId;
+}

package/src/agents/claude-code/lifecycle-hook.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+import { withTranscriptGuard } from '../../conversations/transcript-guard.js';
+import { compactTaskContext } from '../../conversations/task-context-view.js';
+import { syncConversationTranscript, withTranscriptNotice, claimTranscriptBoundary, recordTranscriptTaskEntry } from '../../conversations/sync-transcript.js';
+import { normalizeClaudeRecord, verifyClaudeTranscript } from './conversation-transcript.js';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { callAgentTool } from '../../agent-tools.js';
+import { createRuntimeLeaseClient } from '../../adaptive-runtime/lease-client.js';
+import { openFederatedGraphApplication } from '../../graphiti/federated-application.js';
+import { resolveGraphRuntimeOptions } from '../../graphiti/runtime-config.js';
+import { hookAdditionalContextToolResult } from '../../mcp/tool-result.js';
+import { boundedHookMessage } from '../lifecycle-message.js';
+
+export async function claudeLifecycleOutput(event, input, invoke) {
+  if (!['UserPromptSubmit', 'Stop'].includes(event)) throw new TypeError('Unsupported Claude lifecycle event');
+  const sessionId = input?.session_id;
+  if (typeof sessionId !== 'string' || !sessionId.trim() || sessionId.length > 256) {
+    throw new TypeError('Claude lifecycle requires a host session identifier');
+  }
+  const source = { sourceApplication: 'claude_code', sourceSessionId: sessionId };
+  if (event === 'UserPromptSubmit') {
+    if (typeof input.cwd !== 'string' || !input.cwd.trim() || typeof input.prompt !== 'string') {
+      throw new TypeError('Claude task entry requires cwd and prompt');
+    }
+    const context = await invoke('begin_task_context', {
+      sessionId, projectPath: input.cwd, taskPrompt: input.prompt.slice(0, 8192), ...source
+    });
+    return JSON.parse(hookAdditionalContextToolResult(compactTaskContext(context), {
+      hookEventName: event,
+      label: 'Fuli task context. Apply effective_preferences and use taskContextToken for the final checkpoint.',
+      limitBytes: 128 * 1024,
+      itemLimit: 1000
+    }).content[0].text);
+  }
+  const check = await invoke('verify_task_checkpoint', { sessionId, ...source });
+  const reason = boundedHookMessage(check?.reason);
+  if (check?.decision !== 'block' || !reason.trim()) return {};
+  if (input.stop_hook_active === true) {
+    if (typeof check.task_context_token === 'string' && check.task_context_token.trim()) {
+      await invoke('checkpoint_task_knowledge', {
+        taskContextToken: check.task_context_token,
+        disposition: 'retain_nothing',
+        reason: 'Claude Code Stop hook fallback after one checkpoint continuation.',
+        workLog: { status: 'incomplete', summary: 'The host stopped before the employee submitted a work summary. Review the prior task before resuming.' },
+        ...source
+      });
+    }
+    return {};
+  }
+  return { decision: 'block', reason };
+}
+
+export function claudeLifecycleUnavailable(event) {
+  const warning = 'Fuli context is unavailable; memory recovery and task checkpoint are not verified. '
+    + 'Continue with the user request and use Fuli MCP when it becomes available.';
+  return event === 'UserPromptSubmit'
+    ? { systemMessage: warning, hookSpecificOutput: { hookEventName: event, additionalContext: warning } }
+    : { systemMessage: warning };
+}
+
+export async function runClaudeLifecycleHook(args, dependencies = {}) {
+  const event = args[args.indexOf('--event') + 1];
+  const input = await (dependencies.readInput ?? readHookInput)();
+  if (dependencies.invoke) return claudeLifecycleOutput(event, input, dependencies.invoke);
+  const { runtimeConfigPath } = (dependencies.resolveRuntimeOptions ?? resolveGraphRuntimeOptions)(
+    args, dependencies.env ?? process.env
+  );
+  let app;
+  let leases;
+  try {
+    app = (dependencies.openApplication ?? openFederatedGraphApplication)({ runtimeConfigPath });
+    leases = (dependencies.createLeases ?? createRuntimeLeaseClient)({ runtimeConfigPath });
+    const request = { signal: dependencies.signal };
+    return await leases.withGraphLease('claude-code-lifecycle', async () => {
+      try {
+        if (app.getCapturePolicy?.().enabled && input.transcript_path) dependencies.onTranscriptGuard?.();
+        return await withTranscriptGuard(runtimeConfigPath, input, 'claude_code', app.getCapturePolicy?.().enabled, async guard => {
+          let sync = await syncConversationTranscript(app, input, 'claude_code', {
+            normalize: normalizeClaudeRecord, verify: verifyClaudeTranscript
+          }, guard);
+          if (event === 'UserPromptSubmit' && sync.entryBlocked) return { decision: 'block', reason: sync.reason };
+          const entryGuard = sync.status === 'capture_disabled' ? null : guard;
+          if (event === 'UserPromptSubmit' && entryGuard?.value) await entryGuard.write({ ...entryGuard.value, phase: 'beginning' });
+          const output = await claudeLifecycleOutput(event, input, async (name, parameters) => {
+            const context = await (dependencies.callTool ?? callAgentTool)(app, name, parameters, request);
+            if (name === 'begin_task_context') await recordTranscriptTaskEntry(entryGuard, context);
+            return context;
+          });
+          if (event === 'UserPromptSubmit') sync = await claimTranscriptBoundary(app, input, 'claude_code', sync, {
+            normalize: normalizeClaudeRecord, verify: verifyClaudeTranscript
+          }, entryGuard);
+          if (event === 'UserPromptSubmit' && sync.entryBlocked) return { decision: 'block', reason: sync.reason };
+          return withTranscriptNotice(output, sync);
+        });
+      } catch (error) {
+        if (event !== 'UserPromptSubmit' || !app.getCapturePolicy?.().enabled || !input.transcript_path) throw error;
+        return { decision: 'block', reason: error.code === 'EADDRINUSE'
+          ? 'The session handoff lock is occupied. Retry after the current hook finishes; if it persists, start a new host session and resume the intended Agent.'
+          : 'Fuli transcript handoff could not be completed safely. Retry task entry; no previous Agent context was supplied.' };
+      }
+    }, request);
+  } finally {
+    await Promise.allSettled([close(leases), close(app)]);
+  }
+}
+
+async function close(resource) { await resource?.close(); }
+
+async function readHookInput() {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of process.stdin) {
+    size += chunk.length;
+    if (size > 256 * 1024) throw new TypeError('Hook input exceeds limit');
+    chunks.push(chunk);
+  }
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const event = args[args.indexOf('--event') + 1];
+  const configured = args.includes('--timeout-ms') ? Number(args[args.indexOf('--timeout-ms') + 1]) : 28000;
+  const timeoutMs = Number.isSafeInteger(configured) && configured > 0 && configured <= 2_147_483_647
+    ? configured : 28000;
+  const controller = new AbortController();
+  let emitted = false;
+  let guarded = false;
+  const emit = (output, callback) => {
+    if (emitted) return;
+    emitted = true;
+    process.stdout.write(`${JSON.stringify(output)}\n`, callback);
+  };
+  // Finish before the host timeout, even if a dependency ignores cancellation.
+  // No prompt, transcript, path or raw exception is written to diagnostics.
+  const deadline = setTimeout(() => {
+    controller.abort();
+    emit(guarded && event === 'UserPromptSubmit' ? { decision: 'block', reason: 'Fuli transcript handoff timed out. Retry task entry; the previous Agent context was not supplied.' } : claudeLifecycleUnavailable(event), () => process.exit(0));
+  }, timeoutMs);
+  const abort = setTimeout(() => controller.abort(), Math.max(1, timeoutMs - 1500));
+  try {
+    const output = await runClaudeLifecycleHook(args, { signal: controller.signal, onTranscriptGuard: () => { guarded = true; } });
+    emit(output);
+  } catch {
+    emit(claudeLifecycleUnavailable(event));
+  } finally {
+    clearTimeout(abort);
+    clearTimeout(deadline);
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) await main();

package/src/agents/claude-code/lifecycle-hooks.js

@@ -0,0 +1,20 @@
+import { dirname, join } from 'node:path';
+import { quoteShellArgument } from '../../cli/shell-argument.js';
+
+export const CLAUDE_LIFECYCLE_MARKER = '--fuli-claude-lifecycle';
+
+export function claudeLifecycleCommand(context, event, timeoutSec) {
+  const script = context.claudeLifecycleHookPath ??
+    join(dirname(context.mcpServerPath), 'agents', 'claude-code', 'lifecycle-hook.js');
+  return [
+    context.nodePath, script, CLAUDE_LIFECYCLE_MARKER,
+    '--runtime-config', context.runtimeConfigPath, '--event', event,
+    '--timeout-ms', String(Math.max(100, timeoutSec * 1000 - 2000))
+  ].map(value => quoteShellArgument(value, context.platform)).join(' ');
+}
+
+export function isClaudeLifecycleCommand(hook) {
+  return hook?.type === 'command' && typeof hook.command === 'string' &&
+    hook.command.includes(CLAUDE_LIFECYCLE_MARKER) &&
+    hook.command.includes('lifecycle-hook.js');
+}

package/src/agents/codex/conversation-transcript.js

@@ -0,0 +1,22 @@
+// Codex rollout v1: visible response items only; event_msg mirrors are omitted.
+export function normalizeCodexRecord(record) {
+  if (record?.type !== 'response_item') return [];
+  const item = record.payload;
+  if (item?.type === 'message' && ['user', 'assistant'].includes(item.role)) {
+    const content = (item.content ?? []).filter(block => ['input_text', 'output_text'].includes(block.type))
+      .map(block => block.text ?? '').join('\n');
+    return content ? [{ role: item.role, kind: 'message', content }] : [];
+  }
+  if (['function_call', 'custom_tool_call'].includes(item?.type)) {
+    return [{ role: 'assistant', kind: 'tool_call', content: JSON.stringify({
+      call_id: item.call_id, name: item.name, arguments: item.arguments ?? item.input
+    }) }];
+  }
+  if (['function_call_output', 'custom_tool_call_output'].includes(item?.type)) {
+    return [{ role: 'tool', kind: 'tool_result', content: JSON.stringify({ call_id: item.call_id, output: item.output }) }];
+  }
+  return [];
+}
+export function verifyCodexTranscript(firstRecord, sessionId) {
+  return firstRecord?.type === 'session_meta' && firstRecord.payload?.id === sessionId;
+}

package/src/agents/codex/lifecycle-hook.js

@@ -1,4 +1,9 @@
 #!/usr/bin/env node
+import { withTranscriptGuard } from '../../conversations/transcript-guard.js';
+import { compactTaskContext } from '../../conversations/task-context-view.js';
+import { syncConversationTranscript, withTranscriptNotice, claimTranscriptBoundary, recordTranscriptTaskEntry } from '../../conversations/sync-transcript.js';
+import { normalizeCodexRecord, verifyCodexTranscript } from './conversation-transcript.js';
+import { hookAdditionalContextToolResult } from '../../mcp/tool-result.js';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -37,13 +42,26 @@ export async function codexStopLifecycleOutput(input, invoke) {
   return { decision: 'block', reason: boundedHookMessage(check.reason) };
 }
 
+export async function codexLifecycleOutput(event, input, invoke) {
+  if (event === 'Stop') return codexStopLifecycleOutput(input, invoke);
+  if (!input?.session_id || typeof input.cwd !== 'string' || typeof input.prompt !== 'string') {
+    throw new TypeError('Codex task entry requires session, cwd and prompt');
+  }
+  const context = await invoke('begin_task_context', { sessionId: input.session_id,
+    turnId: input.turn_id ?? null, projectPath: input.cwd, taskPrompt: input.prompt.slice(0, 8192),
+    sourceApplication: 'codex', sourceSessionId: input.session_id });
+  return JSON.parse(hookAdditionalContextToolResult(compactTaskContext(context), { hookEventName: event,
+    label: 'Fuli task context. Apply effective_preferences and checkpoint with taskContextToken.',
+    limitBytes: 128 * 1024, itemLimit: 1000 }).content[0].text);
+}
+
 export async function runCodexLifecycleHook(args, dependencies = {}) {
   const event = args[args.indexOf('--event') + 1];
-  if (event !== 'Stop') throw new TypeError('Missing Codex lifecycle event');
+  if (!['Stop', 'UserPromptSubmit'].includes(event)) throw new TypeError('Missing Codex lifecycle event');
   const input = await (dependencies.readInput ?? readHookInput)();
   const write = dependencies.write ?? ((value) => process.stdout.write(value));
   if (dependencies.invoke) {
-    const output = await codexStopLifecycleOutput(input, dependencies.invoke);
+    const output = await codexLifecycleOutput(event, input, dependencies.invoke);
     write(`${JSON.stringify(output)}\n`);
     return output;
   }
@@ -63,12 +81,33 @@ export async function runCodexLifecycleHook(args, dependencies = {}) {
       runtimeConfigPath
     });
     const invokeTool = dependencies.callTool ?? callAgentTool;
-    const output = await leases.withGraphLease('codex-lifecycle', () =>
-      codexStopLifecycleOutput(
-        input,
-        (name, parameters) => invokeTool(app, name, parameters)
-      )
-    );
+    const output = await leases.withGraphLease('codex-lifecycle', async () => {
+      try {
+        return await withTranscriptGuard(runtimeConfigPath, input, 'codex', app.getCapturePolicy?.().enabled, async guard => {
+          let sync = await syncConversationTranscript(app, input, 'codex', {
+            normalize: normalizeCodexRecord, verify: verifyCodexTranscript
+          }, guard);
+          if (event === 'UserPromptSubmit' && sync.entryBlocked) return { decision: 'block', reason: sync.reason };
+          const entryGuard = sync.status === 'capture_disabled' ? null : guard;
+          if (event === 'UserPromptSubmit' && entryGuard?.value) await entryGuard.write({ ...entryGuard.value, phase: 'beginning' });
+          const result = await codexLifecycleOutput(event, input, async (name, parameters) => {
+            const context = await invokeTool(app, name, parameters);
+            if (name === 'begin_task_context') await recordTranscriptTaskEntry(entryGuard, context);
+            return context;
+          });
+          if (event === 'UserPromptSubmit') sync = await claimTranscriptBoundary(app, input, 'codex', sync, {
+            normalize: normalizeCodexRecord, verify: verifyCodexTranscript
+          }, entryGuard);
+          if (event === 'UserPromptSubmit' && sync.entryBlocked) return { decision: 'block', reason: sync.reason };
+          return withTranscriptNotice(result, sync);
+        });
+      } catch (error) {
+        if (event !== 'UserPromptSubmit' || !app.getCapturePolicy?.().enabled || !input.transcript_path) throw error;
+        return { decision: 'block', reason: error.code === 'EADDRINUSE'
+          ? 'The session handoff lock is occupied. Retry after the current hook finishes; if it persists, start a new host session and resume the intended Agent.'
+          : 'Fuli transcript handoff could not be completed safely. Retry task entry; no previous Agent context was supplied.' };
+      }
+    });
     write(`${JSON.stringify(output)}\n`);
     return output;
   } finally {

package/src/agents/codex/lifecycle-hooks.js

@@ -18,8 +18,8 @@ export function withCodexLifecycleHooks(current, { timeout = 30, context = null
     }],
     ['Stop', 'verify_task_checkpoint', { sessionId: '${session_id}' }]
   ]) {
-    const handler = event === 'Stop' && context
-      ? { type: 'command', command: codexStopCommand(context), timeout }
+    const handler = context
+      ? { type: 'command', command: codexStopCommand(context, event), timeout }
       : { type: 'mcp_tool', server: 'fuli', tool, input, timeout };
     hooks[event] = [...(hooks[event] ?? []), { hooks: [handler] }];
   }
@@ -88,12 +88,12 @@ export function withCodexTomlLifecycleHooks(source, { timeout = 30, context = nu
   const lines = clean.replaceAll('\r\n', '\n').split('\n');
   while (lines.length && !lines.at(-1).trim()) lines.pop();
   const blocks = [
-    ...codexTomlHookBlock('UserPromptSubmit', 'begin_task_context', {
+    ...(context ? codexTomlCommandHookBlock('UserPromptSubmit', codexStopCommand(context, 'UserPromptSubmit'), timeout) : codexTomlHookBlock('UserPromptSubmit', 'begin_task_context', {
       sessionId: '${session_id}',
       turnId: '${turn_id}',
       projectPath: '${cwd}',
       taskPrompt: '${prompt}'
-    }, timeout),
+    }, timeout)),
     ...(context
       ? codexTomlCommandHookBlock('Stop', codexStopCommand(context), timeout)
       : codexTomlHookBlock('Stop', 'verify_task_checkpoint', {
@@ -212,7 +212,7 @@ function isManagedCodexHook(hook) {
       hook.command.includes(COMMAND_MARKER) && hook.command.includes('lifecycle-hook.js');
 }
 
-function codexStopCommand(context) {
+function codexStopCommand(context, event = 'Stop') {
   const script = context.codexLifecycleHookPath ??
     join(dirname(context.mcpServerPath), 'agents', 'codex', 'lifecycle-hook.js');
   return [
@@ -222,7 +222,7 @@ function codexStopCommand(context) {
     '--runtime-config',
     context.runtimeConfigPath,
     '--event',
-    'Stop'
+    event
   ].map(value => quoteShellArgument(value, context.platform)).join(' ');
 }