fix: update export commands in documentation and examples to use 'opengap' instead of 'gapman'; add TODOs for tool implementations

Author: krishvsoni

CONTRIBUTING.md

@@ -136,7 +136,7 @@ If your framework has a config file format, add an exporter in `commands/export.
 If your example directory commits an `expected_output.py` (or similar) snapshot, regenerate it whenever you change the adapter so it does not drift:
 
 ```bash
-gapman export --dir examples/<name> --format <name> --output examples/<name>/expected_output.py
+opengap export --dir examples/<name> --format <name> --output examples/<name>/expected_output.py
 ```
 
 ### 4. Document what's lossy

examples/deepagents/README.md

@@ -6,7 +6,7 @@ A research agent with a fact-checker sub-agent, demonstrating the DeepAgents ada
 - `SOUL.md` — agent identity, embedded in the generated `system_prompt`
 - `skills/web-research/`, `skills/summarize/` — passed via a `skills=` path resolved next to the generated module (`Path(__file__).parent / "skills"`), so discovery works from any working directory; DeepAgents loads each `SKILL.md` natively
 - `tools/web-search.yaml` — emitted as a `@tool` function bound into `tools=[...]`
-- `agents/fact-checker/` — emitted as a `SubAgent` dict in `subagents=[...]`
+- `agents/fact-checker/` — emitted as a `SubAgent` dict in `subagents=[...]`. By default a sub-agent inherits the full parent `TOOLS` list; add a `tools:` list to the sub-agent's own `agent.yaml` to narrow it to a subset.
 - `expected_output.py` — the Python module the adapter produces
 
 DeepAgents is a higher-level harness on top of LangGraph — there is no graph
@@ -17,7 +17,7 @@ adapter instead.
 ## Regenerate
 
 ```bash
-gapman export --dir examples/deepagents --format deepagents --output examples/deepagents/expected_output.py
+opengap export --dir examples/deepagents --format deepagents --output examples/deepagents/expected_output.py
 ```
 
 ## Run the generated agent
@@ -30,7 +30,7 @@ python examples/deepagents/expected_output.py
 Or let gitagent generate and run it for you (pass an initial message with `-p`, read from `GITAGENT_PROMPT`):
 
 ```bash
-gapman run --dir examples/deepagents --adapter deepagents -p "Who won the 2022 World Cup?"
+opengap run --dir examples/deepagents --adapter deepagents -p "Who won the 2022 World Cup?"
 ```
 
 The generated file leaves tool implementations as `NotImplementedError` stubs — replace them with your own logic before invoking.

examples/deepagents/expected_output.py

@@ -39,6 +39,7 @@ def _run_pre_tool_use_hooks(tool_name: str) -> None:
 def web_search(query: str) -> str:
     """Search the public web for a query"""
     _run_pre_tool_use_hooks("web-search")
+    # TODO: replace this stub with a real implementation of "web-search"
     raise NotImplementedError("Implement tool: web-search")
 
 TOOLS = [web_search]
@@ -63,7 +64,8 @@ def web_search(query: str) -> str:
 You are a pedantic fact-checker. Treat every claim as unverified until you
 locate a primary source. If a claim cannot be substantiated, say so plainly.
 """,
-    "tools": TOOLS,
+    "tools": TOOLS,  # inherits the full parent toolset (default) — add `tools: [...]` to
+    # this sub-agent's agent.yaml (agents/fact-checker/agent.yaml) to narrow it
 }
 
 SUBAGENTS = [fact_checker_subagent]

examples/langgraph/README.md

@@ -13,7 +13,7 @@ A two-step research agent that demonstrates the LangGraph adapter:
 ## Regenerate
 
 ```bash
-gapman export --dir examples/langgraph --format langgraph --output examples/langgraph/expected_output.py
+opengap export --dir examples/langgraph --format langgraph --output examples/langgraph/expected_output.py
 ```
 
 ## Run the generated graph
@@ -26,7 +26,7 @@ python examples/langgraph/expected_output.py
 Or let gitagent generate and run it for you (pass an initial message with `-p`, read from `GITAGENT_PROMPT`):
 
 ```bash
-gapman run --dir examples/langgraph --adapter langgraph -p "Summarize the latest on RISC-V adoption"
+opengap run --dir examples/langgraph --adapter langgraph -p "Summarize the latest on RISC-V adoption"
 ```
 
 The generated file leaves tool implementations as `NotImplementedError` stubs — replace them with your own logic before invoking.

examples/langgraph/expected_output.py

@@ -53,6 +53,7 @@ class AgentState(TypedDict):
 @tool
 def web_search(query: str) -> str:
     """Search the public web for a query"""
+    # TODO: replace this stub with a real implementation of "web-search"
     raise NotImplementedError("Implement tool: web-search")
 
 TOOLS = [web_search]

src/adapters/deepagents.test.ts

@@ -191,6 +191,30 @@ describe('exportToDeepAgents', () => {
     assert.match(code, /subagents=SUBAGENTS,/);
   });
 
+  test('sub-agent with its own `tools:` list gets a narrowed tools array, not the full parent TOOLS', () => {
+    const dir = makeAgentDir({
+      tools: [{ name: 'web-search' }, { name: 'send-email' }],
+      subAgents: [{ name: 'fact-checker', description: 'Verifies claims' }],
+    });
+    writeFileSync(
+      join(dir, 'agents', 'fact-checker', 'agent.yaml'),
+      `spec_version: '0.1.0'\nname: fact-checker\nversion: '0.1.0'\ndescription: 'Verifies claims'\ntools:\n  - web-search\n`,
+      'utf-8',
+    );
+    const { code } = exportToDeepAgents(dir);
+    assert.match(code, /"tools": \[web_search\],/);
+    assert.doesNotMatch(code, /"tools": TOOLS,/);
+  });
+
+  test('sub-agent without a `tools:` list inherits the full parent TOOLS', () => {
+    const dir = makeAgentDir({
+      tools: [{ name: 'web-search' }],
+      subAgents: [{ name: 'fact-checker', description: 'Verifies claims' }],
+    });
+    const { code } = exportToDeepAgents(dir);
+    assert.match(code, /"tools": TOOLS,/);
+  });
+
   test('pre_tool_use hooks are invoked from inside each generated tool function', () => {
     const dir = makeAgentDir({
       tools: [{ name: 'noop', description: 'A no-op' }],

src/adapters/deepagents.ts

@@ -38,6 +38,8 @@ interface SubAgentDef {
   description: string;
   systemPrompt: string;
   hasSkills: boolean;
+  /** Tool names to expose to this sub-agent, or null to inherit the full parent TOOLS list. */
+  toolNames: string[] | null;
 }
 
 export function exportToDeepAgents(dir: string): DeepAgentsExport {
@@ -48,7 +50,7 @@ export function exportToDeepAgents(dir: string): DeepAgentsExport {
   const skills = loadAllSkills(join(agentDir, 'skills'));
   const tools = collectTools(agentDir);
   const preToolUseScripts = collectPreToolUseHooks(agentDir);
-  const subAgents = collectSubAgents(agentDir);
+  const subAgents = collectSubAgents(agentDir, tools);
 
   const code = renderPython({
     manifest,
@@ -137,10 +139,11 @@ function collectPreToolUseHooks(agentDir: string): string[] {
   }
 }
 
-function collectSubAgents(agentDir: string): SubAgentDef[] {
+function collectSubAgents(agentDir: string, tools: ToolDef[]): SubAgentDef[] {
   const agentsDir = join(agentDir, 'agents');
   if (!existsSync(agentsDir)) return [];
 
+  const knownToolNames = new Set(tools.map(t => t.name));
   const out: SubAgentDef[] = [];
   const entries = readdirSync(agentsDir, { withFileTypes: true });
   for (const entry of entries) {
@@ -150,11 +153,16 @@ function collectSubAgents(agentDir: string): SubAgentDef[] {
 
     try {
       const subManifest = loadAgentManifest(subDir);
+      // A sub-agent's agent.yaml may declare its own `tools:` list to narrow
+      // which of the parent's tools it receives. Unknown names are dropped;
+      // an empty/absent list means "inherit the full parent TOOLS" (default).
+      const declared = (subManifest.tools ?? []).filter(name => knownToolNames.has(name));
       out.push({
         name: subManifest.name,
         description: subManifest.description,
         systemPrompt: buildSystemPrompt(subDir, subManifest),
         hasSkills: existsSync(join(subDir, 'skills')),
+        toolNames: declared.length > 0 ? declared : null,
       });
     } catch {
       // skip sub-agents that fail to load
@@ -199,6 +207,9 @@ function renderPython(ctx: RenderContext): string {
   lines.push('# Agent metadata');
   lines.push(`AGENT_NAME = ${pyStr(manifest.name)}`);
   lines.push(`AGENT_VERSION = ${pyStr(manifest.version)}`);
+  // create_deep_agent() resolves a string MODEL via langchain's init_chat_model,
+  // which natively understands "provider:model" strings (e.g. "anthropic:claude-sonnet-4-5").
+  // No prefix stripping is needed here — passing it straight through is correct.
   lines.push(`MODEL = ${pyStr(model)}`);
   lines.push('');
 
@@ -236,6 +247,7 @@ function renderPython(ctx: RenderContext): string {
       lines.push(`def ${fnName}(${sig}) -> str:`);
       lines.push(`    ${pyTripleStr(t.description || `Tool: ${t.name}`)}`);
       lines.push(`    _run_pre_tool_use_hooks(${pyStr(t.name)})`);
+      lines.push(`    # TODO: replace this stub with a real implementation of "${t.name}"`);
       lines.push(`    raise NotImplementedError("Implement tool: ${t.name}")`);
       lines.push('');
     }
@@ -270,7 +282,13 @@ function renderPython(ctx: RenderContext): string {
       lines.push(`    "name": ${pyStr(sub.name)},`);
       lines.push(`    "description": ${pyStr(sub.description)},`);
       lines.push(`    "system_prompt": ${pyTripleStr(sub.systemPrompt)},`);
-      lines.push('    "tools": TOOLS,');
+      if (sub.toolNames) {
+        const list = sub.toolNames.map(pyIdent).join(', ');
+        lines.push(`    "tools": [${list}],  # narrowed via agents/${sub.name}/agent.yaml's \`tools:\` list`);
+      } else {
+        lines.push('    "tools": TOOLS,  # inherits the full parent toolset (default) — add `tools: [...]` to');
+        lines.push(`    # this sub-agent's agent.yaml (agents/${sub.name}/agent.yaml) to narrow it`);
+      }
       if (sub.hasSkills) {
         lines.push(`    "skills": [str(Path(__file__).resolve().parent / "agents" / ${pyStr(sub.name)} / "skills")],`);
       }

src/adapters/langgraph.ts

@@ -305,6 +305,7 @@ function renderPython(ctx: RenderContext): string {
       lines.push('@tool');
       lines.push(`def ${fnName}(${sig}) -> str:`);
       lines.push(`    ${pyTripleStr(t.description || `Tool: ${t.name}`)}`);
+      lines.push(`    # TODO: replace this stub with a real implementation of "${t.name}"`);
       lines.push(`    raise NotImplementedError("Implement tool: ${t.name}")`);
       lines.push('');
     }