Complete Tool Catalog and Capability Taxonomy
Inputs, outputs, policy, and UI intent for every model-visible tool
Conclusion: DeepSeek Harness has no single fixed “default tool list”; it has a provably complete shipped-package ceiling and a runtime view resolved by composition
At the pinned baseline, the upstream generated catalog covers 24 shipped tool packages, 52 schema entries, and 51 unique generated names. The only duplicate is bash, registered by both a one-shot shell implementation and a persistent PTY implementation. The generator also records the shipped configured alias subagent_fork without giving it a separate schema heading, so the catalog represents 52 distinct shipped names. Those names never appear together by default: the standard Web preset resolves to 25 root tools on the baseline Linux composition with an attachment service, the minimal preset has 2, and Code/Cordis/custom presets, scope restrictions, dynamic plugins, and child identity change the set further.
This chapter counts package and tool headings in the generated catalog and checks every package-map row. It derives each actual set again from the shipped preset and host-service conditions. The generator boots every package in a separate real Context, reads ctx.tools.schemas(), and uses an on-disk glob to prevent a new tool package from being omitted. TOOLCAT-GENERATEDTOOLCAT-GENERATOR
1. Three Sets That Must Not Be Conflated
| Set | Pinned-baseline result | Question answered | What it does not prove |
|---|---|---|---|
| Generated catalog ceiling | 24 package sections; 52 schema entries; 51 unique generated names; 1 additional shipped alias | What every shipped packages/*/tool-* package can contribute under the selected config | That one Agent sees everything at once |
| Composition set | Preset + host services + platform + feature flags | Which definitions a deployment mounted | That every scope may see them |
| Request set | Scope view + restrictions + native/code/both projection | Which schemas this model request actually receives | That a call will be approved or its backend is ready |
There is also a fourth, temporal dimension: definitions are live Cordis effects. Hot mounting or disposal after queueing but before start can change visibility or parallel classification. Auditing therefore needs the request header and durable call/result records; the process's current catalog cannot reconstruct history by itself.
2. Why the Generated Catalog Is Stronger Than Static Grep—and Still Not Runtime Truth
glob packages/*/tool-* → completeness guard
for each manifest entry:
fresh Context → SystemPrompt → ToolRuntime → package-specific seams
→ mount plugin → ctx.tools.schemas(scope) → sort → dispose
render package map + name + description + JSON Schema + source link
Omitting an on-disk tool package from the manifest fails. Listing a package that remains pending for a missing service and registers zero schemas also fails. Each package boots independently so registrations from one package cannot be attributed to the next. TOOLCAT-GENERATOR
3. Complete Package/Name Map (24 Packages, 51 Generated Names + 1 Shipped Configured Alias)
| Capability family / package | Model-visible names | Main seam / effect |
|---|---|---|
Human · tool-ask-user | ask_user_question | Waits for a human answer from a UI/provider; the call remains open while waiting |
Code transport · tools | run_code | Reserved Code Mode transport; nested subcalls re-enter the complete tool pipeline |
Plan · plan-mode | exit_plan_mode | Reviews a plan and writes plan/mode inactive after approval |
| One-shot shell | bash / pwsh | Fresh process, optional background job; platform selects one |
Runtime self-modification · tool-cordis | cordis_define, cordis_inspect_list, cordis_inspect_query, cordis_inspect_self, cordis_run, cordis_stop, cordis_undefine | Defines, inspects, starts, and disposes process-local dynamic packages; absent from shipped trees by default |
| Persistent shell | bash | Owner-isolated PTY state; same name as one-shot bash, different definition |
| Standalone editor | str_replace_editor | View/create/literal replace/insert over ctx.fs |
| Filesystem | read, read_image, write, edit | Observation events, write/edit intents, durable attachments; image registration requires an attachment service |
| Filesystem discovery | glob, grep | Fixed argv invokes packaged ripgrep; complete capped output may spill |
| Terminal | terminal_open, terminal_read, terminal_send, terminal_signal, terminal_list, terminal_close | Persistent PTY lifecycle; send can register a background job |
| Goal | create_goal, get_goal, update_goal | Session-owned durable goal, revision, and round state with authority checks |
| Schedule | schedule_create, schedule_delete, schedule_list | Opt-in live root scope only; writes schedule/change |
| Language server | lsp | Stable schema and a structured refusal when no provider exists |
| Fixed iteration | ralph | Creates a fresh structured child per round in a fixed foreground workflow |
| Skill | skill | Loads a trusted instruction catalog/body and can inject replacement catalogs |
| Session query | session_search, session_event_search, session_trace, session_event_trace, session_event_read | Explicitly authorized lexical search, lineage, and exact event reads; absent from the default standard preset |
| Delegation | subagent (shipped alias subagent_fork) | Provider, name, and background mode are configured; the child owns a separate Session |
| Child control | send_message, interrupt_agent, list_agents | Follow-up, interruption, and listing for continuable children |
| Child return channel | report | Registered only inside a continuable in-process child; writes a user-role message to its direct parent |
| Background jobs | job_list, job_output, job_kill | Unified control for shell, PTY-send, and one-shot-subagent jobs |
| Todo | todo_write | Writes todo/write; allowing multiple in-progress items is a required deployment choice |
| Programmable orchestration | workflow | Restricted worker script orchestrates Agents; the script itself has no filesystem, network, or timers |
| Web | web_search, web_fetch | Provider-neutral seam; composition selects search and fetch availability |
The upstream package map records Requires, Writes/Affects, shipped aliases, and a deployment note for every package. Exact descriptions, parameter JSON Schemas, and production-source links follow. This table is the complete index without copying more than 1,800 lines of schemas. TOOLCAT-PACKAGE-MAP
4. The Standard Web Root's Actual 25 Tools
| Source | Names | Count |
|---|---|---|
| Platform shell | bash on Linux/macOS; pwsh on Windows | 1 |
| Filesystem + search | read, read_image, write, edit, glob, grep | 6 |
| Jobs + skill | job_list, job_output, job_kill, skill | 4 |
| Goal + plan | create_goal, get_goal, update_goal, exit_plan_mode | 4 |
| Delegation | subagent, subagent_fork, send_message, interrupt_agent, list_agents | 5 |
| Workflow | workflow, ralph | 2 |
| Interaction/state/web | ask_user_question, todo_write, web_search | 3 |
| Total | 25 |
The standard preset selects one platform shell; mounts fs/search/jobs/skill/goal/plan, two delegation names, three controls, workflow/Ralph/ask/todo; and sets fetch:false. The baseline host mounts a local attachment store, so read_image registers. TOOLCAT-STANDARD-BASETOOLCAT-STANDARD-ORCHESTRATIONTOOLCAT-ATTACHMENT
exit_plan_mode remains in the schema even when planning is inactive so changing mode does not churn the tool catalog and request-cache prefix; execution rejects invalid state instead. Codex and Claude Code delegation rows are explicitly disabled in this preset, and web_fetch is absent.
5. Minimal Is Not Merely “A Smaller Standard”; It Encodes a Different Complete Product Assumption
Minimal uses a complete persona, suppresses runtime-context snapshots, omits compaction, and exposes only persistent bash and str_replace_editor. It creates isolated realms for its PTY and bare local filesystem. TOOLCAT-MINIMAL
This is why “the Harness supports 51 tools” and “this Agent has 2 tools” can both be true. Capability is not a binary product checklist; it is the language a profile/preset composes for an Agent.
6. Same Name Does Not Mean Same Semantics: Two bash Definitions
| Implementation | Process model | State | Typical composition |
|---|---|---|---|
dsh-tool-bash | Fresh process per call through ctx.shell | cwd/env come from request and executor; no continuous PTY state | standard/base |
dsh-tool-bash-persistent | Reuses an owner-isolated PTY through ctx.terminals | Shell state survives across calls | minimal |
7. Filesystem Family: Discovery, Reads, Mutation, and Observation Are Separated
| Tool | Action | Key policy | Presentation intent |
|---|---|---|---|
glob/grep | Fixed-argv discovery through packaged rg | Timeout/cap/spill; neither shell nor ctx.fs | Search-result groups |
read | Bounded UTF-8 line window | Records present/absent version observation | Read card + locations |
read_image | Bounded bytes → content-addressed attachment | Extension/media/model-route gates before I/O | Durable image block + metadata |
write/edit | Create/overwrite and literal replacement | Default observation policy requires an unchanged version; sandbox can escalate approval | Diff intent + durable metadata |
str_replace_editor | Combines view/create/replace/insert in one tool | Compressed interface for minimal; still uses the fs seam | Generic/diff |
Notably, glob/grep are semantically read-only but do not opt into parallelism. Read/write semantics and scheduler classification are independent dimensions.
8. Shell, Terminal, and Job: Execution Capability Is Orthogonal to Lifecycle Control
bash/pwsh --run_in_background--> Job Registry <--terminal_send / one-shot subagent
|
job_list / job_output / job_kill
terminal_open/read/send/signal/list/close → persistent PTY registry
Job tools are not a shell-specific API; they form one control plane across producers. The six terminal tools explicitly expose session creation, I/O, signaling, and close in exchange for stronger statefulness. Standard does not mount them. Minimal does not expose terminal controls either; it wraps a persistent PTY as the same bash name.
9. Plan, Goal, Todo, and Ask: Four Human/Collaboration States, Not One Task List
| Primitive | Lifetime | Source of truth | Tool action |
|---|---|---|---|
| Plan mode | Agent mode across steps | plan/mode events + reviewer | exit_plan_mode submits a complete plan |
| Goal | Multi-round and continuable within a Session | Goal service/projection | Create/get/update |
| Todo | Latest checklist projection within a Session | todo/write | Whole-list replacement write |
| Question | Suspension of one tool call | UserQuestion provider | Waits for and returns an answer |
Chapter 15 analyzes their durable semantics. Here the important point is that similar names do not justify merging their tool surfaces.
10. Delegation, Workflow, and Ralph: Three Degrees of Orchestration Freedom
| Tool | The model chooses | The runtime fixes | Result channel |
|---|---|---|---|
subagent* | One child prompt, label, foreground/background | Provider, depth, background mode | Tool result, job settlement, or continuable child |
workflow | Fan-out/control flow in restricted JavaScript | Worker isolation, Agent bridge, concurrency/total caps | Foreground aggregated result |
ralph | Objective and optional round count | Fixed iteration script with a fresh child per round | Foreground final result |
send_message/interrupt_agent/list_agents manage continuable children. report exists in the reverse direction inside child scope, not in the root catalog. Chapters 24–26 trace Sessions, activation, and inboxes.
11. Web, LSP, Session Query, and Skill: Stable Schemas, Potentially Absent Provider Capability
These tools separate their model-facing contracts from backends: web_search/web_fetch use ctx.web, lsp uses ctx.lsp, Session Query uses ctx.sessionQuery whose FTS can be disabled, and Skill uses a scope-layered catalog. Schemas may remain prefix-stable while execution returns unavailable/disabled. A visible tool never proves provider success.
This stable surface favors KV caching and provider replacement. The cost is that capability discovery cannot stop at schemas. A strong host should also surface provider readiness, policy mode, and failure reasons in UI/telemetry instead of making the model probe with failed calls.
12. The Cordis Toolset Is a Deliberately Opt-in “Modify My Runtime” Capability
The seven cordis_* tools define, inspect, run, stop, and undefine dynamic packages. A running package can register more model-visible tools until stop, undefine, or restart, so the 51-name ceiling is naturally non-closed once this facility is enabled.
The generated package map explicitly says this toolset appears in no shipped tree. Without dynamicCordisRunner it never activates. It is not a hidden default superpower; it is a real runtime-code trust boundary a deployment must opt into. TOOLCAT-PACKAGE-MAP
13. Parallel Classification: Only 8 Unique Names/Definitions Explicitly Opt In; Everything Else Fails Closed to Exclusive
| Explicitly parallel-safe | Rationale | In standard root? |
|---|---|---|
read, read_image | Reads only; later mutation closes observation races with an in-lock version check; attachments are content-addressed | Yes |
web_search, web_fetch | Provider reads do not mutate parent-Agent state | Search only |
session_trace, session_event_trace, session_event_read | Authorized exact/lineage reads | No; query package is opt-in |
subagent definition (including configured aliases) | A child does not mutate the parent Session; the only parent write is a synchronous commutative task insertion | subagent and subagent_fork |
After excluding helpers, generated code, and tests, production source contains only these eight isConcurrencySafe: () => true declarations. The registry returns parallel only for an exact true; absence, invalid input, or a thrown classifier is exclusive. Seemingly read-only operations such as glob/grep, goal reads, and job listing therefore remain barriers. TOOLCAT-PARALLEL-OPTINSTOOL-SCHEMA-PROJECTION
14. “Dangerous” Is Not One Boolean on a Tool Name
| Risk axis | Representative tools | Actual control point |
|---|---|---|
| File mutation | write/edit/editor | fs intent, observed version, sandbox escalation, approval |
| Arbitrary process | bash/pwsh/terminal | Sandbox provider, shell policy, timeout, signal/job kill |
| External data flow | web/MCP/LSP | Provider URL/credential/SSRF boundary and output retention |
| Cross-Agent | subagent/control/workflow | Parent authority, depth/caps, workspace effects, continuation ownership |
| Durable state | goal/todo/schedule | Session/root authority, event validation, durability barrier |
| Runtime code | run_code/cordis_* | VM/worker surface, nested pipeline, opt-in composition |
This table is a threat-model classification, not a source-level risk score. Harness distributes controls across provider confinement, pre approval, monotonic guards, tool-specific event gates, and execution ownership. Chapters 19, 20, and 31 verify those boundaries.
15. Inputs, Outputs, and UI Intent: The Catalog Promises Model Schemas; the Execution Contract Still Lives in ToolDefinition
The generator emits name, description, parameter JSON Schema, and source for each item. Output schemas, canonical values, timeout/concurrency metadata, presenters, and finalizers are outside the generated catalog page. The ToolDefinition analysis in Chapter 16 and this package map must be read together. TOOLCAT-GENERATORTOOL-DEFINITION
The UI does not hard-code every card by tool name either. Tools return provider-neutral generic/terminal/diff/search/read/web render intents. The Host pairs calls and results through the current scoped definition; missing pairing or presenter failure preserves the raw event and falls back to a generic card. TOOL-PRESENTATION-INTENTSTOOL-HOST-PRESENTER
16. Availability Matrix: Registration, Visibility, Scheduling, Approval, and Backend Readiness Are Five Gates
package mounted?
→ required service satisfied and tool registered?
→ current Agent scope can see it?
→ presentation mode exposes native name or Code SDK?
→ pre-policy + approval + guards allow this call?
→ provider/runtime is ready and body succeeds?
A “no” at any layer can appear as no schema, UNKNOWN_TOOL, approval required, provider unavailable, or an ordinary error result. Calling all of them “permission failures” sends diagnosis to the wrong layer.
17. Confirmed Documentation/Composition Drift and Audit Traps
| Trap | Correct reading |
|---|---|
| Treating the generated catalog as the standard default | It is an isolated per-package boot ceiling; derive standard from its preset |
| Guessing parallelism from “read-only” | Only an explicit classifier returning true is parallel; everything else is exclusive |
| Inferring implementation from tool name | bash has two shipped definitions, and subagent names are configurable |
| Assuming schema presence means provider readiness | LSP/Web/Query can keep stable schemas and fail as unavailable at execution |
| Using today's presenter to reconstruct historical UI | The Host reads the current definition; a call on an older page gets generic fallback |
| Assuming Code Mode deletes capabilities | It changes the wire entrance; the SDK retains end capabilities and subcalls re-enter the pipeline |
18. Design Assessment and Verification Status
| Choice | Benefit | Cost |
|---|---|---|
| Separate tool package from provider seam | Stable schemas with replaceable backends | Schemas cannot express readiness |
| Collect the generated catalog by real boot | Captures dynamic schemas, configured names, and injection conditions | Still represents the generator's selected config branches |
| Let presets define the capability language | One runtime spans a two-tool minimal Agent and a full Agent | Any “default count” needs surface/platform/service qualifiers |
| Make parallelism explicit opt-in | Unknown third-party tools serialize safely | Read-only tools that omit the declaration lose throughput |
| Provider-neutral presentation | Web and CLI share semantics with replay fallback | Hot-changing a presenter can change the current rendering of old events |
This chapter checked the generated tool catalog, generator completeness/boot logic, all 24 package-map rows, standard and minimal shipped presets, the attachment condition, every production isConcurrencySafe declaration, and the ToolRuntime classifier. Counts come from reproducible heading statistics over the pinned-baseline text. Upstream dependencies are absent, so this chapter does not claim a local generator or upstream-test run. The site's own build and consistency checks run before publication.
My Learning Notes
Autosaved only in this browser. Nothing is uploaded or committed. Export Markdown whenever you want to keep a copy.