fix(agents): honor hook bootstrap content

[ificator]

Summary

Describe the problem and fix in 2-5 bullets:

• Problem: agent:bootstrap hooks can inject BOOTSTRAP.md content, but embedded-runner bootstrap routing decided whether bootstrap was pending before hook-adjusted files were considered.
• Why it matters: hook-provided required setup instructions could be omitted from the system prompt when the workspace did not already have pending filesystem bootstrap state.
• What changed: preload hook-adjusted bootstrap files before routing, treat non-empty hook-provided BOOTSTRAP.md as pending and accessible bootstrap content, and reuse the preloaded files when building Project Context.
• What did NOT change (scope boundary): no changes to hook contracts, bootstrap file formats, or non-workspace/raw model run behavior.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes N/A
• Related N/A
• This PR fixes a bug or regression

Root Cause (if applicable)

For bug fixes or regressions, explain why this happened, not just what changed. Otherwise write N/A. If the cause is unclear, write Unknown.

• Root cause: resolveAttemptWorkspaceBootstrapRouting() only used filesystem/workspace bootstrap pending state, while agent:bootstrap hook output was resolved later by Project Context generation.
• Missing detection / guardrail: routing tests did not cover hook-injected BOOTSTRAP.md content before this change.
• Contributing context (if known): continuation/context-injection logic already preserves full bootstrap mode, but the route into full mode did not account for hook-provided bootstrap content.

Regression Test Plan (if applicable)

For bug fixes or regressions, name the smallest reliable test coverage that should catch this. Otherwise write N/A.

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/agents/pi-embedded-runner/run/attempt.spawn-workspace.bootstrap-routing.test.ts
• Scenario the test should lock in: non-empty BOOTSTRAP.md content injected by agent:bootstrap selects full bootstrap mode and is included in system Project Context, including when normal file read access is unavailable.
• Why this is the smallest reliable guardrail: the bug lived at the seam between hook-resolved bootstrap files and embedded-runner routing, so the routing spawn test exercises the affected path without a broader E2E.
• Existing test that already covers this (if any): src/agents/pi-embedded-runner/run/attempt.spawn-workspace.context-injection.test.ts covers that full bootstrap mode bypasses continuation-skip behavior.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

Hook-provided required bootstrap instructions are now included in the system prompt when agent:bootstrap injects non-empty BOOTSTRAP.md content.

Diagram (if applicable)

Before:
agent:bootstrap -> BOOTSTRAP.md content -> routing had already decided pending=false -> required setup could be omitted

After:
agent:bootstrap -> BOOTSTRAP.md content -> routing sees pending=true -> Project Context includes required setup

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: Windows_NT
• Runtime/container: Node 22.14.0 via nvs, pnpm 10.33.2
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): N/A

Steps

1. Configure an agent:bootstrap hook that returns non-empty BOOTSTRAP.md content for a workspace without filesystem-pending bootstrap state.
2. Start an embedded workspace attempt that resolves bootstrap routing and Project Context.
3. Inspect the generated system Project Context.

Expected

• Hook-provided BOOTSTRAP.md content makes bootstrap pending and required setup instructions are included in the system prompt.

Actual

• Before this PR, routing could decide bootstrap was not pending before hook output was considered, so hook-provided instructions could be omitted.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Focused verification run:

pnpm test src\agents\pi-embedded-runner\run\attempt.spawn-workspace.bootstrap-routing.test.ts src\agents\pi-embedded-runner\run\attempt.spawn-workspace.context-injection.test.ts -- --reporter=verbose

Changed-gate proof:

pnpm check:changed -- --staged

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: hook-provided non-empty BOOTSTRAP.md triggers full bootstrap mode; hook-provided content remains usable when normal file reads are unavailable; empty hook-provided BOOTSTRAP.md does not mark bootstrap pending.
• Edge cases checked: continuation/full-bootstrap behavior covered by existing context-injection regression test; preloaded bootstrap files are reused so hooks are not double-run for context generation.
• What you did not verify: full repository test suite and live/provider scenarios.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: resolving hook-adjusted bootstrap files before routing could add duplicate hook work.
  • Mitigation: the resolved bootstrap files are reused for Project Context generation.
• Risk: empty hook-provided BOOTSTRAP.md could accidentally force bootstrap.
  • Mitigation: routing only treats non-empty trimmed bootstrap content as pending, with regression coverage.

[clawsweeper]

Codex review: needs maintainer review before merge.

Summary
The PR preloads hook-adjusted bootstrap files before embedded-runner routing, treats non-empty hook-provided BOOTSTRAP.md as pending and accessible bootstrap content, reuses the preloaded files for Project Context, and adds tests plus a changelog entry.

Reproducibility: yes. from source inspection: current main routes from filesystem bootstrap-pending state before agent:bootstrap hook overrides are resolved, so a hook-injected BOOTSTRAP.md cannot select full bootstrap mode. I did not execute tests because this pass was read-only.

Next step before merge
No repair job is needed because the open PR is already the focused implementation and I found no concrete blocker for an automated fix lane.

Security
Cleared: The diff changes in-process bootstrap routing, tests, and changelog only; it adds no dependency, workflow, permission, network, package-resolution, or secret-handling surface.

Review details

Best possible solution:

Land this PR after ordinary maintainer review so hook-injected BOOTSTRAP.md controls full bootstrap mode without changing hook contracts or raw model runs.

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

Yes, from source inspection: current main routes from filesystem bootstrap-pending state before agent:bootstrap hook overrides are resolved, so a hook-injected BOOTSTRAP.md cannot select full bootstrap mode. I did not execute tests because this pass was read-only.

Is this the best way to solve the issue?

Yes. Preloading hook-adjusted bootstrap files before routing is the narrow maintainable fix, and the PR adds focused routing and context-engine coverage for the affected seam.

What I checked:

• Current-main routing order misses hook output: runEmbeddedAttempt computes bootstrap routing at resolveAttemptWorkspaceBootstrapRouting before resolveAttemptBootstrapContext calls resolveBootstrapContextForRun, so hook-adjusted files cannot affect bootstrapMode on main. (src/agents/pi-embedded-runner/run/attempt.ts:948, 06056926a099)
• Hook-adjusted files are resolved later on main: resolveBootstrapFilesForRun applies applyBootstrapHookOverrides, and resolveBootstrapContextForRun builds context from those files only after routing has already run in the embedded attempt path. (src/agents/bootstrap-files.ts:253, 06056926a099)
• Hook contract supports mutable bootstrap files: The public hooks docs describe agent:bootstrap as exposing mutable context.bootstrapFiles, which supports the PR's premise that hooks may inject BOOTSTRAP.md content. Public docs: docs/automation/hooks.md. (docs/automation/hooks.md:125, 06056926a099)
• PR patch preloads and reuses bootstrap files: The PR diff resolves bootstrap files before routing, passes them into routing, and reuses those files when building Project Context instead of resolving hook-adjusted files twice. (src/agents/pi-embedded-runner/run/attempt.ts:946, 6dd5ad411387)
• Regression coverage covers hook-provided BOOTSTRAP.md: The PR adds routing tests for non-empty and empty hook-provided BOOTSTRAP.md and a context-engine regression proving preloaded content reaches the system prompt. (src/agents/pi-embedded-runner/run/attempt.spawn-workspace.bootstrap-routing.test.ts:47, 6dd5ad411387)
• PR head checks are green: The public check-runs API showed completed success for the main check, build smoke, lint/type/dependency/security lanes, docs, and changed-path scans on head 6dd5ad411387febbccbc554ee7283163442c2aa2. (6dd5ad411387)

Likely related people:

• steipete: Recent commits centralized bootstrap system-prompt assembly, kept bootstrap context in the system prompt, and trimmed bootstrap exports across the affected runner and bootstrap files. (role: recent maintainer and adjacent owner; confidence: high; commits: 786fdeb36631, 0fa70f5a47f8, 217273037b26; files: src/agents/pi-embedded-runner/run/attempt.ts, src/agents/pi-embedded-runner/run/attempt-bootstrap-routing.ts, src/agents/bootstrap-files.ts)
• Takhoffman: Authored the recent workspace bootstrap prompt routing fix that touched bootstrap routing and bootstrap mode surfaces involved in this PR. (role: bootstrap routing contributor; confidence: medium; commits: 62703d84308a; files: src/agents/pi-embedded-runner/run/attempt.ts, src/agents/bootstrap-files.ts, src/agents/bootstrap-mode.ts)

Remaining risk / open question:

• No live/provider smoke was run in this read-only review; confidence comes from source inspection, the PR diff, regression coverage, and completed public check-runs.

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

[galiniliev]

Merged as be8b4dc.

Squash-merged with co-author trailers for @ificator (PR author) and @galiniliev (reviewer).

Review: no findings. All CI checks green. Rebased onto main to resolve changelog conflicts before merge.