Model agent

The model agent is what runs when you give tsforge a task. It is not a separate program you invoke. It is the loop inside tsforge: send context to the model, run tool calls, check the gate, feed errors back, repeat.

One approved task can involve many agent cycles until the gate passes or tsforge stops.

One cycle

1. Build a prompt from your task, file context, and detected stack hints
2. Offer tools (read/edit/create, optional LSP, optional scaffolders)
3. Execute accepted tool calls on disk
4. Run Fix bad tool calls when JSON is malformed
5. Run the gate; on failure, send structured errors and loop

Tools the model may see

Group	Tools	When
Core	read, run, edit, create	always
Line edits	edit_lines	always (line-number edits with hash verification)
Script	script	always (programmatic tool calling: batch multi-step tool use in one program); withhold with TSFORGE_NO_SCRIPT=1 for eval
Navigation	search, symbol_search, find_references, go_to_definition, type_at, impact, symbol_context, diagnostics, rename_symbol, move_file, organize_imports	existing-code repos
Git context	git_context	existing-code repos (read-only: diff/log/blame/show to scope a change)
Conventions	pull_conventions	build backends that ship a convention library (BoringStack): fetch a how-to guide on demand
Web research	package_info, package_docs, web_fetch, web_search, web_browse	when Web tools is on in /config (no required API keys or paid browser/search service)

On greenfield specs, navigation tools are often withheld so the model focuses on creating files instead of exploring an empty tree. See TypeScript language server.

Stream protection

Stop bad output early (TTSR) can abort a tool call mid-stream if forbidden patterns appear.

File context

The model cannot edit a file it has not read. Specs and tasks should list which files are in scope (files: / context:). See Spec format. Some paths are always read-only regardless of scope. See Vendored & read-only scope.

→ Big picture · When the gate fails