ask-tools-shell 0.5.2 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e0ee1bfe576ebc5adc41d2e6b07334c928eede7abea5b29a8ba991afe2d9921
-  data.tar.gz: cc92808594b5b4a5d6022cf93ae0c6347a1410bccb6443ce56fb9fe49c05dc17
+  metadata.gz: 2407410de312f720991b648cadfdbd84aac2986d87724c11e065c7e0b8d72c21
+  data.tar.gz: 585878ed410c7beff114eb62dd1dd4eb33b7fbe266fd889381d40b971ffd44a6
 SHA512:
-  metadata.gz: 179d47b5235324542e3f3ee08474201ba0f4c5ec1ae7413b997c8cb8574588bbf356e08982bdb2e14a2f722eff89a79c3ef1444251469d27b030a8a4ecc57de3
-  data.tar.gz: f3afa00cf9b407113e4b4ef2af37e4c5ba99ed750296463d4bfc706f850f10da0ca2467b5de6ba050aa30206d2a75dbe5a22de0af600746b804495cb126fd7e5
+  metadata.gz: 6ac091ee7160a917a112846c6ace5e314013fcbd690d05689043111635a68cebf91fcf84ebea29be7c895acbd83854035637c91f1567f4dcc73874596a6f43e7
+  data.tar.gz: 4c6f5fe647154f278132ef95ce1c659478fad636e30ae86fd99847bcc95dcfc8d4958c043d3877bc93a40d7b75b041913d93f772c3952c5dcfff04fb4c96dab4

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [0.6.0] - 2026-08-14
+
+### Added
+- **Git tools** — a scoped git surface for workspace sessions, run through
+  the sandbox (never a free-form shell, argv-array so nothing passes through
+  a shell): `git_status` (branch + changed files), `git_diff` (unstaged,
+  staged with `cached`, optional `path`), `git_log` (recent commits, optional
+  `count`), `git_commit` (commits only what is staged), `git_branch`
+  (current + local branches), `git_worktree` (worktree list). Each tool
+  honors `default_workdir` (the session workspace, pinned by the host) and
+  refuses loudly without one; all are registered in the global registry so
+  any host resolves them by name.
+
 ## [0.5.1] - 2026-08-10
 
 ### Fixed

data/lib/ask/tools/shell/bash.rb

@@ -16,7 +16,14 @@ module Ask
       param :timeout, type: :integer, desc: "Timeout in seconds", required: false
       param :workdir, type: :string, desc: "Working directory", required: false
 
+      # The session's workspace: set by the host when it builds the
+      # session's tools, so commands without an explicit cd run in the
+      # agent's workspace — not in the host process's cwd. The agent
+      # can still override with an explicit workdir or cd.
+      attr_accessor :default_workdir
+
       def execute(command:, timeout: 30, workdir: nil)
+        workdir ||= default_workdir
         result = Ask::Sandbox.provider.call(
           command,
           timeout: timeout,

data/lib/ask/tools/shell/git/base.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "ask-sandbox-providers"
+
+module Ask
+  module Tools
+    module Git
+      # Shared plumbing for the git tools: run scoped git commands in
+      # the workspace through the sandbox — the same provider bash
+      # uses, but with a fixed command (never a free-form shell) and
+      # argv-array form (nothing passes through a shell, so a hostile
+      # value stays a value).
+      #
+      # The host pins default_workdir to the session's workspace (the
+      # same mechanism Bash's workdir uses); a tool invoked without a
+      # workspace — outside a session — refuses loudly rather than
+      # touching the host's own checkout.
+      class Base < Ask::Tool
+        # The session's workspace: set by the host when it builds the
+        # session's tools.
+        attr_accessor :default_workdir
+
+        private
+
+        # Run git with the given arguments in the workspace and map
+        # the sandbox result to Ask::Result, the ecosystem convention.
+        def git(*args, timeout: 30)
+          if default_workdir.to_s.empty?
+            return Ask::Result.error(message: "git tools need a session workspace")
+          end
+
+          result = Ask::Sandbox.provider.call(["git", *args], timeout: timeout, workdir: default_workdir)
+          data = {stdout: result.stdout, stderr: result.stderr, exit_code: result.exit_code, timed_out: result.timed_out}
+          if result.success?
+            Ask::Result.ok(data: data)
+          else
+            stderr = result.stderr.to_s.strip
+            Ask::Result.error(message: stderr.empty? ? "git failed" : stderr, metadata: data)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/tools/shell/git/branch.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Ask
+  module Tools
+    module Git
+      # The workspace's branches: which one is checked out, and what
+      # else exists. Read-only.
+      class Branch < Base
+        description "Show the current branch and all local branches in the workspace. Read-only."
+        name "git_branch"
+
+        def execute
+          git("branch", "--list")
+        end
+      end
+    end
+  end
+end

data/lib/ask/tools/shell/git/commit.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Ask
+  module Tools
+    module Git
+      # Commit the staged changes with a message. The one mutation in
+      # the git toolkit: the executor's deliverable becomes history.
+      # Commits only what is staged — staging stays a deliberate act.
+      class Commit < Base
+        description "Commit the staged changes in the workspace with the given message. " \
+                     "Mutating — only what is staged is committed."
+        name "git_commit"
+
+        params do
+          string :message, description: "The commit message", required: true
+        end
+
+        def execute(message:)
+          git("commit", "-m", message)
+        end
+      end
+    end
+  end
+end

data/lib/ask/tools/shell/git/diff.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Ask
+  module Tools
+    module Git
+      # The changes themselves: an unstaged diff by default, staged
+      # with `cached`, optionally limited to one path. Read-only —
+      # the executor reads before it writes.
+      class Diff < Base
+        description "Show the uncommitted diff in the workspace: unstaged by default, " \
+                     "staged with cached: true, optionally limited to one path. Read-only."
+        name "git_diff"
+
+        params do
+          boolean :cached, description: "Diff the staged changes instead", required: false
+          string :path, description: "Limit the diff to this path", required: false
+        end
+
+        def execute(cached: false, path: nil)
+          args = ["diff"]
+          args << "--cached" if cached
+          args += ["--", path] if path
+          git(*args)
+        end
+      end
+    end
+  end
+end

data/lib/ask/tools/shell/git/log.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Ask
+  module Tools
+    module Git
+      # Recent commit history: hash, subject, author, relative time —
+      # the executor's sense of where the branch has been. Read-only.
+      class Log < Base
+        description "Show the recent commit history: hash, subject, author, and relative time. Read-only."
+        name "git_log"
+
+        params do
+          integer :count, description: "How many commits to show", required: false
+        end
+
+        def execute(count: 20)
+          git("log", "--oneline", "-n", count.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/ask/tools/shell/git/status.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Ask
+  module Tools
+    module Git
+      # The working tree's state: current branch plus staged, unstaged,
+      # and untracked changes — what the workspace looks like since the
+      # last commit. The executor's first question before touching code.
+      class Status < Base
+        description "Show the git working tree status: current branch and changed files " \
+                     "(staged, unstaged, untracked). Read-only."
+        name "git_status"
+
+        def execute
+          git("status", "--short", "--branch")
+        end
+      end
+    end
+  end
+end

data/lib/ask/tools/shell/git/worktree.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Ask
+  module Tools
+    module Git
+      # The workspace's worktrees: paths, branches, and checked-out
+      # commits — parallel work happening in the same repository.
+      # Read-only.
+      class Worktree < Base
+        description "Show the git worktrees in the workspace: path, branch, and commit. Read-only."
+        name "git_worktree"
+
+        def execute
+          git("worktree", "list")
+        end
+      end
+    end
+  end
+end

data/lib/ask/tools/shell/version.rb

@@ -3,7 +3,7 @@
 module Ask
   module Tools
     module Shell
-      VERSION = "0.5.2"
+      VERSION = "0.6.1"
     end
   end
 end

data/lib/ask/tools/shell.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "shell/version"
-require "ask/tools/tool"
+require "ask/tools"
 require_relative "shell/bash"
 require_relative "shell/read"
 require_relative "shell/file_ledger"
@@ -12,11 +12,19 @@ require_relative "shell/grep"
 require_relative "shell/code"
 require_relative "shell/apply_patch"
 require_relative "shell/repl"
+require_relative "shell/git/base"
+require_relative "shell/git/status"
+require_relative "shell/git/diff"
+require_relative "shell/git/log"
+require_relative "shell/git/commit"
+require_relative "shell/git/branch"
+require_relative "shell/git/worktree"
 
 module Ask
   module Tools
     module Shell
-      TOOLS = [Bash, Read, Write, Edit, Glob, Grep, Code, ApplyPatch, Repl].freeze
+      TOOLS = [Bash, Read, Write, Edit, Glob, Grep, Code, ApplyPatch, Repl,
+        Git::Status, Git::Diff, Git::Log, Git::Commit, Git::Branch, Git::Worktree].freeze
 
       def self.all
         TOOLS.map(&:new)
@@ -24,3 +32,13 @@ module Ask
     end
   end
 end
+
+# The git tools resolve by name from the global registry (the host's
+# name-based fallback for non-built-in tools) — registering here makes
+# them available to any host that loads ask-tools-shell.
+Ask::Tools.register(Ask::Tools::Git::Status)
+Ask::Tools.register(Ask::Tools::Git::Diff)
+Ask::Tools.register(Ask::Tools::Git::Log)
+Ask::Tools.register(Ask::Tools::Git::Commit)
+Ask::Tools.register(Ask::Tools::Git::Branch)
+Ask::Tools.register(Ask::Tools::Git::Worktree)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-tools-shell
 version: !ruby/object:Gem::Version
-  version: 0.5.2
+  version: 0.6.1
 platform: ruby
 authors:
 - Kaka Ruto
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.6.1
+        version: 0.6.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.6.1
+        version: 0.6.2
 - !ruby/object:Gem::Dependency
   name: ask-sandbox-providers
   requirement: !ruby/object:Gem::Requirement
@@ -98,6 +98,13 @@ files:
 - lib/ask/tools/shell/edit.rb
 - lib/ask/tools/shell/file_ledger.rb
 - lib/ask/tools/shell/file_mutation_queue.rb
+- lib/ask/tools/shell/git/base.rb
+- lib/ask/tools/shell/git/branch.rb
+- lib/ask/tools/shell/git/commit.rb
+- lib/ask/tools/shell/git/diff.rb
+- lib/ask/tools/shell/git/log.rb
+- lib/ask/tools/shell/git/status.rb
+- lib/ask/tools/shell/git/worktree.rb
 - lib/ask/tools/shell/glob.rb
 - lib/ask/tools/shell/grep.rb
 - lib/ask/tools/shell/read.rb