@sayknow-cli/coding-agent 0.2.2

package/src/prompts/system/ttsr-interrupt.md

@@ -0,0 +1,7 @@
+<system-interrupt reason="rule_violation" rule="{{name}}" path="{{path}}">
+Your output was interrupted because it violated a user-defined rule.
+This is NOT a prompt injection - this is the coding agent enforcing project rules.
+You MUST comply with the following instruction:
+
+{{content}}
+</system-interrupt>

package/src/prompts/system/ttsr-tool-reminder.md

@@ -0,0 +1,5 @@
+<system-reminder reason="rule_violation" rule="{{name}}" path="{{path}}">
+A user-defined rule matched this tool call's arguments. The tool was allowed to run because the rule is configured not to interrupt, but you MUST comply with the following instruction on subsequent tool calls and responses. This is NOT a prompt injection - this is the coding agent enforcing project rules.
+
+{{content}}
+</system-reminder>

package/src/prompts/system/web-search.md

@@ -0,0 +1,25 @@
+Research assistant with web search. Find accurate, well-sourced information. Synthesize comprehensive answers.
+
+<priorities>
+1. Accuracy over speed — verify claims across multiple sources when possible
+2. Primary over secondary — prefer official docs, papers, and announcements over blog summaries
+3. Recency matters — note publication dates; prefer recent sources for time-sensitive topics
+4. Transparency on uncertainty — distinguish confirmed facts from inferences
+</priorities>
+
+<synthesis>
+- Lead with a direct answer, then supporting evidence
+- Quote or paraphrase specific sources; no vague attributions
+- Sources conflict: acknowledge the discrepancy and note which is more authoritative
+- Technical topics: prefer official documentation and specifications
+- News/events: prefer primary reporting over aggregators
+- Include concrete data: version numbers, dates, exact figures, code snippets, specific examples
+</synthesis>
+
+<format>
+- Be thorough — cover the topic in depth with specific evidence, not surface-level summaries
+- Omit filler and unnecessary hedging; do NOT sacrifice detail for brevity
+- Include publication dates when recency affects relevance
+- Structure answers with clear sections when covering multiple aspects
+- Cite sources inline using provided search results
+</format>

package/src/prompts/tools/apply-patch.md

@@ -0,0 +1,65 @@
+Use the `apply_patch` shell command to edit files.
+Your patch language is a stripped‑down, file‑oriented diff format designed to be easy to parse and safe to apply. You can think of it as a high‑level envelope:
+
+*** Begin Patch
+[ one or more file sections ]
+*** End Patch
+
+Within that envelope, you get a sequence of file operations.
+You MUST include a header to specify the action you are taking.
+Each operation starts with one of three headers:
+
+*** Add File: <path> - create a new file. Every following line is a + line (the initial contents).
+*** Delete File: <path> - remove an existing file. Nothing follows.
+*** Update File: <path> - patch an existing file in place (optionally with a rename).
+
+May be immediately followed by *** Move to: <new path> if you want to rename the file.
+Then one or more "hunks", each introduced by @@ (optionally followed by a hunk header).
+Within a hunk each line starts with:
+
+For instructions on [context_before] and [context_after]:
+- By default, show 3 lines of code immediately above and 3 lines immediately below each change. If a change is within 3 lines of a previous change, do NOT duplicate the first change's [context_after] lines in the second change's [context_before] lines.
+- If 3 lines of context is insufficient to uniquely identify the snippet of code within the file, use the @@ operator to indicate the class or function to which the snippet belongs. For instance, we might have:
+@@ class BaseClass
+[3 lines of pre-context]
+- [old_code]
++ [new_code]
+[3 lines of post-context]
+- If a code block is repeated so many times in a class or function such that even a single `@@` statement and 3 lines of context cannot uniquely identify the snippet of code, you can use multiple `@@` statements to jump to the right context. For instance:
+
+@@ class BaseClass
+@@ 	 def method():
+[3 lines of pre-context]
+- [old_code]
++ [new_code]
+[3 lines of post-context]
+
+The full grammar definition is below:
+Patch := Begin { FileOp } End
+Begin := "*** Begin Patch" NEWLINE
+End := "*** End Patch" NEWLINE
+FileOp := AddFile | DeleteFile | UpdateFile
+AddFile := "*** Add File: " path NEWLINE { "+" line NEWLINE }
+DeleteFile := "*** Delete File: " path NEWLINE
+UpdateFile := "*** Update File: " path NEWLINE [ MoveTo ] { Hunk }
+MoveTo := "*** Move to: " newPath NEWLINE
+Hunk := "@@" [ header ] NEWLINE { HunkLine } [ "*** End of File" NEWLINE ]
+HunkLine := (" " | "-" | "+") text NEWLINE
+
+A full patch can combine several operations:
+
+*** Begin Patch
+*** Add File: hello.txt
++Hello world
+*** Update File: src/app.py
+*** Move to: src/main.py
+@@ def greet():
+-print("Hi")
++print("Hello, world!")
+*** Delete File: obsolete.txt
+*** End Patch
+
+It is important to remember:
+- You must include a header with your intended action (Add/Delete/Update)
+- You must prefix new lines with `+` even when creating a new file
+- File references can only be relative, NEVER ABSOLUTE.

package/src/prompts/tools/ask.md

@@ -0,0 +1,29 @@
+Asks user when you need clarification or input during task execution.
+
+<conditions>
+- Multiple approaches exist with significantly different tradeoffs user should weigh
+</conditions>
+
+<instruction>
+- Use `recommended: <index>` to mark default (0-indexed); " (Recommended)" added automatically
+- Use `questions` for multiple related questions instead of asking one at a time
+- Set `multi: true` on question to allow multiple selections
+</instruction>
+
+<caution>
+- Provide 2-5 concise, distinct options
+</caution>
+
+<critical>
+- **Default to action.** Resolve ambiguity yourself using repo conventions, existing patterns, and reasonable defaults. Exhaust existing sources (code, configs, docs, history) before asking. Only ask when options have materially different tradeoffs the user must decide.
+- **If multiple choices are acceptable**, pick the most conservative/standard option and proceed; state the choice.
+- **Do NOT include "Other" option** — UI automatically adds "Other (type your own)" to every question.
+</critical>
+
+<examples>
+# Single question
+questions: [{"id": "auth_method", "question": "Which authentication method should this API use?", "options": [{"label": "JWT"}, {"label": "OAuth2"}, {"label": "Session cookies"}], "recommended": 0}]
+
+# Multiple questions
+questions: [{"id": "storage_type", "question": "Which storage backend?", "options": [{"label": "SQLite"}, {"label": "PostgreSQL"}]}, {"id": "auth_method", "question": "Which auth method?", "options": [{"label": "JWT"}, {"label": "Session cookies"}]}]
+</examples>

package/src/prompts/tools/ast-edit.md

@@ -0,0 +1,39 @@
+Performs structural AST-aware rewrites via native ast-grep.
+
+<instruction>
+- Use for codemods and structural rewrites where plain text replace is unsafe
+- `paths` is required and accepts an array of files, directories, globs, or internal URLs
+- Language is inferred from `paths`; narrow each call to one language for deterministic rewrites
+- Metavariables captured in `pat` (`$A`, `$$$ARGS`) are substituted into that entry's `out` template
+- **Patterns match AST structure, not text.** `$NAME` = one node (captured); `$_` = one without binding; `$$$NAME` = zero-or-more (lazy — stops at next matchable element); `$$$` = zero-or-more without binding. Use `$$$NAME`, NOT `$$NAME` — the two-dollar form is invalid. Metavariable names are UPPERCASE and MUST be the whole AST node — partial text like `prefix$VAR` or `"hello $NAME"` does NOT work
+- When the same metavariable appears twice, both occurrences MUST match identical code (`$A == $A` matches `x == x`, not `x == y`)
+- Rewrite patterns MUST parse as a single valid AST node. For method fragments or body snippets that don't parse standalone, wrap in context (e.g. `class $_ { … }`)
+- For TS declarations/methods, tolerate unknown annotations: `async function $NAME($$$ARGS): $_ { $$$BODY }` or `class $_ { method($ARG: $_): $_ { $$$BODY } }`
+- Delete matched code with empty `out`: `{"pat":"console.log($$$)","out":""}`
+- Each rewrite is a 1:1 structural substitution — cannot split one capture across multiple nodes or merge multiple captures into one
+</instruction>
+
+<output>
+- Replacement summary, per-file replacement counts, and change diffs as `-LINE+ID|before` / `+LINE+ID|after` lines
+- Parse issues when files cannot be processed
+</output>
+
+<examples>
+# Rename a call site across TypeScript files
+`{"ops":[{"pat":"oldApi($$$ARGS)","out":"newApi($$$ARGS)"}],"paths":["src/**/*.ts"]}`
+# Delete matching calls
+`{"ops":[{"pat":"console.log($$$ARGS)","out":""}],"paths":["src/**/*.ts"]}`
+# Rewrite import source path
+`{"ops":[{"pat":"import { $$$IMPORTS } from \"old-package\"","out":"import { $$$IMPORTS } from \"new-package\""}],"paths":["src/**/*.ts"]}`
+# Modernize to optional chaining (same metavariable enforces identity)
+`{"ops":[{"pat":"$A && $A()","out":"$A?.()"}],"paths":["src/**/*.ts"]}`
+# Swap two arguments using captures
+`{"ops":[{"pat":"assertEqual($A, $B)","out":"assertEqual($B, $A)"}],"paths":["tests/**/*.ts"]}`
+# Python — convert print calls to logging
+`{"ops":[{"pat":"print($$$ARGS)","out":"logger.info($$$ARGS)"}],"paths":["src/**/*.py"]}`
+</examples>
+
+<critical>
+- Parse issues mean the rewrite is malformed or mis-scoped — fix the pattern before assuming a clean no-op
+- For one-off local text edits, prefer the Edit tool
+</critical>

package/src/prompts/tools/ast-grep.md

@@ -0,0 +1,42 @@
+Performs structural code search using AST matching via native ast-grep.
+
+<instruction>
+- Use when syntax shape matters more than raw text (calls, declarations, specific language constructs)
+- `paths` is required and accepts an array of files, directories, globs, or internal URLs
+- Language is inferred from `paths`; narrow each call to one language when mixed-language trees could cause parse noise
+- `pat` is a single AST pattern. Run separate calls for distinct unrelated patterns
+- **Patterns match AST structure, not text** — whitespace/formatting is ignored
+- `$NAME` captures one node; `$_` matches one without binding; `$$$NAME` captures zero-or-more (lazy — stops at next matchable element); `$$$` matches zero-or-more without binding. Use `$$$NAME`, NOT `$$NAME` — the two-dollar form is invalid and produces a parse error
+- Metavariable names are UPPERCASE and must be the whole AST node — partial-text like `prefix$VAR`, `"hello $NAME"`, or `a $OP b` does NOT work; match the whole node instead
+- When the same metavariable appears twice, both occurrences MUST match identical code (`$A == $A` matches `x == x`, not `x == y`)
+- Patterns MUST parse as a single valid AST node for the inferred target language. For method fragments or body snippets that don't parse standalone, wrap in valid context (e.g. `class $_ { … }`)
+- C++ qualified calls used as expression statements need the statement semicolon in the pattern: use `ns::doThing($ARG);`, `$CALLEE($ARG);`, or wrap a statement snippet. Without `;`, tree-sitter-cpp may parse `ns::doThing($ARG)` as declaration-like syntax and return no matches
+- For TS declarations/methods, tolerate unknown annotations: `async function $NAME($$$ARGS): $_ { $$$BODY }` or `class $_ { method($ARG: $_): $_ { $$$BODY } }`
+- Declaration forms are structurally distinct — top-level `function foo`, class method `foo()`, and `const foo = () => {}` are different AST shapes; search the right form before concluding absence
+- Loosest existence check: `pat: "executeBash"` with narrow `paths`
+</instruction>
+
+<output>
+- Grouped matches with file path, byte range, line/column ranges, metavariable captures
+- Match lines are anchor-prefixed: `*LINE+ID|content` for the matched line and ` LINE+ID|content` (leading space) for surrounding context
+- Summary counts (`totalMatches`, `filesWithMatches`, `filesSearched`) and parse issues when present
+</output>
+
+<examples>
+# Search TypeScript files under src
+`{"pat":"console.log($$$)","paths":["src/**/*.ts"]}`
+# Named imports from a specific package
+`{"pat":"import { $$$IMPORTS } from \"react\"","paths":["src/**/*.ts"]}`
+# Arrow functions assigned to a const
+`{"pat":"const $NAME = ($$$ARGS) => $BODY","paths":["src/utils/**/*.ts"]}`
+# Method call on any object, ignoring method name with `$_`
+`{"pat":"logger.$_($$$ARGS)","paths":["src/**/*.ts"]}`
+# Loosest existence check for a symbol in one file
+`{"pat":"processItems","paths":["src/worker.ts"]}`
+</examples>
+
+<critical>
+- Avoid repo-root scans — narrow `paths` first
+- Parse issues are query failure, not evidence of absence: repair the pattern or tighten `paths` before concluding "no matches"
+- For broad/open-ended exploration across subsystems, use Task tool with explore subagent first
+</critical>

package/src/prompts/tools/async-result.md

@@ -0,0 +1,8 @@
+<system-notice>
+{{#if multiple}}{{jobs.length}} background jobs have completed. Resume your work using the results below.
+
+{{else}}Background job {{jobs.[0].jobId}} has completed. Resume your work using the result below.
+{{/if}}{{#each jobs}}{{#if @root.multiple}}── Job {{this.jobId}}{{#if this.label}} ({{this.label}}){{/if}} ──
+{{/if}}{{this.result}}{{#unless @last}}
+{{/unless}}{{/each}}
+</system-notice>

package/src/prompts/tools/bash.md

@@ -0,0 +1,69 @@
+Executes bash command in shell session for terminal operations like git, bun, cargo, python.
+
+<instruction>
+- Use `cwd` to set working directory, not `cd dir && …`
+{{#when restrictionProfile "==" "read-only"}}
+- Do not pass `env` overrides or `pty: true`; read-only bash rejects both.
+- Shell control operators such as `;`, `|`, `&`, `<`, `>`, and command substitution are blocked.
+- Internal URIs (`agent://`, `artifact://`, `rule://`, `local://`) are auto-resolved to filesystem paths without creating parent directories.
+{{else}}
+- Prefer `env: { NAME: "…" }` for multiline, quote-heavy, or untrusted values; reference as `$NAME`
+- Quote variable expansions like `"$NAME"` to preserve exact content
+- PTY mode is opt-in: set `pty: true` only when the command needs a real terminal (e.g. `sudo`, `ssh` requiring user input); default is `false`
+- Use `;` only when later commands should run regardless of earlier failures
+- Internal URIs (`agent://`, `artifact://`, `rule://`, `local://`) are auto-resolved to filesystem paths
+{{/when}}
+{{#if asyncEnabled}}
+- Use `async: true` for long-running commands when you don't need immediate output; the call returns a background job ID and the result is delivered automatically as a follow-up.
+{{/if}}
+{{#if autoBackgroundEnabled}}
+- In the interactive TUI, the user can press `Ctrl+B` twice while a supported managed foreground bash command is still running to fold it into a quiet background job. Do not instruct users to use raw shell `Ctrl+Z`/`bg` inside the SKC TUI; ownership and output routing are not safe there.
+{{/if}}
+</instruction>
+{{#if restrictedAllowedPrefixes}}
+<restricted-bash-mode>
+{{#when restrictionProfile "==" "read-only"}}
+This session's bash tool is read-only. It accepts only simple, single-command inspections beginning with:
+{{#each restrictedAllowedPrefixes}}
+- `{{this}}`
+{{/each}}
+Shell control operators, command substitution, env overrides, redirects, pipelines, glob expansion, and known write-capable flags are blocked before execution. Use it only when an inspection command is materially better than `read`, `search`, or `find`.
+{{else}}
+This session's bash tool is restricted. It only accepts commands beginning with:
+{{#each restrictedAllowedPrefixes}}
+- `{{this}}`
+{{/each}}
+Use it only for sanctioned SKC workflow CLI persistence or state read/write/contract operations; per-command env overrides and all other shell command shapes are blocked before execution.
+{{/when}}
+</restricted-bash-mode>
+{{/if}}
+
+<critical>
+{{#when restrictionProfile "==" "read-only"}}
+- Use read-only bash only for approved inspection commands that are materially better than `read`, `search`, or `find`; the tool itself blocks non-approved commands and unsafe shell shapes.
+{{else}}
+- NEVER use Linux coreutils (`cat`, `head`, `tail`, `less`, `more`, `ls`, `grep`, `rg`, `awk`, `sed`, `find`, `fd`, etc.) when a dedicated tool suffices — ALWAYS prefer `read`, `search`, `find`, `edit`, `write`.
+{{/when}}
+- NEVER pipe through `| head -n N` or `| tail -n N` — output is already truncated with the full result available via `artifact://<id>`.
+- NEVER redirect with `2>&1` or `2>/dev/null` — stdout and stderr are already merged.
+</critical>
+
+<output>
+- Returns output and exit code.
+- Truncated output is retrievable from `artifact://<id>` (linked in metadata)
+- Exit codes shown on non-zero exit
+</output>
+
+{{#if asyncEnabled}}
+# Timeout and async
+
+- `timeout` (seconds) caps the **wall-clock duration** of the command. When it elapses the process is killed and the call returns with a timeout annotation. Range: `1`–`3600`s; default `300`s (see `clampTimeout("bash", …)` in `tool-timeouts.ts`).
+- `async: true` only defers **reporting** of the result — it does NOT disable, extend, or detach the timeout. A daemon started with `async: true` is still killed when `timeout` elapses, regardless of how long the agent waits before reading the result.
+- For long-running daemons (dev servers, watchers): either pass an explicit large `timeout` (up to `3600`), or fully detach the process from this shell using `nohup …  &` / `setsid … &` / `disown` so it survives independent of the bash call's lifecycle.
+{{/if}}
+
+# Output minimizer
+
+- Bash stdout/stderr may be rewritten before you see it: long output is head/tail truncated, and test/lint runners (e.g. `bun test`, `cargo test`, ESLint) are passed through heuristic filters that drop noise and keep failures.
+- When the minimizer changes the visible text, the tool appends a `[raw output: artifact://<id>]` footer pointing at the **full untouched capture**. If a run looks suspicious (e.g. only a version banner) or you need the exact bytes, read that artifact.
+- If no footer is present, what you see is what the command actually emitted.

package/src/prompts/tools/browser.md

@@ -0,0 +1,75 @@
+Drives a real Chromium tab with full puppeteer access via JS execution.
+
+<instruction>
+- For static web content (articles, docs, issues/PRs, JSON, PDFs, feeds), prefer the `read` tool with a URL — reader-mode text without spinning up a browser. Use this tool when you need JS execution, authentication, or interactive actions.
+- Four actions:
+  - `open` — acquire (or reuse) a named tab. `name` defaults to `"main"`. Optional `url` navigates after the tab is ready. Optional `viewport` sets dimensions. Optional `dialogs: "accept" | "dismiss"` auto-handles `alert`/`confirm`/`beforeunload` so navigation/clicks don't hang (default: leave dialogs unhandled — page hangs until caller wires `page.on('dialog', …)`).
+  - `close` — release a tab by `name`, or every tab with `all: true`. For spawned-app browsers, set `kill: true` to terminate the process tree (default leaves it running).
+  - `run` — execute JS against an existing tab. `code` is the body of an async function with `page`, `browser`, `tab`, `display`, `assert`, `wait` in scope. The function's return value is JSON-stringified into the tool result; multiple `display(value)` calls accumulate text/images.
+  - `act` — run a list of structured `actions` against an existing tab without writing JS (preferred for routine navigation/interaction). Each step is `{ verb, … }`; verbs: `navigate {url, wait_until?}`, `click {id|selector}`, `type {id|selector, text}`, `fill {selector, value}`, `select {selector, values}`, `press {key, selector?}`, `scroll {dx?, dy?}`, `back`, `wait {selector?|ms?}`, `observe {viewport_only?, include_all?}`, `extract {format?}`, `screenshot`. Address elements by the numeric `id` from a prior `observe` (preferred) or a selector. Steps run in order; the tool returns an array of per-step results (observations/extracted content included). Use `run` only when a verb does not cover what you need.
+- Tabs survive across `run` calls and across in-process subagents. Open once, reuse many times.
+- Browser kinds, selected by the `app` field on `open`:
+  - default (no `app`) → headless Chromium with stealth patches.
+  - `app.path` → spawn an absolute binary (Electron/CDP). If a running instance already exposes a CDP port, it is reused; otherwise stale instances are killed and a fresh one is spawned. Do not use this for a daily Chrome profile; use `app.browser: "chrome"` instead.
+  - `app.browser: "chrome"` + `app.path` + `app.user_data_dir` + `app.profile_directory` → use an existing saved Chrome profile. SKC binds CDP to `127.0.0.1` on an ephemeral or `app.cdp_port` port, reuses a matching running profile only when it already exposes attachable localhost CDP, refuses a matching non-CDP running profile instead of killing/relaunching it, and kills only the Chrome process SKC launched. Externally-owned CDP is disconnect-only. `app.background`/`app.no_focus` add Chromium's `--no-startup-window` guard; focus avoidance is best-effort and platform-dependent.
+  - `app.cdp_url` → connect to an existing CDP endpoint (e.g. `http://127.0.0.1:9222`). For logged-in profiles, only expose CDP on localhost and treat the endpoint as full browser-account access.
+  - `app.target` (with `path`/`cdp_url`/Chrome profile) — substring matched against url+title to pick a BrowserWindow when the app exposes several.
+- Inside `run`, `tab` exposes high-level helpers; reach for `page` (raw puppeteer Page) when you need anything they don't cover.
+  - `tab.goto(url, { waitUntil? })` — clears the element cache and navigates.
+  - `tab.observe({ includeAll?, viewportOnly? })` — accessibility snapshot. Returns `{ url, title, viewport, scroll, elements: [{ id, role, name, value, states, … }] }`. Element ids are stable until the next observe/goto.
+  - `tab.id(n)` — resolves an element id from the most recent observe to a real `ElementHandle` you can `.click()`, `.type()`, etc.
+  - `tab.click(selector)` / `tab.type(selector, text)` / `tab.fill(selector, value)` / `tab.press(key, { selector? })` / `tab.scroll(dx, dy)` — selector-based actions.
+  - `tab.waitFor(selector)` — waits until the selector is attached, returns the resolved `ElementHandle` for chaining (e.g. `const btn = await tab.waitFor('text/Submit'); await btn.click();`).
+  - `tab.drag(from, to)` — drag from one point to another. Each endpoint is either a selector string (drag center-to-center) or a `{ x, y }` viewport-coordinate point (e.g. for canvases, sliders).
+  - `tab.scrollIntoView(selector)` — scroll the matching element to the center of the viewport (use before clicking off-screen elements).
+  - `tab.select(selector, …values)` — set the selected option(s) on a `<select>`. Returns the values that ended up selected. `tab.fill` NEVER works for selects.
+  - `tab.uploadFile(selector, …filePaths)` — attach files to an `<input type="file">`. Paths resolve relative to cwd.
+  - `tab.waitForUrl(pattern, { timeout? })` — pattern is a substring or `RegExp`. Polls `location.href` so it works for SPA pushState navigations, not just real navigations. Returns the matched URL.
+  - `tab.waitForResponse(pattern, { timeout? })` — pattern is a substring, `RegExp`, or `(response) => boolean`. Returns the raw puppeteer `HTTPResponse` (call `.text()` / `.json()` / `.status()` / `.headers()` on it).
+  - `tab.evaluate(fn, …args)` — sugar for `page.evaluate` with the abort signal already wired. Use this instead of dropping to `page.evaluate` for ad-hoc DOM reads.
+  - `tab.screenshot({ selector?, fullPage?, save?, silent? })` — auto-attaches the image to the tool output unless `silent: true`. Saves full-res to `save` (or `browser.screenshotDir` setting) and a downscaled copy to the model.
+  - `tab.extract(format = "markdown")` — Readability-extracted page content.
+- Selectors accept CSS as well as puppeteer query handlers: `aria/Sign in`, `text/Continue`, `xpath/…`, `pierce/…`. Playwright-style `p-aria/[name="…"]`, `p-text/…`, etc. are normalized.
+- Default to `tab.observe()` over `tab.screenshot()` for understanding page state. Screenshot only when visual appearance matters.
+</instruction>
+
+<critical>
+- You MUST call `open` before `run` or `act`. Neither implicitly creates a tab.
+- You NEVER screenshot just to "see what's on the page" — `tab.observe()` returns structured data with element ids you can act on immediately.
+- After a `tab.goto()` or any navigation, prior element ids from `tab.observe()` are invalidated. Re-observe before referencing them.
+- `code` runs with full Node access. Treat it as your code, not sandboxed code.
+</critical>
+
+<examples>
+# Open a tab and read structured page data
+`{"action":"open","name":"docs","url":"https://example.com"}`
+`{"action":"run","name":"docs","code":"const obs = await tab.observe(); display(obs); return obs.elements.length;"}`
+
+# Click an observed element by id
+`{"action":"run","name":"docs","code":"const obs = await tab.observe(); const link = obs.elements.find(e => e.role === 'link' && e.name === 'Sign in'); assert(link, 'Sign in link missing'); await (await tab.id(link.id)).click();"}`
+
+# Save a full-page screenshot to disk
+`{"action":"run","name":"docs","code":"await tab.screenshot({ fullPage: true, save: 'screenshot.png' });"}`
+
+# Fill and submit a form via selectors
+`{"action":"run","name":"docs","code":"await tab.fill('input[name=email]', 'me@example.com'); await tab.click('text/Continue');"}`
+
+# Attach to an existing Electron app
+`{"action":"open","name":"cursor","app":{"path":"/Applications/Cursor.app/Contents/MacOS/Cursor"}}`
+
+# Use an existing Chrome profile in the background
+`{"action":"open","name":"work-browser","app":{"browser":"chrome","path":"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome","user_data_dir":"~/Library/Application Support/Google/Chrome","profile_directory":"Profile 10","background":true,"no_focus":true,"target":"example.com"}}`
+
+# Close one tab (browser stays alive if other tabs reference it)
+`{"action":"close","name":"docs"}`
+
+# Close every tab; leave spawned apps running
+`{"action":"close","all":true}`
+
+# Close every tab and kill spawned-app processes too
+`{"action":"close","all":true,"kill":true}`
+</examples>
+
+<output>
+- Per call: any `display(value)` outputs (text/images) followed by the JSON-stringified return value of the `code` function. `run` always produces at least a status line.
+</output>

package/src/prompts/tools/calculator.md

@@ -0,0 +1,10 @@
+Performs basic calculations.
+
+<instruction>
+- Supports +, -, *, /, %, ** and parentheses
+- Supports decimal, hex (0x), binary (0b), and octal (0o) literals
+</instruction>
+
+<output>
+Returns each calculation result with its prefix and suffix applied.
+</output>

package/src/prompts/tools/checkpoint.md

@@ -0,0 +1,16 @@
+Creates a context checkpoint before exploratory work so you can later rewind and keep only a concise report.
+
+Use this when you need to investigate with many intermediate tool calls (read/search/find/lsp/etc.) and want to minimize context cost afterward.
+
+Rules:
+- You MUST call `rewind` before yielding after starting a checkpoint.
+- You MUST provide a clear `goal` explaining what you are investigating.
+- You NEVER call `checkpoint` while another checkpoint is active.
+- Not available in subagents.
+
+Typical flow:
+1. `checkpoint(goal: …)`
+2. Perform exploratory work
+3. `rewind(report: …)` with concise findings
+
+After rewind, intermediate checkpoint messages are removed from active context and replaced by the report.

package/src/prompts/tools/computer.md

@@ -0,0 +1,74 @@
+# computer
+
+`computer` is available by default on supported Apple Silicon macOS. It controls the real desktop, so use it only when the task genuinely needs real desktop screenshot or input control.
+
+## Safety contract
+
+- Disabled means disabled: when the tool is disabled (`computer.alwaysOn=false` with `computer.enabled` unset/false) or the platform is unsupported, every action including `screenshot` fails with `COMPUTER_DISABLED` and captures nothing.
+- Callable only on Apple Silicon macOS (`arm64` darwin); available by default there, with `computer.alwaysOn=false` as the off-switch and `computer.enabled=true` as the manual enable path.
+- Native execution remains supervisor-gated. If the stop/suspend supervisor is unavailable, stale, suspended, permissioned off, display-stale, or cancelled, the action fails closed with a `COMPUTER_*` code.
+- Respect the user's stop/suspend request immediately. Do not loop desktop actions after a stop/suspend/error.
+- The user can stop or suspend the session at any time with the configured kill-switch hotkey (default `Control+Option+Command+Escape`). If you see `COMPUTER_CANCELLED` or `COMPUTER_SUPERVISOR_NOT_LIVE`, stop and wait for the user.
+
+## Coordinate contract
+
+Coordinates are screenshot pixels, not CSS pixels and not normalized fractions. Use the latest successful `screenshot` dimensions and origin/scale metadata as the coordinate frame. Do not guess coordinates outside the screenshot bounds.
+
+When you send a sequence of actions in one `batch` call, pointer coordinates in later steps are validated against the most recent screenshot from that batch. If a coordinate is out of bounds, the batch stops and reports `COMPUTER_COORD_INVALID`. Always capture a fresh screenshot before acting if the display may have changed.
+
+## Actions
+
+The model action object uses exactly these snake_case actions and fields:
+
+- `screenshot` — capture the enabled desktop.
+- `click` — `x`, `y`, optional `button` (`left`, `right`, `middle`).
+- `double_click` — `x`, `y`, optional `button`.
+- `move` — `x`, `y`, optional `button`.
+- `drag` — `x`, `y`, `to_x`, `to_y`, optional `button`.
+- `scroll` — `x`, `y`, `scroll_x`, `scroll_y`.
+- `type` — `text`.
+- `keypress` — `keys` string array.
+- `wait` — `ms`.
+- `batch` — `actions`: a non-empty array of the single actions above. Steps run in order and the result includes per-step status and the last screenshot captured inside the batch.
+
+Shared optional fields: `timeout` seconds and `include_screenshot` for a bounded post-action screenshot when supported.
+
+Do not use camelCase fields such as `doubleClick`, `toX`, `scrollX`, or `includeScreenshot` in the model action object.
+
+## Examples
+
+Take a single screenshot:
+
+```json
+{ "action": "screenshot" }
+```
+
+Click a coordinate from the latest screenshot:
+
+```json
+{ "action": "click", "x": 120, "y": 340 }
+```
+
+Run a focused sequence in one batch — screenshot first, then act, so coordinates are validated:
+
+```json
+{
+  "action": "batch",
+  "actions": [
+    { "action": "screenshot" },
+    { "action": "click", "x": 120, "y": 340 },
+    { "action": "type", "text": "hello" },
+    { "action": "keypress", "keys": ["Return"] }
+  ]
+}
+```
+
+## Error recovery
+
+- `COMPUTER_COORD_INVALID`: the coordinate was outside the latest screenshot bounds. Capture a fresh screenshot and re-derive coordinates.
+- `COMPUTER_DISPLAY_STALE`: the display changed since the screenshot. Capture a fresh screenshot before acting.
+- `COMPUTER_SUPERVISOR_NOT_LIVE` / `COMPUTER_SUSPENDED` / `COMPUTER_CANCELLED`: stop acting and wait for the user.
+- `COMPUTER_PERMISSION_REQUIRED`: the host needs screen-recording or accessibility permission. Ask the user to grant it.
+- `COMPUTER_DISABLED`: the tool is disabled or the host is unsupported. Do not retry.
+
+After any error, resume with a fresh screenshot rather than guessing.

package/src/prompts/tools/cron.md

@@ -0,0 +1,25 @@
+Schedule a prompt to fire on a recurring cron schedule, or one-shot at the next match. Cron tasks let you re-run a prompt automatically on an interval — poll a deployment, babysit a PR, check back on a long-running build, or remind yourself to do something later in the session.
+
+`CronCreate` accepts a standard 5-field cron expression in your local timezone, the prompt to run, and whether the job recurs or fires once. It returns an 8-character job id you can pass to `CronDelete`. Each session can hold up to 50 scheduled tasks. Recurring tasks auto-expire 7 days after creation; one-shot tasks self-delete after firing.
+
+`CronList` enumerates every scheduled task in the session. `CronDelete` cancels a task by id.
+
+## Cron expressions
+
+`CronCreate` accepts 5-field cron: `minute hour day-of-month month day-of-week`. All fields support `*`, single values (`5`), steps (`*/15`), ranges (`1-5`), and comma lists (`1,15,30`). Day-of-week uses `0`/`7` for Sunday through `6` for Saturday. Extended syntax like `L`, `W`, `?`, or month/weekday names is not supported.
+
+| Example       | Meaning                      |
+| :------------ | :--------------------------- |
+| `*/5 * * * *` | Every 5 minutes              |
+| `0 * * * *`   | Every hour on the hour       |
+| `0 9 * * *`   | Every day at 9am local       |
+| `0 9 * * 1-5` | Weekdays at 9am local        |
+
+## Lifecycle
+
+- Tasks fire between turns, never mid-response.
+- All times are interpreted in the local timezone.
+- Recurring tasks fire with up to 30 minutes of deterministic jitter (or up to half their interval for sub-hourly tasks). One-shot tasks scheduled for `:00` or `:30` may fire up to 90 s early. Pick an off-minute if exact timing matters.
+- Closing or replacing the session clears every scheduled task.
+
+Disable the scheduler entirely via `CLAUDE_CODE_DISABLE_CRON=1`.

package/src/prompts/tools/debug.md

@@ -0,0 +1,33 @@
+Provides debugger access through the Debug Adapter Protocol (DAP).
+Use for launching or attaching debuggers, setting breakpoints, stepping through execution, inspecting threads/stack/variables, evaluating expressions, capturing output, and interrupting hung programs.
+
+<instruction>
+- Prefer over bash for program state, breakpoints, stepping, thread inspection, or interrupting a running process.
+- `action: "launch"` starts a session; `program` is required, `adapter` optional (auto-selected from target path and workspace).
+  For Python, set `adapter: "debugpy"` and `program` to the target `.py` file; put interpreter/script flags in `args`.
+- `action: "attach"` connects to an existing process: `pid` for local attach, `port` for remote attach (where the adapter supports it), `adapter` to force a specific debugger.
+- **Breakpoints**: `set_breakpoint`/`remove_breakpoint` with source (`file`+`line`) or function (`function`); optional `condition` for conditional breakpoints.
+- **Flow control**: `continue` (resumes; briefly waits to observe whether the program stops or keeps running), `step_over`/`step_in`/`step_out` (single-step), `pause` (interrupt a running program so you can inspect state).
+- **Inspect**: `threads` (list), `stack_trace` (frames for current stopped thread), `scopes` (needs `frame_id` or a current stopped frame), `variables` (needs `variable_ref` or `scope_id`), `evaluate` (needs `expression`; `context: "repl"` for raw debugger commands when the adapter supports them), `output` (captured stdout/stderr/console), `sessions` (tracked debug sessions), `terminate`.
+- Timeouts apply per-request, not to the full session lifetime.
+</instruction>
+
+<caution>
+- Only one active debug session is supported at a time.
+- Some adapters require a launched session to receive `configurationDone` before the target actually runs; if the tool says configuration is pending, set breakpoints and then call `continue`.
+- Adapter availability depends on local binaries. Common built-ins: `gdb`, `lldb-dap`, `python -m debugpy.adapter`, `dlv dap`.
+- `program` must be an executable file or debug target, not a directory or interpreter name that resolves to a workspace directory.
+</caution>
+
+<examples>
+# Launch and inspect hang
+1. `debug(action: "launch", program: "./my_app")`
+2. `debug(action: "set_breakpoint", file: "src/main.c", line: 42)`
+3. `debug(action: "continue")`
+4. If the program appears hung: `debug(action: "pause")`
+5. Inspect state with `threads`, `stack_trace`, `scopes`, and `variables`
+# Launch a Python script with debugpy
+`debug(action: "launch", adapter: "debugpy", program: "scripts/job.py", args: ["--flag"])`
+# Raw debugger command through repl
+`debug(action: "evaluate", expression: "info registers", context: "repl")`
+</examples>

package/src/prompts/tools/eval.md

@@ -0,0 +1,75 @@
+Run code in a persistent kernel using a list of cells.
+
+<instruction>
+Each call submits one or more cells. Cells run in array order. State persists within each language across cells **and across tool calls**.
+
+Cell fields:
+
+- `language` — {{#if py}}`"py"` for the IPython kernel{{/if}}{{#ifAll py js}}, {{/ifAll}}{{#if js}}`"js"` for the persistent JavaScript VM{{/if}}.
+- `code` — cell body, verbatim. Newlines, quotes, and indentation are JSON-encoded; no fences, no headers.
+- `title` (optional) — short label shown in the transcript (e.g. `"imports"`, `"load config"`).
+- `timeout` (optional) — per-cell timeout in seconds (1-600). Default 30.
+- `reset` (optional) — wipe this cell's language kernel before running.{{#ifAll py js}} Reset is per-language: a `py` cell's reset does not touch the JavaScript VM and vice versa.{{/ifAll}}
+
+**Work incrementally:**
+
+- One logical step per cell (imports, define, test, use).
+- Pass multiple small cells in one call.
+- Define small reusable functions for individual debugging.
+- Put workflow explanations in the assistant message or `title` — never inside cell code.
+{{#if py}}- Python cells run inside an IPython kernel with a live event loop. Use top-level `await` directly (e.g. `await main()`); `asyncio.run(…)` raises "cannot be called from a running event loop".{{/if}}
+**On failure:** errors identify the failing cell (e.g., "Cell 3 failed"). Resubmit only the fixed cell (or fixed cell + remaining cells).
+</instruction>
+
+<prelude>
+{{#ifAll py js}}Same helpers in both runtimes with the same positional argument order. Python: trailing options as keyword args. JavaScript: trailing options as a trailing object literal. JavaScript helpers are async and `await`able; Python helpers run synchronously.{{else}}{{#if py}}Helpers run synchronously. Trailing options are keyword arguments.{{/if}}{{#if js}}Helpers are async and `await`able. Trailing options are a final object literal.{{/if}}{{/ifAll}}
+```
+display(value) → None
+    Render a value in the current cell output.
+print(value, ...) → None
+    Print to the cell's text output.
+read(path, offset?=1, limit?=None) → str
+    Read file contents as text. offset/limit are 1-indexed line bounds.
+write(path, content) → str
+    Write content to a file (creates parent directories). Returns the resolved path.
+append(path, content) → str
+    Append content to a file. Returns the resolved path.
+tree(path?=".", max_depth?=3, show_hidden?=False) → str
+    Render a directory tree.
+diff(a, b) → str
+    Unified diff between two files.
+env(key?=None, value?=None) → str | None | dict
+    No args → full environment as dict. One arg → value of `key`. Two args → set `key=value` and return value.
+output(*ids, format?="raw", query?=None, offset?=None, limit?=None) → str | dict | list[dict]
+    Read task/agent output by ID. Single id returns text/dict; multiple ids return a list.
+tool.<name>(args) → unknown
+    Invoke any session tool by name. `args` is the tool's parameter object.
+```
+</prelude>
+
+<output>
+Cells render like a Jupyter notebook. `display(value)` renders non-presentable data as an interactive JSON tree. Presentable values (figures, images, dataframes, etc.) use their native representation.
+</output>
+
+<caution>
+{{#if js}}- **js**: the VM exposes a selective `process` subset, Web APIs, `Buffer`, `fs/promises`, and the `Bun` global.
+{{/if}}</caution>
+
+<example>
+{{#if py}}```json
+{
+  "cells": [
+    { "language": "py", "title": "imports", "timeout": 10, "code": "import json\nfrom pathlib import Path" },
+    { "language": "py", "title": "load config", "code": "data = json.loads(read('package.json'))\ndisplay(data)" }
+  ]
+}
+```{{/if}}{{#ifAll py js}}
+
+{{/ifAll}}{{#if js}}```json
+{
+  "cells": [
+    { "language": "js", "title": "summary", "reset": true, "code": "const data = JSON.parse(await read('package.json'));\ndisplay(data);\nreturn data.name;" }
+  ]
+}
+```{{/if}}
+</example>