feat(agents): generalized native compaction ownership for CLI backends by anagnorisis2peripeteia · Pull Request #88315 · openclaw/openclaw

anagnorisis2peripeteia · 2026-05-30T11:43:05Z

Summary

Generalizes native-compaction ownership for CLI backends via a new ownsNativeCompaction capability flag.

When a CLI backend owns transcript compaction and the session has no native-harness compaction endpoint, OpenClaw's CLI compaction lifecycle returns a no-op instead of running its safeguard summarizer. This avoids fighting backend-owned compaction or hard-failing the turn.

Any CLI backend can declare ownsNativeCompaction: true.
This PR wires it for claude-cli: Claude Code compacts internally and exposes no OpenClaw harness compaction endpoint.
Codex still routes to its native-harness compaction endpoint via the session agentHarnessId; the no-op applies only when no harness endpoint exists.

Scope: generalized mechanism plus the claude-cli declaration. Opting in other backends is out of scope.

What changed since review

This PR is purely the opt-out. The earlier contextTokens cap-precedence change was removed: once a backend owns compaction, its budget never drives OpenClaw compaction, so capping below the native window solved a problem that no longer exists. src/agents/context.ts, src/agents/context.test.ts, and generated SDK baseline files are not part of this PR.

Testing

src/agents/command/cli-compaction.test.ts covers over-budget ownsNativeCompaction + no harness endpoint -> no-op defer; native-harness sessions still route to the harness endpoint; non-owning backends still run the safeguard summarizer.
src/agents/cli-backends.test.ts covers capability registration.
Focused local proof: node scripts/run-vitest.mjs src/agents/command/cli-compaction.test.ts src/agents/cli-backends.test.ts.

Real behavior proof

Behavior addressed: claude-cli sessions that own native compaction defer to Claude Code instead of triggering OpenClaw safeguard summarization when over budget and no harness compaction endpoint exists.

Real environment tested: local OpenClaw source checkout with installed Claude CLI 2.1.150 (Claude Code).

Exact steps or command run after this patch: one-off Node/tsx smoke registered the bundled Anthropic CLI backend, invoked OpenClaw runCliAgent with provider=claude-cli and model=claude-sonnet-4-6, then invoked runCliTurnCompactionLifecycle with a synthetic over-budget session entry for the returned claude-cli session.

Evidence after fix:

[agent/cli-backend] cli exec: provider=claude-cli model=claude-sonnet-4-6 promptChars=74 trigger=unknown useResume=false session=none resumeSession=none reuse=none historyPrompt=none
[agent/cli-backend] cli argv: claude -p --output-format stream-json --include-partial-messages --verbose --setting-sources user --allowedTools mcp__openclaw__* --permission-mode bypassPermissions --strict-mcp-config --model claude-sonnet-4-6 --session-id <redacted>
[agent/cli-backend] claude live session turn: provider=claude-cli model=claude-sonnet-4-6 durationMs=3402 rawLines=13 outBytes=25 outHash=2be5da4cba0f
[agents/cli-compaction] CLI backend "claude-cli" owns native compaction — deferring to backend

Observed result after fix: Claude CLI returned the expected response token, the OpenClaw session had a Claude CLI session id, compaction deferred with deferred=true, compactionCount=0, and token counts stayed at the synthetic over-budget values.

What was not tested: an organically over-budget live Claude GA session, because current GA models report a 1M-token window; the over-budget condition was forced only for the lifecycle proof.

clawsweeper · 2026-05-30T11:44:56Z

Codex review: needs maintainer review before merge. Reviewed June 2, 2026, 4:55 AM ET / 08:55 UTC.

Summary
The PR adds ownsNativeCompaction to CLI backend plugins, wires it through backend resolution, marks claude-cli as backend-owned, skips OpenClaw compaction for owning non-harness CLI sessions, and documents/tests the contract.

PR surface: Source +25, Tests +217, Docs +42. Total +284 across 8 files.

Reproducibility: not applicable. as a bug reproduction; this is a feature/API PR, though the changed branch has deterministic tests and PR-body live logs from a lowered-budget real claude-cli run.

Review metrics: 3 noteworthy metrics.

Public Plugin SDK surface: 1 field added. CliBackendPlugin.ownsNativeCompaction becomes an external plugin-author contract and needs owner acceptance before release.
Bundled backend opt-in: 1 backend changed. claude-cli upgrade behavior changes from OpenClaw safeguard compaction to backend-owned deferral.
PR size: 8 files changed, +284/-0. The runtime change is small, but the docs, tests, and SDK surface make this a compatibility-sensitive feature review rather than a trivial fix.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

Get maintainer acceptance for the public Plugin SDK capability and claude-cli upgrade semantics.

Risk before merge

[P1] ownsNativeCompaction becomes public Plugin SDK API once shipped, so third-party backend plugins can rely on the opt-out semantics and future changes become compatibility work.
[P1] Existing claude-cli sessions that cross OpenClaw's compaction threshold will now defer instead of using OpenClaw's context-engine safeguard; if Claude Code does not compact and resume reliably, sessions can stay over budget or stale.
[P1] The live proof demonstrates the OpenClaw defer branch with a lowered budget, but long-horizon natural Claude Code compaction near the 1M-token window remains a maintainer confidence decision.

Maintainer options:

Accept the SDK contract (recommended)
Have agent/plugin owners explicitly accept ownsNativeCompaction as a public Plugin SDK contract and accept the claude-cli upgrade behavior before merge.
Keep ownership internal
If maintainers are not ready to expose this to third-party plugins, keep the compaction skip bundled-backend-only and remove the public docs/API surface.
Pause for stronger backend proof
If the main concern is Claude Code's own compaction and resume reliability, wait for longer real-session proof before shipping the opt-out.

Next step before merge

[P2] Manual owner review is needed because the remaining blocker is the public Plugin SDK contract and claude-cli upgrade semantics, not a narrow autonomous repair.

Security
Cleared: The diff changes TypeScript runtime/types, tests, docs, and generated SDK API metadata only; it does not touch dependencies, workflows, secrets, package scripts, or artifact download/execute paths.

Review details

Best possible solution:

Land the generic backend hook only after agent/plugin owners accept the public SDK contract and claude-cli defer semantics, with focused compaction tests and plugin SDK API validation green.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction; this is a feature/API PR, though the changed branch has deterministic tests and PR-body live logs from a lowered-budget real claude-cli run.

Is this the best way to solve the issue?

The generic backend hook is the right owner-boundary shape if maintainers want this public contract; the unresolved question is API and upgrade ownership, not a discrete code defect.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against dcf21ac3adaf.

Label changes

Label changes:

add proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes redacted after-fix live logs from a real claude-cli invocation with lowered budget showing the actual binary invocation and the defer log, and the latest follow-up only trims the same behavior.

Label justifications:

P2: This is a normal-priority agent/runtime improvement with limited blast radius, but it changes a compatibility-sensitive compaction path.
merge-risk: 🚨 compatibility: The PR adds a public Plugin SDK field and changes the default claude-cli compaction behavior for upgraded users.
merge-risk: 🚨 session-state: Deferring compaction to the backend can leave CLI session state over budget or stale if the backend does not compact and resume correctly.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (logs): The PR body includes redacted after-fix live logs from a real claude-cli invocation with lowered budget showing the actual binary invocation and the defer log, and the latest follow-up only trims the same behavior.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes redacted after-fix live logs from a real claude-cli invocation with lowered budget showing the actual binary invocation and the defer log, and the latest follow-up only trims the same behavior.

Evidence reviewed

PR surface:

Source +25, Tests +217, Docs +42. Total +284 across 8 files.

View PR surface stats

Area	Files	Added	Net
Source	4	25	+25
Tests	2	217	+217
Docs	2	42	+42
Config	0	0	0
Generated	0	0	0
Other	0	0	0
Total	8	284	+284

Acceptance criteria:

[P1] node scripts/run-vitest.mjs src/agents/command/cli-compaction.test.ts src/agents/cli-backends.test.ts.
[P1] pnpm plugin-sdk:api:check.

What I checked:

PR runtime branch: At PR head, runCliTurnCompactionLifecycle resolves the CLI backend and returns the current session entry when ownsNativeCompaction is set and the session is not a native-harness compaction session. (src/agents/command/cli-compaction.ts:532, a1516cc21518)
Public SDK surface: At PR head, CliBackendPlugin gains the public optional ownsNativeCompaction?: boolean field with a safety contract comment. (src/plugins/cli-backend.types.ts:85, a1516cc21518)
Bundled backend opt-in: At PR head, the bundled Anthropic CLI backend declares ownsNativeCompaction: true for claude-cli. (extensions/anthropic/cli-backend.ts:32, a1516cc21518)
Focused test coverage: The PR adds tests for owning backend no-op, non-owning backend fallback to context-engine compaction, and native-harness sessions still using the harness path. (src/agents/command/cli-compaction.test.ts:1411, a1516cc21518)
Current main behavior: Current main has no backend-ownership no-op; after native-harness handling it falls through to context-engine compaction when useContextEngineCompaction remains true. (src/agents/command/cli-compaction.ts:548, dcf21ac3adaf)
Runtime entry point: The real agent command flow invokes runCliTurnCompactionLifecycle after CLI transcript persistence, so the change affects actual CLI turns, not only a helper path. (src/agents/agent-command.ts:2048, dcf21ac3adaf)

Likely related people:

steipete: Peter Steinberger introduced the pluginized CLI backend surface and major Claude CLI runner structure that this PR extends. (role: feature-history owner; confidence: high; commits: a4a00aa1da3c, 48ae97633303, 4e099689c075; files: src/agents/cli-backends.ts, extensions/anthropic/cli-backend.ts, src/agents/command/cli-compaction.ts)
vincentkoc: Vincent Koc recently carried auth/runtime refactors and current-main blame across the CLI compaction and plugin type areas touched by this PR. (role: recent area contributor; confidence: medium; commits: 859eb0666282, 7a8d307bdc44; files: src/agents/cli-backends.ts, src/plugins/cli-backend.types.ts, src/agents/command/cli-compaction.ts)
obviyus: obviyus is assigned on the PR and authored the latest branch follow-up that trimmed the compaction ownership implementation without changing the central behavior. (role: current PR follow-up owner; confidence: medium; commits: a1516cc21518; files: src/agents/command/cli-compaction.ts, src/plugins/cli-backend.types.ts, docs/gateway/cli-backends.md)
Alex Alaniz: Alex Alaniz authored recent merged Claude CLI behavior work near the bundled backend path this PR changes. (role: adjacent Claude CLI contributor; confidence: low; commits: 6bd64ca4a7cf; files: extensions/anthropic/cli-backend.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

anagnorisis2peripeteia · 2026-05-30T14:12:25Z

@clawsweeper re-review

clawsweeper · 2026-05-30T14:12:28Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26685967549
Updated: 2026-05-30T14:20:41.815Z

anagnorisis2peripeteia · 2026-05-31T19:59:46Z

@clawsweeper re-review

clawsweeper · 2026-05-31T19:59:48Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26722973589
Updated: 2026-05-31T20:06:55.824Z

anagnorisis2peripeteia · 2026-05-31T22:03:58Z

@clawsweeper re-review

clawsweeper · 2026-05-31T22:04:00Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26725792850
Updated: 2026-05-31T22:12:42.720Z

anagnorisis2peripeteia · 2026-05-31T22:17:44Z

@clawsweeper re-review

clawsweeper · 2026-05-31T22:17:46Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Superseded
Detail: A newer re-review for this item started before this run finished, so GitHub cancelled this older run. Check the latest ClawSweeper run for the current result.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26726090466
Updated: 2026-05-31T22:23:14.949Z

anagnorisis2peripeteia · 2026-05-31T22:24:33Z

@clawsweeper re-review

clawsweeper · 2026-05-31T22:24:36Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26726237947
Updated: 2026-05-31T22:35:35.209Z

Add `ownsNativeCompaction` capability to CliBackendPlugin so backends that manage their own transcript compaction (e.g. Claude Code) can declare it once and OpenClaw defers instead of fighting or failing. Today only Codex declares compaction ownership (via the embedded runner path + agentHarnessId). Claude-cli never reaches that path because it runs as a CLI subprocess with no harness id set, so the safeguard summarizer fires and hard-fails the turn. This PR: - Adds `ownsNativeCompaction?: boolean` to the backend plugin type - Propagates it through all 4 backend resolution paths - In `runCliTurnCompactionLifecycle`, when a backend declares ownership but has no harness endpoint, returns a no-op instead of falling through to the safeguard - Sets the flag on claude-cli (first adopter) Codex's existing native-harness path is unchanged: when `isNativeHarnessCompactionSession` matches, the harness compaction endpoint is still called as before. Generalizes the partial fix in openclaw#87785 (codex-scoped) to a capability any backend can opt into.

obviyus · 2026-06-02T09:10:09Z

Landed via rebase onto main.

Scoped tests: git diff --check origin/main; oxfmt --check --threads=1 <8 touched files>; node scripts/run-vitest.mjs src/agents/command/cli-compaction.test.ts src/agents/cli-backends.test.ts; node scripts/run-oxlint.mjs src/agents/cli-backends.test.ts src/agents/cli-backends.ts src/agents/command/cli-compaction.test.ts src/agents/command/cli-compaction.ts src/plugins/cli-backend.types.ts extensions/anthropic/cli-backend.ts; local Claude CLI smoke through OpenClaw runCliAgent + compaction lifecycle
CI: green on refreshed head, including Real behavior proof, Critical Quality (agent-runtime-boundary), check-lint, check-prod-types, check-test-types, check-docs, build-artifacts, and security shards
Changelog: not edited; normal PR, release-note context is in the PR body
Land commit: 2384d73
Merge commit: db576c4

Thanks @anagnorisis2peripeteia!

openclaw-barnacle Bot added agents Agent runtime and tooling extensions: anthropic size: M triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels May 30, 2026

anagnorisis2peripeteia force-pushed the feat/generalized-native-compaction-ownership branch from 09120c8 to 36c34e6 Compare May 31, 2026 19:59

anagnorisis2peripeteia force-pushed the feat/generalized-native-compaction-ownership branch from 36c34e6 to 6fdaaec Compare May 31, 2026 21:45

openclaw-barnacle Bot added docs Improvements or additions to documentation gateway Gateway runtime labels May 31, 2026

anagnorisis2peripeteia force-pushed the feat/generalized-native-compaction-ownership branch from bf6e8eb to 8b8c599 Compare May 31, 2026 22:22

anagnorisis2peripeteia force-pushed the feat/generalized-native-compaction-ownership branch from 8b8c599 to 02a2856 Compare May 31, 2026 22:24

anagnorisis2peripeteia force-pushed the feat/generalized-native-compaction-ownership branch from 02a2856 to 6a4b5e7 Compare May 31, 2026 22:53

anagnorisis2peripeteia marked this pull request as ready for review May 31, 2026 23:38

clawsweeper Bot added rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. and removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. labels May 31, 2026

openclaw-barnacle Bot removed the triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. label Jun 1, 2026

obviyus self-assigned this Jun 2, 2026

obviyus force-pushed the feat/generalized-native-compaction-ownership branch from 6fd1c07 to a1516cc Compare June 2, 2026 08:44

openclaw-barnacle Bot added triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. and removed proof: sufficient ClawSweeper judged the real behavior proof convincing. labels Jun 2, 2026

clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label Jun 2, 2026

anagnorisis2peripeteia and others added 3 commits June 2, 2026 14:31

docs(cli-backends): document ownsNativeCompaction opt-out contract

87d69b9

refactor(agents): trim native compaction ownership follow-up

2384d73

obviyus force-pushed the feat/generalized-native-compaction-ownership branch from a1516cc to 2384d73 Compare June 2, 2026 09:03

obviyus merged commit db576c4 into openclaw:main Jun 2, 2026
158 checks passed

ElliotDrel mentioned this pull request Jun 10, 2026

claude-cli resume binding survives long-lived session lifecycle and can bypass compaction #84593

Open

clawsweeper Bot mentioned this pull request Jun 25, 2026

claude-cli backend: no pre-compaction handoff flush + scary bare 100% context display #96858

Closed

anagnorisis2peripeteia deleted the feat/generalized-native-compaction-ownership branch July 13, 2026 12:29

Uh oh!

Uh oh!

Conversation

anagnorisis2peripeteia commented May 30, 2026 • edited by obviyus Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What changed since review

Testing

Real behavior proof

Uh oh!

clawsweeper Bot commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anagnorisis2peripeteia commented May 30, 2026

Uh oh!

clawsweeper Bot commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anagnorisis2peripeteia commented May 31, 2026

Uh oh!

clawsweeper Bot commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anagnorisis2peripeteia commented May 31, 2026

Uh oh!

clawsweeper Bot commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anagnorisis2peripeteia commented May 31, 2026

Uh oh!

clawsweeper Bot commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

anagnorisis2peripeteia commented May 31, 2026

Uh oh!

clawsweeper Bot commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

obviyus commented Jun 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

anagnorisis2peripeteia commented May 30, 2026 •

edited by obviyus

Loading

clawsweeper Bot commented May 30, 2026 •

edited

Loading

clawsweeper Bot commented May 30, 2026 •

edited

Loading

clawsweeper Bot commented May 31, 2026 •

edited

Loading

clawsweeper Bot commented May 31, 2026 •

edited

Loading

clawsweeper Bot commented May 31, 2026 •

edited

Loading

clawsweeper Bot commented May 31, 2026 •

edited

Loading