diff --git a/src/agents/librarian-ast-grep-discipline.test.ts b/src/agents/librarian-ast-grep-discipline.test.ts
new file mode 100644
index 000000000..482a3c174
--- /dev/null
+++ b/src/agents/librarian-ast-grep-discipline.test.ts
@@ -0,0 +1,84 @@
+/// <reference types="bun-types" />
+
+import { describe, expect, it } from "bun:test"
+import { createLibrarianAgent } from "./librarian"
+
+describe("librarian agent ast-grep discipline", () => {
+  const model = "openai/gpt-5.4-mini-fast"
+
+  it("#given the prompt #when inspecting TOOL REFERENCE #then documents ast_grep_search", () => {
+    // given
+    const agent = createLibrarianAgent(model)
+
+    // when
+    const prompt = agent.prompt ?? ""
+
+    // then
+    expect(prompt).toContain("ast_grep_search")
+    expect(prompt).toContain("$$$")
+    expect(prompt).toContain("function $NAME($$$) { $$$ }")
+  })
+
+  it("#given the prompt #when inspecting #then warns against regex inside ast_grep_search", () => {
+    // given
+    const agent = createLibrarianAgent(model)
+
+    // when
+    const prompt = agent.prompt ?? ""
+
+    // then
+    expect(prompt.toLowerCase()).toContain("not regex")
+    expect(prompt).toContain("|")
+    expect(prompt).toContain(".*")
+    expect(prompt).toContain("\\w")
+  })
+
+  it("#given the prompt #when inspecting #then directs LLM to grep/grep_app for text search", () => {
+    // given
+    const agent = createLibrarianAgent(model)
+
+    // when
+    const prompt = agent.prompt ?? ""
+
+    // then
+    expect(prompt.toLowerCase()).toContain("for text")
+    expect(prompt).toContain("grep_app")
+  })
+
+  it("#given the prompt #when inspecting Implementation phase #then recommends ast_grep_search for code shape", () => {
+    // given
+    const agent = createLibrarianAgent(model)
+
+    // when
+    const prompt = agent.prompt ?? ""
+
+    // then
+    expect(prompt).toContain("ast_grep_search for code shape")
+  })
+
+  it("#given the prompt #when inspecting #then preserves the evidence + permalink contract", () => {
+    // given
+    const agent = createLibrarianAgent(model)
+
+    // when
+    const prompt = agent.prompt ?? ""
+
+    // then
+    expect(prompt).toContain("GitHub permalinks")
+    expect(prompt).toContain("MANDATORY CITATION FORMAT")
+  })
+
+  it("#given the prompt #when inspecting #then preserves request classification phases", () => {
+    // given
+    const agent = createLibrarianAgent(model)
+
+    // when
+    const prompt = agent.prompt ?? ""
+
+    // then
+    expect(prompt).toContain("TYPE A: CONCEPTUAL")
+    expect(prompt).toContain("TYPE B: IMPLEMENTATION")
+    expect(prompt).toContain("TYPE C: CONTEXT")
+    expect(prompt).toContain("TYPE D: COMPREHENSIVE")
+  })
+})
diff --git a/src/agents/librarian.ts b/src/agents/librarian.ts
index 6d02c6cef..2c7bad882 100644
--- a/src/agents/librarian.ts
+++ b/src/agents/librarian.ts
@@ -141,9 +141,11 @@ Step 2: Get commit SHA for permalinks
         cd \${TMPDIR:-/tmp}/repo-name && git rev-parse HEAD
 
 Step 3: Find the implementation
-        - grep/ast_grep_search for function/class
-        - read the specific file
-        - git blame for context if needed
+        - ast_grep_search for code shape (function/class/impl declarations)
+          pattern must be valid source code using $VAR and $$$ - NOT regex
+        - grep for string literals, log tags, config keys, comments
+        - read the specific file for surrounding context
+        - git blame for history if needed
 
 Step 4: Construct permalink
         https://github.com/owner/repo/blob/<sha>/path/to/file#L10-L20
@@ -246,8 +248,12 @@ https://github.com/tanstack/query/blob/abc123def/packages/react-query/src/useQue
 - **Sitemap Discovery**: Use webfetch - \`webfetch(docs_url + "/sitemap.xml")\` to understand doc structure
 - **Read Doc Page**: Use webfetch - \`webfetch(specific_doc_page)\` for targeted documentation
 - **Latest Info**: Use websearch_exa - \`websearch_web_search_exa("query ${new Date().getFullYear()}")\`
-- **Fast Code Search**: Use grep_app - \`grep_app_searchGitHub(query, language, useRegexp)\`
-- **Deep Code Search**: Use gh CLI - \`gh search code "query" --repo owner/repo\`
+- **Fast Code Search (cross-repo, text or regex)**: Use grep_app - \`grep_app_searchGitHub(query, language, useRegexp)\`
+- **Deep Code Search (single repo, text or regex)**: Use gh CLI - \`gh search code "query" --repo owner/repo\` or \`grep\` on a cloned repo
+- **AST Pattern Search (cloned repo, by code shape)**: Use ast_grep_search on a cloned repo. Patterns are strict AST, NOT regex:
+    - Valid: \`function $NAME($$$) { $$$ }\`, \`class $C { $$$ }\`, \`impl $T for $S { $$$ }\`, \`callee($$$)\`
+    - Never pass regex: \`|\` (alternation), \`.*\` (wildcards), \`\\w\` / \`\\d\` (escapes), \`[a-z]\` (character classes)
+    - For text search or cross-repo search prefer grep_app or grep
 - **Clone Repo**: Use gh CLI - \`gh repo clone owner/repo \${TMPDIR:-/tmp}/name -- --depth 1\`
 - **Issues/PRs**: Use gh CLI - \`gh search issues/prs "query" --repo owner/repo\`
 - **View Issue/PR**: Use gh CLI - \`gh issue/pr view <num> --repo owner/repo --comments\`