What task are you trying to do?

Free the user-facing surface where "primary agent mode" appears so #128 can rename the current task tool to agent without colliding with PawWork's existing primary-agent picker. The picker concept is inherited from opencode and does not match outside conventions: Cursor, Claude Code, Codex CLI, Gemini CLI all expose a single default assistant plus a permission/auto-approve control, not a switchable mode picker.

What do you do today?

packages/opencode/src/agent/agent.ts defines five mode === "primary" agents. Two are user-visible (build at line 122 as the runtime default, plan at line 137 as visible Plan mode and the target of #127). Three are harness-internal with hidden: true (compaction at line 201, title at line 216, summary at line 232). The runtime depends on this structure across at least seven callsites: agent.ts:315 ("default_agent must not be subagent" invariant), agent.ts:319-320 ("at least one visible primary" invariant), acp/agent.ts:1154 (visible-primary filter exposed via ACP), cli/cmd/agent.ts:235 (CLI listing), cli/cmd/run.ts:595/616 (CLI run flow), session/llm.ts:78 (mode telemetry tag), session/prompt.ts:1751 (subtask detection). packages/app/src/components/prompt-input.tsx:579 exposes subagent definitions through @coder-style mention typeahead. The explore subagent has its prompt narrowly framed as "file search specialist" even though its permission set already allows webfetch, websearch, grep, glob, read. The product effect: PawWork inherits the build/plan mode-picker concept, the @-mention subagent typeahead, the default_agent config field, and a Tab cycle keybind, even though PawWork's audience does not benefit from explicit mode switching.

What would a good result look like?

The user never sees a primary-agent mode picker. The build agent is retained as the implicit default execution path (mode === "primary", hidden: false at the data layer because seven runtime callsites depend on this structure, but no UI picker renders it and no settings panel references it). The plan agent is removed entirely; Plan capability is reintroduced as a model-callable tool by #127. The model-facing tool registry is freed up to accommodate #128's later rename of task to agent. PawWork ships two clearly differentiated subagents: general (writeable, multi-purpose) and explore (read-only, multi-domain research covering web, file, code).

Which audience does this matter to most?

Both. Non-technical users get a simpler product surface. Technical users coming from Cursor/Claude Code/Codex find PawWork consistent with the consumer pattern they already know.

Decisions captured during scoping

• Plan capability: ships as a tool only via [Feature] Replace visible Plan Mode with lightweight plan approval tool #127, no /plan slash command, no plan-specific auto-approve toggle. Approval card per [Feature] Replace visible Plan Mode with lightweight plan approval tool #127.
• Auto-approve: a single boolean toggle in settings (Claude Code pattern, simplified). Not part of this issue's surface but compatible.
• build agent retention: build stays in agent.ts as the runtime default with mode === "primary" and hidden: false. UI never renders a picker for it. Reasoning: deleting build requires refactoring seven runtime callsites and removing two invariants, weakens the mode telemetry signal that [Feature] Detect low-yield repeated probing on the same investigation target #229 / [Feature] Add LLM stream diagnostics to local session export #214 depend on, and adds permanent upstream-sync maintenance cost; deleting only plan achieves the same user-visible outcome (no picker) at far lower harness cost. Full alternative analysis in "Alternatives considered" below.
• @-mention subagent picker (prompt-input.tsx:579): removed entirely. Reasoning: Claude Code's subagent name field requires lowercase + hyphens, which excludes Chinese names and therefore most PawWork users; the feature is power-user-only even within Claude Code (anthropics/claude-code#51190, snapshot 2026-04-20, requests to hide subagents from the picker rather than surface more); PawWork's audience does not need an explicit invocation channel beyond natural language. After this change, subagent invocation lives only on the existing task tool (which [Feature] Rename and rewrite task as subagent #128 will later rename to agent); the model decides when to invoke. Existing chat history with @coder-style strings renders as plain text.
• Default subagents: ship two with clear separation. general (writeable, multi-purpose, todowrite disabled, used for delegation in isolated context) and explore (read-only, multi-domain). Main-session prompts route to build directly; subagents are invoked through the task tool. The current explore.txt prompt is rewritten from "file search specialist" to a multi-domain read-only research helper. Output format: each finding is a Markdown paragraph that names its source first (file path, URL, or grep location) and content second; web and code results may be mixed in one response when the query spans both.
• Skill vs subagent boundary: kept separate. Subagents run in isolated context, skills inject content into the current context. Unification is a future evaluation, not this issue.
• Routines (v1.3+): orthogonal. Routines is scheduling, not a mode picker.
• Migration path (one-shot config rewrite): existing user configs are migrated atomically at startup. The default_agent field is removed from the config file regardless of its previous value (plan, build, subagent name, unknown string). The schema temporarily accepts the field during the rewrite window, after which it is no longer part of the schema. The rewrite is write-then-rename for atomicity and is skipped silently if the field is already absent. Reasoning for the aggressive migration: PawWork's user base at this point is <20 internal-company users, so clobber risk is acceptable; the alternative (deprecated-field-with-debug-log) leaves a long-lived dead field in the schema and a debug-only signal that production builds filter out.
• mode field: retained intact. The "primary" value remains semantically correct (build as visible primary, compaction/title/summary as hidden primary helpers).

Acceptance criteria — Runtime

• packages/opencode/src/agent/agent.ts no longer defines plan; build, compaction, title, summary, general, explore continue to exist with the same mode values and runtime semantics.
• The seven mode-dependent callsites (agent.ts:315, agent.ts:319-320, acp/agent.ts:1154, cli/cmd/agent.ts:235, cli/cmd/run.ts:595/616, session/llm.ts:78, session/prompt.ts:1751) require no source changes beyond the plan removal; existing tests on these paths continue to pass.
• agent.ts:319-320 "at least one visible primary" invariant remains satisfied because build is still visible at the data layer (the predicate is >= 1, satisfied by build alone).
• A test in packages/opencode/test/agent/ (or equivalent existing location) asserts: (a) general.permission denies todowrite; (b) explore.permission denies edit and write; (c) explore.permission allows webfetch, websearch, grep, glob, read (allow assertions are required so accidental removal of research tools is caught).
• packages/opencode/src/agent/prompt/explore.txt is rewritten to cover web/file/code research uniformly. The rewritten prompt mentions each of webfetch, websearch, grep, read at least once and explicitly names the source-first Markdown paragraph output format defined above.

Acceptance criteria — UI

• packages/app/src/components/prompt-input.tsx:579 no longer surfaces an agentList for @-mention; the existing typeahead returns only file matches.
• The Tab keybind no longer cycles primary agents in the prompt input; default textarea behavior is restored.
• No settings panel surface lists "default agent" or offers a primary-agent picker.
• The CLI --agent flag continues to function for users who pass it explicitly. Passing --agent plan after this change emits a clear error message naming the unknown agent (matches existing opencode behavior for unknown agent names).
• A new typed verification test packages/app/test/no-mode-picker.test.ts (vitest, runs in the existing test suite, no new CI surface) replaces the earlier shell-script approach. The test imports the runtime modules and asserts:
  • agents.plan === undefined after default-agent registry build
  • agentList-style export from prompt-input.tsx is gone (or, if the export name changes, the rendered picker DOM is empty for an @ keystroke in a snapshot test)
  • No string in the i18n bundle (packages/app/src/i18n/zh.ts, en.ts) matches the case-insensitive regex /primary agent|default agent|agent mode|mode picker/i
  • No source file in packages/app/src/ (excluding the test itself and any .test.ts files) matches /mode\s*[!=]==?\s*['"]primary['"]/. Implemented via fs walk + regex test, not shell grep, so the assertion survives macOS/Linux grep differences.
• Past-mention rendering: the message renderer file path is identified by the implementer in the first commit (grep for the markdown / message-body rendering component under packages/app/src/components/) and pinned in the test file. The test asserts: (a) historical chat strings containing @coder / @reviewer / @<name> render with no data-mention attribute and no .mention (or equivalent project-specific) class on any descendant of the message body; (b) the original literal substring @coder (or @<name> input) is preserved as visible plain text in the rendered DOM.

Acceptance criteria — Config & Migration

The migration is split into three independently testable layers.

• (Schema) The default_agent field is accepted by the schema parser for any string value during one release window, so existing configs do not fail validation while the rewrite runs. After the rewrite has had one release to propagate, the field is removed from the schema entirely; tracking issue for that follow-up is created and linked here before this PR merges.
• (Migration) On startup, if the user's persisted config file contains a default_agent field with any value, PawWork rewrites the config file to remove the field entirely. The rewrite is atomic (write-then-rename to a path on the same filesystem as the original; falls back to in-memory-only sanitization with a logger.warn if the rename target would cross filesystem boundaries or the path is a symlink). The rewrite is idempotent (re-runs cleanly if the field is re-added). On read-only filesystems, concurrent startups, or any other write failure, startup continues with the in-memory config sanitized and emits a logger.warn; no exception is thrown to the user.
• (Telemetry) When the migration rewrite fires, exactly one logger.info line is emitted at the migration callsite, containing the literal substring migrated deprecated default_agent. The old value is included as a structured logger argument (not string-concatenated into the message) so it is escaped per the logger's standard rules and bounded by the logger's existing length limits. A test asserts this exact substring appears once when a config containing default_agent: "plan" is loaded.

Acceptance criteria — Documentation

• packages/opencode/src/agent/agent.ts gains an inline section comment immediately after the build agent definition: // PawWork: visible Plan mode permanently removed (issue #239); resolve sync conflicts in this region to HEAD. Plan capability migrated to plan tool per #127. Wording is illustrative; reviewer may request phrasing adjustments during PR review.
• packages/opencode/src/agent/prompt/explore.txt gets its rewrite-rationale recorded in the commit message body, not in the file itself, because explore.txt content is sent verbatim to the model and inline maintainer prose would pollute the prompt. The commit message must explicitly note that upstream explore.txt is not synced back.
• The maintainer checklist (this issue's PR description) confirms that the local memory file ~/.claude/projects/-Users-yuhan-workspace-dev-pawwork/memory/project_agent_rename_critical_path.md already exists and describes the A.1 + one-shot-rewrite implementation route. This is a maintainer-side artifact and is not part of repo verification; the PR does not block on its existence.

Out of scope

• The actual rename of task → agent tool: tracked in [Feature] Rename and rewrite task as subagent #128.
• Plan tool design and approval card: tracked in [Feature] Replace visible Plan Mode with lightweight plan approval tool #127.
• Default global AGENTS.md: tracked in [Feature] Improve PawWork system prompt and instruction fallback order #230.
• Auto-approve toggle UI design: separate harness work.
• Skill / subagent unification: future evaluation.
• Refactoring the seven mode-dependent runtime callsites to remove the primary-agent abstraction entirely: explicitly rejected (see "Alternatives considered").
• Removing the default_agent schema field entirely (one-line follow-up issue created and linked before this PR merges).

Alternatives considered

Hard delete (remove both build and plan, remove the visible-primary and default_agent invariants, refactor the seven mode-dependent callsites): rejected on harness-efficiency grounds. Deleting build would require changes at seven runtime callsites — subtask detection, CLI flow, ACP filter, telemetry tag, two invariants, two CLI commands — each of which currently assumes a visible primary exists. The deletion provides no user-visible benefit beyond what hiding the picker already achieves, weakens the mode telemetry signal that #229 and #214 depend on for diagnostics slicing, and increases upstream-sync maintenance cost permanently because every upstream change to build would require the executor to decide "where do we attach this behavior now that build is gone." The reasoning is captured in project_agent_rename_critical_path.md.

Deprecated-field-with-debug-log migration (keep default_agent schema field as a deprecated optional, fallback to build at runtime, log at debug level): rejected because production builds typically filter debug logs, leaving zero observability when the deprecation path fires; and the deprecated field would linger in the schema indefinitely. The one-shot rewrite chosen above is acceptable because PawWork's user base at this point is <20 internal-company users and clobber risk is bounded.

Shell-script-based grep verification (scripts/verify-mode-picker-removed.sh): rejected because shell grep regex syntax differs subtly across macOS/Linux (BRE vs ERE), \| alternation requires -E and silently passes when omitted, and chained checks under set -e exit on first match instead of aggregating. The vitest-based typed assertion approach (specified above) avoids these traps and reuses the existing test harness without adding a new CI surface.

Rename mode === "primary" to mode === "harness" for hidden helpers: rejected because the "primary" value name remains semantically correct under A.1 (visible primary = build, hidden primary = compaction/title/summary), and the rename would touch schema, type, and serialization layers without functional benefit.

Split into two issues — UI removal first, schema/migration second: rejected because A.1 has no schema migration phase requiring its own PR (the field is rewritten away in a single startup pass); the UI changes are bounded to prompt-input.tsx plus i18n cleanup, small enough for a single PR with multiple commits per the project's commit small convention.

Defer to v1.3 Routines: rejected because Routines is scheduling, not a mode picker; the two work areas are orthogonal.

Implementation hints

This is a single-PR change with multiple commits per the project convention. Recommended commit slice ordering — note that the verification test must land last so each prior commit is bisect-clean (intermediate commits do not have the test, so the test does not retroactively fail historical state):

1. Add the default_agent one-shot config rewrite migration (Schema/Migration/Telemetry layers) so any deprecated value is migrated before runtime tries to resolve it.
2. Remove the plan agent definition and its prompt assets from agent.ts. Add the inline section comment.
3. Remove prompt-input.tsx agentList and rebind Tab to default textarea behavior.
4. Rewrite explore.txt for multi-domain scope; commit message records the rewrite rationale and upstream-not-synced status.
5. Identify and pin the message-renderer file path; add the message-renderer test for plain-text @<name> rendering with both no-mention-markup and text-preserved assertions.
6. i18n cleanup driven by the regex matches the new test will assert against (any matches require either fixing the string or removing the file).
7. Add the packages/app/test/no-mode-picker.test.ts vitest verification test as the final commit. Each assertion is its own it() block so a regression in any one surface produces a precise failure rather than an aggregated one. The test file uses Node fs walk + native regex (no shell grep) to assert source-tree absences.

Dependencies

Blocks #128 (rename task → agent). Aligns with #127 (Plan as tool, not mode). Indirectly unblocks #230 (default global AGENTS.md depends on a stable model-facing surface).