@givolt/i3-composer-agent 2.3.4 → 2.3.6

package/skills/i3-ui-prototype/scripts/codebuddy-hook.cjs

@@ -4,13 +4,14 @@ const F=require('./native-files.cjs'),C=require('./codebuddy-context.cjs'),E=req
 const X=require('./execution-runtime.cjs');
 const H=require('./buddy-host.cjs');
 const Recovery=require('./execution-recovery.cjs');
-const {tokens,nativeCommand,stageFor}=require('./native-command.cjs');
+const {tokens,nativeCommand,stageFor,completedBegin}=require('./native-command.cjs');
+const {toolName}=require('./native-tool-name.cjs');
 function eventCall(payload,source) {
  const callId=payload.tool_use_id||payload.call_id;
  const canonical=value=>Array.isArray(value)?value.map(canonical):value&&typeof value==='object'?Object.fromEntries(Object.keys(value).sort().map(k=>[k,canonical(value[k])])):value;
  const partial=(before,after)=>typeof before==='string'?typeof after==='string'&&after.startsWith(before):Array.isArray(before)?Array.isArray(after)&&before.length<=after.length&&before.every((value,i)=>partial(value,after[i])):before&&typeof before==='object'?after&&typeof after==='object'&&Object.keys(before).every(key=>Object.hasOwn(after,key)&&partial(before[key],after[key])):before===after;
  const matches=source.calls.filter(call=>{
-  if(call.name!==payload.tool_name||call.requestLine<source.prompts.at(-1).line||callId&&call.toolCallId!==callId)return false;
+  if(call.name!==toolName(payload.tool_name)||call.requestLine<source.prompts.at(-1).line||callId&&call.toolCallId!==callId)return false;
   if(source.format==='codebuddy-ide-index-v1'&&payload.generation_id&&call.nativeRequestId!==payload.generation_id)return false;
   if(JSON.stringify(canonical(call.input))===JSON.stringify(canonical(payload.tool_input||{})))return true;
   // IDE 4.12 streams incomplete args to disk before PreToolUse. Correlate its
@@ -18,7 +19,11 @@ function eventCall(payload,source) {
   // pending call remains unsuccessful until a native result is persisted.
   return source.format==='codebuddy-ide-index-v1'&&H.isIDE(payload)&&typeof payload.generation_id==='string'&&call.nativeRequestId===payload.generation_id&&!call.resultLine&&partial(call.input,payload.tool_input||{});
  });
- const current=payload.hook_event_name==='PreToolUse'?matches.filter(call=>!call.resultLine):matches;
+ // IDE can omit the call ID and invoke Post before persisting the result.
+ // A failed earlier attempt can have identical args; only the still-pending
+ // request in this exact generation can be the current callback.
+ const pending=matches.filter(call=>!call.resultLine);
+ const current=payload.hook_event_name==='PreToolUse'||source.format==='codebuddy-ide-index-v1'&&pending.length?pending:matches;
  assert.equal(current.length,1,'Native Hook event does not uniquely match the current transcript request');return current[0];
 }
 function eventSource(payload,record,project,{readSource=C.source,pause=milliseconds=>Atomics.wait(new Int32Array(new SharedArrayBuffer(4)),0,0,milliseconds)}={}) {
@@ -26,16 +31,19 @@ function eventSource(payload,record,project,{readSource=C.source,pause=milliseco
  // IDE can persist the current call only AFTER returning from both Hooks. Its
  // current native prompt/generation still binds the callback. Never synthesize
  // a successful call; A checks the persisted request/result at a later stage.
- const attempts=toolEvent&&record.product==='ide'&&H.isIDE(payload)?8:1;
+ const attempts=toolEvent?8:1;
  for(let attempt=1;attempt<=attempts;attempt++) {
   try {
-   const source=readSource(payload,record,project);
+   let source=readSource(payload,record,project);
+   if(toolEvent&&record.product==='cli'&&(payload.agent_type==='ptc'||source.calls.some(c=>c.name==='REPL'&&!c.resultLine))){
+    source=require('./ptc-callbacks.cjs').observe({payload,record,project,source});
+   }
    let nativeRequestStatus='not-tool-event';
    if(toolEvent) {
     if(source.format==='codebuddy-ide-index-v1'&&record.product==='ide'&&H.isIDE(payload)) {
      const latest=source.prompts.at(-1);
      assert.ok(typeof payload.generation_id==='string'&&latest?.nativeRequestId===payload.generation_id,'IDE callback differs from the current native task generation');
-     const pending=source.calls.filter(call=>!call.resultLine&&call.requestLine>latest.line&&call.nativeRequestId===payload.generation_id&&call.name===payload.tool_name);
+     const pending=source.calls.filter(call=>!call.resultLine&&call.requestLine>latest.line&&call.nativeRequestId===payload.generation_id&&call.name===toolName(payload.tool_name));
      if(pending.length) {eventCall(payload,source);nativeRequestStatus='pending-native-request';}
      else nativeRequestStatus='deferred-until-native-persistence';
     }else {eventCall(payload,source);nativeRequestStatus='matched-native-request';}
@@ -48,26 +56,26 @@ function decision({event,source,binding,tool,input,directory,cwd,deliveryCurrent
  if(C.readOnly(source.prompts.at(-1)?.text||''))return {continue:true,reason:'latest-user-read-only'};
  if(event==='PreToolUse'&&G.uiWrite({name:tool,input:input||{},cwd},directory)) {
   const missing=Recovery.missing({source,binding,policy});
-  if(missing.length)return {deny:true,missing,reason:'原型 UI 写入已被阻止。'+Recovery.instruction(missing)};
+  if(missing.length)return {deny:true,missing,reason:'原型 UI 写入已被阻止。'+Recovery.instruction(missing,{directory,automatic:binding?.association==='automatic'})};
  }
  const final=source.latestAssistant||'',claim=/(?:已完成|已经完成|全部通过|可以交付|\b(?:completed|ready for review|all checks passed)\b)/i.test(final)&&!/(?:未完成|尚未|待验证|阻塞|等待|进度|blocked|awaiting|not complete|in progress)/i.test(final);
  const blocked=/(?:\bblocked\b|无法继续|当前阻塞|等待用户|等待授权)/i.test(final);
  if(event==='Stop'&&binding&&!deliveryCurrent&&!blocked&&(policy?.id===P.AUTO_ID||!stopHookActive)&&claim){
   const missing=Recovery.missing({source,binding,policy,stage:'delivery'});if(!missing.length)missing.push('execution-evidence');
-  return {feedback:true,missing,reason:'当前原型没有有效交付回执。'+Recovery.instruction(missing)};
+  return {feedback:true,missing,reason:'当前原型没有有效交付回执。'+Recovery.instruction(missing,{directory,automatic:binding?.association==='automatic'})};
  }
  return {continue:true};
 }
-function prototypeForWrite(project,tool,input) {
+function prototypeForWrite(project,tool,input,cwd=project) {
  if(!['Write','Edit','MultiEdit','write_to_file','replace_in_file'].includes(tool))return null;
  const file=input?.file_path||input?.filePath||input?.path||input?.TargetFile;if(typeof file!=='string')return null;
- let current=path.dirname(path.resolve(project,file));const prototypes=path.join(project,'prototypes');
+ let current=path.dirname(path.resolve(cwd,file));const prototypes=path.join(project,'prototypes');
  while(current.startsWith(prototypes+path.sep)){if(fs.existsSync(path.join(current,'prototype.json')))return fs.realpathSync(current);current=path.dirname(current);}return null;
 }
 function safeProject(payload,options={},env=process.env,real=file=>fs.realpathSync(file),callbackCwd=process.cwd(),workspace=E.ideWorkspace) {
  const ideRoot=options.product==='ide'&&H.isIDE(payload)&&payload.cwd==='/';
  const hostProject=options.host==='workbuddy'?env.WORKBUDDY_PROJECT_DIR:env.CODEBUDDY_PROJECT_DIR;
- const root=options.scope==='project'?path.dirname(options.base):ideRoot?workspace(payload.transcript_path,payload.session_id):hostProject||env.CLAUDE_PROJECT_DIR||payload.cwd||(payload.hook_event_name==='SessionStart'?callbackCwd:null);assert.ok(root&&path.isAbsolute(root),'Native project directory required');
+ const root=options.scope==='project'?path.dirname(options.base):options.nativeProject|| (ideRoot?workspace(payload.transcript_path,payload.session_id):hostProject||env.CLAUDE_PROJECT_DIR||payload.cwd||(payload.hook_event_name==='SessionStart'?callbackCwd:null));assert.ok(root&&path.isAbsolute(root),'Native project directory required');
  const project=real(root);
  // IDE 4.12.2 reports '/' for absolute-path tools. Use the project registration
  // or session-bound native workspace above; reject all other outside cwd.
@@ -80,19 +88,45 @@ function saveIndex(directory,index) {
 function toolCwd(payload,record,project) {
  return record.product==='ide'&&H.isIDE(payload)&&payload.cwd==='/'?project:payload.cwd||project;
 }
-function handle(payload,options) {
+function settleNativeRetries(index,source,{project,sessionId}) {
+ let changed=false;
+ for(const entry of Object.values(index.bindings)) {
+  const repair=entry.recovery,expected=repair?.expectedRetry;
+  if(!expected||!['required','ready-to-retry'].includes(repair.status)||entry.entryLine!==source.prompts.at(-1)?.line||entry.contextLine!==source.contextLine)continue;
+  const matches=source.calls.filter(call=>{
+   if(!call.success||!call.resultLine||call.sessionId!==sessionId||call.requestLine<=entry.entryLine||source.stableThroughLine!==undefined&&call.resultLine>source.stableThroughLine)return false;
+   if(expected.kind==='ui-write') {
+    const input=call.input||{},file=input.file_path||input.filePath||input.path||input.TargetFile;
+    return typeof file==='string'&&path.resolve(call.cwd||project,file)===expected.file&&G.uiWrite({...call,cwd:call.cwd||project},entry.directory);
+   }
+   const parsed=nativeCommand(call.name,call.input,call.cwd||project);
+   return expected.kind==='stage'&&parsed?.root===entry.directory&&parsed.operation===expected.operation;
+  });
+  for(const call of matches) {
+   const stage=expected.kind==='stage'?expected.stage:null;
+   if(stage&&X.check(entry.directory,stage,require('./native-pilot-lib.cjs')).status!=='passed')continue;
+   const retry={...expected,toolCallId:call.toolCallId,resultDigest:call.resultDigest,requestLine:call.requestLine,resultLine:call.resultLine};
+   const answer=Recovery.record(index,{source,sessionId,directory:entry.directory,event:'PostToolUse',eventKey:E.sha(JSON.stringify(['persisted-native-result',call.toolCallId,call.resultDigest])),stage,policy:X.policy(entry.directory),resolved:stage?['execution-evidence']:[],retrySucceeded:true,retry},{continue:true});
+   if(answer.recovery&&JSON.stringify(answer.recovery)!==JSON.stringify(entry.recovery)){entry.recovery=answer.recovery;changed=true;}
+   if(entry.recovery?.status==='recovered')break;
+  }
+ }
+ return changed;
+}
+function dispatch(payload,options) {
+ payload={...payload,tool_name:toolName(payload.tool_name)};
  assert.equal(payload.hook_event_name,options.event,'Hook event mismatch');
  if(options.event==='SessionStart')return {continue:true};
  if(options.event==='UserPromptSubmit'){
   const prompt=payload.prompt||'';
-  if(!C.readOnly(prompt)&&(/\/i3-prototype\b(?!\s+(?:analyze|inspect|confirm-baseline))/.test(prompt)||/(?:生成|实现|创建|修订|修改|继续).{0,16}原型|(?:create|revise|implement).{0,20}prototype/i.test(prompt)))return {continue:true,context:'原型实施：先 execution-begin，再实际调用 i3-frontend-ui-engineering；使用 antDv 时加载 antdv 并通过 prototype-deps query 或检测出的本地 Node 入口查询组件。专业模式还须实际调用 UIUX。成功返回后再实施；收到原型门禁拒绝时按明确缺项补调并重试，不能留到下次修订。'};
+  if(!C.readOnly(prompt)&&(/\/i3-prototype\b(?!\s+(?:analyze|inspect|confirm-baseline))/.test(prompt)||/(?:生成|实现|创建|修订|修改|继续).{0,16}原型|(?:create|revise|implement).{0,20}prototype/i.test(prompt)))return {continue:true,context:'原型实施：界面实现前实际调用 i3-frontend-ui-engineering；使用 antDv 时加载 antdv 并查询实际组件。专业模式还须调用 UIUX。真实浏览器验收使用浏览器 Skill。缺少必要 Skill 时立即补调，成功返回后重试原操作。'};
   return {continue:true};
  }
  let identity,installed;
  try{installed=options.product==='auto'?C.registration(options.base):null;identity=H.identify(payload,installed||{schemaVersion:1,product:options.product},options);}catch(error){
   const project=options.scope==='project'?path.dirname(options.base):payload.cwd;
   if(options.event==='PreToolUse'&&project&&path.isAbsolute(project)){
-   const native=nativeCommand(payload.tool_name,payload.tool_input,project),target=native?.root||prototypeForWrite(project,payload.tool_name,payload.tool_input);
+   const native=nativeCommand(payload.tool_name,payload.tool_input,payload.cwd||project),target=native?.root||prototypeForWrite(project,payload.tool_name,payload.tool_input,payload.cwd==='/'?project:payload.cwd||project);
    if(target&&fs.existsSync(path.join(target,'prototype.json'))&&X.policy(target))return {deny:true,reason:'原型原生宿主身份尚未核验，禁止受管写入或阶段推进：'+error.message};
   }
   throw error;
@@ -105,26 +139,32 @@ function handle(payload,options) {
  try {
   source=eventSource(payload,record,project);
  }catch(error){
-  const target=options.event==='PreToolUse'?prototypeForWrite(project,payload.tool_name,payload.tool_input):null;
-  if(target&&X.policy(target)&&G.uiWrite({name:payload.tool_name,input:payload.tool_input,cwd},target))return {deny:true,reason:`Native evidence unavailable for strict prototype UI write: ${error.message}`};
+  // The outer diagnostic handler must persist and bound this failure as well;
+  // returning an uncounted denial here used to create an endless repair loop.
   throw error;
  }
  const latest=source.prompts.at(-1);
  if(C.readOnly(latest.text)) {
-  const native=nativeCommand(payload.tool_name,payload.tool_input,cwd),root=native?.root||prototypeForWrite(project,payload.tool_name,payload.tool_input);
+  const native=nativeCommand(payload.tool_name,payload.tool_input,cwd),root=native?.root||prototypeForWrite(project,payload.tool_name,payload.tool_input,cwd);
   if(options.event==='PreToolUse'&&(native&&['create','execution-begin','build','revise','replan','record-run','record-devtools-review','finalize'].includes(native.operation)||root&&X.policy(root)&&G.uiWrite({name:payload.tool_name,input:payload.tool_input,cwd},root)))return {deny:true,reason:'The latest user request is read-only or stopped; no prototype mutation is authorized.'};
   return {continue:true};
  }
  const stateDirectory=C.sessionDirectory(record,project,payload.session_id),file=path.join(stateDirectory,'session.json');
- const index=JSON.parse(C.read(file)||'{"schemaVersion":1,"bindings":{}}');assert.equal(index.schemaVersion,1,'Unsupported audit session state');
+ let index=JSON.parse(C.read(file)||'{"schemaVersion":1,"bindings":{}}');assert.equal(index.schemaVersion,1,'Unsupported audit session state');
+ if(Object.values(index.bindings).some(entry=>['required','ready-to-retry'].includes(entry.recovery?.status))) {
+  const lock=path.join(stateDirectory,'.audit.lock');fs.mkdirSync(stateDirectory,{recursive:true});
+  try{fs.mkdirSync(lock);}catch{throw new Error('Concurrent audit callback; retry the original operation');}
+  try{index=JSON.parse(C.read(file));if(settleNativeRetries(index,source,{project,sessionId:payload.session_id}))saveIndex(stateDirectory,index);}
+  finally{fs.rmdirSync(lock);}
+ }
  const command=nativeCommand(payload.tool_name,payload.tool_input,cwd);
  if(options.event==='PreToolUse'&&command?.operation==='create'&&(installed?.schemaVersion===2||E.loaded(source.calls,'prototype').some(c=>c.requestLine>source.contextLine)||/^\s*\/i3-prototype\b/.test(latest.text))){
   const at=command.argv.indexOf('--execution-policy'),expected=installed?.schemaVersion===2?P.AUTO_ID:P.ID;
   const hostAt=command.argv.indexOf('--host');
   if(at<0||command.argv[at+1]!==expected||installed?.schemaVersion===2&&(hostAt<0||command.argv[hostAt+1]!==identity.host))return {deny:true,reason:`New ${identity.host} prototypes require --host ${identity.host} --execution-policy ${expected} and fixed --execution-assertions. Existing artifacts keep their original contracts.`};
  }
- const directory=command?.root||prototypeForWrite(project,payload.tool_name,payload.tool_input);
- const existing=directory?index.bindings[directory]:null;
+ const directory=command?.root||prototypeForWrite(project,payload.tool_name,payload.tool_input,cwd);
+ let existing=directory?index.bindings[directory]:null;
  const stage=options.event==='Stop'?'delivery':stageFor[command?.operation];
  let callbackCall=null;if(['PreToolUse','PostToolUse'].includes(options.event))try{callbackCall=eventCall(payload,source);}catch{/* Deferred IDE requests cannot attest results. */}
  const callId=payload.tool_use_id||payload.call_id||callbackCall?.toolCallId;
@@ -132,8 +172,10 @@ function handle(payload,options) {
  const recoveryContext=target=>{
   const stagePassed=stage&&options.event!=='Stop'&&X.check(target,stage,require('./native-pilot-lib.cjs')).status==='passed';
   const retryCall=options.event==='PostToolUse'&&callbackCall?.success&&(stagePassed||G.uiWrite({...callbackCall,cwd:callbackCall.cwd||cwd},target))?callbackCall:null;
-  return {source,sessionId:payload.session_id,directory:target,event:options.event,eventKey,stage,policy:X.policy(target),resolved:[...(existing?['execution-begin']:[]),...(stagePassed?['execution-evidence']:[])],retrySucceeded:!!retryCall,
-   ...(retryCall?{retry:{toolCallId:retryCall.toolCallId,resultDigest:retryCall.resultDigest,requestLine:retryCall.requestLine,resultLine:retryCall.resultLine,...(stagePassed?{kind:'stage',stage,operation:command.operation}:{kind:'ui-write'})}}:{})};
+  const input=payload.tool_input||{},uiFile=input.file_path||input.filePath||input.path||input.TargetFile;
+  const expectedRetry=stage?{kind:'stage',stage,operation:options.event==='Stop'?'finalize':command.operation}:G.uiWrite({name:payload.tool_name,input,cwd},target)?{kind:'ui-write',file:path.resolve(cwd,uiFile)}:null;
+  return {source,sessionId:payload.session_id,directory:target,event:options.event,eventKey,stage,expectedRetry,policy:X.policy(target),resolved:[...(completedBegin(source,existing)?['execution-begin']:[]),...(stagePassed?['execution-evidence']:[])],retrySucceeded:!!retryCall,
+   ...(retryCall?{retry:{toolCallId:retryCall.toolCallId,resultDigest:retryCall.resultDigest,requestLine:retryCall.requestLine,resultLine:retryCall.resultLine,...(stagePassed?{kind:'stage',stage,operation:command.operation}:{kind:'ui-write',file:path.resolve(cwd,uiFile)})}}:{})};
  };
  const respond=answer=>{
   const lock=path.join(stateDirectory,'.audit.lock');fs.mkdirSync(stateDirectory,{recursive:true});
@@ -141,37 +183,52 @@ function handle(payload,options) {
   try{const fresh=JSON.parse(C.read(file)||'{"schemaVersion":1,"bindings":{}}');const result=Recovery.record(fresh,recoveryContext(directory),answer);if(fresh.bindings[directory]&&result.recovery)fresh.bindings[directory].recovery=result.recovery;saveIndex(stateDirectory,fresh);return result;}
   finally{fs.rmdirSync(lock);}
  };
- if(options.event==='PreToolUse'&&command?.operation==='execution-begin') {
+ const automatic=options.event==='PreToolUse'&&directory&&fs.existsSync(path.join(directory,'prototype.json'))&&X.policy(directory)&&
+  (command||G.uiWrite({name:payload.tool_name,input:payload.tool_input||{},cwd},directory))&&command?.operation!=='execution-begin'&&
+  (!existing||existing.entryLine!==latest.line||existing.contextLine!==source.contextLine||existing.inputDigest!==require('./native-pilot-lib.cjs').manifest(directory).inputDigest);
+ if(options.event==='PreToolUse'&&command?.operation==='execution-begin'||automatic) {
   assert.ok(directory&&directory.startsWith(path.join(project,'prototypes')+path.sep),'Prototype must be in this project');
   const fixed=X.policy(directory);assert.ok(fixed,'Existing prototype retains its original contract; do not rewrite it implicitly');
   assert.equal(fixed.host,identity.host,'This prototype has a fixed contract for another host; inspect it or explicitly migrate and revalidate, do not inherit its invocation proof');
   const loaded=E.loaded(source.calls,'prototype').some(c=>c.requestLine>source.contextLine);
-  assert.ok(loaded||/^\s*\/i3-prototype\b/.test(latest.text),'Native prototype Skill or actual shortcut entry required');
+  assert.ok(loaded||/^\s*\/i3-prototype\b/.test(latest.text)||automatic&&require('./execution-diagnostics.cjs').intent(latest.text),'Native prototype Skill or actual shortcut entry required');
   const meta=F.json(path.join(directory,'prototype.json')),lib=require('./native-pilot-lib.cjs'),current=lib.manifest(directory);
   const runId=existing&&existing.entryLine===latest.line&&existing.inputDigest===current.inputDigest&&existing.contextLine===source.contextLine?existing.runId:crypto.randomUUID();
-  index.bindings[directory]={schemaVersion:1,runId,sessionId:payload.session_id,project,projectKey:C.projectKey(project),directory,instanceId:meta.instanceId,policyDigest:fixed.digest,inputDigest:current.inputDigest,entryLine:latest.line,promptDigest:latest.digest,contextLine:source.contextLine,
+  index.bindings[directory]={schemaVersion:1,...(automatic?{association:'automatic'}:{}),runId,sessionId:payload.session_id,project,projectKey:C.projectKey(project),directory,instanceId:meta.instanceId,policyDigest:fixed.digest,inputDigest:current.inputDigest,entryLine:latest.line,promptDigest:latest.digest,contextLine:source.contextLine,
    operation:meta.revision==='r001'?'create':'revise',host:identity.host,identitySource:identity.identitySource,product:record.product,productVersion:identity.productVersion,scope:record.scope,registrationDigest:record.registrationDigest,settingsDigest:record.settingsDigest,source:{path:source.path,bytes:source.bytes,digest:source.digest},lastHook:{event:options.event,at:new Date().toISOString(),nativeReadAttempts:source.nativeReadAttempts,nativeRequestStatus:source.nativeRequestStatus}};
   const lock=path.join(stateDirectory,'.audit.lock');fs.mkdirSync(stateDirectory,{recursive:true});
-  try{fs.mkdirSync(lock);}catch{throw new Error('Concurrent audit callback; retry execution-begin');}
+  try{fs.mkdirSync(lock);}catch{throw new Error('Concurrent audit callback; retry the original operation');}
   try {
    const fresh=JSON.parse(C.read(file)||'{"schemaVersion":1,"bindings":{}}');fresh.bindings[directory]=index.bindings[directory];
    saveIndex(stateDirectory,fresh);
    F.write(directory,'qa/execution-context.json',{schemaVersion:1,runId,sessionId:payload.session_id,project,base:record.base,host:identity.host,product:record.product});
   }finally{fs.rmdirSync(lock);}
-  return {continue:true};
+  existing=index.bindings[directory];
+  if(!automatic)return {continue:true};
  }
  if(directory&&fs.existsSync(path.join(directory,'prototype.json'))&&X.policy(directory)) {
   const fixed=X.policy(directory),answer=decision({event:options.event,source,binding:existing,tool:payload.tool_name,input:payload.tool_input,directory,cwd,policy:fixed});
   if(answer.deny)return respond(answer);
+  if(options.event==='PostToolUse'&&command&&(command.operation==='execution-begin'||stage)){
+   // IDE may not have persisted a callback's result yet. Only observed native
+   // failures produce recovery feedback; outer tool success is insufficient.
+   if(callbackCall?.resultLine&&!callbackCall.success){
+    const missing=command.operation==='execution-begin'?['execution-begin']:['execution-evidence'];
+    return respond({feedback:true,missing,reason:`原型 ${command.operation} 实际返回失败，阶段尚未通过。`+Recovery.instruction(missing,{directory,automatic:existing?.association==='automatic'})});
+   }
+   if(command.operation==='execution-begin')return respond({continue:true});
+  }
   if(options.event==='PreToolUse'&&command&&['build','record-run','record-devtools-review','finalize'].includes(command.operation)){
-   if(!existing)return respond({deny:true,missing:['execution-begin'],reason:Recovery.instruction(['execution-begin'])});
+   if(existing?.association!=='automatic'&&!completedBegin(source,existing))return respond({deny:true,missing:['execution-begin'],reason:Recovery.instruction(['execution-begin'],{directory})});
    const checked=X.check(directory,stage,require('./native-pilot-lib.cjs'));
    if(checked.status==='failed'){
     const missing=Recovery.missing({source,binding:existing,policy:fixed,stage});if(!missing.length)missing.push('execution-evidence');
-    return respond({deny:true,missing,reason:Recovery.instruction(missing)+' '+checked.errors.join('; ')});
+    return respond({deny:true,missing,reason:Recovery.instruction(missing,{directory,automatic:existing?.association==='automatic'})+' '+checked.errors.join('; ')});
    }
   }
-  if(G.uiWrite({name:payload.tool_name,input:payload.tool_input||{},cwd},directory)||stage&&['PreToolUse','PostToolUse'].includes(options.event))respond({continue:true});
+  if(G.uiWrite({name:payload.tool_name,input:payload.tool_input||{},cwd},directory)||stage&&['PreToolUse','PostToolUse'].includes(options.event)){
+   const recovery=respond({continue:true});if(recovery.deny||recovery.feedback||recovery.context)return recovery;
+  }
  }
  if(!Object.keys(index.bindings).length)return {continue:true};
  const lock=path.join(stateDirectory,'.audit.lock');fs.mkdirSync(stateDirectory,{recursive:true});
@@ -193,4 +250,51 @@ function handle(payload,options) {
  }finally{fs.rmdirSync(lock);}
  return {continue:true};
 }
+function handle(payload,options){
+ const D=require('./execution-diagnostics.cjs');
+ payload={...payload,tool_name:toolName(payload.tool_name)};
+ let diagnostic;
+ try{
+  if(options.event==='UserPromptSubmit')D.remember(payload,options);
+  diagnostic=D.context(payload,options);
+ }catch{/* The authoritative dispatcher still checks registration and identity. */}
+ const toolEvent=['PreToolUse','PostToolUse'].includes(options.event);
+ const cwd=diagnostic&&toolCwd(payload,diagnostic.record,diagnostic.project);
+ const command=diagnostic&&nativeCommand(payload.tool_name,payload.tool_input,cwd);
+ const root=diagnostic&&(command?.root||prototypeForWrite(diagnostic.project,payload.tool_name,payload.tool_input,cwd));
+ const mutation=command&&['create','execution-begin','build','revise','replan','record-run','record-devtools-review','finalize'].includes(command.operation)||root&&G.uiWrite({name:payload.tool_name,input:payload.tool_input||{},cwd},root);
+ if(diagnostic&&toolEvent&&['Write','Edit','MultiEdit'].includes(payload.tool_name)&&!mutation)return {continue:true};
+ if(diagnostic?.task.readOnly&&toolEvent)return options.event==='PreToolUse'&&mutation?{deny:true,reason:'The latest user request is read-only or stopped; no prototype mutation is authorized.'}:{continue:true};
+ if(diagnostic&&!diagnostic.task.active&&toolEvent&&!mutation)return {continue:true};
+ if(diagnostic&&mutation&&!diagnostic.task.active)diagnostic.task={...diagnostic.task,active:true};
+ const guarded=mutation?D.guard(diagnostic,payload):null;if(guarded)return guarded;
+ if(D.blocked(diagnostic)&&toolEvent&&!mutation)return {continue:true};
+ try{
+  const answer=dispatch(payload,diagnostic?{...options,nativeProject:diagnostic.project}:options);
+  if(toolEvent&&!answer.deny&&!answer.feedback)D.observed(diagnostic,payload);
+  if(options.event==='PostToolUse'&&command?.operation==='execution-begin'&&!answer.deny&&root&&fs.existsSync(path.join(root,'qa/execution-context.json'))){
+   const pointer=F.json(path.join(root,'qa/execution-context.json'));
+   const source=diagnostic&&C.source(payload,diagnostic.record,diagnostic.project);
+   if(pointer&&completedBegin(source,{...pointer,entryLine:source.prompts.at(-1).line,contextLine:source.contextLine,directory:root}))D.recover(diagnostic);
+  }
+  return answer;
+ }catch(error){
+  if(diagnostic){const failure=D.failure(diagnostic,payload,error);if(!mutation&&failure.deny){const {deny,reason,...rest}=failure;return {...rest,continue:true,context:reason};}return failure;}
+  if(options.event==='PreToolUse') {
+   // A damaged/absent task source must not turn a protected write into exit 1
+   // (which CodeBuddy treats as non-blocking). This is a failure-only fallback,
+   // not a successful task association or invocation receipt.
+   const cwd=payload.cwd==='/'&&options.scope==='project'?path.dirname(options.base):payload.cwd;
+   if(cwd&&path.isAbsolute(cwd)) {
+    const parsed=nativeCommand(payload.tool_name,payload.tool_input,cwd),input=payload.tool_input||{},file=input.file_path||input.filePath||input.path||input.TargetFile;
+    let target=typeof file==='string'?path.dirname(path.resolve(cwd,file)):parsed?.root;
+    while(target&&target!==path.dirname(target)) {
+     if(fs.existsSync(path.join(target,'prototype.json'))&&X.policy(target)&&(parsed||G.uiWrite({name:payload.tool_name,input,cwd},target)))return {deny:true,reason:'原型 Hook 运行异常，当前操作未放行：'+error.message+'。请停止自动重试并交由维护入口处理；原型会话不排查 Hook。'};
+     target=path.dirname(target);
+    }
+   }
+  }
+  throw error;
+ }
+}
 module.exports={tokens,nativeCommand,eventCall,eventSource,decision,safeProject,toolCwd,handle};

package/skills/i3-ui-prototype/scripts/codebuddy-ide-source.cjs

@@ -3,7 +3,7 @@
 // UUID message files explicitly referenced by that index. No directory scan.
 const fs=require('node:fs'),path=require('node:path'),assert=require('node:assert/strict');
 const ID=/^[a-f0-9]{32}$/;
-const aliases={use_skill:'Skill',execute_command:'Bash',write_to_file:'Write',read_file:'Read',replace_in_file:'Edit'};
+const {toolName}=require('./native-tool-name.cjs');
 function read(file) {
  assert.equal(path.basename(file),'index.json','Expected native IDE index');
  const directory=path.dirname(file),sessionId=path.basename(directory);
@@ -52,13 +52,13 @@ function read(file) {
    if(text)latestAssistant=text;
    for(const block of message.content.filter(b=>b.type==='tool-call')){
     assert.ok(block.args&&typeof block.args==='object'&&!Array.isArray(block.args),'Invalid IDE tool arguments');
-    events.push({...base,type:'assistant',message:{content:[{type:'tool_use',id:block.toolCallId,name:aliases[block.toolName]||block.toolName,input:block.args}]}});
+    events.push({...base,type:'assistant',message:{content:[{type:'tool_use',id:block.toolCallId,name:toolName(block.toolName),input:block.args}]}});
    }
   }else if(row.role==='tool'){
    for(const block of message.content.filter(b=>b.type==='tool-result')){
     const result=block.result,success=!block.isError&&result?.success===true&&result.status==='success';
     events.push({...base,type:'user',message:{content:[{type:'tool_result',tool_use_id:block.toolCallId,
-     tool_name:aliases[block.toolName]||block.toolName,content:result,is_error:!success}]}});
+     tool_name:toolName(block.toolName),content:result,is_error:!success}]}});
    }
   }
  }

package/skills/i3-ui-prototype/scripts/execution-assertions.cjs

@@ -17,7 +17,7 @@ function validate(value,scenarioIds) {
  return value;
 }
 function resultData(result) {
- const text=E.contentText(result).trim();let value;
+ const text=E.resultText(result).trim();let value;
  try{value=JSON.parse(text);}catch{const blocks=[...text.matchAll(/```(?:json)?\s*\n([\s\S]*?)\n```/g)];assert.equal(blocks.length,1,'One actual JSON result or JSON code block required');value=JSON.parse(blocks[0][1]);}
  assert.ok(value&&typeof value==='object','Native JSON fact result required');return value;
 }

package/skills/i3-ui-prototype/scripts/execution-diagnostics.cjs

@@ -0,0 +1,94 @@
+'use strict';
+// Protocol failures exist before a run binding. Never turn them into invocation proof.
+const fs=require('node:fs'),path=require('node:path');
+const F=require('./native-files.cjs'),C=require('./codebuddy-context.cjs'),E=require('./execution-evidence.cjs'),H=require('./buddy-host.cjs');
+const intent=text=>typeof text==='string'&&!C.readOnly(text)&&(/\/i3-prototype\b(?!\s+(?:analyze|inspect|confirm-baseline))/.test(text)||/(?:生成|实现|创建|修订|修改|继续).{0,16}原型|(?:create|revise|implement).{0,20}prototype/i.test(text));
+const read=file=>fs.existsSync(file)?JSON.parse(C.read(file)):null;
+function location(payload,options){
+ if(!payload.session_id||!path.isAbsolute(options.base||''))return null;
+ const installation=read(path.join(options.base,'state/i3-prototype/installation.json'));if(!installation)return null;
+ const identity=H.identify(payload,installation,options),pointer=`state/i3-prototype/tasks/${E.sha(identity.host+':'+identity.product+':'+payload.session_id).slice(0,24)}.json`;
+ const previous=read(F.inside(options.base,pointer));
+ let project=options.scope==='project'?path.dirname(options.base):previous?.project;
+ if(!project)project=H.isIDE(payload)&&payload.cwd==='/'?E.ideWorkspace(payload.transcript_path,payload.session_id):payload.cwd;
+ if(!project||!path.isAbsolute(project))return null;project=fs.realpathSync(project);
+ if(payload.cwd&&payload.cwd!=='/'){
+  const relative=path.relative(project,fs.realpathSync(payload.cwd));if(relative==='..'||relative.startsWith('..'+path.sep)||path.isAbsolute(relative))return null;
+ }
+ const record={...installation,...identity,base:options.base,registrationDigest:E.sha(JSON.stringify(installation)),settingsDigest:E.sha(C.read(path.join(options.base,'settings.json')))};
+ return {project,record,identity,pointer,previous,directory:C.sessionDirectory(record,project,payload.session_id)};
+}
+function context(payload,options,{source,prompt}={}){
+ const where=location(payload,options);if(!where)return null;
+ let native=source;if(!native)try{native=C.source(payload,where.record,where.project);}catch{/* Failure diagnostics must survive unreadable native history. */}
+ const latest=native?.prompts.at(-1),text=prompt??latest?.text??where.previous?.text;
+ if(typeof text!=='string')return null;
+ const digest=latest?.digest||E.sha(text),entryLine=latest?.line||where.previous?.entryLine||null;
+ const taskKey=E.sha(JSON.stringify([payload.session_id,payload.prompt_id||null,entryLine,digest]));
+ // A callback without prompt_id reuses only the exact observed native task.
+ const task=payload.hook_event_name!=='UserPromptSubmit'&&where.previous&&where.previous.digest===digest&&where.previous.entryLine===entryLine?where.previous:
+  {schemaVersion:1,taskKey,sessionId:payload.session_id,project:where.project,host:where.identity.host,product:where.identity.product,text,digest,entryLine,active:intent(text),readOnly:C.readOnly(text),at:new Date().toISOString()};
+ return {...where,source:native,task};
+}
+function remember(payload,options){
+ const value=context(payload,options,{prompt:payload.prompt});if(!value)return;
+ F.write(options.base,value.pointer,value.task);
+}
+function state(value){return read(path.join(value.directory,'diagnostics.json'))||{schemaVersion:1,tasks:{}};}
+function current(value){return value&&state(value).tasks[value.task.taskKey];}
+function blocked(value){return current(value)?.status==='blocked';}
+function message(failure){return `原型 Hook 运行异常${failure.status==='blocked'?'，已达到自动恢复上限':''}：${failure.reason}。请简要报告当前原型及未验收项，由维护入口处理；不要在原型任务中检查日志、修复 Hook 或重复绑定，也不能宣称已验证。`;}
+function failure(value,payload,error){
+ if(!value?.task.active)return {continue:true};
+ return F.withLock(value.directory,'.diagnostics.lock',()=>{
+ const store=state(value),key=value.task.taskKey;
+ const phase=/JSON|transcript|source|history|日志/i.test(error.message)?'native-source':'native-request';
+ const eventKey=E.sha(JSON.stringify([key,payload.tool_use_id||payload.call_id||payload.hook_event_name,payload.tool_name||null,payload.tool_input||null,phase]));
+ const item=store.tasks[key]||{schemaVersion:1,taskKey:key,total:0,counts:{},events:{},status:'required'};
+ if(!item.events[eventKey]&&item.status!=='blocked'){
+  if(item.total>=6||(item.counts[phase]||0)>=2)item.status='blocked';
+  else {item.total++;item.counts[phase]=(item.counts[phase]||0)+1;item.status='required';}
+  Object.assign(item,{eventKey,reason:String(error.message).slice(0,2000),phase,at:new Date().toISOString(),host:value.identity.host,product:value.identity.product,productVersion:value.identity.productVersion,
+   callMode:payload.agent_type==='ptc'||value.source?.calls.some(c=>c.name==='REPL')?'ptc-repl':value.identity.product==='ide'?'native-ide':'direct',sessionId:payload.session_id,project:value.project,
+   registrationDigest:value.record.registrationDigest,settingsDigest:value.record.settingsDigest,transcriptPath:payload.transcript_path});
+  item.events[eventKey]=true;store.tasks[key]=item;F.write(value.directory,'diagnostics.json',store);
+ }
+ const result={reason:message(item),failure:item};
+ return payload.hook_event_name==='PreToolUse'?{...result,deny:true}:payload.hook_event_name==='Stop'?{...result,feedback:true}:{...result,continue:true,context:result.reason};
+ });
+}
+function guard(value,payload){
+ if(!value?.task.active||!blocked(value))return null;
+ const item=current(value),reason=message(item);
+ // Do not trap the whole host. Read tools and explicit state/check commands remain available.
+ const command=require('./native-command.cjs').nativeCommand(payload.tool_name,payload.tool_input,value.project);
+ const managed=command&&['create','execution-begin','revise','replan','build','record-run','record-devtools-review','finalize'].includes(command.operation)||['Write','Edit','MultiEdit','write_to_file','replace_in_file'].includes(payload.tool_name);
+ if(payload.hook_event_name==='PreToolUse'&&managed)return {deny:true,reason,failure:item};
+ return null;
+}
+function recover(value){
+ if(!value)return;
+ return F.withLock(value.directory,'.diagnostics.lock',()=>{const store=state(value),item=store.tasks[value.task.taskKey];
+  if(item&&item.status!=='blocked'){item.status='recovered';item.recoveredAt=new Date().toISOString();F.write(value.directory,'diagnostics.json',store);}
+ });
+}
+function observed(value,payload){
+ if(!value?.task.active)return;
+ const source=C.source(payload,value.record,value.project),at=new Date().toISOString();
+ const entry={schemaVersion:1,sessionId:payload.session_id,taskKey:value.task.taskKey,project:value.project,projectKey:C.projectKey(value.project),host:value.identity.host,product:value.identity.product,
+  productVersion:value.identity.productVersion,identitySource:value.identity.identitySource,registrationDigest:value.record.registrationDigest,settingsDigest:value.record.settingsDigest,
+  source:{path:source.path,bytes:source.bytes,digest:source.digest},callMode:source.callMode||'direct',skills:Object.fromEntries(['prototype','frontend','antdv','uiux','browser'].map(key=>[key,E.loaded(source.calls,key).length])),
+  lastHook:{event:payload.hook_event_name,at}};
+ F.write(value.directory,'observation.json',entry);
+}
+function latest({base,project,host,record}){
+ const parent=path.join(base,'state/i3-prototype',C.projectKey(project));let found=null;
+ if(!fs.existsSync(parent))return null;
+ for(const name of fs.readdirSync(parent)){
+  if(!/^[a-f0-9]{24}$/.test(name))continue;
+  const data=read(path.join(parent,name,'diagnostics.json'));if(!data)continue;
+  for(const item of Object.values(data.tasks||{}))if(item.host===host&&item.project===project&&item.registrationDigest===record.registrationDigest&&item.settingsDigest===record.settingsDigest&&item.status!=='recovered'&&(!found||item.at>found.at))found=item;
+ }
+ if(!found)return null;const {events,...summary}=found;return summary;
+}
+module.exports={intent,context,remember,current,blocked,failure,guard,recover,observed,latest};

package/skills/i3-ui-prototype/scripts/execution-evidence.cjs

@@ -4,6 +4,7 @@ const crypto = require('node:crypto');
 const fs = require('node:fs');
 const path = require('node:path');
 const P = require('./execution-policy.cjs');
+const {toolName}=require('./native-tool-name.cjs');
 const sha = value => crypto.createHash('sha256').update(value).digest('hex');
 function contentText(content) {
   if (typeof content === 'string') return content;
@@ -36,17 +37,47 @@ function nativeEvent(event) {
 function successful(block) {
   if (block.is_error || block.isError || block.success === false || block.error) return false;
   const text = contentText(block.content ?? block.result ?? block.tool_response);
-  if (!text.trim() || /^\s*(?:Error:|Error\b|错误[:：]|Unknown skill\b|Skill[^\n]*not (?:found|available))/i.test(text)) return false;
-  try {
-    const value = JSON.parse(text);
-    if (value && typeof value === 'object') {
-      if (value.isError || value.success === false || value.error || value.status === 'failed') return false;
-      if (typeof value.exitCode === 'number' && value.exitCode !== 0) return false;
-      if (typeof value.stdout === 'string' && /^\s*(?:Error:|Error\b|错误[:：])/i.test(value.stdout)) return false;
+  if (!text.trim()) return false;
+  function failed(value,depth=0) {
+    if(depth>8)return true;
+    if(typeof value==='string'){
+      if(/^\s*(?:Error:|Error\b|错误[:：]|Unknown skill\b|Skill[^\n]*not (?:found|available))/i.test(value))return true;
+      try{return failed(JSON.parse(value),depth+1);}catch{return false;}
     }
-  } catch { /* Native tool text need not be JSON. */ }
-  return true;
+    if(!value||typeof value!=='object')return false;
+    if(value.type==='text')return failed(value.text,depth+1);
+    if(value.isError||value.is_error||value.success===false||value.error||['failed','error','cancelled'].includes(value.status))return true;
+    if(typeof value.exitCode==='number'&&value.exitCode!==0)return true;
+    if(typeof value.stdout==='string'&&failed(value.stdout,depth+1))return true;
+    // Only descend through native execution envelopes, not arbitrary observed
+    // application data such as {result:{status:'failed'}} from a browser check.
+    const envelope=typeof value.success==='boolean'||['success','error'].includes(value.status)||value.type==='execute_command_result';
+    return !!(envelope&&value.result!==undefined&&failed(value.result,depth+1));
+  }
+  return !failed(text);
+}
+function resultContent(content){
+  let value=content;
+  for(let depth=0;depth<8;depth++){
+    if(typeof value==='string'){
+      try{const parsed=JSON.parse(value);if(parsed&&typeof parsed==='object'&&(parsed.type==='text'||parsed.type==='execute_command_result'||typeof parsed.success==='boolean')){value=parsed;continue;}}catch{/* Plain text and fenced MCP facts remain text. */}
+      return value;
+    }
+    if(Array.isArray(value)){value=contentText(value);continue;}
+    if(value?.type==='text'){value=value.text;continue;}
+    if(!value||typeof value!=='object')return value;
+    if((typeof value.success==='boolean'||['success','error'].includes(value.status)||value.type==='execute_command_result')&&value.result!==undefined){value=value.result;continue;}
+    if(typeof value.stdout==='string'){value=value.stdout;continue;}
+    return value;
+  }
+  return null;
+}
+function resultValue(content){
+  const value=resultContent(content);
+  if(typeof value==='string'){try{return JSON.parse(value);}catch{return null;}}
+  return value;
 }
+const resultText=content=>contentText(resultContent(content));
 function parse(text) {
   assert.ok(typeof text === 'string' && Buffer.byteLength(text) <= 64 * 1024 * 1024, 'Native transcript is too large');
   const calls = [], requests = new Map(); let nativeMessages = 0, contextLine = 0, promptLine = 0;
@@ -65,16 +96,16 @@ function parse(text) {
       if (event.type === 'assistant' && block.type === 'tool_use') {
         assert.ok(typeof block.id === 'string' && block.id && typeof block.name === 'string', 'Native request identity missing');
         assert.ok(!requests.has(block.id), 'Duplicate native tool call ID');
-        const input = block.input || {}, skillName = ['Skill', 'skill'].includes(block.name) ? input.skill || input.name || input.command : null;
+        const name=toolName(block.name),input = block.input || {}, skillName = name==='Skill' ? input.skill || input.name || input.command : null;
         const normalized = typeof skillName === 'string' ? skillName.replace(/^i3-composer-agent:/, '') : null;
-        const call = { toolCallId: block.id, name: block.name, input, skillName: normalized, skill: P.skillKey(normalized),
+        const call = { toolCallId: block.id, name, ...(name!==block.name?{rawName:block.name}:{}), input, skillName: normalized, skill: P.skillKey(normalized),
           sessionId:event.sessionId||event.session_id||null, cwd:event.cwd||null, nativeRequestId:event.nativeRequestId||null, contextLine, promptLine,
           requestLine: lineIndex + 1, requestDigest: sha(JSON.stringify(block)), success: false };
         requests.set(block.id, call); calls.push(call);
       } else if (event.type === 'user' && block.type === 'tool_result') {
         const call = requests.get(block.tool_use_id);
         assert.ok(call && !call.resultLine, 'Unmatched or duplicate native tool result');
-        if (block.tool_name !== undefined) assert.equal(block.tool_name, call.name, 'Native tool result name differs');
+        if (block.tool_name !== undefined) assert.equal(toolName(block.tool_name), call.name, 'Native tool result name differs');
         if (call.sessionId && (event.sessionId||event.session_id)) assert.equal(call.sessionId,event.sessionId||event.session_id,'Cross-session native result');
         Object.assign(call, { resultLine: lineIndex + 1, resultDigest: sha(JSON.stringify(block)),
           result: block.content, success: successful(block) });
@@ -143,4 +174,4 @@ function readSource(file, roots, {mode='manual',project}={}) {
     ...(data.latestAssistant!==undefined?{latestAssistant:data.latestAssistant}:{}),
     sourceVerification: mode==='auto'?'native-hook-transcript':'configured-host-transcript', tamperProof: false };
 }
-module.exports = { sha, contentText, successful, parse, loaded, reference, describe, readSource, cursorBytes, ideWorkspace };
+module.exports = { sha, contentText, successful, resultContent, resultText, resultValue, parse, loaded, reference, describe, readSource, cursorBytes, ideWorkspace };