# SF Tool Rename Mapping Draft

Status: draft. Evidence read in this pass: `src/resources/extensions/sf/extension-manifest.json`, `src/resources/extensions/sf/experimental.js`, `src/resources/extensions/sf/bootstrap/register-extension.js`, `src/resources/extensions/sf/bootstrap/*tools*.js`, `src/resources/extensions/sf/tools/*.js`, `src/resources/extensions/sf/subagent/index.js`, `src/resources/extensions/sf/prompts/*.md`, `packages/coding-agent/src/core/tools/*.ts`, `packages/coding-agent/src/core/sdk.ts`, `packages/coding-agent/src/core/agent-session.ts`, and `src/resources/extensions/mcp-client/index.js`.

## Inventory Notes

The current SF manifest exposes 45 tools, not the approximate 33 in the operator note. Registration code adds at least two more SF-owned tools (`context_board`, `manage_todos`) that are not listed in the manifest. SF sessions also expose the coding-agent built-ins (`read`, `grep`, `find`, `ls`, `bash`, `edit`, `write`, `lsp`; hashline mode swaps `read`/`edit` behavior). MCP tools are a separate extension surface.

Prompt/source risk anchors:

- `src/resources/extensions/sf/extension-manifest.json:12-56` lists the manifest tool surface.
- `src/resources/extensions/sf/bootstrap/register-extension.js:87-99` registers SF bootstrap tool groups.
- `src/resources/extensions/sf/bootstrap/db-tools.js:84-2845` registers the planning, completion, requirement, issue, checkpoint, gate, and chapter tools.
- `src/resources/extensions/sf/bootstrap/exec-tools.js:23-172` registers `run_command`, `read_output`, `resume_agent`, and `kill_agent`.
- `src/resources/extensions/sf/subagent/index.js:1965-3266` registers subagent and codebase-search tools.
- `src/resources/extensions/sf/prompts/*.md` contains hard references to `plan_milestone`, `plan_slice`, `complete_task`, `complete_slice`, `complete_milestone`, `validate_milestone`, `reassess_roadmap`, `replan_slice`, `save_summary`, and related tools.
- `packages/coding-agent/src/core/tools/index.ts:154-165` defines built-in tool names; `packages/coding-agent/src/core/sdk.ts:361-379` defines default active tool names.
- `packages/coding-agent/src/core/agent-session.ts:985-1009` swaps hashline mode by active registry keys.
- `src/resources/extensions/mcp-client/index.js:8-11` documents `mcp_servers`, `mcp_discover`, and `mcp_call`.

## Mapping Table

Risk means rename migration risk: low = no meaningful callers by name found in prompts/tests/error strings; medium = source/renderer/runtime references; high = prompts, test fixtures, error strings, or workflow guards reference the exact name.

| Current tool | Source evidence | Decision | Target | Lazy | Risk | Rationale |
|---|---|---|---|---|---|---|
| `Bash` target | `packages/coding-agent/src/core/tools/bash.ts:374`, `src/resources/extensions/sf/bootstrap/dynamic-tools.js:155` | rename alias | keep canonical `bash`; add `Bash` alias only if provider benefits from Claude-style case | no | high | Already canonical lowercase; prompts mention `bash`; tests reference `bash`. Case rename could break provider/tool registry assumptions. |
| `Read` target | `packages/coding-agent/src/core/tools/read.ts`, `src/resources/extensions/sf/bootstrap/dynamic-tools.js:164-171` | rename alias | keep `read`; optional `Read` alias | no | high | Core file read surface; hashline mode also returns name `read`. |
| `Edit` target | `packages/coding-agent/src/core/tools/edit.ts:95`, `src/resources/extensions/sf/bootstrap/dynamic-tools.js:172-179` | rename alias | keep `edit`; optional `Edit` alias | no | high | Core file edit surface and prompt assumptions. |
| `Write` target | `packages/coding-agent/src/core/tools/write.ts:45`, `src/resources/extensions/sf/bootstrap/dynamic-tools.js:156-163` | rename alias | keep `write`; optional `Write` alias | no | high | Core file creation surface; execution prompts refer to `Write`. |
| `Grep` target | `packages/coding-agent/src/core/tools/grep.ts:93`, `packages/coding-agent/src/core/system-prompt.ts:191-206` | rename alias | keep `grep`; optional `Grep` alias | no | medium | Built-in prompt guidance names lowercase `grep`. |
| `Glob` target | `packages/coding-agent/src/core/tools/find.ts:74` | rename-to | `glob` / `Glob` alias for `find` | no | high | Known dialect drift; `find` is semantically Claude Code `Glob`, but shell `find` also appears in prompts and docs. Keep `find` during alias phase. |
| `ls` | `packages/coding-agent/src/core/tools/ls.ts:68` | keep-as-is | `ls` | no | medium | Claude Code has no exact high-value case rename; low confusion. |
| `lsp` | `packages/coding-agent/src/core/tools/index.ts:162`, `packages/coding-agent/src/core/system-prompt.ts:226-236` | keep-as-is | `lsp` | no | medium | SF-specific semantic navigation tool; prompts recommend it directly. |
| `hashline_read` | `packages/coding-agent/src/core/agent-session.ts:997-1004`, `packages/coding-agent/src/core/tools/hashline-read.ts:79` | fold-into | `read` with hashline mode metadata | no | high | Registry key exists, but actual tool name is `read`; mode swap already hides novel name from most LLM calls. |
| `hashline_edit` | `packages/coding-agent/src/core/tools/hashline-edit.ts:170`, `packages/coding-agent/src/core/agent-session.ts:997-1006` | fold-into | `edit` with hashline mode metadata | no | high | Novel name has tests and UI references; alias/fold only after hashline mode can advertise `edit`. |
| `run_command` | `src/resources/extensions/sf/bootstrap/exec-tools.js:23`, `src/resources/extensions/sf/tools/exec-tool.js:1-145` | fold-into | `bash` or `Bash` with SF run-history mode | no | high | Duplicate shell exec surface; prompts/error strings and saved history say `run_command`. Requires careful compatibility. |
| `read_output` | `src/resources/extensions/sf/bootstrap/exec-tools.js:91` | fold-into | `bash` result retrieval or `read_command_output` alias | yes | medium | Only meaningful after async `run_command`; lazy candidate if `run_command` remains. |
| `resume_agent` | `src/resources/extensions/sf/bootstrap/exec-tools.js:141` | mark-lazy | `resume_agent` | yes | medium | Session/runtime operation, not common planning path. |
| `kill_agent` | `src/resources/extensions/sf/bootstrap/exec-tools.js:172` | mark-lazy | `kill_agent` | yes | medium | Runtime control; keep explicit due destructive semantics. |
| `subagent` | `src/resources/extensions/sf/subagent/index.js:1965` | keep-as-is | `subagent` | no | high | Prompts and skills reference it as SF fabric. |
| `await_subagent` | `src/resources/extensions/sf/subagent/index.js:3041` | mark-lazy | `await_subagent` | yes | medium | Only after `subagent`; load with subagent result controls. |
| `cancel_subagent` | `src/resources/extensions/sf/subagent/index.js:3125` | mark-lazy | `cancel_subagent` | yes | medium | Runtime control, uncommon. |
| `write_subagent` | `src/resources/extensions/sf/subagent/index.js:3153` | mark-lazy | `write_subagent` | yes | medium | Only useful for active subagent. |
| `read_subagent` | `src/resources/extensions/sf/subagent/index.js:3266` | mark-lazy | `read_subagent` | yes | medium | Only useful for active subagent. |
| `codebase_search` | `src/resources/extensions/sf/subagent/index.js:2641` | rename-to | `Grep`/`search_code` alias; keep old | yes | medium | Broad semantic search overlaps Grep/Sift; can lazy-load as advanced retrieval. |
| `sift_search` | `src/resources/extensions/sf/tools/sift-search-tool.js:272` | mark-lazy | `sift_search` | yes | medium | Specialized retrieval; system context suggests scoped sift when healthy. |
| `memory_search` | `src/resources/extensions/sf/bootstrap/memory-tools.js:71` | mark-lazy | `memory_search` | yes | medium | Not every turn needs memory retrieval. |
| `memory_graph` | `src/resources/extensions/sf/bootstrap/memory-tools.js:131` | mark-lazy | `memory_graph` | yes | medium | Specialized visualization/query. |
| `log_reasoning` | `src/resources/extensions/sf/bootstrap/memory-tools.js:16` | mark-lazy | `log_reasoning` | yes | low | Lower prompt presence; keep explicit audit semantics. |
| `log_decision` | `src/resources/extensions/sf/bootstrap/judgment-tools.js:11` | fold-into | `save_decision` | yes | medium | Duplicate decision capture surface. |
| `save_decision` | `src/resources/extensions/sf/bootstrap/db-tools.js:84` | keep-as-is | `save_decision` | no | high | Prompted planning contract and DB projection surface. |
| `save_knowledge` | `src/resources/extensions/sf/bootstrap/db-tools.js:785` | mark-lazy | `save_knowledge` | yes | medium | Useful but not core per-turn planning CRUD. |
| `save_requirement` | `src/resources/extensions/sf/bootstrap/db-tools.js:323` | fold-into | `requirements` facade | yes | high | Requirement prompts and DB update paths refer to exact names. |
| `update_requirement` | `src/resources/extensions/sf/bootstrap/db-tools.js:210` | fold-into | `requirements` facade | yes | high | Same risk as `save_requirement`; status transitions are important. |
| `save_summary` | `src/resources/extensions/sf/bootstrap/db-tools.js:393` | keep-as-is | `save_summary` | no | high | Project/discuss/research prompts require it. |
| `new_milestone_id` | `src/resources/extensions/sf/bootstrap/db-tools.js:520` | fold-into | `plan_milestone` or `milestone` facade | yes | high | Discuss prompts explicitly name it. |
| `plan_milestone` | `src/resources/extensions/sf/bootstrap/db-tools.js:1195` | fold-into | `milestone` facade (`op: plan`) | no | high | 27 files matched; prompt-critical DB write. |
| `complete_milestone` | `src/resources/extensions/sf/bootstrap/db-tools.js:2286` | fold-into | `milestone` facade (`op: complete`) | no | high | Completion prompt and tests reference exact name. |
| `validate_milestone` | `src/resources/extensions/sf/bootstrap/db-tools.js:2405` | fold-into | `milestone` facade (`op: validate`) | no | high | Validation prompt-critical. |
| `plan_slice` | `src/resources/extensions/sf/bootstrap/db-tools.js:1547` | fold-into | `slice` facade (`op: plan`) | no | high | 20 files matched; core autonomous planning. |
| `replan_slice` | `src/resources/extensions/sf/bootstrap/db-tools.js:2469` | fold-into | `slice` facade (`op: replan`) | no | high | Replan prompts and workflow guards reference exact name. |
| `complete_slice` | `src/resources/extensions/sf/bootstrap/db-tools.js:2000` | fold-into | `slice` facade (`op: complete`) | no | high | Completion prompt-critical. |
| `skip_slice` | `src/resources/extensions/sf/bootstrap/db-tools.js:2254` | fold-into | `slice` facade (`op: skip`) | yes | medium | Less frequent control operation. |
| `plan_task` | `src/resources/extensions/sf/bootstrap/db-tools.js:1806` | fold-into | `task` facade (`op: plan`) | no | high | Planning prompts forbid/require it in specific flows. |
| `complete_task` | `src/resources/extensions/sf/bootstrap/db-tools.js:1853` | fold-into | `task` facade (`op: complete`) | no | high | 32 files matched; mandatory execution completion. |
| `reassess_roadmap` | `src/resources/extensions/sf/bootstrap/db-tools.js:2615` | keep-as-is or fold into `roadmap` facade | no | high | Reassess prompt requires it; renaming mid-cycle is risky. |
| `milestone_status` | `src/resources/extensions/sf/bootstrap/query-tools.js:8` | keep-as-is | `milestone_status` | no | high | Read-only DB-safe status path; reassess prompt directs use instead of sqlite. |
| `search_evidence` | `src/resources/extensions/sf/bootstrap/query-tools.js:41` | mark-lazy | `search_evidence` | yes | medium | Specialized evidence retrieval. |
| `query_journal` | `src/resources/extensions/sf/bootstrap/journal-tools.js:7` | mark-lazy | `query_journal` | yes | medium | Useful for investigation but not baseline. |
| `audit_product` | `src/resources/extensions/sf/bootstrap/product-audit-tool.js:10` | mark-lazy | `audit_product` | yes | medium | Product-audit unit specific. |
| `report_issue` | `src/resources/extensions/sf/bootstrap/db-tools.js:629` | mark-lazy | `report_issue` | yes | medium | Self-feedback/issue path; not core for all turns. |
| `resolve_issue` | `src/resources/extensions/sf/bootstrap/db-tools.js:948` | mark-lazy | `resolve_issue` | yes | medium | Issue workflow specific. |
| `checkpoint` | `src/resources/extensions/sf/bootstrap/db-tools.js:1076`, `src/resources/extensions/sf/auto/run-unit.js:753` | keep-as-is | `checkpoint` | no | high | Solver/executor contracts mention checkpoint. |
| `record_gate` | `src/resources/extensions/sf/bootstrap/db-tools.js:2694` | mark-lazy | `record_gate` | yes | medium | Gate-specific write. |
| `chapter_open` | `src/resources/extensions/sf/bootstrap/db-tools.js:2755` | mark-lazy | `chapter_open` | yes | low | Narrative/run chapter operation. |
| `chapter_close` | `src/resources/extensions/sf/bootstrap/db-tools.js:2845` | mark-lazy | `chapter_close` | yes | low | Narrative/run chapter operation. |
| `context_board` | `src/resources/extensions/sf/bootstrap/context-board-tool.js:35` | mark-lazy | `context_board` | yes | medium | Registered but absent from manifest; system context can render board without always exposing writer. |
| `manage_todos` | `src/resources/extensions/sf/bootstrap/session-todo-tools.js:24` | mark-lazy | `manage_todos` | yes | low | Registered but absent from manifest; session UX helper. |
| `mcp_servers` | `src/resources/extensions/mcp-client/index.js:129-142` | keep-as-is | `mcp_servers` | yes | medium | External MCP discovery boundary; not SF workflow CRUD. |
| `mcp_discover` | `src/resources/extensions/mcp-client/index.js:179-194` | keep-as-is | `mcp_discover` | yes | medium | Already lazy-connect prior art. |
| `mcp_call` | `src/resources/extensions/mcp-client/index.js:307-318` | keep-as-is | `mcp_call` | yes | medium | Distinct external-tool semantics. |
| `mcp__<server>__<tool>` | `packages/coding-agent/src/modes/interactive/components/tool-execution.ts:65-74` | keep-as-is | adapter-owned | yes | medium | Adapter-surfaced names are external and should not be normalized with SF CRUD tools. |

## Highest-Risk Rename Set

The highest-risk rename set is `complete_task`, `plan_milestone`, and `plan_slice`. They are hard-coded in prompts, workflow reconciliation, tests, and status summaries; changing them without aliases will stop autonomous units from persisting the canonical DB-backed artifacts.

## Suggested Collapsed Facades

- `milestone`: `op: "new_id" | "plan" | "validate" | "complete" | "status"`.
- `slice`: `op: "plan" | "replan" | "complete" | "skip"`.
- `task`: `op: "plan" | "complete"`.
- `requirements`: `op: "save" | "update"`.

Do not remove old names in the first release. The alias period must include prompt rewrites, test fixture rewrites, renderer/event summaries, and a repo-wide forbidden-name guard.
