typeclaw 0.34.1 → 0.35.0

package/src/sandbox/writable-zones.ts

@@ -1,4 +1,4 @@
-import { lstat, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { lstat, mkdir, readdir, readFile, realpath, writeFile } from 'node:fs/promises'
 import path, { isAbsolute, join, resolve } from 'node:path'
 
 export type WritableZones = {
@@ -35,6 +35,25 @@ export type ProtectedZones = {
 // exactly that escalation.
 const WRITABLE_DIRS = ['workspace', 'public', 'mounts', '.git'] as const
 
+// SECURITY: configured writable paths (`sandbox.writablePaths`) may NOT resolve
+// onto these. `.git` carries the hook/config escalation surface; `.env` and
+// `secrets.json` are the credential files; `sessions`/`memory` are the agent's
+// private surface (masked from low-trust roles by hidden-paths); `.typeclaw`
+// holds system-managed home persistence; `node_modules` is executable
+// dependency code. Granting blanket RW to any of these via config would defeat
+// the very guards the narrow built-in set exists to preserve. The agent root
+// itself is also rejected (a writablePaths of '' or '.') — an RW bind of the
+// whole tree erases the read-only confinement wholesale.
+const FORBIDDEN_WRITABLE_ROOTS = [
+  '.git',
+  '.env',
+  'secrets.json',
+  'sessions',
+  'memory',
+  '.typeclaw',
+  'node_modules',
+] as const
+
 const PROTECTED_GIT_DIRS = ['.git/hooks'] as const
 const PROTECTED_GIT_FILES = ['.git/config'] as const
 
@@ -54,16 +73,157 @@ const WRITABLE_ROOT_FILES = [
 // so a `workspace -> /etc` symlink at a zone root would grant write access to an
 // outside path. (Symlinks INSIDE a real zone are already safe — the kernel
 // resolves them to the read-only parent mount.)
-export async function resolveWritableZones(agentDir: string): Promise<WritableZones> {
-  const dirs = await collectExisting(
+//
+// `configuredWritablePaths` are operator-chosen agent-relative dirs from
+// `sandbox.writablePaths`. They join the built-in dirs through the SAME
+// existence + symlink filter, plus the extra guardrails in
+// `resolveConfiguredWritableDirs`: each must resolve inside agentDir and must
+// not land on a forbidden root. A path that fails any check is dropped, never
+// throws — a stale config should degrade the one bad entry, not abort sandboxing.
+export async function resolveWritableZones(
+  agentDir: string,
+  configuredWritablePaths: readonly string[] = [],
+): Promise<WritableZones> {
+  const builtinDirs = await collectExisting(
     WRITABLE_DIRS.map((d) => join(agentDir, d)),
     'dir',
   )
+  const configuredDirs = await resolveConfiguredWritableDirs(agentDir, configuredWritablePaths)
   const files = await collectExisting(
     WRITABLE_ROOT_FILES.map((f) => join(agentDir, f)),
     'file',
   )
-  return { dirs, files }
+  return { dirs: dedupe([...builtinDirs, ...configuredDirs]), files }
+}
+
+// SECURITY: validation is on the REAL path, not the lexical one. A lexical-only
+// check (resolve + isInside) is bypassable by a symlinked INTERMEDIATE component:
+// with `/agent/alias -> /tmp/outside` (or `-> /agent/sessions`) and a config of
+// `alias/sub`, the lexical path `/agent/alias/sub` passes isInside and the
+// forbidden-root check, while the bwrap `--bind` follows the ancestor symlink to
+// write outside /agent (or onto a forbidden root). The zone-root lstat alone
+// can't see it — lstat of the final component follows ancestor symlinks. So we
+// realpath BOTH the candidate and agentDir (+ the forbidden roots) and validate
+// the resolved targets. A path whose real form escapes agentDir or lands on a
+// real forbidden root is dropped. realpath also rejects the final component
+// being a symlink (its real target is re-checked), subsuming the prior lstat.
+async function resolveConfiguredWritableDirs(agentDir: string, configured: readonly string[]): Promise<string[]> {
+  const realAgentDir = await realpathOrUndefined(agentDir)
+  if (realAgentDir === undefined) return []
+  const realForbidden = await resolveRealForbiddenRoots(agentDir)
+
+  const accepted: string[] = []
+  for (const rel of configured) {
+    const absolute = resolve(agentDir, rel)
+    // Cheap lexical pre-filter: reject obvious escapes before touching the disk.
+    if (absolute === agentDir || !isInside(agentDir, absolute)) continue
+    const real = await realpathOrUndefined(absolute)
+    if (real === undefined) continue
+    if (!(await isRealEntry(real, 'dir'))) continue
+    if (real === realAgentDir || !isInside(realAgentDir, real)) continue
+    if (realForbidden.some((root) => real === root || isInside(root, real))) continue
+    // Bind the lexical (caller-facing) path; bwrap resolves it to `real` itself.
+    accepted.push(absolute)
+  }
+  return accepted
+}
+
+async function resolveRealForbiddenRoots(agentDir: string): Promise<string[]> {
+  const resolved: string[] = []
+  for (const root of FORBIDDEN_WRITABLE_ROOTS) {
+    const real = await realpathOrUndefined(join(agentDir, root))
+    if (real !== undefined) resolved.push(real)
+  }
+  return resolved
+}
+
+async function realpathOrUndefined(target: string): Promise<string | undefined> {
+  try {
+    return await realpath(target)
+  } catch {
+    return undefined
+  }
+}
+
+function dedupe(values: string[]): string[] {
+  return [...new Set(values)]
+}
+
+export type PackageInstallZones = {
+  root: string
+  protected: ProtectedZones
+}
+
+// SECURITY: the package-install RW root is governed by an ALLOWLIST, not a
+// denylist. `bun add` writes exactly these and nothing else: `node_modules/`
+// (deps), `package.json` + `bun.lock` (manifest + lockfile, plus the temp
+// lockfile created in the root DIR). The scratch zones (`workspace`, `public`,
+// `mounts`) stay writable to match the normal jail. EVERY other existing root
+// entry is RO-bound, so a denylist of "executable/runtime-sensitive" paths is
+// not needed — it would be unbounded (any file the unsandboxed runtime reads or
+// execs, including `src/`/`scripts/` in dev-mode agents where typeclaw is a
+// file:/link: dep, the agent's own lifecycle scripts, and prompt-source files)
+// and fails OPEN for any root entry not yet listed. An allowlist fails CLOSED.
+const PACKAGE_INSTALL_WRITABLE_DIRS = ['node_modules', 'workspace', 'public', 'mounts'] as const
+const PACKAGE_INSTALL_WRITABLE_FILES = ['package.json', 'bun.lock'] as const
+
+// Resolves the jail layout for a recognized standalone dependency install
+// (`bun add` / `bun install`). The RW root lets bun create node_modules/ and its
+// temp lockfile (`bun.lock.NNN.tmp`, renamed) — a file-level bind of `bun.lock`
+// alone cannot, since the temp file needs DIRECTORY write. Pre-creates an empty
+// node_modules/ so the dir exists before the RW root bind. Then RO-binds every
+// EXISTING root entry not in the writable allowlist (readdir enumeration, so a
+// new file like `src/` or a planted `cron.json` is covered without a hardcoded
+// list), plus `node_modules/typeclaw` (the live/symlinked runtime, nested under
+// the writable node_modules) and the whole `.git` (a `bun add` never needs git,
+// so RO-binding it wholesale is simpler and safer than the hooks/config carve-out
+// — it closes the hook / core.hooksPath escalation by construction).
+//
+// SECURITY: rejects a symlink at agentDir, at any install-touched path
+// (node_modules, package.json, bun.lock), and at every RO-bind source — an RW
+// root or an RO bind that follows a symlink would write/read outside the jail.
+// The secret/private masks render AFTER this protected set (subtractMasked in
+// applyBashSandbox drops any protected entry a mask already hides), so .env /
+// secrets.json / memory / sessions stay hidden, not merely RO.
+export async function resolvePackageInstallZones(agentDir: string): Promise<PackageInstallZones> {
+  await assertNotSymlink(agentDir)
+  await mkdir(join(agentDir, 'node_modules'), { recursive: true })
+  for (const rel of ['node_modules', ...PACKAGE_INSTALL_WRITABLE_FILES] as const) {
+    const target = join(agentDir, rel)
+    if (await exists(target)) await assertNotSymlink(target)
+  }
+
+  const writable = new Set<string>([...PACKAGE_INSTALL_WRITABLE_DIRS, ...PACKAGE_INSTALL_WRITABLE_FILES])
+  const dirs: string[] = []
+  const files: string[] = []
+  for (const entry of await readdir(agentDir, { withFileTypes: true })) {
+    if (writable.has(entry.name)) continue
+    // A symlinked root entry is skipped, not RO-bound: an RO bind follows it to
+    // an outside target. Skipping leaves it under the RW root — but it is the
+    // agent's OWN symlink under its OWN root, contained by the agent-folder bind
+    // and the always-on kernel invariants, the same residual the default jail
+    // accepts for symlinks pointing outside /agent.
+    if (entry.isSymbolicLink()) continue
+    const target = join(agentDir, entry.name)
+    if (entry.isDirectory()) dirs.push(target)
+    else if (entry.isFile()) files.push(target)
+  }
+
+  // node_modules itself is writable (deps land there), but the runtime under it
+  // must not be — RO-bind it nested, last-op-wins over the writable node_modules.
+  const runtime = join(agentDir, 'node_modules', 'typeclaw')
+  if (await isRealEntry(runtime, 'dir')) dirs.push(runtime)
+
+  return { root: agentDir, protected: { dirs: dedupe(dirs), files: dedupe(files) } }
+}
+
+async function exists(target: string): Promise<boolean> {
+  try {
+    await lstat(target)
+    return true
+  } catch {
+    return false
+  }
 }
 
 // Read-only re-protections rendered on top of the writable .git bind. Unlike

package/src/skills/typeclaw-channel-github/SKILL.md

@@ -145,7 +145,7 @@ The `reviewer` subagent is the analyst; you are the integration layer between it
 
    Then submit the review. **Write the JSON payload to a file with the `write` tool, then run a single bare `gh api --input <file>`** — two steps:
 
-   First write `/tmp/review-<N>.json` (via the `write` tool, not bash) — `/tmp` is per-session scratch, and the `<N>` keeps concurrent reviews in one session from colliding:
+   First write `/tmp/review-<N>.json` (via the `write` tool, not bash) — `/tmp` is per-session scratch, and the `<N>` keeps concurrent reviews in one session from colliding. **Every `gh api --input` payload — review JSON, dismissal JSON, top-level issue-comment JSON — is throwaway scratch and MUST be written under `/tmp/`, never the workspace/agent folder.** A path with no leading `/tmp/` (e.g. a bare `review.json`, `review_comment.json`, or `review-<N>-approve.json`) lands in the agent root and gets force-committed by the backup loop, littering the repo with review payloads. Always prefix the path with `/tmp/`; never write a `*.json` scratch file to the workspace:
 
    ```json
    {
@@ -190,7 +190,7 @@ The `reviewer` subagent is the analyst; you are the integration layer between it
 A finding is "actionable" if its severity is `blocker`, `concern`, or `nit`. The inline-review post in step 4 applies whenever the actionable count is **at least one**. When the reviewer returns **exactly zero** actionable findings (only `praise`, or none), there is nothing to anchor inline — handle by verdict:
 
 - `approve` → post a plain `APPROVE` with the `<summary>` as the review body (no `comments[]` array). **Post the `<summary>` verbatim — do not pad it back into a play-by-play.** The reviewer's contract already makes the summary a terse, author-facing verdict justification (no process narration, no "I loaded the X skill", no recap of what the PR does); your job is to forward it, not re-expand it. **This is still a formal review via `POST /pulls/<N>/reviews`, NOT a `channel_reply`.** A zero-findings approval is the single most common place this goes wrong: with nothing to anchor inline, the model is tempted to just `channel_reply({ text: "Approved …" })` and end the turn. That posts a plain PR comment and leaves the PR **"awaiting review"** with no approval — the verdict never reaches GitHub's review API. Never start a top-level `channel_reply` on a `pr:N` with "Approved" / "LGTM" / "Request changes": those are verdicts, and verdicts are always formal reviews. Submit the `APPROVE` via `gh api`, confirm it landed (step 5), then `skip_response`. **If the operator approval policy above disabled approval, submit a `COMMENT` review instead — same `<summary>` as the review body, `event: "COMMENT"`, no `comments[]` array. Keep it a formal review, not a top-level issue comment, so the review metadata and flow are preserved.** (Re-review caveat: a `COMMENT` review does **not** clear a sticky `CHANGES_REQUESTED` block. If this is a re-review under approval-disabled policy, follow the step-4 re-review branch — dismiss your prior review — instead of relying on this `COMMENT`.)
-- `comment` → post the summary as a top-level PR comment via `gh api -X POST /repos/.../issues/<N>/comments` instead of submitting an empty review. **Exception — re-reviews:** if this is a re-review (you have an unresolved blocking obligation — a formal `CHANGES_REQUESTED` **or** an unretracted flat-comment blocker), a top-level comment discharges neither. Do not use this branch; resolve it via the step-4 re-review branch (`APPROVE` if resolved and approval is enabled, the dismissal endpoint if a formal block is resolved but approval is disabled, `REQUEST_CHANGES` if not resolved).
+- `comment` → post the summary as a top-level PR comment via `gh api -X POST /repos/.../issues/<N>/comments`, feeding the body from a `/tmp/` scratch file: write `/tmp/review-comment-<N>.json` (e.g. `{ "body": "<summary>" }`) with the `write` tool, then `gh api -X POST /repos/owner/repo/issues/<N>/comments --input /tmp/review-comment-<N>.json`. As with the review payload, this scratch file goes under `/tmp/`, **never** a bare `review_comment.json` in the workspace — the file-then-`--input` shape also keeps backticks/newlines in the summary from being mangled by shell parsing. Submit an empty review instead of this comment only when a formal review is required. **Exception — re-reviews:** if this is a re-review (you have an unresolved blocking obligation — a formal `CHANGES_REQUESTED` **or** an unretracted flat-comment blocker), a top-level comment discharges neither. Do not use this branch; resolve it via the step-4 re-review branch (`APPROVE` if resolved and approval is enabled, the dismissal endpoint if a formal block is resolved but approval is disabled, `REQUEST_CHANGES` if not resolved).
 - `request-changes` → submit `REQUEST_CHANGES` with the `<summary>` as the review body and no `comments[]` array. This combination is rare (the reviewer's contract says `request-changes` requires at least one blocker or load-bearing concern); if it happens, faithfully encode the verdict and trust the reviewer's reasoning is in the summary.
 
 The bundled `agent-browser` is **not** for PR reviews — `gh api` is faster and more reliable. Only use the browser when the API genuinely can't reach what you need.
@@ -272,6 +272,8 @@ gh pr create --repo owner/repo --title "Fix: ..." --head my-branch --base main -
 
 For App auth, `GH_TOKEN` is an installation access token that refreshes automatically — it stays current as long as the adapter is running.
 
+Before you compose the issue/PR body, read `typeclaw-github-contributing` — it covers the target repo's contribution etiquette (fill the issue/PR template if one exists, honor `CONTRIBUTING.md`, match the repo's title conventions, search for duplicates first). Opening an issue or PR that ignores the repo's template reads as careless; following it reads as someone who belongs. That skill applies whenever you open a new issue/PR, whether or not the work arrived through this channel.
+
 ## Self-loop safety
 
 The adapter will **not** wake you when you assign yourself as a reviewer (e.g., via `gh pr edit --add-reviewer`). It will only wake you when someone else requests your review.

package/src/skills/typeclaw-github-contributing/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: typeclaw-github-contributing
+description: Use this skill BEFORE you open a new issue or pull request on GitHub with `gh issue create` / `gh pr create` (or before composing the `--body`/`--title` for one, or editing an issue/PR body after the fact). Triggers include any `gh issue create`, `gh pr create`, `gh api … /issues`, `gh api … /pulls`, any time you are about to file a bug report, feature request, or PR against a repo — yours or someone else's — and any phrasing like "open an issue", "file a bug", "raise a PR", "submit a pull request". Read it first, because every repo has its own contribution rules — an issue/PR template, a CONTRIBUTING.md, a title convention — and a maintainer's first impression of your contribution is whether you bothered to follow them. Ignoring a template that the repo author wrote on purpose reads as careless; following it reads as someone who belongs. This is platform etiquette, independent of how the work reached you (it applies whether the request came through the github channel or you decided to file on your own).
+---
+
+# typeclaw-github-contributing
+
+When you open an issue or a PR on GitHub, you are writing into **someone else's repository** — even when it's nominally "yours," it usually has collaborators, a history, and conventions that predate this turn. The repo's maintainers encoded what they want from a contribution in a few well-known files. Honoring them is not bureaucracy; it's the difference between a contribution that gets triaged and merged and one that gets a "please use the template" and sits.
+
+This skill is the **etiquette of contributing to a GitHub repo**. It is not about replying to inbound GitHub events or running PR reviews — that's `typeclaw-channel-github`. It is not about committing to your own agent folder — that's `typeclaw-git`. It is specifically about _what you put on GitHub the moment you open a new issue or PR._
+
+## The rule
+
+**Before you open an issue or PR, find the repo's contribution conventions and follow them. If a template exists, fill it — don't bypass it. If a CONTRIBUTING file exists, read it and honor it. Match the title style the repo already uses.**
+
+The principle underneath all five rules below: **the repo already told you how it wants contributions; your job is to look before you write, not to impose your defaults.**
+
+## Do this first — read the repo before you write
+
+A contribution composed from your defaults and one composed from the repo's conventions look completely different to a maintainer. The five-second check that separates them:
+
+**Templates do not live in one fixed spot — GitHub resolves them from several.** Probing only `.github/PULL_REQUEST_TEMPLATE.md` is the trap: a repo that keeps its template at the root, under `docs/`, or in a `PULL_REQUEST_TEMPLATE/` directory will look template-less to that one check, and you'll bypass a convention the maintainer actually set. GitHub looks in **three base locations** — the repo root, `docs/`, and `.github/` — and the filename is **case-insensitive** (`PULL_REQUEST_TEMPLATE.md`, `pull_request_template.md`). It also supports a **`PULL_REQUEST_TEMPLATE/` _directory_** of multiple named templates (same three base locations). Issue templates follow the same pattern: a single `.github/ISSUE_TEMPLATE.md`, or — far more common now — an `ISSUE_TEMPLATE/` directory of forms (`*.md` / `*.yml`).
+
+The cheapest reliable check is to list each base directory once and scan the names, rather than guessing exact filenames:
+
+```sh
+# PR template — scan all three base dirs for any case of the file OR a PULL_REQUEST_TEMPLATE/ dir.
+# (Listing the dir surfaces both the single-file and the multi-template-directory forms at once.)
+for base in "" "docs/" ".github/"; do
+  gh api "repos/OWNER/REPO/contents/${base}" --jq '.[].name' 2>/dev/null \
+    | grep -iE '^pull_request_template(\.md)?$'
+done
+# If a PULL_REQUEST_TEMPLATE/ directory exists in ANY base, list the choices inside it
+# (the directory form is supported at root, docs/, and .github/ alike):
+for base in "" "docs/" ".github/"; do
+  gh api "repos/OWNER/REPO/contents/${base}PULL_REQUEST_TEMPLATE" --jq '.[].name' 2>/dev/null
+done
+
+# Issue templates — the modern form is an ISSUE_TEMPLATE/ directory of forms;
+# the legacy form is a single ISSUE_TEMPLATE.md. Check both, in all three base dirs.
+for base in "" "docs/" ".github/"; do
+  gh api "repos/OWNER/REPO/contents/${base}ISSUE_TEMPLATE" --jq '.[].name' 2>/dev/null  # directory of forms
+  gh api "repos/OWNER/REPO/contents/${base}" --jq '.[].name' 2>/dev/null \
+    | grep -iE '^issue_template(\.md)?$'                                                 # single legacy file
+done
+
+# Contribution guide (root or .github/)
+gh api repos/OWNER/REPO/contents/CONTRIBUTING.md 2>/dev/null
+gh api repos/OWNER/REPO/contents/.github/CONTRIBUTING.md 2>/dev/null
+
+# What do existing titles look like?
+gh pr list --repo OWNER/REPO --state all --limit 20 --json title --jq '.[].title'
+gh issue list --repo OWNER/REPO --state all --limit 20 --json title --jq '.[].title'
+
+# Is this a duplicate?
+gh issue list --repo OWNER/REPO --search "<keywords from what you're about to file>" --state all
+```
+
+A `grep` that matches **nothing across all three base dirs** is your evidence there is genuinely no template — a single 404 on `.github/PULL_REQUEST_TEMPLATE.md` is not. You don't need every command every time, but you do need to _look in all the supported places_ before concluding "no template" and composing from your own defaults. The cost is a few API calls; the cost of skipping it is bypassing a convention the repo set on purpose — the exact failure this skill exists to prevent.
+
+## The five rules
+
+### 1. Fill the issue/PR template if one exists
+
+If the discovery scan above surfaced a template in **any** of the supported locations (root, `docs/`, or `.github/` — single file or directory), the maintainers want every issue/PR to follow that shape. Fetch its content, read its sections, and produce a `--body` that fills each one with real content.
+
+- For PRs, the template often has a checklist ("- [ ] tests added", "- [ ] docs updated"). Fill the prose sections; for checkboxes, check only what is genuinely true and leave the rest unchecked — don't tick a box you can't back up.
+- A **`PULL_REQUEST_TEMPLATE/` directory** holds more than one PR template; pick the one that matches your change and fill it. (GitHub can also select one via a `?template=` URL param, but when you're filing through `gh` you choose by reading the directory and using the right file as your body.)
+- An **`ISSUE_TEMPLATE/` directory** likewise holds multiple issue forms (bug report, feature request, etc.) — pick the one that matches what you're filing. A bug filed against the feature-request template is noise. Forms may be YAML (`.yml` issue forms) rather than markdown; translate their fields into a sensible body, or use the matching markdown template if one is offered.
+- A repo with genuinely no template (the scan matched nothing in all three base dirs) gives you latitude — but a clear, scannable body (what / why / how, repro steps for bugs) is still the courteous default.
+
+### 2. Don't bypass the template to file faster
+
+This is rule 1's hard edge and the failure this skill most exists to prevent. When a template has required sections or a checklist, **fill or honor them — do not delete them to save effort.** Stripping the template, leaving placeholder text (`<!-- describe your change -->`) un-replaced, or dumping a one-liner where the template asked for repro steps all read as "I didn't bother." If a section genuinely doesn't apply, say so explicitly ("N/A — no user-facing change") rather than silently removing it; the maintainer can tell the difference between _considered and skipped_ and _ignored_.
+
+### 3. Follow CONTRIBUTING.md
+
+If the repo has a `CONTRIBUTING.md` (root or `.github/`), read it before you open anything. It encodes rules the templates can't — branch naming, whether PRs go against `main` or `develop`, whether a linked issue is required first, commit sign-off (DCO), the expected PR description format, "open an issue before a large PR," and so on. These are the maintainers' actual process; violating them is the most common reason a well-intentioned PR gets bounced. Honor what it says even when it differs from your habits.
+
+### 4. Match the repo's title conventions
+
+A repo's existing issue/PR titles tell you the house style. Pull the last ~20 (commands above) and infer the pattern, then match it:
+
+- **Conventional-commit prefixes** (`feat:`, `fix:`, `docs(scope):`) — if the PR list is full of them, your PR title uses one too.
+- **Ticket/issue references** (`[PROJ-123]`, `(#456)`) — if titles routinely carry them and you have a ref, include it.
+- **Sentence case vs. lowercase, imperative mood** — small things, but matching them signals you read the log.
+
+If there's no discernible pattern, a clear imperative summary (`Fix race in port allocation`) is the safe default. The point is never to invent your own scheme on top of an established one.
+
+### 5. Search for duplicates before opening
+
+Before filing an issue, search existing issues (open _and_ closed — a closed one may carry the resolution or the maintainer's "won't fix" rationale). If a matching thread exists:
+
+- **Open and relevant** → add your context as a comment on that thread instead of opening a duplicate. Duplicates fragment the discussion and annoy triagers.
+- **Closed as resolved** → check whether the fix is in the version you're on before re-filing; if it's a regression, reference the old issue in your new one.
+
+The same applies to PRs: a quick `gh pr list --search` avoids opening a PR for something already in flight.
+
+## Workflow
+
+1. **Identify the target repo** (`OWNER/REPO`) and whether you're filing an issue or a PR.
+2. **Read the room** — run the checks in "Do this first": templates, CONTRIBUTING, existing titles, duplicate search.
+3. **Compose to the conventions** — fill the template, honor CONTRIBUTING, match the title style. Write the body to a file when it's long or contains backticks/markdown that shell-quoting would mangle, then pass it with `--body-file`.
+4. **Open it** with `gh`:
+   ```sh
+   gh issue create --repo OWNER/REPO --title "<conventional title>" --body-file /tmp/issue-body.md
+   gh pr create   --repo OWNER/REPO --title "<conventional title>" --body-file /tmp/pr-body.md --base <branch>
+   ```
+5. **Verify it landed** as intended (`gh issue view` / `gh pr view`) — confirm the template rendered and nothing got truncated.
+
+## Things you must not do
+
+- **Do not open an issue/PR without checking for a template.** A repo that ships a template wants it used; skipping the check is how you end up filing against conventions you never looked at.
+- **Do not strip, gut, or placeholder-leave a template** to file faster. Fill it, or explicitly mark sections N/A. An empty template body is worse than a thoughtful free-form one.
+- **Do not ignore CONTRIBUTING.md** because its rules differ from your defaults. Its rules win in its repo.
+- **Do not invent a title scheme** when the repo already has one. Match what's there.
+- **Do not file a duplicate** without searching first. Comment on the existing thread instead.
+- **Do not tick checklist boxes you can't back up.** A checked "tests added" with no tests is a false claim the reviewer will catch.
+
+## What this skill does not cover
+
+- **Replying to inbound GitHub events, and running PR reviews** — `typeclaw-channel-github`. That skill owns triage of github-channel inbounds, formal reviews via the reviews API, and resolving review threads. This skill owns only the act of _opening_ a new issue/PR.
+- **Committing to your own agent folder** — `typeclaw-git`. Local commit hygiene and decision-context messages live there; this skill is about GitHub artifacts, not your local history.
+- **The `gh` CLI's full surface** — auth, sub-commands, flags. Defer to `gh <command> --help`. Under the github channel adapter, `GH_TOKEN` is pre-injected; see `typeclaw-channel-github` for the single-bare-invocation constraint that applies to repo-targeting `gh` calls (no pipes, `;`, `&&`, heredocs, or command substitution).

package/typeclaw.schema.json

@@ -1310,13 +1310,44 @@
     },
     "sandbox": {
       "default": {
-        "realProc": false
+        "realProc": false,
+        "writablePaths": [],
+        "symlinks": []
       },
       "type": "object",
       "properties": {
         "realProc": {
           "default": false,
           "type": "boolean"
+        },
+        "writablePaths": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "symlinks": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "from": {
+                "type": "string",
+                "minLength": 1
+              },
+              "to": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "required": [
+              "from",
+              "to"
+            ]
+          }
         }
       }
     },