openclaw - ✅(Solved) Fix Bootstrap: preserve effective AGENTS source across compaction, retry, reset, and reinjection [5 pull requests, 1 participants]

100yenadmin · 2026-04-10T10:21:18Z

[openclaw] Hard-coded rereads of AGENTS.md outside the initial bootstrap path can cause a run to regain the wrong AGENTS source after compaction, retry, reset,… Hard-coded rereads of `AGENTS.md` outside the initial bootstrap path can cause a run to regain the wrong AGENTS source after compaction, retry, reset, or continuation-style reinjection. For the planned model-aware AGENTS/SubAGENTS feature, the selected AGENTS source must remain stable for the lifetime of the run context. If the runtime initially injects `SUBAGENTS.md` or `AGENTS.gpt-5.4.md`, later bootstrap refresh paths must not silently fall back to `workspace/AGENTS.md`. # PR #64264: fix(bootstrap): use effective AGENTS source across compaction, retry, and reinjection - Repository: openclaw/openclaw - Author: 100yenadmin - State: open | 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/

openclaw2026-04-10 10:21:18

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#64246•Fetched 2026-04-11 06:15:42

View on GitHub

Comments

Participants

Timeline

Reactions

Author

100yenadmin

Participants

100yenadmin

Timeline (top)

cross-referenced ×6

Hard-coded rereads of AGENTS.md outside the initial bootstrap path can cause a run to regain the wrong AGENTS source after compaction, retry, reset, or continuation-style reinjection.

For the planned model-aware AGENTS/SubAGENTS feature, the selected AGENTS source must remain stable for the lifetime of the run context. If the runtime initially injects SUBAGENTS.md or AGENTS.gpt-5.4.md, later bootstrap refresh paths must not silently fall back to workspace/AGENTS.md.

Root Cause

This is both a correctness issue and a security issue:

subagents should not regain broader orchestrator instructions after compaction
model-optimized prompt variants should stay stable across retries
diagnostics and prompt reports should reflect the actual injected file, not a fallback default

Fix Action

Fixed

Fixed by PR: fix(bootstrap): use effective AGENTS source across compaction, retry, and reinjection (https://github.com/openclaw/openclaw/pull/64264)
Fixed by PR: feat(agents): model-aware AGENTS and SUBAGENTS bootstrap selection (https://github.com/openclaw/openclaw/pull/64266)
Fixed by PR: docs(agents): document model-aware AGENTS and SUBAGENTS migration (https://github.com/openclaw/openclaw/pull/64265)
Fixed by PR: feat(agents): model-aware AGENTS and SUBAGENTS bootstrap selection (https://github.com/openclaw/openclaw/pull/64502)
Fixed by PR: feat(agents): model-aware AGENTS and SUBAGENTS bootstrap selection (https://github.com/openclaw/openclaw/pull/64504)

PR fix notes

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

Repository: openclaw/openclaw
Author: 100yenadmin
State: open | 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 #64265: docs(agents): document model-aware AGENTS and SUBAGENTS migration

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

Description (problem / solution / changelog)

Why

This PR documents the shipped core feature in plain English and engineering terms.

The goal is to make the model-aware AGENTS behavior understandable to three audiences:

end users who just want to configure different prompt files for different models
maintainers reviewing the runtime behavior and security implications
AI-agent users trying to understand why they might want a different worker prompt for GPT-5.4 than for Claude/Opus-style orchestrator runs

What Changed

document the new agentsFile and agentsFilesByModel keys for main agents and sub-agents
document the per-agent override surface under agents.list[] and agents.list[].subagents
explain selection order and fallback behavior
explain why sub-agents should keep a narrowed AGENTS source through compaction/reinjection
add migration guidance from plugin-only SubAgent Context Limiter setups
add examples, scenarios, and Mermaid diagrams in the subagents and system prompt docs

Docs Included

How To Review

Recommended review path:

review #64263 first
review #64264 second
then review the docs-only delta here: parity -> docs compare

User Scenarios Covered

main orchestrator on anthropic/claude-opus-4-6, workers on openai/gpt-5.4
narrower SUBAGENTS.md for workers as a security/least-privilege boundary
model-specific worker variants such as SUBAGENTS.gpt-5.4.md
exact-match fallback behavior when no model-specific override exists
prompt-shape tuning by model without rewriting the team's primary workspace AGENTS.md

Validation

pnpm test -- src/config/schema.base.generated.test.ts src/config/doc-baseline.integration.test.ts

Merge Order

This is PR 3 of 3.

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

After the earlier PRs merge, GitHub will automatically shrink this PR down to the docs-only remainder.

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, +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, +22/-0)
src/agents/workspace.ts (modified, +49/-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, +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 #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: open | 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)

RAW_BUFFERClick to expand / collapse

Summary

Hard-coded rereads of AGENTS.md outside the initial bootstrap path can cause a run to regain the wrong AGENTS source after compaction, retry, reset, or continuation-style reinjection.

Problem

The initial bootstrap assembly is only one part of the effective prompt lifecycle. OpenClaw also rereads bootstrap context during:

post-compaction context refresh
compaction safeguard summaries
retry / repeated-attempt flows
reinjection / continuation skip paths

Any path that directly reads workspace/AGENTS.md instead of the effective selected AGENTS source breaks consistency and can widen subagent exposure after the first turn.

Desired behavior

All bootstrap refresh and reinjection paths should use the same resolved AGENTS source that was selected for the run based on:

run role (main vs subagent)
target workspace
resolved model
configured base file / per-model override

Why this matters

This is both a correctness issue and a security issue:

subagents should not regain broader orchestrator instructions after compaction
model-optimized prompt variants should stay stable across retries
diagnostics and prompt reports should reflect the actual injected file, not a fallback default

Related work

Related #63216
Related #25369
Related #53706
Planned umbrella: model-aware AGENTS/SUBAGENTS bootstrap selection

Acceptance criteria

No hard-coded workspace/AGENTS.md fallback remains in compaction/retry/reinjection paths that should use the effective AGENTS source
Embedded and CLI flows preserve the same AGENTS source across retries and prompt refreshes
Tests lock in parity for subagent and model-specific AGENTS variants

extent analysis

TL;DR

Remove hard-coded references to workspace/AGENTS.md and ensure all bootstrap refresh and reinjection paths use the resolved AGENTS source selected for the run.

Guidance

Identify and refactor code paths that directly read workspace/AGENTS.md to use the effective selected AGENTS source instead.
Review post-compaction context refresh, compaction safeguard summaries, retry/repeated-attempt flows, and reinjection/continuation skip paths for hard-coded workspace/AGENTS.md references.
Ensure that the resolved AGENTS source is determined based on run role, target workspace, resolved model, and configured base file/per-model override.
Verify that embedded and CLI flows preserve the same AGENTS source across retries and prompt refreshes.

Example

No specific code snippet can be provided without more context, but an example of using the resolved AGENTS source might involve replacing a line like agents_source = 'workspace/AGENTS.md' with agents_source = get_effective_agents_source(run_role, target_workspace, resolved_model, base_file_override).

Notes

This fix requires careful review of the codebase to ensure all relevant paths are updated to use the resolved AGENTS source. Additionally, thorough testing is necessary to lock in parity for subagent and model-specific AGENTS variants.

Recommendation

Apply workaround by removing hard-coded workspace/AGENTS.md references and implementing a mechanism to use the resolved AGENTS source selected for the run, as this will ensure consistency and prevent subagent exposure after the first turn.

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?

#database connection #vector store #embedding generation #cache error #pipeline error

Still need to ship something?

×6

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