14 KiB
14 KiB
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-56lists the manifest tool surface.src/resources/extensions/sf/bootstrap/register-extension.js:87-99registers SF bootstrap tool groups.src/resources/extensions/sf/bootstrap/db-tools.js:84-2845registers the planning, completion, requirement, issue, checkpoint, gate, and chapter tools.src/resources/extensions/sf/bootstrap/exec-tools.js:23-172registersrun_command,read_output,resume_agent, andkill_agent.src/resources/extensions/sf/subagent/index.js:1965-3266registers subagent and codebase-search tools.src/resources/extensions/sf/prompts/*.mdcontains hard references toplan_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-165defines built-in tool names;packages/coding-agent/src/core/sdk.ts:361-379defines default active tool names.packages/coding-agent/src/core/agent-session.ts:985-1009swaps hashline mode by active registry keys.src/resources/extensions/mcp-client/index.js:8-11documentsmcp_servers,mcp_discover, andmcp_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.