[senamakel]

Why this PR is on the fork. tinyhumansai/openhuman refuses new branch
creation (Cannot create ref due to creations being restricted), so neither
this branch nor its base fix/ui-v4 can be pushed there. Retargeting at
upstream main was the alternative and is worse: fix/ui-v4 is far enough
ahead of main that the diff grows from 12 files / ~277 insertions to 37
files / ~2,690, sweeping in unrelated tokenjuice, modules, documents and
voice work. Re-point this at upstream once fix/ui-v4 lands there.

Summary

• Sub-agent tool surface cut from 11 tools to 3 (spawn_async_subagent, list_subagents, continue_subagent). A sub-agent is always async and its result is delivered back on an idle system turn, so the collection surface (wait, wait_loop, wait_subagent) was buying nothing but tokens and an invitation to stall the turn. spawn_parallel_agents, steer_subagent and close_subagent go with them.
• Agent identity and writing style moved out of compiled prompts into workspace files — ROLE.md (role brief) and STYLE.md (writing style) join SOUL.md / IDENTITY.md under the workspace, so tuning either is an edit rather than a rebuild.
• ## Core Responsibilities, ## Rules and ## Grounding and tool use merged into one ## Rules section. They overlapped: Core Responsibilities largely restated "direct-first" and "delegate when it helps".
• ## Output style and ## Response Style compressed into a single # Writing style in STYLE.md, ending a split where the same concern lived in both builder.rs and orchestrator/prompt.md.
• HEARTBEAT.md and MEMORY_GOALS.md are no longer seeded. The subconscious engine that read HEARTBEAT.md was deleted; the goals store already returns an empty GoalsDoc for a missing file and creates it on first write.
• Fixed a latent bug where prompt tests wrote into the repo root — sync_workspace_file now refuses a non-absolute workspace.

Problem

The orchestrator's fixed per-turn cost was 18,168 tokens and nothing measured where it went. Breaking it down surfaced three things:

1. The sub-agent surface was 11 tools / 2,060 tokens for one capability. orchestration::background_delivery already returns a finished worker's result on an idle system turn, so nothing had to block for it. wait / wait_loop / wait_subagent existed to collect a result that arrives on its own, and spawn_parallel_agents was a second way to say "spawn again".
2. Identity and style were compiled in. SOUL.md / IDENTITY.md already had a sync-and-inject path, but the orchestrator ran with omit_identity = true and never loaded them; its role text and voice were instead baked into orchestrator/prompt.md and a GLOBAL_STYLE_SUFFIX constant. Tuning either meant a rebuild, and style specifically was split across two files.
3. Three sections repeated each other. Core Responsibilities, Rules, and the grounding contract each restated direct-first and delegate-when-it-helps.

Solution

Sub-agent tools. Dropped six from orchestrator/agent.toml and rewrote the "Running several workers at once" section around the async model: fan-out is several spawns, results arrive as they land, continue_subagent resumes a worker that stopped to ask. The loader assertions became a both-ways contract — the three required, the six pinned as retired so they cannot drift back without someone re-teaching them in prompt.md.

Result-gating work ("critique it before you finalize") still needs an answer inside the turn, so that hard rule now names a blocking delegate_* specialist or spawn_async_subagent with blocking: true. #4681's regression test is updated to pin those two rather than the retired primitives.

Identity and style. ROLE.md and STYLE.md are bundled, seeded into the workspace by sync_workspace_file, and injected from there. GLOBAL_STYLE_SUFFIX becomes include_str!("STYLE.md") — the bundled seed and the read-failure fallback — with global_style_block() preferring the workspace copy.

omit_identity turned out to be inert for this agent: the orchestrator is a PromptSource::Dynamic agent, and SystemPromptBuilder::from_dynamic installs only that builder and never consults the flag. The identity render therefore lives in orchestrator/prompt.rs, beside the render_user_files call that is there for the same reason.

Grounding is now folded into the orchestrator's merged ## Rules, so build() skips the global append when the assembled prompt already carries the heading. Matching on the heading keeps it self-maintaining: an agent that stops carrying its own copy silently gets the global one back.

The repo-root bug. Enabling identity rendering made the prompt path write, and ~20 test fixtures pass workspace_dir: Path::new("."). The suite promptly seeded five files plus their .builtin-hash siblings into the repo root. Fixed at the source rather than across 20 call sites: a real workspace is always absolute, so a relative one means the caller never had one.

Measured

	before	after
system prompt	6,647	7,008
tool schemas	11,521 (59 tools)	10,331 (53 tools)
fixed per-turn	18,168	17,339

The system prompt grows, and deliberately: SOUL.md + IDENTITY.md now load for this agent where they previously did not, costing ~700 tokens that the merges (~340) and the tool cut (~1,190) offset. Editability was the goal; the token reduction is incidental. Counts are tiktoken o200k_base, a GPT tokenizer — relative weights, not a billing figure.

Submission Checklist

• Tests added or updated (happy path + at least one failure / edge case) per Testing Strategy
• Diff coverage ≥ 80% — not measured locally; deferring to the CI gate. The change is overwhelmingly prompt text and TOML; the Rust touched (global_style_block, the sync_workspace_file guard, the grounding-dedup branch) is covered by the updated prompts::tests and loader::tests.
• N/A: behaviour-only change — no feature rows added, removed or renamed in docs/TEST-COVERAGE-MATRIX.md.
• N/A: no matrix feature IDs apply to this change.
• No new external network dependencies introduced
• N/A: does not touch a release-cut surface in docs/RELEASE-MANUAL-SMOKE.md.
• N/A: no tracking issue — this came from an interactive prompt-budget review.

Impact

Behaviour changes reviewers should weigh:

• A sub-agent can no longer be steered or explicitly closed. A worker needing different instructions must be respawned; idle sessions are reaped against the existing registry cap rather than torn down by hand.
• STYLE.md is global, so its voice guidance reaches every agent, where ## Response Style previously reached only the orchestrator. The file scopes itself in prose ("output handed to another agent is data, not conversation"), but if a sub-agent's handoffs start reading conversationally, this is the cause.
• Existing workspaces keep their HEARTBEAT.md / MEMORY_GOALS.md — this stops seeding them, it does not delete them. HEARTBEAT.md keeps its WORKSPACE_INTERNAL_FILES entry so a file a user still has on disk stays not-agent-writable.
• A user edit to any of the four workspace files now changes agent behaviour, taking effect from the next session (the existing KV-cache freeze rule is unchanged).

Desktop/CLI only; no migration, no platform-specific surface, no perf implication beyond the smaller per-turn payload.

Related

• Closes:
• Follow-up PR(s)/TODOs: spawn_async_subagent keeps its name though it is now the only spawn tool — renaming it to spawn_subagent collides with the retired synchronous variant and would cascade across ~20 files.

---

AI Authored PR Metadata (required for Codex/Linear PRs)

Linear Issue

• Key: N/A
• URL: N/A

Commit & Branch

• Branch: prompt-slimming
• Commit SHA: see head of branch

Validation Run

• N/A: pnpm --filter openhuman-app format:check — no files under app/ changed.
• N/A: pnpm typecheck — no TypeScript changed.
• Focused tests: full Rust lib suite, 11558 passed; 0 failed (--test-threads=1, RUST_MIN_STACK=16777216)
• Rust fmt/check: cargo fmt --check clean; cargo check clean on the product feature set
• N/A: Tauri fmt/check — app/src-tauri/ untouched.

Validation Blocked

• command: N/A
• error: N/A
• impact: N/A

Behavior Changes

• Intended behavior change: identity and writing style become user-editable workspace files; the sub-agent tool surface narrows to spawn/list/continue; HEARTBEAT.md and MEMORY_GOALS.md stop being seeded.
• User-visible effect: agent voice and role are tunable without a rebuild; the agent no longer offers to steer or close a worker.

Parity Contract

• Legacy behavior preserved: grounding contract still reaches every agent (globally, or via the merged section, never twice); the goals domain is unaffected by the dropped seed because store::load returns GoalsDoc::default() on NotFound; retired sub-agent tools remain registered in the base registry and are only out of this agent's named scope.
• Guard/fallback/dispatch parity checks: loader::tests pins the three-tool surface and the six retired names in both directions; prompts::tests pins that ROLE.md seeds and HEARTBEAT.md / MEMORY_GOALS.md do not; context_composer still asserts the prompt came through SystemPromptBuilder::build.

Duplicate / Superseded PR Handling

• Duplicate PR(s): none
• Canonical PR: this one
• Resolution: N/A

---

Note on commit history: an auto-commit hook checkpoints this working tree, so the branch carries machine-generated commit subjects and, at two points, commits that regressed vendor/* gitlinks. Those were restored; git diff <base> -- vendor/ is empty, so the net change touches no submodule pointer.