# Agent Semantic Protocols > Use when working with the language provider binaries maintained by agent-semantic-protocols, including asp hook install, compact semantic search flow, and non-JSON agent command guidance. - Skill: `tao3k/agent-semantic-protocols` (Agent Skill) - Install (CLI): `npx skillmds@latest add tao3k/agent-semantic-protocols` - Raw SKILL.md: https://api.skillmd.com/api/skills/tao3k/agent-semantic-protocols/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tao3k (https://skillmd.com/u/tao3k) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tao3k/agent-semantic-protocols --- # Agent Semantic Protocols > [!IMPORTANT] > Generated by `asp hook install` from the repository root `SKILL.md` template and the current provider activation. Do not edit this installed copy. Edit root `SKILL.md` or `asp.toml`, then rerun `asp hook install --client .`. ## ASP Explorer Subagent When a hook deny message or `search pipe` output points to `asp-explorer`, Codex should reuse the ASP search agent thread already opened for the current main task. If no such thread exists, call `spawn_agent` with `fork_turns="none"` and include a self-contained ASP Explorer branch prompt plus the safe ASP command group in the message. Keep model, reasoning, and agent-type defaults in Codex config, not in the prompt. Spawn one read-only instance per independent `actionFrontier` or `targetActions` branch, and require a compact `[asp-search-subagent] role=... action=... evidence=... missing=... next=... risk=...` receipt. Keep reasoning state in the parent. `asp-explorer` workers receive only the explicit branch prompt through `fork_turns="none"`, do not share sibling context, must not edit files, and must not spawn child subagents. If the custom subagent remains open, reuse it with `send_input` so it keeps its own thread history. If the custom subagent is unavailable, run the same ASP routes sequentially and synthesize the receipts in the parent. `asp hook install --client codex .` registers the role in project Codex config, but a thread that was already running before install may need a reload or new thread before `spawn_agent` lists `asp_explorer`. ## Provider Activation This root `SKILL.md` is the embedded template source used by `asp hook install`. The installed copy under `.agents/skills/agent-semantic-protocols/SKILL.md` is rendered from this template plus the current hook activation. Do not hard-code the active language list here: activation is owned by provider binary detection and `asp.toml`. ## Active Providers Detected from provider binaries plus `asp.toml`; only activated languages are listed. | Language | Facade | Provider | Execution | Command | | ---------- | ---------------- | -------------------------- | ---------------- | ------------------- | | rust | `asp rust` | rs-harness | external-process | `rs-harness` | | typescript | `asp typescript` | ts-harness | external-process | `ts-harness` | | python | `asp python` | py-harness | external-process | `py-harness` | | julia | `asp julia` | julia-lang-project-harness | external-process | `asp-julia-harness` | | org | `asp org` | orgize | embedded | `asp` | | md | `asp md` | orgize | embedded | `asp` | Start with `asp guide .` when a task needs the provider-owned tool map. Use `asp providers` or `asp doctor` when the active language or provider binary is unclear. The root `asp search` and `asp query` forms are thin routers: use `--language ` when the project root is ambiguous, or pass an owner/selector path or project root that matches one active provider's activation coverage so the root facade can route to the same `asp search|query` boundary. Document languages use the same facade shape but are not policy harnesses: `asp org ...` and `asp md ...` run the native orgize document provider inside `asp`. Use them for parser-owned document elements and metadata navigation. Normal document query must be explicit and element-oriented, such as `--term` or `--selector` with `--view metadata`; use `--kind` and `--field` to narrow parser-owned elements without post-processing. Add `--content` only when the same explicit query should print the matched element content instead of metadata. Source-preserved document reads are only a hook recovery surface through `--from-hook direct-source-read`. `check`, `ast-patch`, and `evidence` are intentionally unsupported for document files. ## Rules - Use the `asp ` facade for agent exploration; provider binaries are implementation/debug surfaces. - Do not move language path-context resolution into `asp`. The facade may locate a provider project hint from that language's marker file, such as `Cargo.toml`, `tsconfig.json`, `package.json`, `pyproject.toml`, or `Project.toml`, but it must not parse package membership, project references, virtual environments, source/test roots, or language layout. Cargo context resolution belongs to `rs-harness`; TypeScript, Python, and Julia path context resolution belongs to their provider binaries. `PRJ_CACHE_HOME` and git toplevel `.cache` only select state storage. - Do not add `--json` during agent exploration. `--json` is for schema tests, validators, receipts, and IDE integrations. - When a search/query term contains shell metacharacters copied from docs or code, such as backticks, pipes, `$`, globs, braces, or spaces, pass it as a single-quoted argv literal. If the text itself contains single quotes, narrow it into separate safe terms or use a provider-documented file/stdin surface; do not interpolate raw prose into a shell command. - `asp hook install --client codex .` installs hooks, provider activation, and the rendered skill for the detected providers. - Search and non-code query are discovery surfaces and should not inline source code. - Direct source reads are last-mile transport for exact, source-preserved text after a parser-owned frontier has selected the locator. Do not use `direct-source-read` for discovery, owner mapping, import scanning, symbol search, or "show me this file" habits. - `--view metadata` is document-only and only valid for `asp org query` and `asp md query`. Do not use it with code providers such as Python, Rust, TypeScript, or Julia; use `search ... --view seeds` for discovery and `query --term --code` or `--names-only` for code extraction. - Query with `--code` is for exact or unique code extraction. - Tree-sitter-compatible query is the syntax base; native parser facts enrich the capture/frontier. When syntax shape matters, use the tree-sitter guide and locator query before falling back to source-preserved direct read. - Hook config may disable provider `ast-patch`; when disabled, patch with `apply_patch` after exact locator/code evidence. ## Complex Flows ### Command Selection Ladder For code tasks, keep the command order structural-first: ```sh asp search --language prime --workspace --view seeds asp query --language --treesitter-query '' . asp search prime --workspace --view seeds asp search pipe '' --workspace --view seeds asp search fzf '' owner tests --view seeds . asp fd -query '' asp rg -query '' asp search owner items --query '' --view seeds . asp query --selector --workspace --code ``` For a concrete deep question, bug, feature, or API-usage task, use `search prime` once to establish the project graph context, then use `search pipe` with an LLM-generated `question-or-feature-term` and read its `queryPack`, `queryTerms`, `globalCoverage`, `pathCoverage`, `declarationCoverage`, `strongCoverage`, `symbolTextCoverage`, `clauseCoverage`, `ownerCoverage`, `packageCohesion`, `queryQuality`, `handles`, `rankedEvidence`, `evidenceFrontier`, `commandHandles`, `treeSitterHandles`, optional `fdPreview`, `actionRank`, `actionFrontier`, `recommendedNext`, optional `subagentHint`, `nextCommand`, `nextClasses`, and `avoid` lines. `--source` changes only candidate acquisition: `auto` is the default, `provider` avoids finder, `finder` uses bounded lexical recall, and `ingest` normalizes stdin candidates. ASP does not model-expand the seed query. When more owner/path recall is needed, low-quality pipe output may include bounded `fdPreview` rows with `ownerCandidates`, `packageClusters`, `parserIndexNext`, and `rgScopeNext`; use those preview facts before running a separate `asp fd -query`. Use owner-local item queries and tree-sitter locator output only when the pipe action frontier asks for them. Do not follow a code selector when `queryQuality=low` or the output says `query-selector-low-confidence`; use `recommendedNext` and the ranked `A*` action rows, normally `owner-items`, `rg-query`, `treesitter-query`, or query-pack refinement, instead. When `subagentHint` is present it is advisory: client runtimes with subagents may delegate the named `targetActions` to a read-only explorer, while runtimes without subagents should follow the same `recommendedNext` sequentially. A single broad clause can have strong declaration coverage while still being low quality; split it into 2-4 short clauses before reading code. Only after an exact selector is known and the frontier permits `query-selector` should stdout become source text through `query --selector ... --code`. ### Hook Recovery When a hook blocks a raw source read or broad raw search, follow the recovery route printed in the hook message. Do not retry `Read`, `cat`, `sed`, `rg`, or source-dump commands on the same matched source. Treat any `direct-source-read` route as a bounded fallback, not the default next step. First try the structural recovery path that matches the blocked intent: ```sh asp search pipe '' --workspace --source finder --view seeds asp search fzf '' owner tests --view seeds . asp fd -query '' asp rg -query '' asp search owner items --query '' --view seeds . asp query --term '' --names-only . asp query --treesitter-query '' . asp query --selector --treesitter-query '' --workspace --code asp query --from-hook direct-source-read --selector --workspace --code asp org query --from-hook direct-source-read --selector . asp md query --from-hook direct-source-read --selector . ``` Use `direct-source-read --code` only when the exact selector is already known and source preservation matters, such as a small file-header import window, staged/index/head source-version inspection, or a provider-selected read-plan frontier that cannot be expressed as a syntax query. If the selector is a whole file, glob, package root, or broad line range, ask the provider for owner items, tree-sitter locator output, or a read-plan frontier instead of printing code. For document languages, do not add `--content` to `direct-source-read`. Use `query --content` only as a filtered element-content projection with `--selector`, `--term`, `--kind`, or `--field`; use `direct-source-read` only after an exact selector is known and source-preserved text is required. ### Search Before Code ```sh asp search --language prime --workspace --view seeds asp search prime --workspace --view seeds asp search pipe '' --workspace --view seeds asp fd -query '' . asp rg -query '' . asp search owner items --query '' --view seeds . asp query --term --names-only . asp query --treesitter-query '' . asp query --term --code . ``` Use `--names-only` for broad owner-local prefixes before requesting code. Within one task session, do not repeat `asp search pipe ...` for the same concrete term or `asp search prime --workspace --view seeds` for the same language/root after a fresh frontier is already available. Reuse that frontier and move to the emitted selector, owner, tests, read-plan, `fd -query`, `rg -query`, or query-code action unless the project root, language provider state, search scope, or requested `--source` has changed. ### Reasoning Search Profiles Use `asp search guide .` as the source of truth for current reasoning profiles. Its `command=` rows are executable shapes. Do not reconstruct reasoning commands from `entries=` text as positional arguments. When `search prime` or `search fzf` exposes a reasoning frontier, run the matching profile with explicit flags before falling back to broad query or direct-source-read: ```sh asp search reasoning owner-query --owner --query '' --view seeds . asp search reasoning owner-tests --owner --view seeds . asp search reasoning query-deps --query '' --dependency '' --view seeds . asp search reasoning finding-frontier --query '' --owner --view seeds . asp search reasoning feature-cfg --query '' --view seeds . ``` Invalid shapes such as `search reasoning owner-query ` or `search reasoning owner-query --owner ` waste turns. If the required flags are unclear, ask `search guide` for the profile command instead of guessing. ### Failure Frontier Search When a check or test failure has already produced a compact failure transcript, project it into hot selectors before reading code: ```sh asp check changed --view seeds . asp check --changed --view seeds . asp search failure --message '' --view seeds . asp search failure --from-last-check --view seeds . asp search failure --message '' --view graph-turbo-request . asp query --selector --code . ``` `search failure` stdout is a search surface, not a source surface. It should start with `[search-failure]` and return failure facts, candidate owners, hot blocks, query profiles, frontier actions, and `avoid` guidance. Follow only the hot block selectors in `frontierActions` for code reads. `check ... --view seeds` is the same failure-frontier projection after a failing provider check; it strips ASP projection flags before provider execution and then renders the last-check transcript through `asp-graph-turbo` with `profile=failure-frontier`. Use `--view graph-turbo-request` only to debug the typed request packet sent to the ranking engine. Do not recover a failure by manually scanning repeated 100-line windows. ### Document Element Search Start from the document guide when you need the element and field vocabulary: ```sh asp org guide . asp org query guide . asp md guide . asp md query guide . ``` ```sh asp org search prime --view seeds . asp org search toc . asp org query --term --view metadata . asp org query --term --content . asp org query --kind --view metadata . asp org query --field --view metadata . asp org query --selector --view metadata . asp md search prime --view seeds . asp md search toc . asp md query --term --view metadata . asp md query --term --content . asp md query --kind paragraph --view metadata . asp md query --field --view metadata . asp md query --selector --view metadata . ``` Document search and query return parser-owned element facts: headings, paragraphs, properties, planning rows, tables, blocks, lists, tasks, links, and images. Use `search toc` as the repository documentation entrypoint: it returns only document heading outlines grouped by file, with `level`, `title`, range locators, and selector-query next actions. Use selector query for the element frontier inside a known range. Use `--content` when stdout should be only the matched element content. Use `direct-source-read` only when source-preserved document text is required after that range is known. Document query is an intersection of explicit axes: - `--term ` searches element kind, source kind, path, text/content, field keys, and field values. - `--selector ` narrows to elements overlapping a known range. - `--kind ` narrows to an exact element kind. - `--field ` or `--field ` narrows to parser-owned fields; the value match is substring-based. Org element fields are parser-owned by orgize: - `heading`: `level`, `title`, `todo`, `todoType`, `priority`, `tag` - `property`: `key`, `value` - `planning`: `scheduled`, `deadline`, `closed` - `table`: `header` - `block`: `kind=source|export`, `lang`, `backend` - `list`: `listKind`, `descriptive` - `listItem`: `bullet`, `indent`, `counter`, `tag` - `task`: `bullet`, `indent`, `checkbox`, `checked`, `tag` - `link` / `image`: `target`, `description` Useful Org query shapes: ```sh asp org query --kind heading --field todo=TODO --view metadata . asp org query --kind task --field checked=true --view metadata . asp org query --kind property --field key=CUSTOM_ID --view metadata . asp org query --kind block --field kind=source --field lang=rust --view metadata . asp org query --kind paragraph --term --content . ``` ### Tree-sitter Locate Then Code ```sh asp query guide treesitter . asp query --treesitter-query '' . asp query --selector --treesitter-query '' --workspace --code ``` Without `--code`, tree-sitter query output is a capture/frontier locator. Use it to pick the owner, symbol, import, call, attribute, decorator, or test window. With `--code`, stdout should be pure source for an exact selector or unique match. If the provider cannot compile the pattern or reports unsupported captures, record that reason and fall back to owner items or a bounded direct-source-read instead of silently widening the read. ### Verification ```sh asp check --changed . asp ast-patch dry-run --packet . ``` Use provider `ast-patch` only for structural/mechanical edits after a dry-run receipt and only when hook config enables that path.