Git Worktree

The session git tool runs git as a privileged host operation. It accepts a structured command object (command, plus subcommand/name/path for worktrees) and returns a tool result with output and an exit code. worktree with subcommand: 'create' adds a worktree at path on a new branch named name. This example inspects a repo, then creates, lists, and removes a worktree directly through the tool surface.

Rust

Node.js

Python

Rust

use a3s_code_core::Agent;
use serde_json::json;
use std::path::Path;

#[tokio::main]
async fn main() -> a3s_code_core::Result<()> {
    let agent = Agent::new("agent.acl").await?;
    let session = agent.session_builder("/path/to/repo").build().await?;

    let status = session.tool("git", json!({ "command": "status" })).await?;
    println!("{}", status.output);

    let worktree = Path::new("/path/to/repo").join("wt-feature-auth");
    let created = session
        .tool(
            "git",
            json!({
                "command": "worktree",
                "subcommand": "create",
                "name": "feature-auth",
                "path": worktree
            }),
        )
        .await?;
    if created.exit_code != 0 {
        return Err(a3s_code_core::CodeError::Tool {
            tool: "git".into(),
            message: format!("create failed: {}", created.output),
        });
    }

    let list = session
        .tool(
            "git",
            json!({ "command": "worktree", "subcommand": "list" }),
        )
        .await?;
    println!("{}", list.output);

    let removed = session
        .tool(
            "git",
            json!({
                "command": "worktree",
                "subcommand": "remove",
                "path": worktree
            }),
        )
        .await?;
    if removed.exit_code != 0 {
        return Err(a3s_code_core::CodeError::Tool {
            tool: "git".into(),
            message: format!("remove failed: {}", removed.output),
        });
    }

    session.close().await;
    agent.close().await;
    Ok(())
}

TypeScript

import { Agent } from '@a3s-lab/code';
import * as path from 'path';

const agent = await Agent.create('agent.acl');
const session = await agent.sessionAsync('/path/to/repo');

// Inspect the repo
const status = await session.git({ command: 'status' });
console.log(status.output);

// Create a worktree on a new branch
const wtPath = path.join('/path/to/repo', 'wt-feature-auth');
const created = await session.git({
  command: 'worktree',
  subcommand: 'create',
  name: 'feature-auth',
  path: wtPath,
});
if (created.exitCode !== 0) throw new Error(`create failed: ${created.output}`);

// List worktrees
const list = await session.git({ command: 'worktree', subcommand: 'list' });
console.log(list.output);

// Remove the worktree when done
const removed = await session.git({
  command: 'worktree',
  subcommand: 'remove',
  path: wtPath,
});
if (removed.exitCode !== 0) throw new Error(`remove failed: ${removed.output}`);

await session.closeAsync();
await agent.close();

Python

import os
from a3s_code import Agent, SessionOptions

agent = Agent.create("agent.acl")
session = agent.session("/path/to/repo", SessionOptions())

# Inspect the repo
status = session.git({"command": "status"})
print(status.output)

# Create a worktree on a new branch
wt_path = os.path.join("/path/to/repo", "wt-feature-auth")
created = session.git({
    "command": "worktree",
    "subcommand": "create",
    "name": "feature-auth",
    "path": wt_path,
})
if created.exit_code != 0:
    raise RuntimeError(f"create failed: {created.output}")

# List worktrees
listing = session.git({"command": "worktree", "subcommand": "list"})
print(listing.output)

# Remove the worktree when done
removed = session.git({
    "command": "worktree",
    "subcommand": "remove",
    "path": wt_path,
})
if removed.exit_code != 0:
    raise RuntimeError(f"remove failed: {removed.output}")

session.close()
agent.close()

package main

import (
	"context"
	"fmt"
	"log"
	"path/filepath"

	code "github.com/A3S-Lab/Code/sdk/go/v9"
)

func main() {
	ctx := context.Background()
	agent, err := code.Create(ctx, "agent.acl")
	if err != nil {
		log.Fatal(err)
	}
	defer agent.Close(context.Background())
	session, err := agent.Session(ctx, "/path/to/repo", nil)
	if err != nil {
		log.Fatal(err)
	}
	defer session.Close(context.Background())

	status, err := session.Git(ctx, code.GitOptions{Command: "status"})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(status.Output)

	worktree := filepath.Join("/path/to/repo", "wt-feature-auth")
	created, err := session.Git(ctx, code.GitOptions{
		Command: "worktree", Subcommand: "create",
		Name: "feature-auth", Path: worktree,
	})
	if err != nil {
		log.Fatal(err)
	}
	if created.ExitCode != 0 {
		log.Fatalf("create failed: %s", created.Output)
	}
	list, err := session.Git(ctx, code.GitOptions{
		Command: "worktree", Subcommand: "list",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(list.Output)

	removed, err := session.Git(ctx, code.GitOptions{
		Command: "worktree", Subcommand: "remove", Path: worktree,
	})
	if err != nil {
		log.Fatal(err)
	}
	if removed.ExitCode != 0 {
		log.Fatalf("remove failed: %s", removed.Output)
	}
}

Pass a command object rather than positional arguments: { command: 'status' }, { command: 'diff' }, or { command: 'worktree', subcommand: 'list' }. The command values are status, log, branch, checkout, diff, stash, remote, and worktree; the tool has no commit or push command. Each call returns a tool result, so check exit_code (Rust/Python), exitCode (Node.js), or ExitCode (Go) before trusting the output.

Direct git calls are privileged host operations: they skip the session's permission policy and confirmation prompts. Gate branch switches and worktree removal in your application, or use governedTool('git', ...) / governed_tool / GovernedTool to keep the session's gates.

A runnable version ships at sdk/node/examples/git/test_worktree_git.ts.

#Git Worktree

Git Worktree