clikit-plugin 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clikit-plugin",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "OpenCode plugin — 7 agents, 15 commands, 22 skills, 10 hooks",
   "type": "module",
   "main": "./dist/index.js",

package/skill/tilth-reading/SKILL.md

@@ -10,43 +10,60 @@ When any task requires reading files or exploring a codebase, follow this priori
 ## Priority Chain
 
 ```
-1. tilth      → smart, outline-aware, section-targeted reading
-2. read       → raw file content (fallback for full-file needs)
-3. glob       → fallback when you need to discover file paths
-4. grep       → fallback when you need to search content patterns
+1. bash: tilth <path>    → smart, outline-aware, section-targeted reading
+2. read <path>           → raw file content (auto-enhanced by hook when tilth available)
+3. glob <pattern>        → fallback when you need to discover file paths
+4. grep <pattern>        → fallback when you need to search content patterns
 ```
 
+## Two Paths — Know Which to Use
+
+| Situation | How to invoke tilth |
+|-----------|-------------------|
+| Want smart full read or outline | `bash: tilth <path>` |
+| Want a specific section or heading | `bash: tilth <path> --section "## Heading"` |
+| Want a line range | `bash: tilth <path> --section 45-89` |
+| Tilth unavailable or bash not permitted | `read <path>` (hook auto-enhances when possible) |
+| Need to discover paths first | `glob pattern="…"` |
+| Need content pattern search | `grep pattern="…"` |
+
+> **Runtime hook:** the `tilth_reading` hook already enhances `read` tool output via tilth when tilth is on PATH.  
+> So `read` alone is often sufficient for full-file reads — use explicit `bash: tilth` when you need section targeting or outline-only mode.
+
 ## Workflow
 
-### Step 1 — Try tilth (always first)
+### Step 1 — Try tilth via bash (always first for large/unknown files)
 
 ```bash
+# Check tilth is available (cache result — don't repeat every call)
+tilth --version
+
 # Read a whole file (smart: outline or full depending on size)
 tilth <path>
 
-# Read a specific section by line range
-tilth <path> --section 45-89
-
 # Read a specific section by markdown heading
 tilth <path> --section "## Installation"
-```
 
-**Tilth is available if:** `npx tilth --version` exits 0, or a local `tilth` binary is on PATH.
+# Read a specific section by line range
+tilth <path> --section 45-89
+```
 
 **When tilth succeeds:** use its output directly. Do not duplicate with `read`.
 
-**When tilth fails or is unavailable:** immediately fall back — do not retry tilth for the same path.
+**When tilth fails or is unavailable:** fall back immediately — do not retry tilth for the same path.
 
 ---
 
-### Step 2 — Fallback: read (full file content)
+### Step 2 — Fallback: read (full file content, hook-enhanced)
 
-Use when you need complete, unprocessed file content and tilth is not available.
+Use when tilth bash is unavailable or you need raw content.
 
 ```
 read <path>
 ```
 
+The `tilth_reading` runtime hook automatically runs tilth on the output when available.
+
 Use `read` with `offset` + `limit` to scope large files:
 ```
 read <path> offset=<line> limit=<n>
@@ -81,13 +98,13 @@ Combine with `glob` results when searching a pre-discovered set of files.
 
 ## Decision Table
 
-| Need | Tool |
-|------|------|
-| Read a known file, outline/section | `tilth` |
-| Read a known file, need full raw content | `tilth` → `read` |
-| Find files matching a name/extension pattern | `tilth` → `glob` |
-| Search for a symbol/pattern across files | `tilth` → `grep` |
-| tilth unavailable or errored | `read` + `glob` + `grep` as needed |
+| Need | Primary | Fallback |
+|------|---------|---------|
+| Read known file — smart outline | `bash: tilth <path>` | `read <path>` |
+| Read known file — specific section | `bash: tilth <path> --section "…"` | `read <path> offset=X limit=N` |
+| Discover file paths | `glob pattern="…"` | — |
+| Search content patterns | `bash: tilth <path>` then `grep` | `grep pattern="…"` |
+| tilth unavailable / bash denied | `read <path>` | `glob` + `grep` |
 
 ---
 
@@ -96,14 +113,14 @@ Combine with `glob` results when searching a pre-discovered set of files.
 - **Never use `read` + `tilth` for the same path** — pick one.
 - **Never use `glob` when you already know the path** — call `read`/`tilth` directly.
 - **Never call `grep` for something `tilth --section` can already isolate.**
-- **Log fallback reason** when possible (e.g. "tilth not found, using read").
+- **Never assume bash: tilth works** — verify permission first (`tilth*: allow` in agent frontmatter).
 
 ## Red Flags
 
-- Calling `read` on a large file (>500 lines) without first trying `tilth` — tilth's outline mode saves context.
+- Calling `read` on a large file (>500 lines) without first trying `bash: tilth` — tilth's outline mode saves context.
 - Using `grep` to extract a known section — use `tilth --section` instead.
-- Ignoring tilth exit code and retrying without fallback.
-- Calling `glob` to discover a path you already know.
+- Agent has `bash: "*": deny` without `tilth*: allow` — tilth is silently blocked; fallback to `read`.
+- Assuming `read` is not enhanced — the hook runs tilth on `read` output automatically.
 
 ## References
 

package/src/agents/build.md

@@ -201,15 +201,24 @@ The `files_in_scope` field is the execution boundary — read it first.
 
 **File reading: load `tilth-reading` skill — tilth first, fallback to read/glob/grep.**
 
+```bash
+# 1st choice: smart outline-aware read (bash tool)
+tilth <path>
+tilth <path> --section "## Heading"   # section by heading
+tilth <path> --section 45-89          # section by line range
+```
+
 ```
-tilth <path>                         # 1st choice: smart outline-aware read
-tilth <path> --section "## Heading"  # section-targeted read
-read <path>                          # fallback: full raw content
-glob + grep                          # fallback: discovery + pattern search
+# Fallback: use these tools when tilth unavailable or fails
+read <path>                           # full raw content
+glob + grep                           # discovery + pattern search
 ```
 
-> The runtime hook already enhances `read` output via tilth automatically.
-> For large files (>500 lines), call `tilth` directly before `read` to get the outline first.
+> **Two paths available:**
+> - **Automatic:** `read` tool output is already enhanced by the tilth runtime hook when tilth is available.
+> - **Explicit:** call `bash: tilth <path>` for section-targeted reads or outline-only mode.
+>
+> For large files (>500 lines), prefer explicit `tilth` via bash to get an outline first.
 
 Use LSP tools to understand the code before touching it:
 

package/src/agents/explore.md

@@ -19,6 +19,8 @@ tools:
 permission:
   edit: deny
   bash:
+    "tilth*": allow
+    "npx tilth*": allow
     "git log*": allow
     "git blame*": allow
     "git show*": allow
@@ -56,17 +58,24 @@ Work from precise to broad. **Stop when the answer is found** — do not over-ex
 
 ### Reading priority (load `tilth-reading` skill before heavy file work)
 
-When reading files, follow the tilth-first chain:
+When reading files, use `bash: tilth` first — it is now allowed in your bash permissions.
 
+```bash
+# 1st choice — bash tool (allowed: tilth* and npx tilth*)
+bash: tilth <path>
+bash: tilth <path> --section "## Heading"
+bash: tilth <path> --section 45-89
 ```
-1. tilth <path>                          — smart read (full or outline)
-2. tilth <path> --section "## Heading"  — section-targeted
-3. read <path>                           — fallback: full raw content
-4. glob + grep                           — fallback: discovery + pattern search
+
+```
+# Fallback tools (when tilth unavailable or bash fails)
+read <path>        — full raw content (hook auto-enhances via tilth when available)
+glob <pattern>     — file discovery
+grep <pattern>     — content search
 ```
 
-> The runtime hook automatically enhances `read` output via tilth when available.
-> For large files (>500 lines), prefer `tilth` directly to get an outline before committing to full read.
+> `tilth` is permitted via `bash` in your frontmatter (`tilth*: allow`).
+> Use it for any file that may be large (>200 lines) or where section targeting helps.
 
 ### Search priority table
 
@@ -75,9 +84,10 @@ When reading files, follow the tilth-first chain:
 | 1 | Symbol definitions, type signatures | `lsp_workspace_symbols`, `lsp_goto_definition`, `lsp_hover` |
 | 2 | File structure, file listing | `glob` (pattern), `read` (directory listing) |
 | 3 | All call sites / usages | `lsp_find_references` |
-| 4 | File content — known path | `tilth <path>` → `read <path>` (fallback) |
-| 5 | Text pattern across files | `grep` (dedicated tool, not bash) |
-| 6 | Recent changes, authorship | `bash: git log`, `git blame`, `git show`, `git diff` |
+| 4 | File content — known path | `bash: tilth <path>` → `read <path>` (fallback) |
+| 5 | File section — known heading/range | `bash: tilth <path> --section "…"` |
+| 6 | Text pattern across files | `grep` (dedicated tool, not bash) |
+| 7 | Recent changes, authorship | `bash: git log`, `git blame`, `git show`, `git diff` |
 
 **Prefer LSP over text search for symbols.** `lsp_find_references` returns all usages with zero false positives; text grep may miss renamed or aliased identifiers.
 

package/src/agents/oracle.md

@@ -21,6 +21,8 @@ tools:
 permission:
   edit: deny
   bash:
+    "tilth*": allow
+    "npx tilth*": allow
     "git log*": allow
     "git blame*": allow
     "git show*": allow
@@ -95,20 +97,29 @@ If the request is ambiguous, state your interpretation assumption at the top —
 
 ## Phase 2 — Gather Local Evidence
 
-Use **LSP tools first**, then `tilth`/`read`/`glob`/`grep`, then git history last.
+Use **LSP tools first**, then `bash: tilth`/`read`/`glob`/`grep`, then git history last.
 
-> Load the `tilth-reading` skill for file reading. Priority: `tilth <path>` → `read` (fallback) → `glob` + `grep` (fallback).
-> The runtime hook enhances `read` output via tilth automatically when tilth is available.
+> Load the `tilth-reading` skill for file reading.
+> `tilth` is permitted via bash (`tilth*: allow` in your frontmatter).
+> Priority: `bash: tilth <path>` → `read` (auto-enhanced fallback) → `glob` + `grep`.
+
+```bash
+# Explicit tilth for outline or section (allowed via bash permissions)
+bash: tilth <path>
+bash: tilth <path> --section "## SectionName"
+bash: tilth <path> --section 45-89
+```
 
 | Priority | What to find | Tools |
 |----------|-------------|-------|
 | 1 | Symbol definitions, type signatures, current design | `lsp_workspace_symbols`, `lsp_goto_definition`, `lsp_hover` |
 | 2 | All callers / consumers of affected code | `lsp_find_references` |
 | 3 | Structural patterns, coupling, duplication | `ast_grep_search`, `grep` |
-| 4 | File content — smart read (outline or full) | `tilth <path>` → `read <path>` (fallback) |
-| 5 | File structure, scope of change | `glob`, directory listing via `read` |
-| 6 | Recent changes, authorship, regression risk | `bash: git log`, `git blame`, `git diff` |
-| 7 | Type errors, lint issues in affected scope | `lsp_diagnostics` |
+| 4 | File content — smart read (outline or full) | `bash: tilth <path>` → `read <path>` (fallback) |
+| 5 | File section — targeted by heading or range | `bash: tilth <path> --section "…"` |
+| 6 | File structure, scope of change | `glob`, directory listing via `read` |
+| 7 | Recent changes, authorship, regression risk | `bash: git log`, `git blame`, `git diff` |
+| 8 | Type errors, lint issues in affected scope | `lsp_diagnostics` |
 
 **Stop when you have enough evidence to make a well-grounded recommendation.** Do not over-read beyond what the decision requires.