feat(hook): carry locked + relevant beliefs into dispatched subagent prompts

[robotrocketscience]

Closes #1068.

What this does

Dispatched subagents now inherit memory context. A new default-on hook (aelf-agent-context-hook, PreToolUse matcher ^(Agent|Task)$) rewrites the worker's prompt via the harness updatedInput channel before dispatch, prepending a bounded <aelfrice-worker-context> block:

• L0 locked beliefs — feat(locks): bound lock injection + fix lock framing — frozen/reference tiers, locks-file manifest, provenance-aware framing #1016 provenance-aware framing, reference-lock manifest bounding (manifest_reference_locks=True).
• Prompt-relevant retrieval — retrieve() against the worker's prompt at the Grep|Glob lane's auxiliary budget (token_budget=600, l1_limit=10), with the UserPromptSubmit lane's post-filters (project-context feat(hook): project-scoped retrieval filtering — surface beliefs only from active scope (#855 defect 3) #858, session scope-outs feat(hook): session-scoped belief exclusion via aelf:scope-out (#855 defect 1) #856) and feedback-loop audit rows.

Design notes

• Channel selection is evidence-based (probe record on feat(hook): carry locked + relevant beliefs into dispatched subagent prompts (PreToolUse:Agent updatedInput) #1068): updatedInput applies without a permissionDecision, so the hook never touches the user's permission flow; SubagentStart was rejected for this lane because its payload carries no prompt text (no query-aware retrieval possible). This follows the fix(hook): PreCompact rebuild block rejected by harness — move injection to SessionStart(source=compact) #1031 lesson — verify the harness channel before building on it.
• Anchored matcher ^(Agent|Task)$ can never partial-match TaskCreate/TaskGet/etc.; the module additionally re-checks tool_name by exact membership.
• Fail-open everywhere: no store / empty retrieval / malformed payload / import error → exit 0 with no stdout, byte-identical passthrough. Same non-blocking contract as hook_search_tool.
• Idempotent: a prompt already carrying the open tag (nested dispatch, retried call) passes through — no double-injection. Worker tags joined hook.py:_ESCAPE_TAGS so stored belief content cannot spoof the envelope (feat(lock): inject reference-tier locks as a bounded manifest (#1016-B) #1037 posture).
• Kill switch: AELFRICE_AGENT_CONTEXT=0; setup flag --no-agent-context with feat(setup): self-installing hook manifest at aelf-CLI first run #623 opt-out persistence.
• Codex host untouched: the desired-set in host_codex.py is unchanged, pending [Tracking] First-class OpenAI Codex CLI support #1056 live validation.
• Deterministic per v3.0 PHILOSOPHY: natural-language-relatedness gate — deterministic vs embedding #605 — L0 listing + existing retrieve() only, no new ranking machinery.

What ships

• src/aelfrice/hook_agent_context.py + aelf-agent-context-hook console script.
• setup.py install/uninstall/resolve; manifest row (default_on: true, since 3.9.0); auto_install dispatch entry; aelf setup / aelf unsetup flags + opt-out map.
• 27 new tests (hook lane + setup wiring); CHANGELOG entry.

Verification

• tests/test_agent_context_hook.py + tests/test_aelf_setup_agent_context.py: 27/27 pass.
• Adjacent suites re-run green: cli_setup, opt-out sync, search-tool setup, pre-issue guard, auto_install ×2, host_codex, host_opt_out (119 tests).
• Live end-to-end: wired the built console script into a sandbox project with a seeded store (1 locked rule + 1 topical belief), dispatched a real worker; the worker's transcript shows the framed block (lock rides along with lock="user", original prompt preserved verbatim at the end), and the worker correctly answered a question whose answer existed only in the belief store. Passthrough paths (no store, tagged prompt, kill switch) verified by unit tests.
• Pyright-strict profile matches the sibling hook_search_tool.py (same pre-existing finding categories: lazy private reuse, db_path cwd shim); pyright is not a CI gate.

Reviewer notes

• default_on: true matches every sibling hook; flag if you want this landing default-off first. The mutation risk is bounded by fail-open + the idempotency tag, and the emit changes only the prompt key.
• The retrieval call reuses record_retrieval (exposure valence 0.1), so worker-lane exposure feeds the posterior like the UserPromptSubmit lane does.

[sourcery-ai]

Sorry @robotrocketscience, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Warning

Review limit reached

@robotrocketscience, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 40 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e830a9c0-d547-4028-8637-5a48cd14a07a

📥 Commits

Reviewing files that changed from the base of the PR and between 5c02067 and 1d13b94.

📒 Files selected for processing (10)

• CHANGELOG/v3.md
• pyproject.toml
• src/aelfrice/auto_install.py
• src/aelfrice/cli.py
• src/aelfrice/data/hook_manifest.json
• src/aelfrice/hook.py
• src/aelfrice/hook_agent_context.py
• src/aelfrice/setup.py
• tests/test_aelf_setup_agent_context.py
• tests/test_agent_context_hook.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/issue-1068-agent-context-hook

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

PR-size soft cap

This PR is over the advisory size threshold:

• 905 changed lines (limit: 200)
• 10 changed files (limit: 3)

Bigger PRs collide with more open work, which under the parallel-session workflow tends to produce repeated attn:merge-conflict cycles (see #602). When practical, split into smaller PRs that each touch a focused surface.

This is advisory only — nothing is blocked. If the size is intentional (large refactor, module removal, generated code), apply the size:override label and this comment will be removed on the next push.

[robotrocketscience]

[claim:review:garsecg:2026-07-04T07:04:57Z]

[robotrocketscience]

Reviewed the full diff; verifying claims against call sites rather than the PR body:

• Envelope spoof-guard confirmed: worker-context tags are appended to hook.py:_ESCAPE_TAGS, so stored belief content can't fake the idempotency tag or close the envelope early; test_belief_content_cannot_spoof_envelope covers it.
• Channel posture confirmed in code: _emit writes updatedInput with no permissionDecision, single write at the end of the fallible path — any exception before it yields byte-identical passthrough (exit 0, no stdout). Fail-open paths all have tests (malformed stdin, non-dict tool_input, missing prompt, missing db, empty store, tagged prompt, kill switch).
• Anchored matcher + exact tool-name membership both present (^(Agent|Task)$ in setup, AGENT_TOOL_NAMES re-check in the module) — TaskCreate/TaskUpdate can't match.
• Wiring follows the house per-hook pattern: install/uninstall/resolve triplet in setup.py, manifest row (default_on, since 3.9.0), auto_install dispatch entry, opt-out map key, console script, --no-agent-context flags.
• Independent verification: fetched the PR head locally, both new test files pass 27/27 in a fresh dev venv; CI pytest matrix (3.12/3.13) green; no unresolved review threads.
• Discretion grep on the diff: clean (the one hit is a pre-existing context line).

One non-blocking flag for a docs follow-up rather than this PR: bench-run contamination. Benchmark reader/judge workers are dispatched through the same tool this hook matches, so a default-on install will inject store context into bench dispatch prompts. docs/concepts/BENCHMARKS.md (and the lab runner conventions) should instruct setting AELFRICE_AGENT_CONTEXT=0 for reader/judge dispatches — otherwise injected beliefs are a fresh gold-leak vector of exactly the class the bench protocol gates against.

LGTM — adding ready-to-merge.

[robotrocketscience]

[release:review:garsecg:2026-07-04T07:09:20Z]

[github-actions]

merge-train: merged 1d13b94 → main via FF push.