Summary

Adds a separate agent:turn:transcript:save internal hook event for the ACP turn transcript save phase. This PR is scoped to transcript-save durability outcomes and does not include the sibling agent:turn:end lifecycle hook from #89152.

Current implementation

• Adds agent:turn:transcript:save event typing, validation, and docs with explicit saved, skipped, and failed outcomes.
• Routes both chat-dispatch ACP turns and direct ACP command turns through the manager save callback before the hook event is emitted.
• Reports saveOutcome: saved only when the transcript append path reports a fresh durable append; no callback, declined boundaries, idempotency replays, blocked writes, empty turns, and save failures become non-saved outcomes.
• Preserves the lower append API's appended flag through the user-turn transcript wrapper so replay/no-op writes are not counted as save evidence.
• Covers manager outcomes, dispatch/direct ACP persistence, invalid callback results, skipped outcomes, failed runtime turns, blocked writes, and idempotency replay.
• Hardens gateway test fixtures surfaced by changed-path OpenGrep: env restoration avoids bulk-copying host env back into process.env, and noServer WebSocket test servers set an explicit preauth maxPayload.

Real behavior proof

• Behavior or issue addressed: proves that a source-built OpenClaw ACP manager turn with an installed internal hook handler observes agent:turn:transcript:save only after transcript persistence reports saveOutcome: saved; also verifies idempotency replay is not counted as a fresh save.
• Real environment tested: local OpenClaw source checkout on macOS at /Users/mantis/Projects/openclaw-pr-turn-save, branch feat/agent-turn-save-outcome-hook, head 4a7985a37c89030d877f1145d344dacf9d3436cc.
• Exact steps or command run after this patch: created an isolated temp OPENCLAW_STATE_DIR, installed a managed internal hook with HOOK.md + handler.js, loaded it through loadInternalHooks, ran AcpSessionManager.runTurn from source with an onBeforeTurnSaveHook that calls the real persistAcpTurnTranscript, then read both the hook log and transcript JSONL.
• Evidence after fix:

$ git rev-parse HEAD
4a7985a37c89030d877f1145d344dacf9d3436cc

$ node --import tsx --input-type=module <source-built transcript-save proof script>
{
  "loadedHooks": 1,
  "stateDir": "/Users/mantis/.openclaw/state/tmp/oc-89154-proof-clean-jy246I/state",
  "hookEventCount": 1,
  "hookEvent": {
    "type": "agent",
    "action": "turn:transcript:save",
    "sessionKey": "agent:codex:acp:proof-transcript-save",
    "context": {
      "sessionKey": "agent:codex:acp:proof-transcript-save",
      "turnSuccess": true,
      "durationMs": 1,
      "success": true,
      "saveOutcome": "saved"
    }
  },
  "transcriptPath": "/Users/mantis/.openclaw/state/tmp/oc-89154-proof-clean-jy246I/state/agents/codex/sessions/proof-session-89154.jsonl",
  "messageCount": 2,
  "transcriptRoles": ["user", "assistant"],
  "assistantText": "PROOF_TRANSCRIPT_SAVE_OK"
}

$ node scripts/test-projects.mjs src/agents/command/attempt-execution.cli.test.ts
[test] passed 1 Vitest shard in 4.95s

• Observed result after fix: the installed internal hook saw one agent:turn:transcript:save event with success: true and saveOutcome: saved, and the corresponding transcript file contained the persisted user and assistant messages. The idempotency replay regression now returns saveOutcome: skipped / saveSkipReason: no_transcript_write and leaves the transcript at one user message.
• What was not tested: a full production-account ACP backend session was not run from this branch.
• Proof limitations or environment constraints: the runtime was source-built and isolated with a temp state dir; the ACP runtime itself was a local proof runtime so the proof focuses on OpenClaw manager/save/hook behavior rather than an external harness provider.

Validation

• node scripts/test-projects.mjs src/acp/control-plane/manager.test.ts src/hooks/internal-hooks.test.ts src/agents/command/attempt-execution.cli.test.ts src/commands/agent.acp.test.ts src/commands/agent.test.ts src/auto-reply/reply/dispatch-acp.test.ts src/auto-reply/reply/dispatch-from-config.test.ts src/agents/agent-command.live-model-switch.test.ts — passed 5 Vitest shards in 33.76s.
• node scripts/test-projects.mjs src/gateway/server-discovery-runtime.test.ts src/gateway/server.plugin-node-capability-auth.test.ts src/gateway/server.preauth-hardening.test.ts — passed 1 Vitest shard in 41.59s.
• pnpm exec oxlint src/acp/control-plane/manager.core.ts src/acp/control-plane/manager.types.ts src/acp/control-plane/manager.test.ts src/acp/control-plane/manager.turn-runner.ts src/hooks/internal-hooks.ts src/hooks/internal-hooks.test.ts src/auto-reply/reply/dispatch-acp.ts src/auto-reply/reply/dispatch-acp.test.ts src/auto-reply/reply/dispatch-from-config.test.ts src/auto-reply/reply/dispatch-acp-transcript.runtime.ts src/agents/agent-command.ts src/agents/agent-command.live-model-switch.test.ts src/agents/command/attempt-execution.ts src/agents/command/attempt-execution.cli.test.ts src/commands/agent.acp.test.ts src/commands/agent.test.ts src/sessions/user-turn-transcript.ts — passed.
• pnpm exec oxfmt --check --threads=1 docs/automation/hooks.md src/acp/control-plane/manager.core.ts src/acp/control-plane/manager.types.ts src/acp/control-plane/manager.test.ts src/acp/control-plane/manager.turn-runner.ts src/hooks/internal-hooks.ts src/hooks/internal-hooks.test.ts src/auto-reply/reply/dispatch-acp.ts src/auto-reply/reply/dispatch-acp.test.ts src/auto-reply/reply/dispatch-from-config.test.ts src/auto-reply/reply/dispatch-acp-transcript.runtime.ts src/agents/agent-command.ts src/agents/agent-command.live-model-switch.test.ts src/agents/command/attempt-execution.ts src/agents/command/attempt-execution.cli.test.ts src/commands/agent.acp.test.ts src/commands/agent.test.ts src/sessions/user-turn-transcript.ts src/gateway/server-discovery-runtime.test.ts src/gateway/server.plugin-node-capability-auth.test.ts src/gateway/server.preauth-hardening.test.ts — passed.
• pnpm tsgo:core:test — passed.
• git diff --check origin/main...HEAD && git diff --check — passed.

Related

Related #37833
Sibling to #89152
Split from #71399

Latest head refresh (2026-06-22)

Current head: bbc4673b17f175529b491e534b600d79f2df2a8b

Merged current origin/main (3ff59df960) into the PR branch, resolved Plugin SDK surface report/test conflicts against the merged hook surface, and aligned the slash-command browser-import expectation with the current shared-registry import order.

Validation on the current head:

node scripts/test-projects.mjs src/acp/control-plane/manager.test.ts src/hooks/internal-hooks.test.ts src/agents/command/attempt-execution.cli.test.ts src/commands/agent.acp.test.ts src/commands/agent.test.ts src/auto-reply/reply/dispatch-acp.test.ts src/auto-reply/reply/dispatch-from-config.test.ts src/agents/agent-command.live-model-switch.test.ts
pnpm exec vitest run ui/src/ui/chat/slash-commands.browser-import.test.ts test/scripts/plugin-sdk-surface-report.test.ts

Observed results:

• Focused ACP/save-hook validation passed 5 Vitest shards / 507 tests.
• Focused slash-command import + Plugin SDK surface tests passed 2 files / 7 tests.

Limitations: the original source-built transcript-save proof harness was not present in this worktree during this refresh, so I did not rerun live transcript-save behavior proof on this head; the prior source-built proof remains from the earlier proof head.