refactor(agent): remove CherryClaw branding and the Soul Mode toggle

[vaayne]

What this PR does

Before this PR:

• Agents had a Soul Mode / Autonomous Mode toggle (configuration.soul_enabled). Only soul-enabled agents got the claw/autonomy MCP tools, the agent-memory MCP server, the workspace persona system prompt (SOUL.md / USER.md / FACT.md), and the autonomous-operation disallowed-tools overlay. Enabling it force-switched the agent to bypassPermissions, and scheduled tasks / channels refused agents without it.
• CherryClaw branding lingered across the repo: a src/main/ai/agents/cherryclaw/ directory (the engine actually powering soul mode for every agent), a docs/references/cherryclaw/ doc set, brand mentions in system prompts and channel help text, and an agent.cherryClaw.* i18n namespace.

After this PR:

• Soul-mode behavior is unconditional for every agent: the cherry-tools autonomy tools + agent-memory MCP server are always injected and allow-listed, the PromptBuilder workspace prompt always replaces the SDK preset, and all agents are eligible for scheduled tasks and channels.
• The soul disallowed-tools overlay is deleted outright: agents keep AskUserQuestion, plan-mode, and worktree tools where the tool registry allows them (Cron* / TodoWrite / NotebookEdit remain blocked by their pre-existing exposure: 'disabled' registry classification). Exception added after review: headless runs (channel-triggered and scheduled-task dispatches) still disallow AskUserQuestion — they have no responder, so a question would stall the run.
• Review hardening on top of the removal: the auto-approved config tool now rejects channels owned by another agent; notify / config are user-disableable (exposure: 'user') like cron; agents with non-blank user instructions skip the bootstrap onboarding interview; the prompt no longer references the unmounted mcp__skills__skills tool.
• The soul_enabled flag is fully removed: no UI toggle, no zod schema field, no reads anywhere. permission_mode is now a fully independent setting and its field is always visible in the agent edit dialog.
• CherryClaw branding is gone: the cherryclaw/ engine directory is flattened into src/main/ai/agents/ (prompt / bootstrap / heartbeat), prompts and channel help are de-branded, the CherryClaw doc set is deleted, and agent.cherryClaw.channels.* / agent.cherryClaw.tasks.* i18n keys are flattened to agent.channels.* / agent.tasks.* across all locales.
• The old claw MCP server is merged into cherry-tools; autonomy tools now live under mcp__cherry-tools__cron, mcp__cherry-tools__notify, and mcp__cherry-tools__config.
• Dead code removed along the way: seedWorkspaceTemplates, PromptBuilder.buildToolGuidance, and the always-true branches of composeToolGuidance / adjustAllowedToolsForMcp.

Fixes # N/A

Why we need it and why it was done in this way

CherryClaw's autonomy features were productized as soul mode and recent work already made personality + autonomy the default for new agents. Keeping a toggle (and a brand) for behavior that every agent should have added a second code path, a confusing permission-mode coupling, stale docs, and tool-name drift. Removing the flag and merging the autonomy tools into cherry-tools gives the app one agent behavior instead of two.

The following tradeoffs were made:

• The soul overlay's interactive-tool bans are not carried over: AskUserQuestion, plan-mode, and worktree tools stay available to every agent unless the tool registry disables them. The assistant role's pre-existing AskUserQuestion disable is preserved explicitly, and headless (channel / scheduled-task) runs keep AskUserQuestion disallowed via a transient dispatch flag.
• Data-migration shims that reference the legacy name are intentionally kept: the 'cherry-claw' → 'claude-code' read-time type remap in AgentService and the 'cherry-claw-default' id remap migrator. The unrelated cherry-claw.png model icon is untouched.
• The stored soul_enabled configuration key is simply ignored (the configuration zod schema is .loose()), so no data migration is needed.
• Existing references to old MCP tool names (mcp__claw__*) are not kept as aliases; callers must use the new mcp__cherry-tools__* names.

The following alternatives were considered:

• Renaming cherryclaw/ to workspace/ or persona/ instead of flattening — rejected: workspace is heavily overloaded in this codebase and the directory only held a few agent-engine modules.
• Keeping the toggle but defaulting it on — rejected: leaves the dual code path and the permission-mode coupling in place.
• Keeping a separate claw MCP server name as a compatibility alias — rejected: this PR removes the CherryClaw product surface rather than preserving a legacy synonym.

Links to places where the discussion took place: N/A

Breaking changes

The Soul Mode / Autonomous Mode toggle is removed from agent settings; every agent now always runs with autonomy features (scheduled tasks, channels, cron/notify/config tools, agent-memory tools, workspace persona prompt). Scheduled tasks and channels no longer require Soul Mode or bypassPermissions.

MCP tool names changed from mcp__claw__* to mcp__cherry-tools__*:

• mcp__claw__cron → mcp__cherry-tools__cron
• mcp__claw__notify → mcp__cherry-tools__notify
• mcp__claw__config → mcp__cherry-tools__config

Documented in v2-refactor-temp/docs/breaking-changes/2026-07-03-remove-soul-mode-toggle.md; no user data migration is required.

Special notes for your reviewer

• Review focus: whether dropping compatibility aliases for mcp__claw__* is acceptable, whether all Claude Code Agents should default to autonomy tools, and whether the preserved assistant-role AskUserQuestion special case is still correct.
• git log shows the moved engine files as renames (cherryclaw/prompt.ts → agents/prompt.ts, etc.) — review with rename detection on.
• Verification on the final rebased tree: pnpm lint, pnpm test, and pnpm build:check pass locally. GitHub CI is green: changes, catalog-hand-edit-check, changeset-check, basic-checks, general-test, and render-test passed (notify skipped).

Checklist

This checklist is not enforcing, but it's a reminder of items that could be relevant to every PR.
Approvers are expected to review this list.

• Branch: This PR targets the correct branch — main for active development, v1 for v1 maintenance fixes
• PR: The PR description is expressive enough and will help future contributors
• Code: Write code that humans can understand and Keep it simple
• Refactor: You have left the code cleaner than you found it (Boy Scout Rule)
• Upgrade: Impact of this change on upgrade flows was considered and addressed if required
• Documentation: A user-guide update was considered and is present (link) or not required. Check this only when the PR introduces or changes a user-facing feature or behavior.
• Self-review: I have reviewed my own code (e.g., via /gh-pr-review, gh pr diff, or GitHub UI) before requesting review from others

Release note

Removed the Soul Mode (Autonomous Mode) toggle from agent settings — all agents now always have autonomy features (scheduled tasks, channels, cron/notify/config tools, agent-memory tools, workspace persona prompt), and the permission mode setting is now independent of autonomy. Action required only for integrations that referenced old MCP tool names: use mcp__cherry-tools__cron/notify/config instead of mcp__claw__cron/notify/config.

[vaayne]

All three suggestions fixed + full self-review pass

Thanks @eeee0717. Addressed all three, and rather than trickle these out I did a complete independent + adversarial sweep of the whole diff to close the loop — details at the end.

1. skills MCP doc drift — a489d261e2
Reconciled every remaining "wires/newly-wired skills" claim in declarative-tool-registry.md (PR-7 line, de-soul-gating risk, and the "skills newly wired" risk item) to say wiring stays deferred — SkillsServer defined but unmounted, matching the earlier note + classification. Swept all 10 skills mentions in the doc; they're now consistent.

2. Stale cherryclaw/claw fs-audit paths — 3d022563e2
Marked the relocated entries historical in fs-usage-audit.md: seedWorkspace.ts removed, prompt.ts/heartbeat.ts → ai/agents/, claw.ts → ai/mcp/servers/cherryAutonomyTools.ts, plus the import-style summary row. Included the un-flagged heartbeat.ts entry (same class) so future audit work doesn't chase any dead path.

3. In-flight connecting headless rebuild test — 967b1185e7
Added the regression test for the branch where no live connection exists yet but a non-headless connect is still in flight and a headless run arrives → rebuild. Now all four idle-reuse states are covered (live+match reuse, live+mismatch rebuild, connecting+mismatch rebuild, headless+headless reuse).

---

Full-diff review (not just these lines). Ran my own pass plus an independent adversarial review of origin/main...HEAD across five angles — correctness after soul-gate removal, channel-ownership isolation, headless staleness, dead-code/orphans, and test gaps. Both came back clean:

• Isolation: every channel_id-accepting handler in cherryAutonomyTools.ts validates channel.agentId === this.agentId (cron add, config update/remove/reconnect); notify is structurally scoped via getAgentAdapters(this.agentId).
• Orphans: zero dangling cherryclaw/seedWorkspace/SOUL_MODE/autonomous-toggle references in live source.
• settingsBuilder de-soul-gating: the adjustAllowedToolsForMcp change is additive (adds SDK pre-approval for the now-always-injected cherry-tools/agent-memory) — it doesn't restrict built-ins, which still route through canUseTool.

CI green (general-test, basic-checks, changeset, catalog, changes). Re-requesting @eeee0717.

[eeee0717]

Findings:

• Blocking: src/main/data/services/AgentTaskService.ts:96 and :190 still pass raw task channelIds into replaceTaskSubscriptions() without checking that each channel belongs to the task's agentId. The MCP cron add path now validates ownership, but the DataApi/settings path can still create or update Agent A's scheduled task with Agent B's channel id, which sends scheduled output into the wrong Telegram/Slack/etc. channel. Please enforce channel.agentId === agentId at the service boundary, and/or filter the settings channel picker by the selected task agent before writing subscriptions.
• Blocking: src/main/ai/runtime/claudeCode/settingsBuilder.ts:640 still treats any session with a persisted channel link as headless via channelService.findBySessionId(session.id), even when the current turn was opened from the interactive renderer path with headless: false. Opening a channel-linked session in the app UI would therefore rebuild settings with AskUserQuestion disabled despite an interactive responder being present. Now that headless is explicitly plumbed through scheduled/channel call sites, the build-time policy should key off the current run's options.headless === true rather than the persistent channel link fallback, or otherwise distinguish channel-triggered turns from UI-triggered turns.
• Suggestion: v2-refactor-temp/docs/ai/declarative-tool-registry.md:75 and :146 still describe buildMcpServers() as injecting in-process MCP servers only when at least one tool is enabled. Current code and tests inject cherry-tools and agent-memory for every session and rely on disallowedTools / hooks for per-tool policy, with skills still unmounted. Please update those stale lines to match the current model.
• Suggestion: v2-refactor-temp/docs/ai/data-cluster.md:87 still lists soul_enabled as a typed AgentConfigurationSchema key, but this PR removes that key from the schema and documents stored values as ignored. Please remove it from the current key list or mark it historical so follow-up data/API reviews do not treat it as live schema surface.

CI: GitHub checks are green for this head (changes, catalog-hand-edit-check, changeset-check, basic-checks, general-test, and render-test passed; notify skipped). Local pnpm lint/test/format was not run per repository review rules.

修复后请 request eeee0717 再进行后续 review。

[vaayne]

Review follow-up — all four findings addressed (8fd7456a91..8e34071121)

Thanks @eeee0717. Both blockings and both suggestions are fixed; also merged latest main (6db9d4ed31).

Blocking 1 — task channel ownership (8fd7456a91)

AgentTaskService.createTask/updateTask now validate every incoming channel id against the task's agentId before touching subscriptions, with the same notFound('Channel', id) for foreign and missing ids as the MCP cron guard — no existence leak. createTask validates before registerJobSchedule, so a bad id no longer needs the rollback path; updateTask accepts [] to clear subscriptions. On the UX side, the Tasks settings channel picker (create form and task detail) is now filtered to the task's agent, and switching the agent in the create form drops selections that no longer belong.

Tests: create/update reject foreign and missing ids (no schedule left behind), own-channel success, [] clears; renderer asserts foreign channels are not offered.

Blocking 2 — headless derivation (faf693c9a1)

buildToolPermissions now keys off options.headless === true only; the channelService.findBySessionId(session.id) fallback is dropped. Both headless producers (runAgentTask.ts, ChannelMessageHandler.ts) pass the flag explicitly, and AgentSessionRuntimeService already rebuilds a warm connection on a headless mismatch, so the fallback was redundant on headless paths and wrong for channel-linked sessions opened interactively. The other findBySessionId use (channel prompt context in buildSystemPrompt) is unrelated and untouched; no other headless-inference site exists under runtime/claudeCode/.

Tests updated: explicit headless: true disallows AskUserQuestion; a channel-linked interactive session keeps it; the assistant-role disable stays.

Suggestions (8e34071121)

• declarative-tool-registry.md — MCP injection text (both §Layer 3 and the PR-7 entry) now says cherry-tools/agent-memory are injected for every session with per-tool policy via disallowedTools/hooks, skills still defined-but-unmounted.
• data-cluster.md — soul_enabled removed from the live typed-key list and marked historical (stored values ignored by the loose schema).

Verification on the merged tree: pnpm lint, pnpm test, pnpm build:check all pass locally.

[vaayne]

Full-PR multi-lens review (3 parallel independent reviewers, basis 8e34071121)

Ran a complete adversarial review of the whole diff across three lenses — main-process correctness & security, removal-residue & regression audit, renderer & shared data layer. Every claimed finding was re-verified against the code before this report; one reviewer claim was rejected as a false positive (the fs-usage-audit "stale headers" are intentional historical snapshots, annotated as such by 3d022563e2).

Fixed — missing i18n for the promoted autonomy tools (36bc41a5be)

CherryNotify / CherryConfig became exposure: 'user' alongside CherryCron, so the agent edit dialog renders them via agent.tools.builtin.<key>.label/.description — but only CherryCron had locale entries. The two new tool cards silently fell back to English in every locale, and the dynamic template key means i18n:check can't catch it. Added entries to en-us/zh-cn/zh-tw (matching the established 频道/頻道 terminology) and synced translate/*.

Known residual edge — headless flag is not applied on the enqueue/steer path

The beginTurn headless-mismatch rebuild added in 0ae4127130 covers idle-session reuse, but when a channel message arrives while its bound session is busy (isSessionBusy → AgentChatContextProvider.prepareDispatch enqueue branch → enqueueUserMessage), the dispatch's headless: true is never applied: the message is either steered into the live turn or queued onto the existing connection, both running with the connection's already-baked (non-headless) policy — AskUserQuestion stays available for that channel-triggered turn.

Bounded impact, verified: scheduled tasks always create a fresh session per fire (runAgentTask.ts), so only channel dispatches can hit this, and only when the user has the channel-bound session open and streaming at that exact moment — in which case an interactive responder usually is present and can answer. The bad sub-case is a queued channel turn starting after the user stops watching: an unanswered AskUserQuestion would stall collectStreamResponse's executionDone await (no timeout).

Not patching this inline: a correct fix needs per-turn policy reconciliation on a shared warm connection (steer vs queue vs rebuild-between-turns), which is real design work on a state machine that already went through several review rounds here. Proposing a follow-up issue instead — options are (a) plumb headless through enqueueUserMessage and force a connection rebuild before running a queued headless turn, or (b) add a timeout/auto-answer guard on the channel side. @eeee0717 if you'd rather see (a) in this PR, say the word.

Everything else — clean

• Autonomy tool authorization (cron add/list/remove, notify targets, config channel ops) all correctly scoped to the owning agent; no action escapes it.
• No soul_enabled / cherryClaw / mcp__claw__ residue anywhere in src/ beyond the intentionally kept migration shims; no dangling imports from the flattened engine dir; deleted helpers (seedWorkspaceTemplates, buildToolGuidance, removed always-true branches) have zero remaining callers.
• i18n flattening verified key-by-key: every agent.channels.* / agent.tasks.* call site resolves; no orphaned or leftover keys in locales or translate/*.
• Persona/bootstrap/heartbeat guards hold for the assistant role and headless runs; configuration saves preserve unknown keys (loose schema) so stored soul_enabled values survive untouched as intended; breaking-changes doc matches the code.

Verification: pnpm i18n:check and targeted checks pass locally; CI running on the new head.

[eeee0717]

This review was translated automatically.

Findings:

• Blocking: src/main/ai/streamManager/context/AgentChatContextProvider.ts:98 drops the backend headless: true state when a channel-bound session is already busy. The busy branch only calls enqueueUserMessage(sessionId, userMessage), and enqueueUserMessage() can either steer into the current non-headless connection or queue the next turn without changing the connection's baked tool policy. A channel message that arrives during an interactive turn can therefore still expose AskUserQuestion for a later responder-less channel turn and stall. Please carry headless state through the enqueue/steer path and rebuild or tighten the runtime policy before the queued headless turn runs.
• Blocking: src/main/data/services/AgentChannelWorkflowService.ts:67 allows a channel's agentId to be changed without clearing or revalidating existing agent_channel_task subscriptions. src/main/ai/agents/runAgentTask.ts:149 then reads subscribed channels only by schedule id and sends through their adapters, so a task owned by Agent A can keep delivering through a channel after that channel is reassigned to Agent B. Please clear subscriptions on channel ownership changes, or enforce task/channel owner matching at the subscription read/delivery boundary.
• Suggestion: src/main/ai/mcp/servers/cherryAutonomyTools.ts:90 documents omitted channel_ids as "auto-bind all agent channels", but addJob() only binds explicit ids or the current source channel; non-channel invocations create a task with no channel subscriptions. Please align the schema text with the current behavior or implement the advertised all-channel default.
• Suggestion: src/renderer/pages/settings/ChannelsSettings/ChannelForms.tsx:74 emits undefined when the user chooses inherited permission mode, and src/renderer/pages/settings/ChannelsSettings/ChannelDetail.tsx:489 drops undefined before PATCH. That means an existing channel permission override cannot be cleared back to inherit from the settings UI. The API already accepts nullable values, so send null for the inherit case.

After fixing, please request eeee0717 for further review.

Verification:

• Reviewed PR #16726 at 36bc41a5be9767b5aa19821ffc8396bab39dd3bf in isolated worktree /Users/cherryai004/Documents/Cherry_Studio_Dev/cherry-studio-pr-review/.codex-tmp/pr-review-sweep-20260707T071612Z-16726-36bc41a5.
• Ran six scoped reviewer passes and used only results that repeated PR #16726, this head SHA, and the assigned worktree.
• Checked existing reviews/comments to avoid repeating previously raised issues.
• Checked GitHub CI: general-test failed in src/main/core/job/__tests__/JobManager.integration.test.ts on a 20s timeout for arms a delayed job after commit and promotes it at scheduledAt; render-test, basic-checks, changes, changeset-check, and catalog-hand-edit-check passed; notify skipped.
• Local pnpm lint/test/format not run per repository review rules.

---

Original Content

Findings:

• Blocking: src/main/ai/streamManager/context/AgentChatContextProvider.ts:98 drops the backend headless: true state when a channel-bound session is already busy. The busy branch only calls enqueueUserMessage(sessionId, userMessage), and enqueueUserMessage() can either steer into the current non-headless connection or queue the next turn without changing the connection's baked tool policy. A channel message that arrives during an interactive turn can therefore still expose AskUserQuestion for a later responder-less channel turn and stall. Please carry headless state through the enqueue/steer path and rebuild or tighten the runtime policy before the queued headless turn runs.
• Blocking: src/main/data/services/AgentChannelWorkflowService.ts:67 allows a channel's agentId to be changed without clearing or revalidating existing agent_channel_task subscriptions. src/main/ai/agents/runAgentTask.ts:149 then reads subscribed channels only by schedule id and sends through their adapters, so a task owned by Agent A can keep delivering through a channel after that channel is reassigned to Agent B. Please clear subscriptions on channel ownership changes, or enforce task/channel owner matching at the subscription read/delivery boundary.
• Suggestion: src/main/ai/mcp/servers/cherryAutonomyTools.ts:90 documents omitted channel_ids as "auto-bind all agent channels", but addJob() only binds explicit ids or the current source channel; non-channel invocations create a task with no channel subscriptions. Please align the schema text with the current behavior or implement the advertised all-channel default.
• Suggestion: src/renderer/pages/settings/ChannelsSettings/ChannelForms.tsx:74 emits undefined when the user chooses inherited permission mode, and src/renderer/pages/settings/ChannelsSettings/ChannelDetail.tsx:489 drops undefined before PATCH. That means an existing channel permission override cannot be cleared back to inherit from the settings UI. The API already accepts nullable values, so send null for the inherit case.

修复后请 request eeee0717 再进行后续 review。

Verification:

• Reviewed PR #16726 at 36bc41a5be9767b5aa19821ffc8396bab39dd3bf in isolated worktree /Users/cherryai004/Documents/Cherry_Studio_Dev/cherry-studio-pr-review/.codex-tmp/pr-review-sweep-20260707T071612Z-16726-36bc41a5.
• Ran six scoped reviewer passes and used only results that repeated PR #16726, this head SHA, and the assigned worktree.
• Checked existing reviews/comments to avoid repeating previously raised issues.
• Checked GitHub CI: general-test failed in src/main/core/job/__tests__/JobManager.integration.test.ts on a 20s timeout for arms a delayed job after commit and promotes it at scheduledAt; render-test, basic-checks, changes, changeset-check, and catalog-hand-edit-check passed; notify skipped.
• Local pnpm lint/test/format not run per repository review rules.

[vaayne]

Review follow-up — all four findings addressed (36bc41a5be..802dbcf0b6)

Thanks @eeee0717. Both blockings and both suggestions are fixed at head 802dbcf0b6, plus additional hardening from an independent re-review pass over the same surface.

Blocking 1 — busy branch drops headless (64e050717b + 1184bda149)

Headless is now a per-turn property enforced at fire time, not only a baked connection setting:

• The busy branch passes { headless: req.headless === true } into enqueueUserMessage(), which marks the message id in a per-session headlessMessageIds set (mirroring steerMessageIds). startNextTurn consumes the mark, so a queued channel message runs as a headless turn even on a warm interactive connection.
• canUseTool in settingsBuilder denies AskUserQuestion whenever AgentSessionRuntimeService.isCurrentTurnHeadless(sessionId) is true, instructing the model to proceed and state assumptions. The baked disallowedTools entry stays as a second layer for turns headless from the start.
• Steer continuations inherit correctly (1184bda149): at the steer boundary we compute whether the interrupted turn and every steering input were headless; only then does the roll continuation stay headless. Any interactive participant makes the continuation interactive — a responder exists.

Tests cover the enqueue path, the fire-time denial, and all three roll combinations (headless+headless, headless+interactive, interactive+headless).

Blocking 2 — channel agentId rebind keeps task subscriptions (9ef6050390 + a39455d652)

Fixed on both sides of the boundary:

• Data hygiene: rebinding a channel's agentId clears its agent_channel_task subscriptions; if syncChannel fails and the old agentId is restored, subscriptions created during the transient window are cleared again (a39455d652).
• Authoritative delivery guard: runAgentTask filters subscribed channels by channel.agentId === agentId before sending, so wrong-agent delivery is impossible even if a stale row survives.

Suggestions

• channel_ids "auto-bind all agent channels" (6d5c1c1c6d) — the schema text now matches actual behavior: explicit ids, else the current source channel, else no subscriptions.
• Permission mode can't be cleared back to inherit (5c3f95499b) — the inherit option now emits null, which survives the PATCH filter.

Additional hardening (independent re-review at the same head)

• 3e8a56b0d1 — the v1 migrator no longer imports agent_channel_task rows whose channel owner differs from the task owner (same cross-agent invariant as Blocking 2, at the import boundary); skips are logged as skippedCrossAgentChannelLinks.
• b873ed53ee — heartbeat runs skip the assistant builtin role instead of creating pointless sessions.
• a6f1e95a5b — proxy URLs are credential-redacted before injection into the assistant system prompt (pre-existing leak of basic-auth userinfo to the provider).
• 7df2c6d061 — the bootstrap completion log uses tags: ["bootstrap"] (the memory API ignores the singular tag, so the entry was written untagged), and the prompt no longer contradicts itself about FACT.md write paths (memory tool only).
• b61a978f15 — /whoami help names the real config fields (allowed_chat_ids / allowed_channel_ids); allow_ids doesn't exist.
• 802dbcf0b6 — feishu/wechat add_channel descriptions no longer promise a QR-on-omitted-credentials flow that the strict ChannelConfigSchema makes unreachable; QR reconnection points at reconnect_channel / settings UI, and the enabled default semantics are stated accurately.

Pre-existing issues found but out of scope for this PR (follow-ups to be filed): plan/small model clear writes undefined and never persists (agentForm.ts), per-field save clobbers in-progress drafts in ChannelForms, timeoutMinutes: null treated as keep-old in AgentTaskService, stale agent_task tables section in data-cluster.md.

Verification

pnpm lint, pnpm test, pnpm build:check all green locally at 802dbcf0b6.