- If reserve headroom is already high, fallback guidance should avoid always suggesting `reserveTokensFloor` as primary fix. - Retry path should avoid repeatedly re-inflating prompt context where possible. - If truncation reports `empty session`, recovery should either branch to a minimal context execution path or provide a more actionable root-cause diagnostic.

openclaw - ✅(Solved) Fix [Bug]: Repeated hard resets on same session key despite high reserveTokensFloor; retry loop re-injects bootstrap context [4 pull requests, 1 participants]

sisutuulenisa · 2026-04-08T15:22:42Z

[openclaw] OpenClaw repeatedly hits hard context-overflow resets on a specific group session key: - agent:main:voltti:group:46679641 This happens even with hig… OpenClaw repeatedly hits hard context-overflow resets on a specific group session key: - `agent:main:voltti:group:46679641` This happens even with high compaction headroom configured (`reserveTokensFloor` already above the recommended value), and after aggressive pruning/compaction tuning. The user-facing fallback message suggests increasing `agents.defaults.compaction.reserveTokensFloor`, but in this case it is already high and does not resolve the loop. # PR #64264: fix(bootstrap): use effective AGENTS source across compaction, retry, and reinjection - Repository: openclaw/openclaw - Author: 100yenadmin - State: closed | merged: False - Link: https://github.com/openclaw/openclaw/pull/64264 ## Description (problem / solution / changelog) ## Why This PR keeps model-aware AGENTS selection intact after the first bootstrap pass. Without this layer, sub-agents can start with a narrowed worker file such as `SUBAGENTS.md`, but later compaction or post-compaction refresh paths can silently fall back to the main workspace `AGENTS.md`. That breaks the least-privilege goal and makes model-specific tuning inconsistent over time. ## What Changed - switch post-compaction reinjection to the same effective AGENTS source selected during bootstrap - switch compaction-safeguard summaries to the same effective AGENTS source - reuse already-loaded AGENTS content where possible instead of reopening the same file - thread the agent/session/model context needed to resolve the correct AGENTS source in compaction paths - keep sub-agent AGENTS narrowing intact after continuation, compaction, retry, and reinjection flows ## How To Review GitHub only allows upstream PRs to use base branches that exist in `openclaw/openclaw` itself. Because the staging branches in this stack live on the fork, this PR still targets `main` upstream even though it is logically PR 2 of 3. Recommended review path: 1. review #64263 first 2. then review the parity-only delta here: [bootstrap -> parity compare](https://github.com/100yenadmin/openclaw-1/compare/codex/modelaware-agents-bootstrap...codex/modelaware-agents-parity) 3. then look at the compaction-specific files in this PR Key files: - [src/auto-reply/reply/post-compaction-context.ts](https://github.com/openclaw/openclaw/pull/64264/files#diff-c80c74c02a62397d6edb64b8af6c3f2e0e38c6f72a3dcca0c556b4a27f26519e) - [src/agents/pi-hooks/compaction-safeguard.ts](https://github.com/openclaw/openclaw/pull/64264/files#diff-aab3dc10e4d1d86a2254ea5d8dbe0c25ae2e7f57aa1bdd2f6f7ae2a245e2d437) - [src/auto-reply/reply/agent-runner.ts](https://github.com/openclaw/openclaw/pull/64264/files) ## Acceptance Criteria - a sub-agent that starts with `SUBAGENTS.md` or `SUBAGENTS.gpt-5.4.md` keeps that effective AGENTS source after compaction - post-compaction refresh does not reread hardcoded workspace `AGENTS.md` - compaction-safeguard summary generation does not reread hardcoded workspace `AGENTS.md` - already-loaded AGENTS content is reused when available ## Validation - `pnpm test -- src/auto-reply/reply/post-compaction-context.test.ts src/agents/pi-hooks/compaction-safeguard.test.ts src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts` - `pnpm build` ## Merge Order This is PR 2 of 3. - #64263 first - this PR second - #64265 third - #64504 tracks the full stack After #64263 merges, GitHub will automatically shrink this PR down to the parity-only remainder. ## Links - Closes #64246 - Part of #64248 - Related to #63216 - Related to #25369 - Related to #53706 - Tracked by #64504 ## Changed files - `src/agents/agent-scope.ts` (modified, +7/-0) - `src/agents/bootstrap-files.test.ts` (modified, +368/-0) - `src/agents/bootstrap-files.ts` (modified, +338/-9) - `src/agents/bootstrap-hooks.ts` (modified, +4/-0) - `src/agents/cli-runner.spawn.test.ts` (modified, +33/-1) - `src/agents/cli-runner.test-support.ts` (modified, +8/-1) - `src/agents/cli-runner/prepare.ts` (modified, +3/-0) - `src/agents/pi-embedded-runner/compact.ts` (modified, +8/-0) - `src/agents/pi-embedded-runner/extensions.ts` (modified, +11/-0) - `src/agents/pi-embedded-runner/run/attempt.context-engine-helpers.ts` (modified, +21/-5) - `src/agents/pi-embedded-runner/run/attempt.spawn-workspace.context-injection.test.ts` (modified, +53/-2) - `src/agents/pi-embedded-runner/run/attempt.ts` (modified, +54/-11) - `src/agents/pi-hooks/compaction-safeguard-runtime.ts` (modified, +8/-0) - `src/agents/pi-hooks/compaction-safeguard.test.ts` (modified, +55/-0) - `src/agents/pi-hooks/compaction-safeguard.ts` (modified, +39/-22) - `src/agents/workspace.test.ts` (modified, +45/-0) - `src/agents/workspace.ts` (modified, +60/-22) - `src/auto-reply/reply/agent-runner-memory.ts` (modified, +9/-0) - `src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts` (modified, +80/-1) - `src/auto-reply/reply/agent-runner.ts`

openclaw2026-04-08 15:22:42

ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

GitHub issue URL

Helpful · Quick feedback

GitHub stats

openclaw/openclaw#63216•Fetched 2026-04-09 07:56:49

View on GitHub

Comments

Participants

Timeline

Reactions

Author

sisutuulenisa

Participants

sisutuulenisa

OpenClaw repeatedly hits hard context-overflow resets on a specific group session key:

agent:main:voltti:group:46679641

This happens even with high compaction headroom configured (reserveTokensFloor already above the recommended value), and after aggressive pruning/compaction tuning.

The user-facing fallback message suggests increasing agents.defaults.compaction.reserveTokensFloor, but in this case it is already high and does not resolve the loop.

Root Cause

OpenClaw repeatedly hits hard context-overflow resets on a specific group session key:

agent:main:voltti:group:46679641

This happens even with high compaction headroom configured (reserveTokensFloor already above the recommended value), and after aggressive pruning/compaction tuning.

The user-facing fallback message suggests increasing agents.defaults.compaction.reserveTokensFloor, but in this case it is already high and does not resolve the loop.

PR fix notes

PR #64264: fix(bootstrap): use effective AGENTS source across compaction, retry, and reinjection

Repository: openclaw/openclaw
Author: 100yenadmin
State: closed | merged: False
Link: https://github.com/openclaw/openclaw/pull/64264

Description (problem / solution / changelog)

Why

This PR keeps model-aware AGENTS selection intact after the first bootstrap pass.

Without this layer, sub-agents can start with a narrowed worker file such as SUBAGENTS.md, but later compaction or post-compaction refresh paths can silently fall back to the main workspace AGENTS.md. That breaks the least-privilege goal and makes model-specific tuning inconsistent over time.

What Changed

switch post-compaction reinjection to the same effective AGENTS source selected during bootstrap
switch compaction-safeguard summaries to the same effective AGENTS source
reuse already-loaded AGENTS content where possible instead of reopening the same file
thread the agent/session/model context needed to resolve the correct AGENTS source in compaction paths
keep sub-agent AGENTS narrowing intact after continuation, compaction, retry, and reinjection flows

How To Review

GitHub only allows upstream PRs to use base branches that exist in openclaw/openclaw itself. Because the staging branches in this stack live on the fork, this PR still targets main upstream even though it is logically PR 2 of 3.

Recommended review path:

review #64263 first
then review the parity-only delta here: bootstrap -> parity compare
then look at the compaction-specific files in this PR

Key files:

Acceptance Criteria

a sub-agent that starts with SUBAGENTS.md or SUBAGENTS.gpt-5.4.md keeps that effective AGENTS source after compaction
post-compaction refresh does not reread hardcoded workspace AGENTS.md
compaction-safeguard summary generation does not reread hardcoded workspace AGENTS.md
already-loaded AGENTS content is reused when available

Validation

pnpm test -- src/auto-reply/reply/post-compaction-context.test.ts src/agents/pi-hooks/compaction-safeguard.test.ts src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts
pnpm build

Merge Order

This is PR 2 of 3.

#64263 first
this PR second
#64265 third
#64504 tracks the full stack

After #64263 merges, GitHub will automatically shrink this PR down to the parity-only remainder.

Changed files

src/agents/agent-scope.ts (modified, +7/-0)
src/agents/bootstrap-files.test.ts (modified, +368/-0)
src/agents/bootstrap-files.ts (modified, +338/-9)
src/agents/bootstrap-hooks.ts (modified, +4/-0)
src/agents/cli-runner.spawn.test.ts (modified, +33/-1)
src/agents/cli-runner.test-support.ts (modified, +8/-1)
src/agents/cli-runner/prepare.ts (modified, +3/-0)
src/agents/pi-embedded-runner/compact.ts (modified, +8/-0)
src/agents/pi-embedded-runner/extensions.ts (modified, +11/-0)
src/agents/pi-embedded-runner/run/attempt.context-engine-helpers.ts (modified, +21/-5)
src/agents/pi-embedded-runner/run/attempt.spawn-workspace.context-injection.test.ts (modified, +53/-2)
src/agents/pi-embedded-runner/run/attempt.ts (modified, +54/-11)
src/agents/pi-hooks/compaction-safeguard-runtime.ts (modified, +8/-0)
src/agents/pi-hooks/compaction-safeguard.test.ts (modified, +55/-0)
src/agents/pi-hooks/compaction-safeguard.ts (modified, +39/-22)
src/agents/workspace.test.ts (modified, +45/-0)
src/agents/workspace.ts (modified, +60/-22)
src/auto-reply/reply/agent-runner-memory.ts (modified, +9/-0)
src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts (modified, +80/-1)
src/auto-reply/reply/agent-runner.ts (modified, +7/-2)
src/auto-reply/reply/commands-compact.ts (modified, +1/-0)
src/auto-reply/reply/post-compaction-context.test.ts (modified, +51/-0)
src/auto-reply/reply/post-compaction-context.ts (modified, +48/-20)
src/config/schema.base.generated.ts (modified, +114/-2)
src/config/schema.help.ts (modified, +17/-1)
src/config/schema.labels.ts (modified, +8/-0)
src/config/types.agent-defaults.ts (modified, +33/-0)
src/config/types.agents.ts (modified, +12/-1)
src/config/zod-schema.agent-defaults.test.ts (modified, +17/-0)
src/config/zod-schema.agent-defaults.ts (modified, +3/-0)
src/config/zod-schema.agent-runtime.ts (modified, +7/-0)
src/gateway/server-methods/sessions.ts (modified, +1/-0)
src/hooks/internal-hooks.ts (modified, +2/-0)
src/shared/avatar-policy.test.ts (modified, +1/-0)
src/shared/avatar-policy.ts (modified, +4/-4)

PR #64266: feat(agents): model-aware AGENTS and SUBAGENTS bootstrap selection

Repository: openclaw/openclaw
Author: 100yenadmin
State: closed | merged: False
Link: https://github.com/openclaw/openclaw/pull/64266

Description (problem / solution / changelog)

Purpose

This is the real non-draft umbrella PR for the full model-aware AGENTS / SUBAGENTS rollout.

It tracks the end-to-end integration of:

core model-aware AGENTS selection
sub-agent-specific AGENTS narrowing
compaction/reinjection parity
docs and migration guidance

Why This Improves OpenClaw

This feature gives users a supported core way to tune prompt shape by both run role and model.

Examples:

keep a broader planning/orchestration file for a main agent on anthropic/claude-opus-4-6
give GPT-5.4 workers a shorter, stricter SUBAGENTS.gpt-5.4.md with tighter task boundaries and less global policy overhead
keep that narrowed worker context intact even after compaction instead of silently reverting to the main AGENTS.md

This is not a benchmark claim about one model being universally better than another. It is a prompt-control feature: different models often respond better to different context density, output constraints, and task framing.

Review Order

Because I only have READ permission on openclaw/openclaw, GitHub will not let me stack these upstream PRs on fork-only base branches. So the child PRs all target main, and later PRs temporarily include prerequisite commits until earlier PRs merge.

Recommended review order:

#64263
#64264
#64265
this PR for the final integrated view

Helpful delta links:

bootstrap -> parity: compare view
parity -> docs: compare view

Rollout Diagram

flowchart LR
    A["Run starts"] --> B["Determine role: main or subagent"]
    B --> C["Resolve actual runtime model"]
    C --> D["Select AGENTS source from base + model overrides"]
    D --> E["Apply agent:bootstrap hooks"]
    E --> F["Inject project context"]
    F --> G["Reuse same effective AGENTS source for continuation / compaction / reinjection"]

Child PRs

#64263 feat(bootstrap): add model-aware AGENTS file selection config and resolved-model plumbing
- core config, runtime model plumbing, bootstrap signature behavior
#64264 fix(bootstrap): use effective AGENTS source across compaction, retry, and reinjection
- parity for compaction/post-compaction paths so narrowed worker AGENTS files stay narrowed
#64265 docs(agents): document model-aware AGENTS and SUBAGENTS migration
- plain-English docs, engineering docs, config reference, migration notes, diagrams

Acceptance Criteria

main/orchestrator runs can use a model-specific AGENTS file
sub-agents can use a different AGENTS base file than the main agent
exact provider/model overrides work for both main and sub-agent runs
invalid overrides warn and fall back safely
continuation, compaction, and reinjection reuse the same effective AGENTS source
docs explain the feature clearly for users and maintainers

Local Validation

pnpm test -- src/agents/bootstrap-files.test.ts src/agents/workspace.test.ts src/agents/cli-runner.spawn.test.ts src/agents/pi-embedded-runner/run/attempt.spawn-workspace.context-injection.test.ts
pnpm test -- src/auto-reply/reply/post-compaction-context.test.ts src/agents/pi-hooks/compaction-safeguard.test.ts src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts
pnpm test -- src/config/schema.base.generated.test.ts src/config/doc-baseline.integration.test.ts
pnpm build

Issue Tree

Umbrella: #64248
Reused upstream issue: #31070
Child issue: #64246
Child issue: #64247
Related upstream issue: #46595
Related upstream issue: #45413

Related Upstream Work

Issues: #31070, #46595, #45413, #50263, #22438, #50876, #59900, #63216, #56029
PRs: #62264, #42781, #44862, #39284, #31901, #9977, #22439, #53706, #29404

Changed files

.oxfmtrc.jsonc (modified, +2/-2)
.oxlintrc.json (modified, +4/-5)
CHANGELOG.md (modified, +46/-1)
docs/.generated/plugin-sdk-api-baseline.sha256 (modified, +2/-2)
docs/concepts/qa-e2e-automation.md (modified, +4/-0)
docs/concepts/system-prompt.md (modified, +35/-2)
docs/gateway/cli-backends.md (modified, +8/-0)
docs/gateway/configuration-reference.md (modified, +89/-4)
docs/gateway/security/index.md (modified, +4/-4)
docs/help/testing.md (modified, +4/-0)
docs/plugins/manifest.md (modified, +25/-0)
docs/reference/templates/AGENTS.md (modified, +0/-3)
docs/tools/browser.md (modified, +2/-2)
docs/tools/skills.md (modified, +7/-0)
docs/tools/subagents.md (modified, +140/-1)
extensions/acpx/package.json (modified, +1/-1)
extensions/active-memory/index.test.ts (modified, +20/-20)
extensions/amazon-bedrock/package.json (modified, +1/-1)
extensions/anthropic/stream-wrappers.test.ts (modified, +5/-5)
extensions/browser/index.test.ts (modified, +1/-1)
extensions/browser/src/browser-tool.ts (modified, +1/-1)
extensions/browser/src/browser/bridge-server.auth.test.ts (modified, +10/-1)
extensions/browser/src/browser/bridge-server.ts (modified, +12/-7)
extensions/browser/src/browser/cdp.helpers.test.ts (added, +65/-0)
extensions/browser/src/browser/cdp.helpers.ts (modified, +45/-10)
extensions/browser/src/browser/cdp.test.ts (modified, +23/-6)
extensions/browser/src/browser/cdp.ts (modified, +2/-1)
extensions/browser/src/browser/chrome-mcp.snapshot.ts (modified, +1/-1)
extensions/browser/src/browser/chrome-mcp.ts (modified, +1/-1)
extensions/browser/src/browser/chrome.test.ts (modified, +2/-2)
extensions/browser/src/browser/chrome.ts (modified, +14/-6)
extensions/browser/src/browser/client-actions-core.ts (modified, +2/-87)
extensions/browser/src/browser/client-actions.types.ts (added, +87/-0)
extensions/browser/src/browser/client-fetch.ts (modified, +14/-12)
extensions/browser/src/browser/client.ts (modified, +2/-19)
extensions/browser/src/browser/client.types.ts (added, +19/-0)
extensions/browser/src/browser/config.test.ts (modified, +15/-4)
extensions/browser/src/browser/config.ts (modified, +4/-4)
extensions/browser/src/browser/errors.test.ts (modified, +26/-1)
extensions/browser/src/browser/errors.ts (modified, +21/-1)
extensions/browser/src/browser/form-fields.ts (modified, +1/-1)
extensions/browser/src/browser/local-dispatch.runtime.ts (added, +20/-0)
extensions/browser/src/browser/navigation-guard.test.ts (modified, +88/-0)
extensions/browser/src/browser/navigation-guard.ts (modified, +40/-1)
extensions/browser/src/browser/profiles-service.test.ts (modified, +3/-1)
extensions/browser/src/browser/profiles-service.ts (modified, +5/-5)
extensions/browser/src/browser/pw-session.create-page.navigation-guard.test.ts (modified, +51/-1)
extensions/browser/src/browser/pw-session.ts (modified, +71/-13)
extensions/browser/src/browser/pw-tools-core.interactions.navigation-guard.test.ts (modified, +563/-2)
extensions/browser/src/browser/pw-tools-core.interactions.ts (modified, +132/-42)
extensions/browser/src/browser/pw-tools-core.test-harness.ts (modified, +19/-0)
extensions/browser/src/browser/routes/agent.act.existing-session-navigation-guard.test.ts (added, +385/-0)
extensions/browser/src/browser/routes/agent.act.normalize.ts (modified, +1/-1)
extensions/browser/src/browser/routes/agent.act.ts (modified, +223/-63)
extensions/browser/src/browser/routes/tabs.test.ts (added, +112/-0)
extensions/browser/src/browser/routes/tabs.ts (modified, +6/-0)
extensions/browser/src/browser/server-context.loopback-direct-ws.test.ts (modified, +22/-0)
extensions/browser/src/browser/server-context.remote-profile-tab-ops.playwright.test.ts (modified, +45/-3)
extensions/browser/src/browser/server-context.remote-tab-ops.harness.ts (modified, +3/-3)
extensions/browser/src/browser/server-context.selection.ts (modified, +15/-2)
extensions/browser/src/browser/server-context.tab-ops.ts (modified, +22/-6)
extensions/browser/src/browser/server-context.ts (modified, +1/-8)
extensions/browser/src/browser/server-context.types.ts (modified, +1/-2)
extensions/browser/src/browser/server-middleware.ts (modified, +16/-1)
extensions/browser/src/browser/server.control-server.test-harness.ts (modified, +1/-0)
extensions/device-pair/index.test.ts (modified, +1/-1)
extensions/device-pair/openclaw.plugin.json (modified, +6/-0)
extensions/diffs/assets/viewer-runtime.js (modified, +48/-48)
extensions/diffs/package.json (modified, +1/-1)
extensions/diffs/src/language-hints.ts (modified, +8/-1)
extensions/diffs/src/viewer-payload.ts (modified, +4/-1)
extensions/discord/package.json (modified, +1/-1)
extensions/discord/src/monitor/thread-title.generate.test.ts (modified, +4/-4)
extensions/discord/src/monitor/thread-title.ts (modified, +6/-1)
extensions/discord/src/voice/manager.e2e.test.ts (modified, +3/-1)
extensions/feishu/src/bot.broadcast.test.ts (modified, +4/-1)
extensions/feishu/src/client.ts (modified, +46/-3)
extensions/feishu/src/monitor.account.ts (modified, +12/-22)
extensions/feishu/src/monitor.bot-menu.test.ts (modified, +1/-1)
extensions/feishu/src/probe.test.ts (modified, +7/-6)
extensions/feishu/src/probe.ts (modified, +15/-14)
extensions/feishu/src/reply-dispatcher.test.ts (modified, +1/-1)
extensions/feishu/src/sequential-key.test.ts (added, +72/-0)
extensions/feishu/src/sequential-key.ts (added, +25/-0)
extensions/feishu/src/sequential-queue.test.ts (added, +64/-0)
extensions/feishu/src/sequential-queue.ts (added, +15/-0)
extensions/feishu/src/streaming-card.ts (modified, +6/-1)
extensions/feishu/src/tool-account-routing.test.ts (modified, +1/-1)
extensions/github-copilot/stream.test.ts (modified, +3/-3)
extensions/google/oauth.test.ts (modified, +20/-4)
extensions/google/package.json (modified, +1/-1)
extensions/google/video-generation-provider.test.ts (modified, +0/-4)
extensions/imessage/src/media-contract.ts (modified, +1/-1)
extensions/irc/src/channel.ts (modified, +1/-5)
extensions/lobster/package.json (modified, +1/-1)
extensions/matrix/SPEC-SUPPORT.md (added, +116/-0)
extensions/matrix/package.json (modified, +1/-1)
extensions/matrix/src/actions.account-propagation.test.ts (modified, +41/-0)
extensions/matrix/src/actions.test.ts (modified, +26/-0)
extensions/matrix/src/actions.ts (modified, +9/-4)

PR #64502: feat(agents): model-aware AGENTS and SUBAGENTS bootstrap selection

Repository: openclaw/openclaw
Author: 100yenadmin
State: closed | merged: False
Link: https://github.com/openclaw/openclaw/pull/64502

Description (problem / solution / changelog)

Purpose

This is the live non-draft umbrella PR for the full model-aware AGENTS / SUBAGENTS rollout.

It tracks the end-to-end integration of:

core model-aware AGENTS selection
sub-agent-specific AGENTS narrowing
compaction/reinjection parity
docs and migration guidance

Why This Improves OpenClaw

This feature gives users a supported core way to tune prompt shape by both run role and model.

Examples:

keep a broader planning/orchestration file for a main agent on anthropic/claude-opus-4-6
give GPT-5.4 workers a shorter, stricter SUBAGENTS.gpt-5.4.md with tighter task boundaries and less global policy overhead
keep that narrowed worker context intact even after compaction instead of silently reverting to the main AGENTS.md

What Changed Across The Stack

add schema-backed model-aware AGENTS file selection for both main and sub-agent runs
support exact provider/model overrides for both base AGENTS files and narrowed sub-agent files
resolve the effective AGENTS source after runtime model normalization
preserve the same effective AGENTS source through continuation, compaction, retry, and reinjection
document the feature in plain English, engineering terms, and migration scenarios from plugin-only SubAgent Context Limiter setups

Review Order

GitHub only allows upstream PRs to retarget branches that exist in openclaw/openclaw itself. Because these staging branches exist on the fork, the child PRs still target main upstream even though they form a logical stack.

Recommended review order:

#64263
#64264
#64265
this PR for the integrated final view

Helpful delta links:

bootstrap -> parity: compare view
parity -> docs: compare view
docs -> umbrella: compare view

Mental Model

flowchart LR
    A["Run starts"] --> B["Determine role: main or subagent"]
    B --> C["Resolve actual runtime model"]
    C --> D["Pick base AGENTS file for that role"]
    D --> E["Apply exact model override if configured"]
    E --> F["Apply bootstrap hooks and inject context"]
    F --> G["Reuse the same effective AGENTS source for continuation / compaction / reinjection"]

Scenarios

GPT-5.4 worker scenario

A team can keep a broad orchestrator file for a planning-oriented main agent, but give openai/gpt-5.4 workers a more explicit SUBAGENTS.gpt-5.4.md with shorter instructions, tighter scope, and stricter output expectations.

Opus / Claude orchestrator scenario

A team can keep anthropic/claude-opus-4-6 on a broader orchestration-oriented AGENTS variant that includes more planning context and delegation guidance, without forcing every worker model to carry that same context.

Security / least-privilege scenario

A sub-agent can start with SUBAGENTS.md instead of full AGENTS.md, and compaction will continue to reuse that narrowed source rather than silently broadening the worker's instructions later.

Child PRs

#64263 feat(bootstrap): add model-aware AGENTS file selection config and resolved-model plumbing
- core config, runtime model plumbing, bootstrap signature behavior
#64264 fix(bootstrap): use effective AGENTS source across compaction, retry, and reinjection
- compaction/post-compaction parity so narrowed worker AGENTS files stay narrowed
#64265 docs(agents): document model-aware AGENTS and SUBAGENTS migration
- plain-English docs, engineering docs, config reference, migration notes, diagrams

Acceptance Criteria

main/orchestrator runs can use a model-specific AGENTS file
sub-agents can use a different AGENTS base file than the main agent
exact provider/model overrides work for both main and sub-agent runs
invalid overrides warn and fall back safely
continuation, compaction, and reinjection reuse the same effective AGENTS source
docs explain the feature clearly for users and maintainers

Local Validation

pnpm test -- src/agents/bootstrap-files.test.ts src/agents/workspace.test.ts src/agents/cli-runner.spawn.test.ts src/agents/pi-embedded-runner/run/attempt.spawn-workspace.context-injection.test.ts
pnpm test -- src/auto-reply/reply/post-compaction-context.test.ts src/agents/pi-hooks/compaction-safeguard.test.ts src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts
pnpm test -- src/config/schema.base.generated.test.ts src/config/doc-baseline.integration.test.ts
pnpm build

Issue Tree

Umbrella: #64248
Reused upstream issue: #31070
Child issue: #64246
Child issue: #64247
Related upstream issue: #46595
Related upstream issue: #45413

Related Upstream Work

Issues: #31070, #46595, #45413, #50263, #22438, #50876, #59900, #63216, #56029
PRs: #62264, #42781, #44862, #39284, #31901, #9977, #22439, #53706, #29404

Changed files

.oxfmtrc.jsonc (modified, +2/-2)
.oxlintrc.json (modified, +4/-5)
CHANGELOG.md (modified, +46/-1)
INCIDENT_RESPONSE.md (added, +52/-0)
docs/.generated/plugin-sdk-api-baseline.sha256 (modified, +2/-2)
docs/concepts/qa-e2e-automation.md (modified, +4/-0)
docs/concepts/system-prompt.md (modified, +35/-2)
docs/gateway/cli-backends.md (modified, +8/-0)
docs/gateway/configuration-reference.md (modified, +89/-4)
docs/gateway/security/index.md (modified, +4/-4)
docs/help/testing.md (modified, +4/-0)
docs/plugins/manifest.md (modified, +25/-0)
docs/reference/templates/AGENTS.md (modified, +0/-3)
docs/tools/browser.md (modified, +2/-2)
docs/tools/skills.md (modified, +7/-0)
docs/tools/subagents.md (modified, +140/-1)
extensions/acpx/package.json (modified, +1/-1)
extensions/active-memory/index.test.ts (modified, +20/-20)
extensions/amazon-bedrock/package.json (modified, +1/-1)
extensions/anthropic/stream-wrappers.test.ts (modified, +5/-5)
extensions/browser/index.test.ts (modified, +1/-1)
extensions/browser/src/browser-tool.ts (modified, +1/-1)
extensions/browser/src/browser/bridge-server.auth.test.ts (modified, +10/-1)
extensions/browser/src/browser/bridge-server.ts (modified, +12/-7)
extensions/browser/src/browser/cdp.helpers.test.ts (added, +65/-0)
extensions/browser/src/browser/cdp.helpers.ts (modified, +59/-14)
extensions/browser/src/browser/cdp.test.ts (modified, +23/-6)
extensions/browser/src/browser/cdp.ts (modified, +2/-1)
extensions/browser/src/browser/chrome-mcp.snapshot.ts (modified, +1/-1)
extensions/browser/src/browser/chrome-mcp.ts (modified, +1/-1)
extensions/browser/src/browser/chrome.test.ts (modified, +2/-2)
extensions/browser/src/browser/chrome.ts (modified, +14/-6)
extensions/browser/src/browser/client-actions-core.ts (modified, +2/-87)
extensions/browser/src/browser/client-actions.types.ts (added, +87/-0)
extensions/browser/src/browser/client-fetch.ts (modified, +14/-12)
extensions/browser/src/browser/client.ts (modified, +2/-19)
extensions/browser/src/browser/client.types.ts (added, +19/-0)
extensions/browser/src/browser/config.test.ts (modified, +15/-4)
extensions/browser/src/browser/config.ts (modified, +4/-4)
extensions/browser/src/browser/errors.test.ts (modified, +26/-1)
extensions/browser/src/browser/errors.ts (modified, +21/-1)
extensions/browser/src/browser/form-fields.ts (modified, +1/-1)
extensions/browser/src/browser/local-dispatch.runtime.ts (added, +20/-0)
extensions/browser/src/browser/navigation-guard.test.ts (modified, +88/-0)
extensions/browser/src/browser/navigation-guard.ts (modified, +40/-1)
extensions/browser/src/browser/profiles-service.test.ts (modified, +3/-1)
extensions/browser/src/browser/profiles-service.ts (modified, +5/-5)
extensions/browser/src/browser/pw-session.create-page.navigation-guard.test.ts (modified, +51/-1)
extensions/browser/src/browser/pw-session.ts (modified, +71/-13)
extensions/browser/src/browser/pw-tools-core.interactions.navigation-guard.test.ts (modified, +563/-2)
extensions/browser/src/browser/pw-tools-core.interactions.ts (modified, +132/-42)
extensions/browser/src/browser/pw-tools-core.test-harness.ts (modified, +19/-0)
extensions/browser/src/browser/routes/agent.act.existing-session-navigation-guard.test.ts (added, +385/-0)
extensions/browser/src/browser/routes/agent.act.normalize.ts (modified, +1/-1)
extensions/browser/src/browser/routes/agent.act.ts (modified, +223/-63)
extensions/browser/src/browser/routes/tabs.test.ts (added, +112/-0)
extensions/browser/src/browser/routes/tabs.ts (modified, +6/-0)
extensions/browser/src/browser/server-context.loopback-direct-ws.test.ts (modified, +22/-0)
extensions/browser/src/browser/server-context.remote-profile-tab-ops.playwright.test.ts (modified, +45/-3)
extensions/browser/src/browser/server-context.remote-tab-ops.harness.ts (modified, +3/-3)
extensions/browser/src/browser/server-context.selection.ts (modified, +17/-2)
extensions/browser/src/browser/server-context.tab-ops.ts (modified, +31/-8)
extensions/browser/src/browser/server-context.ts (modified, +1/-8)
extensions/browser/src/browser/server-context.types.ts (modified, +1/-2)
extensions/browser/src/browser/server-middleware.ts (modified, +16/-1)
extensions/browser/src/browser/server.control-server.test-harness.ts (modified, +1/-0)
extensions/device-pair/index.test.ts (modified, +1/-1)
extensions/device-pair/openclaw.plugin.json (modified, +6/-0)
extensions/diffs/assets/viewer-runtime.js (modified, +48/-48)
extensions/diffs/package.json (modified, +1/-1)
extensions/diffs/src/language-hints.ts (modified, +8/-1)
extensions/diffs/src/viewer-payload.ts (modified, +4/-1)
extensions/discord/package.json (modified, +1/-1)
extensions/discord/src/monitor/thread-title.generate.test.ts (modified, +4/-4)
extensions/discord/src/monitor/thread-title.ts (modified, +6/-1)
extensions/discord/src/voice/manager.e2e.test.ts (modified, +3/-1)
extensions/feishu/src/bot.broadcast.test.ts (modified, +4/-1)
extensions/feishu/src/client.ts (modified, +46/-3)
extensions/feishu/src/monitor.account.ts (modified, +12/-22)
extensions/feishu/src/monitor.bot-menu.test.ts (modified, +1/-1)
extensions/feishu/src/probe.test.ts (modified, +7/-6)
extensions/feishu/src/probe.ts (modified, +15/-14)
extensions/feishu/src/reply-dispatcher.test.ts (modified, +1/-1)
extensions/feishu/src/sequential-key.test.ts (added, +72/-0)
extensions/feishu/src/sequential-key.ts (added, +25/-0)
extensions/feishu/src/sequential-queue.test.ts (added, +64/-0)
extensions/feishu/src/sequential-queue.ts (added, +15/-0)
extensions/feishu/src/streaming-card.ts (modified, +6/-1)
extensions/feishu/src/tool-account-routing.test.ts (modified, +1/-1)
extensions/github-copilot/stream.test.ts (modified, +3/-3)
extensions/google/oauth.test.ts (modified, +20/-4)
extensions/google/package.json (modified, +1/-1)
extensions/google/video-generation-provider.test.ts (modified, +0/-4)
extensions/imessage/src/media-contract.ts (modified, +1/-1)
extensions/irc/src/channel.ts (modified, +1/-5)
extensions/lobster/package.json (modified, +1/-1)
extensions/matrix/SPEC-SUPPORT.md (added, +116/-0)
extensions/matrix/package.json (modified, +1/-1)
extensions/matrix/src/actions.account-propagation.test.ts (modified, +41/-0)
extensions/matrix/src/actions.test.ts (modified, +26/-0)

PR #64504: feat(agents): model-aware AGENTS and SUBAGENTS bootstrap selection

Repository: openclaw/openclaw
Author: 100yenadmin
State: closed | merged: False
Link: https://github.com/openclaw/openclaw/pull/64504

Description (problem / solution / changelog)

Purpose

This is the umbrella PR for the full model-aware AGENTS / SUBAGENTS rollout.

It tracks the end-to-end integration of:

core model-aware AGENTS selection
sub-agent-specific AGENTS narrowing
compaction/reinjection parity
docs and migration guidance

Why This Improves OpenClaw

This feature gives users a supported core way to tune prompt shape by both run role and model.

Examples:

keep a broader planning/orchestration file for a main agent on anthropic/claude-opus-4-6
give GPT-5.4 workers a shorter, stricter SUBAGENTS.gpt-5.4.md with tighter task boundaries and less global policy overhead
keep that narrowed worker context intact even after compaction instead of silently reverting to the main AGENTS.md

What Changed Across The Stack

add schema-backed model-aware AGENTS file selection for both main and sub-agent runs
support exact provider/model overrides for both base AGENTS files and narrowed sub-agent files
resolve the effective AGENTS source after runtime model normalization
preserve the same effective AGENTS source through continuation, compaction, retry, and reinjection
document the feature in plain English, engineering terms, and migration scenarios from plugin-only SubAgent Context Limiter setups

Review Order

Recommended review order:

#64263
#64264
#64265
this PR for the integrated final view

Helpful delta links:

bootstrap -> parity: compare view
parity -> docs: compare view
docs -> umbrella: compare view

Mental Model

flowchart LR
    A["Run starts"] --> B["Determine role: main or subagent"]
    B --> C["Resolve actual runtime model"]
    C --> D["Pick base AGENTS file for that role"]
    D --> E["Apply exact model override if configured"]
    E --> F["Apply bootstrap hooks and inject context"]
    F --> G["Reuse the same effective AGENTS source for continuation / compaction / reinjection"]

Scenarios

GPT-5.4 worker scenario

Opus / Claude orchestrator scenario

Security / least-privilege scenario

A sub-agent can start with SUBAGENTS.md instead of full AGENTS.md, and compaction will continue to reuse that narrowed source rather than silently broadening the worker's instructions later.

Child PRs

#64263 feat(bootstrap): add model-aware AGENTS file selection config and resolved-model plumbing
- core config, runtime model plumbing, bootstrap signature behavior
#64264 fix(bootstrap): use effective AGENTS source across compaction, retry, and reinjection
- compaction/post-compaction parity so narrowed worker AGENTS files stay narrowed
#64265 docs(agents): document model-aware AGENTS and SUBAGENTS migration
- plain-English docs, engineering docs, config reference, migration notes, diagrams

Acceptance Criteria

main/orchestrator runs can use a model-specific AGENTS file
sub-agents can use a different AGENTS base file than the main agent
exact provider/model overrides work for both main and sub-agent runs
invalid overrides warn and fall back safely
continuation, compaction, and reinjection reuse the same effective AGENTS source
docs explain the feature clearly for users and maintainers

Local Validation

pnpm test -- src/agents/bootstrap-files.test.ts src/agents/workspace.test.ts src/agents/cli-runner.spawn.test.ts src/agents/pi-embedded-runner/run/attempt.spawn-workspace.context-injection.test.ts src/auto-reply/reply/post-compaction-context.test.ts src/agents/pi-hooks/compaction-safeguard.test.ts src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts src/config/schema.base.generated.test.ts src/config/doc-baseline.integration.test.ts
pnpm build

Issue Tree

Umbrella: #64248
Reused upstream issue: #31070
Child issue: #64246
Child issue: #64247
Related upstream issue: #46595
Related upstream issue: #45413

Related Upstream Work

Issues: #31070, #46595, #45413, #50263, #22438, #50876, #59900, #63216, #56029
PRs: #62264, #42781, #44862, #39284, #31901, #9977, #22439, #53706, #29404

Changed files

docs/concepts/system-prompt.md (modified, +35/-2)
docs/gateway/configuration-reference.md (modified, +86/-1)
docs/tools/subagents.md (modified, +140/-1)
src/agents/agent-scope.ts (modified, +7/-0)
src/agents/bootstrap-files.test.ts (modified, +397/-0)
src/agents/bootstrap-files.ts (modified, +355/-9)
src/agents/bootstrap-hooks.ts (modified, +4/-0)
src/agents/cli-runner.spawn.test.ts (modified, +33/-1)
src/agents/cli-runner.test-support.ts (modified, +8/-1)
src/agents/cli-runner/prepare.ts (modified, +3/-0)
src/agents/pi-embedded-runner/compact.ts (modified, +8/-0)
src/agents/pi-embedded-runner/extensions.ts (modified, +11/-0)
src/agents/pi-embedded-runner/run/attempt.context-engine-helpers.ts (modified, +21/-5)
src/agents/pi-embedded-runner/run/attempt.spawn-workspace.context-injection.test.ts (modified, +53/-2)
src/agents/pi-embedded-runner/run/attempt.ts (modified, +54/-11)
src/agents/pi-hooks/compaction-safeguard-runtime.ts (modified, +8/-0)
src/agents/pi-hooks/compaction-safeguard.test.ts (modified, +96/-0)
src/agents/pi-hooks/compaction-safeguard.ts (modified, +43/-22)
src/agents/workspace.test.ts (modified, +39/-0)
src/agents/workspace.ts (modified, +57/-14)
src/auto-reply/reply/agent-runner-memory.ts (modified, +9/-0)
src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts (modified, +80/-1)
src/auto-reply/reply/agent-runner.ts (modified, +7/-2)
src/auto-reply/reply/commands-compact.ts (modified, +1/-0)
src/auto-reply/reply/post-compaction-context.test.ts (modified, +86/-0)
src/auto-reply/reply/post-compaction-context.ts (modified, +52/-20)
src/config/schema.base.generated.ts (modified, +114/-2)
src/config/schema.help.ts (modified, +17/-1)
src/config/schema.labels.ts (modified, +8/-0)
src/config/types.agent-defaults.ts (modified, +33/-0)
src/config/types.agents.ts (modified, +12/-1)
src/config/zod-schema.agent-defaults.test.ts (modified, +17/-0)
src/config/zod-schema.agent-defaults.ts (modified, +3/-0)
src/config/zod-schema.agent-runtime.ts (modified, +7/-0)
src/gateway/server-methods/sessions.ts (modified, +1/-0)
src/hooks/internal-hooks.ts (modified, +2/-0)
src/shared/avatar-policy.test.ts (modified, +1/-0)
src/shared/avatar-policy.ts (modified, +4/-4)

Code Example

[agent] [context-overflow-diag] sessionKey=agent:main:voltti:group:46679641 ... compactionAttempts=3 ...
[agent] [context-overflow-recovery] Attempting tool result truncation ...
[agent] [context-overflow-recovery] Tool result truncation did not help: empty session
Auto-compaction failed (...). Restarting session agent:main:voltti:group:46679641 -> <new-session-id> and retrying.

---

[agent] workspace bootstrap file AGENTS.md is 11593 chars (limit 6000); truncating ...
[agent] workspace bootstrap file TOOLS.md is 13283 chars (limit 1579); truncating ...
[agent] remaining bootstrap budget is 53 chars (<64); skipping additional bootstrap files ...

RAW_BUFFERClick to expand / collapse

Summary

OpenClaw repeatedly hits hard context-overflow resets on a specific group session key:

agent:main:voltti:group:46679641

This happens even with high compaction headroom configured (reserveTokensFloor already above the recommended value), and after aggressive pruning/compaction tuning.

The user-facing fallback message suggests increasing agents.defaults.compaction.reserveTokensFloor, but in this case it is already high and does not resolve the loop.

Environment

OpenClaw: 2026.4.8
Provider/model: openai-codex/gpt-5.3-codex
Channel/plugin path: Basecamp via local Voltti extension
Host: Linux

Relevant config at time of failures:

agents.defaults.compaction.reserveTokensFloor: 60000
agents.defaults.compaction.reserveTokens: 60000
agents.defaults.compaction.keepRecentTokens: 8000
agents.defaults.bootstrapMaxChars: 6000
agents.defaults.bootstrapTotalMaxChars: 12000
agents.defaults.contextPruning.mode: cache-ttl

What happens

For normal inbound Basecamp events in this thread, OpenClaw repeatedly does:

context overflow detected (attempt 1/3)
auto-compaction retry
context overflow detected (attempt 2/3)
auto-compaction retry
context overflow detected (attempt 3/3)
tool result truncation attempt (sometimes)
hard reset/restart of session key to a new session ID

This cycle repeats across multiple newly restarted session IDs.

Representative logs

[agent] [context-overflow-diag] sessionKey=agent:main:voltti:group:46679641 ... compactionAttempts=3 ...
[agent] [context-overflow-recovery] Attempting tool result truncation ...
[agent] [context-overflow-recovery] Tool result truncation did not help: empty session
Auto-compaction failed (...). Restarting session agent:main:voltti:group:46679641 -> <new-session-id> and retrying.

Also observed repeatedly in the same failing cycle:

[agent] workspace bootstrap file AGENTS.md is 11593 chars (limit 6000); truncating ...
[agent] workspace bootstrap file TOOLS.md is 13283 chars (limit 1579); truncating ...
[agent] remaining bootstrap budget is 53 chars (<64); skipping additional bootstrap files ...

This suggests bootstrap context is re-injected on each retry path for the same failing turn.

Why this looks like a bug

The fallback operator hint is misleading in this scenario:
- reserve floor is already high (60000), yet resets continue.
tool result truncation did not help: empty session appears in cases where failures still persist immediately after.
Re-injecting bootstrap context every retry may amplify failure loops in already-tight runs.

Additional related observation

In earlier failing sessions for this same key, duplicate user payloads were observed in transcript history during retries/restarts (same inbound content repeated multiple times with different message IDs/timestamps), which may contribute to avoidable token growth.

Expected behavior

If reserve headroom is already high, fallback guidance should avoid always suggesting reserveTokensFloor as primary fix.
Retry path should avoid repeatedly re-inflating prompt context where possible.
If truncation reports empty session, recovery should either branch to a minimal context execution path or provide a more actionable root-cause diagnostic.

Related issues

#55366 (hard reset UX/state loss)
#10694 (large tool-result overflow)
#15409 (aggregate overflow/truncation blind spot)
#46005 (duplicate user messages causing context bloat)
#54623 (bootstrap truncation visibility)

Request

Please investigate retry-path prompt construction and recovery behavior for cases where:

compaction repeatedly succeeds but overflow immediately reoccurs,
truncation says "did not help: empty session",
and bootstrap injection appears on every retry in the same failing cycle.

extent analysis

TL;DR

Adjust the retry path to minimize re-injection of bootstrap context and investigate the root cause of immediate overflow reoccurrence after compaction.

Guidance

Review the contextPruning.mode configuration to ensure it is optimal for the specific use case, considering the cache-ttl mode may not be suitable for this scenario.
Investigate the bootstrapMaxChars and bootstrapTotalMaxChars settings to determine if they are contributing to the repeated bootstrap context re-injection.
Analyze the transcript history for duplicate user payloads and their impact on token growth, potentially relating to issue #46005.
Consider implementing a more nuanced retry path that branches to a minimal context execution path when truncation reports an empty session.

Example

No code snippet is provided due to the lack of specific implementation details in the issue.

Notes

The provided information suggests a complex interaction between compaction, truncation, and bootstrap context re-injection. The root cause may not be solely related to the reserveTokensFloor setting, and a more detailed analysis of the retry path and context pruning strategy is necessary.

Recommendation

Apply a workaround by adjusting the retry path and context pruning strategy to minimize bootstrap context re-injection and investigate the root cause of immediate overflow reoccurrence. This approach is chosen due to the complexity of the issue and the potential for the workaround to mitigate the problem while a more permanent fix is developed.

Vote matrix · Quick signals

Works

Did the solution work? Tap to confirm.

Easy Fix

Was it a quick fix?

Time Saver

Did it save you time?

Blocking

Was it severely blocking?

Common Issue

Are others likely hitting this too?

Flaky / Intermittent

Is it intermittent?

Verified / Reproducible

Can you reproduce it reliably?

FAQ

Expected behavior

If reserve headroom is already high, fallback guidance should avoid always suggesting reserveTokensFloor as primary fix.
Retry path should avoid repeatedly re-inflating prompt context where possible.
If truncation reports empty session, recovery should either branch to a minimal context execution path or provide a more actionable root-cause diagnostic.

#model loading #dependency error #configuration error #environment variable #network issue

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.