tau-coding-agent 0.4.6__tar.gz → 0.4.7__tar.gz

{tau_coding_agent-0.4.6/tau_coding_agent.egg-info → tau_coding_agent-0.4.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tau-coding-agent
-Version: 0.4.6
+Version: 0.4.7
 Summary: A self-extensible agent CLI with terminal UI, multi-provider LLM support, session management with branching, and a plugin system for tools and commands
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -26,6 +26,7 @@ Requires-Dist: pygments==2.20.0
 Requires-Dist: pathspec==1.1.1
 Requires-Dist: gitpython==3.1.50
 Requires-Dist: grapheme==0.6.0
+Requires-Dist: arrow==1.4.0
 Provides-Extra: tools
 Requires-Dist: ripgrep>=14.0.0; extra == "tools"
 Dynamic: license-file

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.7}/docs/cli-reference.md

@@ -31,6 +31,13 @@ augment it.
 
 ## Run Modes
 
+## Interactive Commands
+
+`/watch <url> [question]` loads metadata and available English captions for a
+public video through `yt-dlp`, then sends them to the active model. Install
+`yt-dlp` separately and ensure it is available on `PATH`. Video frames and
+audio transcription are not performed.
+
 ### Interactive (default)
 
 Start the full terminal UI:

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.7}/docs/docs.json

@@ -43,6 +43,10 @@
         {
           "title": "Tools",
           "path": "tools.md"
+        },
+        {
+          "title": "Project Context",
+          "path": "project-context.md"
         }
       ]
     },

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.7}/docs/extensions.md

@@ -487,6 +487,34 @@ def register(tau):
 | `input` | `text`, `source` | `InputEventResult` | New user message received. `source`: `interactive \| rpc \| extension \| queue`. Return `action="transform"` with `text=` to replace, or `action="handled"` to suppress |
 | `context` | `messages` | `ContextEventResult` | Full message history about to be sent to LLM. Return `messages=` to rewrite it |
 
+For dynamic browser or computer-use state that must be refreshed before every
+LLM request without being persisted, return `ephemeral_messages` from a
+`context` handler:
+
+```python
+from tau.hooks import ContextEventResult
+from tau.message.types import UserMessage
+
+def register(tau):
+    @tau.on("context")
+    async def inject_state(event, ctx):
+        screenshot = await capture_screen()
+        return ContextEventResult(
+            ephemeral_messages=[
+                UserMessage.with_images(
+                    "Current browser state",
+                    images=[screenshot],
+                )
+            ]
+        )
+```
+
+The hook runs before every inference, including after tool execution.
+`ephemeral_messages` must contain only `UserMessage` objects. They are appended
+only to the provider request, are not persisted, and are excluded from
+Anthropic prompt-cache breakpoints. Use `messages=` in the same result to
+replace the stable request context.
+
 **Streaming & messages**
 
 | Event | Payload fields | Result type | Description |

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.7}/docs/index.md

@@ -27,6 +27,7 @@ Tau allows you to:
 - [Sessions](sessions.md) - Session persistence, branching, compaction, JSONL format
 - [Inference Providers](inference-providers.md) - Supported LLMs and provider setup
 - [Tools](tools.md) - Tool registry, built-in tools, execution model
+- [Project Context Files](project-context.md) - Repository-specific agent instructions
 - [CLI Reference](cli-reference.md) - All command-line options and run modes
 
 ## Configuration & Customization

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.7}/docs/messages.md

@@ -62,9 +62,14 @@ Output from executing a tool.
 }
 ```
 
+Assistant text and thinking content are rendered as Markdown in the interactive
+TUI, including while content is streaming. Tool results remain plain text unless
+the tool explicitly marks a successful result for Markdown rendering.
+
 ### System Message
 
-Context and instructions for the agent. Loaded from `.agents.md` file in project or home directory.
+Context and instructions for the agent. Tau constructs this separately from
+persisted session messages and may include trusted project context files.
 
 ```python
 {
@@ -145,17 +150,18 @@ Use `@` in the editor to fuzzy-search files.
 
 ## System Instructions
 
-Tau loads system instructions from `.agents.md` files in your project or home directory:
+Tau loads project instructions from context files:
+
+**Within a Git repository:**
 
-**Project-level** (priority):
-- `.agents.md` or `agents.md` in project root or parent directories
-- Injected into context for the current project
+- `AGENTS.md` or `CLAUDE.md`, matched case-insensitively
+- One file per directory from the repository root through the current directory
+- Files closer to the current directory take precedence
 
-**Global**:
-- `~/.tau/agents.md` in home directory
-- Used as fallback for all projects
+Outside a Git repository, only the current directory is checked. Context files
+are loaded only for trusted projects.
 
-Example `.agents.md`:
+Example `AGENTS.md`:
 
 ```markdown
 # Project Instructions
@@ -167,6 +173,7 @@ Example `.agents.md`:
 ```
 
 Instructions are automatically injected into every turn sent to the LLM.
+See [Project Context Files](project-context.md) for complete behavior.
 
 ## Message Delivery
 

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.7}/docs/project-context.md

@@ -5,9 +5,13 @@ Tau automatically discovers and includes project-specific instructions from `AGE
 ## Overview
 
 When you run Tau in a project directory, it:
+
 1. Looks for `AGENTS.md` or `CLAUDE.md` (case-insensitive)
-2. If found and the project is trusted, includes the content in the system prompt
-3. Prioritizes project instructions above general Tau guidelines
+2. Walks from the Git repository root through the current directory
+3. If the project is trusted, includes one context file from each directory
+4. Prioritizes the closest file above parent files, general Tau rules, and tool guidelines
+
+Outside a Git repository, Tau checks only the current directory.
 
 This is useful for:
 - **Coding standards** — Define how the agent should write code
@@ -53,13 +57,14 @@ Or use `CLAUDE.md` for the same purpose (they're equivalent).
 
 ### File priority
 
-Tau checks for these files in order (case-insensitive):
+Tau checks for these names case-insensitively, in this order:
+
 1. `AGENTS.md`
-2. `AGENTS.MD`
-3. `CLAUDE.md`
-4. `CLAUDE.MD`
+2. `CLAUDE.md`
 
-The first one found is used.
+The first one found in each directory is used. When multiple directories provide
+instructions, Tau orders them from the repository root to the current directory.
+The closest file takes precedence if instructions conflict.
 
 ## Trust & Security
 
@@ -140,7 +145,8 @@ Project-specific guidelines and rules (from AGENTS.md):
 
 [Content of AGENTS.md here]
 
-Follow project-specific instructions before general Tau guidelines.
+Files are ordered from the repository root toward the current directory; later
+files take precedence.
 ```
 
 The agent sees this and prioritizes project instructions when making decisions.
@@ -220,14 +226,15 @@ The agent sees this and prioritizes project instructions when making decisions.
 ## Common Issues
 
 **Project context not appearing**
-- Check the file exists in the project root
-- Verify filename is exactly `AGENTS.md` or `CLAUDE.md`
+
+- Check the file exists between the repository root and current directory
+- Verify the filename is `AGENTS.md` or `CLAUDE.md`, in any letter case
 - Check project trust: `tau --approve` or `/trust` command
 - Use `--no-context-files` to confirm it's being loaded
 
 **Want to see if it's loaded**
-- Run with `--verbose` flag for logging (when available)
-- Check system prompt in `/session` command
+
+- Inspect the effective system prompt through the Python API or an extension context
 
 **Trust decisions not persisting**
 - By default, trust decisions are stored in `~/.tau/trust.json`
@@ -239,7 +246,7 @@ The agent sees this and prioritizes project instructions when making decisions.
 | Approach | When to use | Pros | Cons |
 |----------|-----------|------|------|
 | **AGENTS.md/CLAUDE.md** | Team project guidelines | Lightweight, auto-discovered, version-controlled | Limited to per-project |
-| **Custom prompt (`--system-prompt`)** | One-off instructions | Flexible | Lost after session |
+| **Custom prompt (`--system`)** | Complete one-off prompt replacement | Flexible | Bypasses generated tools, project context, skills, Git, environment, and append sections |
 | **settings.json** | User/global preferences | Persistent | Not project-specific |
 | **Environment variables** | Sensitive data, deployment-specific | Secure, flexible | Not human-readable |
 

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.7}/docs/python-api.md

@@ -46,7 +46,7 @@ asyncio.run(main())
 | `tools` | `list[Tool]` | Extra tools registered as `"runtime"` source |
 | `tool_allowlist` | `set[str] \| None` | Enable only these built-in, runtime, or extension tool names |
 | `exclude_tools` | `set[str]` | Tool names disabled after applying the allowlist |
-| `system_prompt` | `str` | Custom system prompt (overrides the default) |
+| `system_prompt` | `str` | Complete system-prompt replacement; bypasses generated tools, project context, skills, Git, environment, and append sections |
 | `disable_context_files` | `bool` | Skip AGENTS.md / CLAUDE.md discovery and loading |
 | `project_trusted` | `bool \| None` | Override project trust detection (`None` uses trust-store and policy defaults) |
 | `resource_loader` | `ResourceLoader \| None` | Replace resource discovery and registry loading |
@@ -451,6 +451,31 @@ await runtime.invoke("What is 2 + 2?")
 print(last_response)
 ```
 
+## Ephemeral Context Injection
+
+Browser and computer-use agents can inject current state before every model
+request without persisting it in the session by configuring the engine:
+
+```python
+from tau.engine import Agent as Engine, Options as EngineOptions
+from tau.message.types import UserMessage
+
+async def current_browser_state() -> list[UserMessage]:
+    return [UserMessage.with_images("Current browser state", images=[screenshot])]
+
+engine = Engine(
+    cwd=Path.cwd(),
+    llm=llm,
+    tools=tools,
+    options=EngineOptions(ephemeral_injection=current_browser_state),
+)
+```
+
+The callback runs after context transformation and before each inference,
+including inference after tool execution. Failures are logged and ignored.
+Injected messages are appended only to the request copy. Anthropic prompt-cache
+breakpoints exclude this transient tail.
+
 ## Example: Batch Processing
 
 ```python

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.7}/docs/settings.md

@@ -79,8 +79,7 @@ All field names use `snake_case`.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `provider` | string | Default provider, e.g. `"anthropic"`, `"openai"` |
-| `model` | string | Default model ID, e.g. `"claude-sonnet-4-6"` |
+| `model` | object | Per-modality model selections: `text`, `voice`, `speak`, `image`, and `video` |
 | `thinking_level` | string | Extended thinking budget level (see below) |
 | `transport` | string | Transport layer override (`"streaming"` or `"polling"`) |
 | `enabled_models` | list[string] | Restrict the model picker to these model IDs |
@@ -88,12 +87,25 @@ All field names use `snake_case`.
 
 ```json
 {
-  "provider": "anthropic",
-  "model": "claude-sonnet-4-6",
+  "model": {
+    "text": {
+      "id": "claude-sonnet-4-6",
+      "provider": "anthropic"
+    },
+    "speak": {
+      "id": "tts-1",
+      "provider": "openai",
+      "voice": "coral"
+    }
+  },
   "thinking_level": "low"
 }
 ```
 
+Each model reference contains `id` and `provider`. The `speak` reference may
+also contain `voice`; `/model` prompts for it after selecting a text-to-speech
+model that declares supported voices.
+
 #### Extended thinking
 
 Extended thinking gives the model a private scratchpad — a reasoning trace it works through before producing its response. It trades token budget (and cost) for accuracy on complex tasks like multi-step reasoning, planning, and math.

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.7}/docs/tools.md

@@ -8,13 +8,15 @@ Tau ships with seven built-in tools covering file I/O, search, and shell executi
 
 ### read
 
-Read the contents of a file. Every returned line is prefixed with a hashline
-anchor in the form `<line>:<hash>|<content>`. The `edit` tool uses these anchors.
+Read a UTF-8 text file. Invalid byte sequences are replaced during decoding.
+Every returned line is prefixed with a content-based hashline anchor in the form
+`<line>:<hash>|<content>`. Duplicate content, including blank lines, can share a
+hash; the line number acts as a proximity hint when `edit` resolves an anchor.
 
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
 | `path` | string | Yes | — | Absolute path to the file to read |
-| `offset` | integer | No | `0` | Line number to start reading from (0-based) |
+| `offset` | integer | No | `0` | Number of lines to skip; `0` starts at the first line |
 | `limit` | integer | No | `2000` | Maximum number of lines to return |
 
 ### write
@@ -24,14 +26,16 @@ Create a new file or overwrite an existing file entirely.
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `path` | string | Yes | Absolute path to write |
-| `content` | string | Yes | Full file content |
+| `content` | string | Yes | Exact complete UTF-8 text content |
 
 ### edit
 
 Replace an inclusive line range using hashline anchors returned by `read`.
-The content hash lets an anchor survive line insertions or deletions elsewhere
+The content hash can let an anchor survive line insertions or deletions elsewhere
 in the file; when content occurs more than once, its original line number is
-used as a proximity hint. Edit-result diffs also display hashline anchors:
+used as a proximity hint and the closest occurrence is selected. An empty
+`new_content` deletes the selected range. Because the complete file is rewritten,
+an edit may normalize line endings. Edit-result diffs also display hashline anchors:
 removed lines use their old hashes, while added and context lines use current hashes.
 
 | Parameter | Type | Required | Default | Description |
@@ -39,50 +43,55 @@ removed lines use their old hashes, while added and context lines use current ha
 | `path` | string | Yes | — | Absolute path to the file |
 | `start_anchor` | string | Yes | — | First line to replace, formatted `<line>:<hash>` |
 | `end_anchor` | string | Yes | — | Last line to replace; use the start anchor for a single-line edit |
-| `new_content` | string | Yes | — | Content that replaces the anchored range |
+| `new_content` | string | Yes | — | UTF-8 text replacing the range; empty text deletes it |
 
 ### terminal
 
-Execute a shell command and return combined stdout + stderr.
+Execute a non-interactive shell command and return the combined stdout + stderr
+tail. At most 50 KiB or 2,000 lines are retained.
 
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
-`command` | string | Yes | — | Shell command to execute.
-`timeout` | integer | No | `30` | Timeout in seconds (max 600)
+| `cmd` | string | Yes | — | Non-interactive shell command to execute |
+| `timeout` | integer | No | `30` | Timeout in seconds (max 600) |
 
 Commands run in the agent's current working directory.
 
 ### glob
 
-Find files matching a glob pattern.
+Find files matching a glob pattern. Patterns are evaluated relative to `path`.
+Ripgrep's default filtering excludes hidden files and files matched by ignore
+rules.
 
 Requires `rg` (ripgrep); the tool returns an error when `rg` is unavailable.
 
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
 | `pattern` | string | Yes | — | Glob pattern, e.g. `src/**/*.py` |
-| `path` | string | No | cwd | Base directory to search from |
+| `path` | string | No | cwd | Base directory; relative values use Tau's process working directory |
 
 ### grep
 
-Search for a regular expression across files.
+Search for a regular expression across files. Directory searches are recursive.
+Ripgrep's default filtering excludes hidden files and files matched by ignore
+rules.
 
 Requires `rg` (ripgrep); the tool returns an error when `rg` is unavailable.
 
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
 | `pattern` | string | Yes | — | Regular expression to search for |
-| `path` | string | No | cwd | File or directory to search |
+| `path` | string | No | cwd | File or directory; relative values use Tau's process working directory |
 | `include` | string | No | `""` | Glob filter for files, e.g. `*.py` (only applies when `path` is a directory) |
 | `case_sensitive` | boolean | No | `true` | Whether the pattern is case-sensitive |
 
 ### ls
 
-List the contents of a directory.
+List a directory's immediate contents without recursing.
 
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
-| `path` | string | No | cwd | Directory path to list |
+| `path` | string | No | cwd | Directory; relative values use Tau's process working directory |
 
 ---
 
@@ -120,6 +129,11 @@ threshold or `result_expandable=False` to always show their complete rendered
 output. Custom renderers should return their complete semantic output and must
 not add expand/collapse hints.
 
+Tool results render as plain text by default. A tool can opt an individual
+successful result into Markdown rendering with
+`metadata={"_render_format": "markdown"}`. Tau renders the Markdown before
+applying the standard preview/collapse shell. Error results remain plain text.
+
 ---
 
 ## Adding Custom Tools
@@ -137,7 +151,7 @@ path and committed with an atomic replacement.
 
 ## Tool Constraints
 
-Add a `.agents.md` file to your project root to give the agent standing instructions about tool usage:
+Add an `AGENTS.md` file to your project to give the agent standing instructions about tool usage:
 
 ```markdown
 # Project Instructions
@@ -148,7 +162,9 @@ Add a `.agents.md` file to your project root to give the agent standing instruct
 - Use `edit` for small changes, `write` for new files
 ```
 
-Tau searches for `.agents.md`, `agents.md`, or `~/.tau/agents.md`. The file is automatically loaded at session start and injected into the agent's context.
+Tau searches case-insensitively for `AGENTS.md` or `CLAUDE.md` from the Git
+repository root through the current directory. See
+[Project Context Files](project-context.md) for precedence and trust behavior.
 
 ---
 

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.7}/docs/usage.md

@@ -46,7 +46,7 @@ Type `/` to open the command palette. Commands are fuzzy-searchable — type a f
 
 | Command | Description |
 |---------|-------------|
-| `/model` | Open the model picker |
+| `/model` | Pick a model by modality; Speak models with declared voices open a second voice picker |
 | `/theme` | Open the theme picker |
 | `/effort` | Set the thinking effort level |
 
@@ -65,11 +65,16 @@ Type `/` to open the command palette. Commands are fuzzy-searchable — type a f
 | `/copy` | Copy the last assistant message to the clipboard |
 | `/reload` | Reload extensions, skills, prompts, and settings |
 | `/settings` | Show current settings |
+| `/watch <url> [question]` | Load public video metadata and captions using `yt-dlp` |
 | `/help` or `/?` | List all commands and keyboard shortcuts |
 | `/quit` or `/q` or `/exit` | Exit tau |
 
 Extensions and prompts also appear in the command palette. Type `/` and browse to see everything available.
 
+`/watch` requires `yt-dlp` on `PATH`. It reads metadata and English captions
+from public URLs supported by `yt-dlp`; it does not download or inspect video
+frames. When captions are unavailable, the agent receives metadata only.
+
 ---
 
 ## Command Details
@@ -166,8 +171,13 @@ tau --ephemeral      # temporary session, nothing saved
 
 Tau loads context files at startup to give the agent standing instructions. It searches for:
 
-1. `.agents.md` or `agents.md` in current directory and parent directories (up to home)
-2. `~/.tau/agents.md` in the user's home
+1. `AGENTS.md` or `CLAUDE.md`, matched case-insensitively
+2. Every directory from the Git repository root through the current directory
+
+Outside a Git repository, Tau checks only the current directory. It loads at most
+one context file per directory, preferring `AGENTS.md` over `CLAUDE.md`. Files
+closer to the current directory take precedence over files closer to the repository
+root.
 
 Use context files to provide system-level instructions:
 

{tau_coding_agent-0.4.6 → tau_coding_agent-0.4.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tau-coding-agent"
-version = "0.4.6"
+version = "0.4.7"
 description = "A self-extensible agent CLI with terminal UI, multi-provider LLM support, session management with branching, and a plugin system for tools and commands"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -30,6 +30,7 @@ dependencies = [
     "pathspec==1.1.1",
     "gitpython==3.1.50",
     "grapheme==0.6.0",
+    "arrow==1.4.0",
 ]
 
 [project.scripts]